webspresso 0.0.111 → 0.0.113

package/core/client/fragments.js

@@ -65,6 +65,16 @@ function parseFragmentInputAttr(raw) {
   }
 }
 
+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
@@ -79,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;
       }
     }
@@ -140,11 +150,179 @@ function createFragmentCoordinator(options = {}) {
 
   // 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;
 
+  // Per-version patch options (mode, limit, target, removeKeys, onBeforePatch, onAfterPatch)
+  const pendingPatchOptsByKey = new Map();
+
+  // Lazy fragment IntersectionObserver state
+  let lazyObserver = null;
+  const observedLazyEls = new WeakSet();
+
+  function getLazyObserver() {
+    if (lazyObserver) return lazyObserver;
+    const win =
+      typeof window !== 'undefined'
+        ? window
+        : typeof globalThis !== 'undefined'
+          ? globalThis
+          : null;
+    const IOCtor = win && typeof win.IntersectionObserver === 'function' ? win.IntersectionObserver : null;
+    if (!IOCtor) return null;
+    lazyObserver = new IOCtor((entries) => {
+      if (isDisposed) return;
+      const visibleIds = [];
+      for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (!entry || !entry.isIntersecting) continue;
+        const targetEl = entry.target;
+        try {
+          lazyObserver.unobserve(targetEl);
+        } catch (_e) {}
+        const fragId = targetEl && targetEl.getAttribute ? targetEl.getAttribute('data-w-fragment-id') : null;
+        const inst = fragId ? instances.get(fragId) : null;
+        if (inst && inst.lazy && inst.lazyState === 'idle') {
+          inst.lazyState = 'loading';
+          visibleIds.push(inst.instanceId);
+        }
+      }
+      if (visibleIds.length > 0) {
+        scheduleAutoRefresh(visibleIds, 'lazy');
+      }
+    });
+    return lazyObserver;
+  }
+
+  function observeLazyFragment(inst) {
+    if (!inst || !inst.el || !inst.lazy || inst.lazyState !== 'idle') return;
+    if (observedLazyEls.has(inst.el)) return;
+    const obs = getLazyObserver();
+    if (!obs) return;
+    observedLazyEls.add(inst.el);
+    try {
+      obs.observe(inst.el);
+    } catch (_e) {}
+  }
+
+  function unobserveLazyFragment(inst) {
+    if (!inst || !inst.el || !lazyObserver) return;
+    try {
+      lazyObserver.unobserve(inst.el);
+    } catch (_e) {}
+  }
+
+  function getListItemKey(node) {
+    if (!node || node.nodeType !== 1 || typeof node.getAttribute !== 'function') return null;
+    if (node.id) return `id:${node.id}`;
+    const wKey = node.getAttribute('data-w-key');
+    if (wKey) return `wkey:${wKey}`;
+    return null;
+  }
+
+  function patchIncrementalList(fragEl, html, opts = {}) {
+    const doc = fragEl.ownerDocument || (typeof document !== 'undefined' ? document : null);
+    const parsed = datastar && typeof datastar.parseHtmlFragment === 'function'
+      ? datastar.parseHtmlFragment(html, doc)
+      : null;
+    if (!parsed) return false;
+
+    const targetSel = opts.target || null;
+    const container =
+      (targetSel && fragEl.querySelector ? fragEl.querySelector(targetSel) : null) ||
+      (fragEl.querySelector ? fragEl.querySelector('[data-w-list]') : null) ||
+      fragEl;
+    const incomingContainer =
+      (targetSel && parsed.querySelector ? parsed.querySelector(targetSel) : null) ||
+      (parsed.querySelector ? parsed.querySelector('[data-w-list]') : null) ||
+      parsed;
+
+    // 1. Remove explicitly requested keys if any
+    if (isArray(opts.removeKeys) && opts.removeKeys.length > 0) {
+      const removeSet = new Set(opts.removeKeys.map(String));
+      const curChildren = Array.from(container.children || []);
+      for (let i = 0; i < curChildren.length; i++) {
+        const child = curChildren[i];
+        const rawKey = child.getAttribute('data-w-key') || child.id || '';
+        const fullKey = getListItemKey(child);
+        if (removeSet.has(rawKey) || (fullKey && removeSet.has(fullKey))) {
+          if (typeof opts.onBeforeNodeRemove === 'function') opts.onBeforeNodeRemove(child);
+          container.removeChild(child);
+        }
+      }
+    }
+
+    // 2. Index existing keyed items in container
+    const existingByKey = new Map();
+    const existingChildren = Array.from(container.children || []);
+    for (let i = 0; i < existingChildren.length; i++) {
+      const k = getListItemKey(existingChildren[i]);
+      if (k && !existingByKey.has(k)) {
+        existingByKey.set(k, existingChildren[i]);
+      }
+    }
+
+    const incomingItems = Array.from(incomingContainer.children || []);
+    const mode = opts.mode === 'prepend' ? 'prepend' : 'append';
+    const itemsToInsert = mode === 'prepend' ? incomingItems.slice().reverse() : incomingItems;
+
+    for (let i = 0; i < itemsToInsert.length; i++) {
+      const incoming = itemsToInsert[i];
+      if (incoming.nodeType !== 1) continue;
+      const key = getListItemKey(incoming);
+      const existingMatch = key ? existingByKey.get(key) : null;
+
+      if (existingMatch && existingMatch.tagName === incoming.tagName) {
+        // Update existing keyed item in place without duplicating
+        if (datastar && typeof datastar.morphDomTrees === 'function') {
+          datastar.morphDomTrees(existingMatch, incoming, {
+            onBeforeNodeRemove: opts.onBeforeNodeRemove,
+            onNodeAdded: opts.onNodeAdded,
+          });
+        }
+        continue;
+      }
+
+      const imported = container.ownerDocument
+        ? container.ownerDocument.importNode(incoming, true)
+        : incoming.cloneNode(true);
+
+      if (mode === 'prepend') {
+        const firstRef = (container.children && container.children[0]) || container.firstChild || null;
+        container.insertBefore(imported, firstRef);
+      } else {
+        container.appendChild(imported);
+      }
+
+      if (key) {
+        existingByKey.set(key, imported);
+      }
+      if (typeof opts.onNodeAdded === 'function') {
+        opts.onNodeAdded(imported);
+      }
+    }
+
+    // 3. Enforce optional retained item limit
+    const limitAttr = container.getAttribute ? container.getAttribute('data-w-limit') : null;
+    const rawLimit = opts.limit !== undefined ? opts.limit : limitAttr;
+    const limit = rawLimit !== null && rawLimit !== undefined && rawLimit !== '' ? Number(rawLimit) : 0;
+    if (Number.isFinite(limit) && limit > 0) {
+      while (container.children && container.children.length > limit) {
+        const ch = container.children;
+        const victim = mode === 'prepend' ? ch[ch.length - 1] : ch[0];
+        if (!victim) break;
+        if (typeof opts.onBeforeNodeRemove === 'function') opts.onBeforeNodeRemove(victim);
+        container.removeChild(victim);
+      }
+    }
+
+    return true;
+  }
+
   function isDocumentHidden() {
     const root = getRoot();
     const doc = root && root.nodeType === 9 ? root : root && root.ownerDocument ? root.ownerDocument : typeof document !== 'undefined' ? document : null;
@@ -195,76 +373,100 @@ function createFragmentCoordinator(options = {}) {
     }
   }
 
-  function scheduleAutoRefresh(instanceIds, reason = 'auto') {
-    if (isDisposed || !isArray(instanceIds) || instanceIds.length === 0) return;
-    for (const id of instanceIds) {
-      if (id) pendingAutoInstanceIds.add(id);
+  async function flushAutoRefresh() {
+    autoBatchScheduled = false;
+    if (autoBatchTimer) {
+      clearTimeout(autoBatchTimer);
+      autoBatchTimer = null;
     }
-    if (autoBatchScheduled || pendingAutoInstanceIds.size === 0) return;
-    autoBatchScheduled = true;
+    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;
 
-    Promise.resolve().then(async () => {
-      autoBatchScheduled = false;
-      if (isDisposed || pendingAutoInstanceIds.size === 0) return;
-      const idsToRefresh = Array.from(pendingAutoInstanceIds);
-      pendingAutoInstanceIds.clear();
+    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,
+      };
+    });
 
-      // Skip background auto-refresh if a mutation invalidation batch is currently in flight
-      if (inFlightBatchCount > 0) return;
+    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),
+      });
+    }
 
-      const candidates = [];
-      for (const id of idsToRefresh) {
-        const inst = instances.get(id);
-        if (inst && inst.el && inst.el.isConnected !== false && !inst.abortController) {
-          candidates.push(inst);
+    try {
+      await executeBatchRefresh(targets);
+    } catch (_err) {
+      // Background auto-refetch errors are non-fatal; reset lazyState if still unloaded so retry/re-observe works
+      for (const inst of deduped) {
+        if (inst.lazy && inst.lazyState === 'loading') {
+          inst.lazyState = 'idle';
         }
       }
-      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,
-        };
-      });
+  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 (debug && typeof debug.recordEvent === 'function') {
-        debug.recordEvent('fragment:auto-refetch', {
-          reason,
-          fragments: targets.map((t) => t.instanceId),
-        });
+    if (reason === 'mount' || reason === 'lazy') {
+      if (!autoBatchScheduled) {
+        autoBatchScheduled = true;
+        Promise.resolve().then(flushAutoRefresh);
       }
+      return;
+    }
 
-      try {
-        await executeBatchRefresh(targets);
-      } catch (_err) {
-        // Background auto-refetch errors are non-fatal
-      }
-    });
+    if (autoBatchTimer || autoBatchScheduled) return;
+    autoBatchTimer = setTimeout(flushAutoRefresh, 5);
   }
 
   function triggerFocusRefetch() {
     if (isDisposed || isDocumentHidden()) return;
-    if (focusDebounceTimer) clearTimeout(focusDebounceTimer);
-    focusDebounceTimer = setTimeout(() => {
-      focusDebounceTimer = null;
-      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');
+    scanDomInstances();
+    const matchedIds = [];
+    for (const inst of instances.values()) {
+      if (isInstanceStale(inst, inst.refetchOnWindowFocus)) {
+        matchedIds.push(inst.instanceId);
       }
-    }, 20);
+    }
+    if (matchedIds.length > 0) {
+      scheduleAutoRefresh(matchedIds, 'window-focus');
+    }
   }
 
   function triggerReconnectRefetch() {
@@ -394,12 +596,21 @@ function createFragmentCoordinator(options = {}) {
       `frag_input:${name}`;
 
     let effectiveInput = input;
-    if (isInputPersistEnabled) {
+    let pendingRestoredInput = null;
+    if (!existing && isInputPersistEnabled) {
       const store = inputStorageType === 'local' ? defaultStorage.local : defaultStorage.session;
-      if (rawInput === null || Object.keys(effectiveInput).length === 0) {
-        const stored = store.get(inputStorageKey, null);
-        if (stored && typeof stored === 'object' && !isArray(stored)) {
-          effectiveInput = stored;
+      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 };
         }
       }
     }
@@ -429,13 +640,16 @@ function createFragmentCoordinator(options = {}) {
       ensureLifecycleListeners();
     }
 
+    const rawLazyAttr = el.getAttribute('data-w-lazy');
+    const isLazyUnloaded = Boolean(rawLazyAttr && rawLazyAttr !== 'false' && rawLazyAttr !== 'loaded');
+
     if (existing) {
       existing.name = name;
       existing.pagePath = pagePath;
       existing.el = el;
       existing.dependsOn = dependsOn;
-      if (rawInput !== null || isInputPersistEnabled) {
-        existing.input = effectiveInput;
+      if (rawInput !== null && rawInput !== existing._rawInput) {
+        existing.input = input;
       }
       existing.persistInput = isInputPersistEnabled ? { type: inputStorageType, key: inputStorageKey } : null;
       existing.staleTime = staleTime;
@@ -449,16 +663,21 @@ function createFragmentCoordinator(options = {}) {
       existing._rawStale = rawStale;
       existing._rawInterval = rawInterval;
       syncInstanceInterval(existing);
+      if (existing.lazy && existing.lazyState === 'idle') {
+        observeLazyFragment(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,
@@ -469,6 +688,9 @@ function createFragmentCoordinator(options = {}) {
         refetchIntervalInBackground,
         intervalTimer: null,
         activeIntervalMs: 0,
+        lazy: isLazyUnloaded,
+        lazyState: isLazyUnloaded ? 'idle' : 'loaded',
+        staleWhileUnloaded: false,
         _rawInput: rawInput,
         _rawDepends: rawDepends,
         _rawStale: rawStale,
@@ -476,7 +698,15 @@ function createFragmentCoordinator(options = {}) {
       };
       instances.set(instanceId, created);
       syncInstanceInterval(created);
-      if (refetchOnMount === 'always' || (refetchOnMount === true && staleTime <= 0)) {
+      if (isLazyUnloaded) {
+        observeLazyFragment(created);
+      } else 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');
       }
     }
@@ -510,6 +740,7 @@ function createFragmentCoordinator(options = {}) {
           !seenIds.has(id) || (inst.el && inst.el.isConnected === false);
         if (disconnected) {
           clearInstanceInterval(inst);
+          unobserveLazyFragment(inst);
           if (inst.abortController) {
             try {
               inst.abortController.abort();
@@ -535,7 +766,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) {
@@ -555,25 +786,58 @@ function createFragmentCoordinator(options = {}) {
     const html = fragmentPayload && typeof fragmentPayload.html === 'string' ? fragmentPayload.html : '';
     if (!html) return false;
 
+    const patchKey = `${inst.instanceId}:${reqVersion}`;
+    const patchOpts = pendingPatchOptsByKey.get(patchKey) || null;
+    if (patchOpts) {
+      pendingPatchOptsByKey.delete(patchKey);
+    }
+
+    if (typeof options.onBeforePatch === 'function') {
+      options.onBeforePatch(inst.el, inst);
+    }
+    if (patchOpts && typeof patchOpts.onBeforePatch === 'function') {
+      try {
+        patchOpts.onBeforePatch(inst.el, inst);
+      } catch (_e) {}
+    }
+
     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;
-      const serializedInput = JSON.stringify(fragmentPayload.input);
-      inst.el.setAttribute('data-w-fragment-input', serializedInput);
+      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);
       }
     }
 
-    if (datastar && typeof datastar.patchFragmentElement === 'function') {
+    const patchMode = fragmentPayload.mode || (patchOpts && patchOpts.mode) || 'replace';
+    if (patchMode === 'append' || patchMode === 'prepend') {
+      patchIncrementalList(inst.el, html, {
+        mode: patchMode,
+        limit: fragmentPayload.limit !== undefined ? fragmentPayload.limit : patchOpts && patchOpts.limit,
+        target: fragmentPayload.target || (patchOpts && patchOpts.target),
+        removeKeys: fragmentPayload.removeKeys || (patchOpts && patchOpts.removeKeys),
+        onBeforeNodeRemove: options.onBeforeNodeRemove,
+        onNodeAdded: options.onNodeAdded,
+      });
+    } else if (datastar && typeof datastar.patchFragmentElement === 'function') {
       datastar.patchFragmentElement(inst.el, html, {
         onBeforeNodeRemove: options.onBeforeNodeRemove,
         onNodeAdded: options.onNodeAdded,
@@ -582,15 +846,37 @@ function createFragmentCoordinator(options = {}) {
       inst.el.innerHTML = html;
     }
 
+    // Clear lazy unloaded markers once a real patch is applied
+    if (inst.lazy || inst.lazyState !== 'loaded') {
+      inst.lazy = false;
+      inst.lazyState = 'loaded';
+      inst.staleWhileUnloaded = false;
+      unobserveLazyFragment(inst);
+      if (inst.el && typeof inst.el.removeAttribute === 'function') {
+        inst.el.removeAttribute('data-w-lazy');
+      }
+    }
+
     const patchMs = Math.max(0, Date.now() - patchStart);
-    inst.lastUpdatedAt = Date.now();
+    const now = Date.now();
+    inst.lastUpdatedAt = now;
 
     // Re-sync nested fragment instances that may have been updated inside this parent fragment
     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);
     }
+    if (patchOpts && typeof patchOpts.onAfterPatch === 'function') {
+      try {
+        patchOpts.onAfterPatch(inst.el, inst);
+      } catch (_e) {}
+    }
 
     if (debug) {
       debug.recordChainPatch(chainId, {
@@ -633,6 +919,29 @@ 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)) {
+          // Supersede any older in-flight refresh on the nested child so a late child response
+          // cannot overwrite the newer parent+child snapshot.
+          otherInst.version += 1;
+          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) => ({
@@ -641,6 +950,29 @@ 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 = uid('frag_req', 4);
@@ -686,6 +1018,7 @@ function createFragmentCoordinator(options = {}) {
         signal: batchAbortController.signal,
       });
     } catch (err) {
+      decrementTargetBusy();
       if (timeoutTimer) {
         clearTimeout(timeoutTimer);
         timeoutTimer = null;
@@ -766,6 +1099,8 @@ function createFragmentCoordinator(options = {}) {
       }
     } catch (_e) {
       body = null;
+    } finally {
+      decrementTargetBusy();
     }
 
     if (!response.ok) {
@@ -800,16 +1135,61 @@ function createFragmentCoordinator(options = {}) {
       debug.trackRequestEnd(reqId, { status: 'completed', httpStatus: response.status });
     }
 
-    lastFailedBatch = null;
-    const resultsMap = (body && body.fragments) || {};
+    const rawFragments = (body && body.fragments) || {};
+    const rawErrors = (body && body.errors && typeof body.errors === 'object' ? body.errors : {}) || {};
+    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 = [];
+    const batchErrors = [];
+    const failedTargets = [];
+    let staleDiscardCount = 0;
     let totalLoadMs = 0;
     let totalRenderMs = 0;
 
     for (const target of targets) {
       const inst = instances.get(target.instanceId);
+      const fragError =
+        rawErrors[target.instanceId] ||
+        rawErrors[target.name] ||
+        (resultsMap[target.instanceId] && resultsMap[target.instanceId].error) ||
+        (resultsMap[target.name] && resultsMap[target.name].error) ||
+        null;
+      if (fragError) {
+        const errObj =
+          fragError instanceof Error
+            ? fragError
+            : Object.assign(
+                new Error(
+                  (fragError && typeof fragError === 'object' && fragError.message) ||
+                    String(fragError) ||
+                    `Fragment "${target.name}" failed to refresh`
+                ),
+                {
+                  status: (fragError && fragError.status) || 500,
+                  code: (fragError && fragError.code) || 'FRAGMENT_REFRESH_ERROR',
+                  instanceId: target.instanceId,
+                  fragmentName: target.name,
+                }
+              );
+        batchErrors.push(errObj);
+        failedTargets.push(target);
+        continue;
+      }
+
       const fragResult = resultsMap[target.instanceId] || resultsMap[target.name];
       if (!inst || !fragResult) continue;
+      if (target.reqVersion < inst.version) {
+        staleDiscardCount += 1;
+      }
       if (isNumber(fragResult.loadMs)) totalLoadMs += fragResult.loadMs;
       if (isNumber(fragResult.renderMs)) totalRenderMs += fragResult.renderMs;
 
@@ -817,18 +1197,42 @@ function createFragmentCoordinator(options = {}) {
         inst,
         fragResult,
         target.reqVersion,
-        chainIds[0] || null
+        chainIds[0] || null,
+        target.input
       );
       if (applied) {
         refreshedIds.push(target.instanceId);
       }
     }
 
+    const allSuperseded =
+      refreshedIds.length === 0 &&
+      batchErrors.length === 0 &&
+      staleDiscardCount > 0 &&
+      staleDiscardCount === targets.length;
+
+    if (refreshedIds.length > 0 && lastFailedBatch && isArray(lastFailedBatch.targets)) {
+      const refreshedSet = new Set(refreshedIds);
+      const remainingFailed = lastFailedBatch.targets.filter((t) => !refreshedSet.has(t.instanceId));
+      lastFailedBatch =
+        remainingFailed.length > 0
+          ? { targets: remainingFailed, chainIds: lastFailedBatch.chainIds }
+          : null;
+    }
+
+    if (batchErrors.length > 0) {
+      lastFailedBatch = {
+        targets: failedTargets,
+        chainIds,
+      };
+    }
+
     for (const cid of chainIds) {
       if (debug) {
         debug.recordChainRefresh(cid, {
           fragmentIds: refreshedIds,
-          status: 'ok',
+          status: batchErrors.length > 0 ? (refreshedIds.length > 0 ? 'partial-error' : 'error') : allSuperseded ? 'superseded' : 'ok',
+          error: batchErrors[0] || null,
           loadMs: totalLoadMs,
           renderMs: totalRenderMs,
           totalServerMs: body && isNumber(body.totalMs) ? body.totalMs : null,
@@ -836,6 +1240,34 @@ function createFragmentCoordinator(options = {}) {
       }
     }
 
+    if (allSuperseded) {
+      return {
+        ok: false,
+        canceled: true,
+        superseded: true,
+        refreshed: [],
+        errors: [],
+        timings: {
+          loadMs: totalLoadMs,
+          renderMs: totalRenderMs,
+        },
+      };
+    }
+
+    if (batchErrors.length > 0) {
+      return {
+        ok: false,
+        partial: refreshedIds.length > 0,
+        refreshed: refreshedIds,
+        errors: batchErrors,
+        error: batchErrors[0],
+        timings: {
+          loadMs: totalLoadMs,
+          renderMs: totalRenderMs,
+        },
+      };
+    }
+
     return {
       ok: true,
       refreshed: refreshedIds,
@@ -876,13 +1308,18 @@ function createFragmentCoordinator(options = {}) {
     for (const inst of instances.values()) {
       let matched = false;
       for (const tag of tagsToFlush) {
-        if (inst.dependsOn.has(tag) || inst.name === tag) {
+        if (inst.dependsOn.has(tag) || inst.name === tag || inst.instanceId === tag) {
           matched = true;
           break;
         }
       }
       if (matched) {
-        matchingInstances.push(inst);
+        if (inst.lazy && inst.lazyState === 'idle') {
+          // Do not fetch off-screen unloaded lazy fragments on invalidation; mark stale for when visible
+          inst.staleWhileUnloaded = true;
+        } else {
+          matchingInstances.push(inst);
+        }
       }
     }
 
@@ -1038,34 +1475,73 @@ 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') {
-          const serializedInput = JSON.stringify(inst.input);
-          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, inst.input);
-        }
+      if (inst.lazy && inst.lazyState === 'idle') {
+        inst.lazyState = 'loading';
+        unobserveLazyFragment(inst);
       }
 
+      if (
+        refreshOpts.mode ||
+        refreshOpts.limit !== undefined ||
+        refreshOpts.target ||
+        refreshOpts.removeKeys ||
+        typeof refreshOpts.onBeforePatch === 'function' ||
+        typeof refreshOpts.onAfterPatch === 'function'
+      ) {
+        pendingPatchOptsByKey.set(`${inst.instanceId}:${inst.version}`, {
+          mode: refreshOpts.mode || null,
+          limit: refreshOpts.limit,
+          target: refreshOpts.target,
+          removeKeys: refreshOpts.removeKeys,
+          onBeforePatch: refreshOpts.onBeforePatch,
+          onAfterPatch: refreshOpts.onAfterPatch,
+        });
+      }
+
+      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.ok === false && !enrichedResult.canceled && !enrichedResult.superseded && enrichedResult.error) {
+        const failHandler = refreshOpts.onFailure || refreshOpts.onError;
+        if (typeof failHandler === 'function') {
+          await failHandler(enrichedResult.error);
+        }
+        if (typeof refreshOpts.onSettled === 'function') {
+          await refreshOpts.onSettled(enrichedResult, enrichedResult.error);
+        } else if (typeof refreshOpts.onComplete === 'function') {
+          await refreshOpts.onComplete(enrichedResult, enrichedResult.error);
+        }
+        if (refreshOpts.throwOnError === true) {
+          throw enrichedResult.error;
+        }
+        return enrichedResult;
+      }
+      if (!enrichedResult.canceled && !enrichedResult.superseded && enrichedResult.ok !== false) {
         if (typeof refreshOpts.onSuccess === 'function') {
           await refreshOpts.onSuccess(enrichedResult);
         }
@@ -1077,6 +1553,7 @@ function createFragmentCoordinator(options = {}) {
       }
       return enrichedResult;
     } catch (err) {
+      clearOwnedAbortControllers();
       const failHandler = refreshOpts.onFailure || refreshOpts.onError;
       if (typeof failHandler === 'function') {
         try {
@@ -1121,7 +1598,7 @@ function createFragmentCoordinator(options = {}) {
         inst.version += 1;
         retryTargets.push({
           ...t,
-          input: { ...inst.input },
+          input: t.input ? { ...t.input } : { ...inst.input },
           reqVersion: inst.version,
         });
       }
@@ -1134,6 +1611,24 @@ function createFragmentCoordinator(options = {}) {
     return executeBatchRefresh(retryTargets, chainIds);
   }
 
+  function resolveInstanceByIdOrName(idOrName) {
+    if (!idOrName) return null;
+    const direct = instances.get(idOrName);
+    if (direct && (!direct.el || direct.el.isConnected !== false)) {
+      return direct;
+    }
+    const defaultInst = instances.get(`${idOrName}:default`);
+    if (defaultInst && (!defaultInst.el || defaultInst.el.isConnected !== false)) {
+      return defaultInst;
+    }
+    for (const inst of instances.values()) {
+      if (inst.name === idOrName && (!inst.el || inst.el.isConnected !== false)) {
+        return inst;
+      }
+    }
+    return null;
+  }
+
   return {
     syncDomInstances,
     invalidate,
@@ -1145,17 +1640,28 @@ function createFragmentCoordinator(options = {}) {
       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);
-        if (inst) {
-          if (item.input && typeof item.input === 'object') {
-            inst.input = { ...item.input };
-            if (inst.el && typeof inst.el.setAttribute === 'function') {
-              const serializedInput = JSON.stringify(inst.input);
-              inst.el.setAttribute('data-w-fragment-input', serializedInput);
-              inst._rawInput = serializedInput;
+        const matchedList = [];
+        if (item.instanceId && instances.has(item.instanceId)) {
+          matchedList.push(instances.get(item.instanceId));
+        } else {
+          for (const inst of instances.values()) {
+            if (inst.instanceId === key || inst.name === key) {
+              matchedList.push(inst);
+            }
+          }
+        }
+        if (matchedList.length > 0) {
+          for (const inst of matchedList) {
+            if (item.input && typeof item.input === 'object') {
+              inst.input = { ...item.input };
+              if (inst.el && typeof inst.el.setAttribute === 'function') {
+                const serializedInput = JSON.stringify(inst.input);
+                inst.el.setAttribute('data-w-fragment-input', serializedInput);
+                inst._rawInput = serializedInput;
+              }
             }
+            pendingTags.add(item.instanceId ? inst.instanceId : inst.name);
           }
-          pendingTags.add(inst.name);
         } else if (key) {
           pendingTags.add(String(key).trim());
         }
@@ -1168,7 +1674,7 @@ function createFragmentCoordinator(options = {}) {
       const matching = [];
       for (const inst of instances.values()) {
         for (const t of tagSet) {
-          if (inst.dependsOn.has(t) || inst.name === t) {
+          if (inst.dependsOn.has(t) || inst.name === t || inst.instanceId === t) {
             matching.push(inst);
             break;
           }
@@ -1178,24 +1684,38 @@ function createFragmentCoordinator(options = {}) {
     },
     retryFailed,
     retryLastFailed: retryFailed,
-    getInstance(instanceId) {
-      const hit = instances.get(instanceId);
-      if (hit && (!hit.el || hit.el.isConnected !== false)) {
+    getInstance(instanceIdOrName) {
+      const hit = resolveInstanceByIdOrName(instanceIdOrName);
+      if (hit) {
         return hit;
       }
       scanDomInstances();
-      return instances.get(instanceId) || null;
+      return resolveInstanceByIdOrName(instanceIdOrName);
     },
-    getInstances() {
+    getInstances(nameOrId) {
       scanDomInstances();
-      return Array.from(instances.values());
+      const all = Array.from(instances.values());
+      if (!nameOrId) return all;
+      return all.filter((inst) => inst.instanceId === nameOrId || inst.name === nameOrId);
     },
     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() {
@@ -1207,7 +1727,19 @@ function createFragmentCoordinator(options = {}) {
         clearTimeout(focusDebounceTimer);
         focusDebounceTimer = null;
       }
+      if (autoBatchTimer) {
+        clearTimeout(autoBatchTimer);
+        autoBatchTimer = null;
+      }
       pendingAutoInstanceIds.clear();
+      pendingAutoReasons.clear();
+      pendingPatchOptsByKey.clear();
+      if (lazyObserver && typeof lazyObserver.disconnect === 'function') {
+        try {
+          lazyObserver.disconnect();
+        } catch (_e) {}
+        lazyObserver = null;
+      }
       removeLifecycleListeners();
       for (const inst of instances.values()) {
         clearInstanceInterval(inst);