webspresso 0.0.112 → 0.0.114

package/core/client/fragments.js

@@ -157,6 +157,173 @@ function createFragmentCoordinator(options = {}) {
   let isDisposed = false;
   let lifecycleListenersAttached = false;
 
+  // Per-version patch options (mode, limit, target, removeKeys, onBeforePatch, onAfterPatch, hookChainDepth)
+  const pendingPatchOptsByKey = new Map();
+  let pendingInvalidateHookDepth = 0;
+
+  // 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;
@@ -260,7 +427,12 @@ function createFragmentCoordinator(options = {}) {
     try {
       await executeBatchRefresh(targets);
     } catch (_err) {
-      // Background auto-refetch errors are non-fatal
+      // 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';
+        }
+      }
     }
   }
 
@@ -272,7 +444,7 @@ function createFragmentCoordinator(options = {}) {
     if (reason) pendingAutoReasons.add(reason);
     if (pendingAutoInstanceIds.size === 0) return;
 
-    if (reason === 'mount') {
+    if (reason === 'mount' || reason === 'lazy') {
       if (!autoBatchScheduled) {
         autoBatchScheduled = true;
         Promise.resolve().then(flushAutoRefresh);
@@ -469,6 +641,9 @@ 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;
@@ -489,6 +664,9 @@ function createFragmentCoordinator(options = {}) {
       existing._rawStale = rawStale;
       existing._rawInterval = rawInterval;
       syncInstanceInterval(existing);
+      if (existing.lazy && existing.lazyState === 'idle') {
+        observeLazyFragment(existing);
+      }
     } else {
       const created = {
         instanceId,
@@ -511,6 +689,9 @@ function createFragmentCoordinator(options = {}) {
         refetchIntervalInBackground,
         intervalTimer: null,
         activeIntervalMs: 0,
+        lazy: isLazyUnloaded,
+        lazyState: isLazyUnloaded ? 'idle' : 'loaded',
+        staleWhileUnloaded: false,
         _rawInput: rawInput,
         _rawDepends: rawDepends,
         _rawStale: rawStale,
@@ -518,7 +699,9 @@ function createFragmentCoordinator(options = {}) {
       };
       instances.set(instanceId, created);
       syncInstanceInterval(created);
-      if (pendingRestoredInput) {
+      if (isLazyUnloaded) {
+        observeLazyFragment(created);
+      } else if (pendingRestoredInput) {
         Promise.resolve().then(() => {
           if (!isDisposed && created.version === 0 && instances.get(instanceId) === created) {
             refresh(instanceId, pendingRestoredInput).catch(() => {});
@@ -558,6 +741,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();
@@ -603,7 +787,27 @@ 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);
+    }
+
+    const patchMeta = {
+      hookChainDepth: (patchOpts && patchOpts.hookChainDepth) || 0,
+    };
+
+    if (typeof options.onBeforePatch === 'function') {
+      options.onBeforePatch(inst.el, inst, patchMeta);
+    }
+    if (patchOpts && typeof patchOpts.onBeforePatch === 'function') {
+      try {
+        patchOpts.onBeforePatch(inst.el, inst, patchMeta);
+      } catch (_e) {}
+    }
+
     const patchStart = Date.now();
+    const patchMode = fragmentPayload.mode || (patchOpts && patchOpts.mode) || 'replace';
 
     const committedInput =
       fragmentPayload.input && typeof fragmentPayload.input === 'object' && !isArray(fragmentPayload.input)
@@ -613,6 +817,8 @@ function createFragmentCoordinator(options = {}) {
           : null;
 
     if (
+      patchMode !== 'append' &&
+      patchMode !== 'prepend' &&
       committedInput &&
       !followUpNeeded &&
       pendingTags.size === 0
@@ -629,7 +835,26 @@ function createFragmentCoordinator(options = {}) {
       }
     }
 
-    if (datastar && typeof datastar.patchFragmentElement === 'function') {
+    // Track existing strict descendant fragments before replace morph so removed children can be cleaned up
+    const prevDescendants = [];
+    if (patchMode !== 'append' && patchMode !== 'prepend') {
+      for (const otherInst of instances.values()) {
+        if (otherInst !== inst && otherInst.el && isStrictAncestor(inst.el, otherInst.el)) {
+          prevDescendants.push(otherInst);
+        }
+      }
+    }
+
+    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,
@@ -638,20 +863,56 @@ 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);
     const now = Date.now();
     inst.lastUpdatedAt = now;
 
+    // Clean up any nested child fragments removed during this parent patch
+    for (let i = 0; i < prevDescendants.length; i++) {
+      const prevChild = prevDescendants[i];
+      if (!prevChild.el || prevChild.el.isConnected === false || !isStrictAncestor(inst.el, prevChild.el)) {
+        clearInstanceInterval(prevChild);
+        unobserveLazyFragment(prevChild);
+        if (prevChild.abortController) {
+          try {
+            prevChild.abortController.abort();
+          } catch (_e) {}
+          prevChild.abortController = null;
+        }
+        instances.delete(prevChild.instanceId);
+      }
+    }
+
     // 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 (otherInst.el.__wPreservedLazyChild) {
+          delete otherInst.el.__wPreservedLazyChild;
+        } else if (!(otherInst.lazy && otherInst.lazyState === 'idle')) {
+          otherInst.lastUpdatedAt = now;
+        }
       }
     }
 
     if (typeof options.onAfterPatch === 'function') {
-      options.onAfterPatch(inst.el, inst);
+      options.onAfterPatch(inst.el, inst, patchMeta);
+    }
+    if (patchOpts && typeof patchOpts.onAfterPatch === 'function') {
+      try {
+        patchOpts.onAfterPatch(inst.el, inst, patchMeta);
+      } catch (_e) {}
     }
 
     if (debug) {
@@ -704,6 +965,9 @@ function createFragmentCoordinator(options = {}) {
       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]) {
@@ -908,8 +1172,8 @@ function createFragmentCoordinator(options = {}) {
       debug.trackRequestEnd(reqId, { status: 'completed', httpStatus: response.status });
     }
 
-    lastFailedBatch = null;
     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) {
@@ -922,12 +1186,42 @@ function createFragmentCoordinator(options = {}) {
       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) {
@@ -949,13 +1243,33 @@ function createFragmentCoordinator(options = {}) {
     }
 
     const allSuperseded =
-      refreshedIds.length === 0 && staleDiscardCount > 0 && staleDiscardCount === targets.length;
+      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: allSuperseded ? 'superseded' : '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,
@@ -977,6 +1291,20 @@ function createFragmentCoordinator(options = {}) {
       };
     }
 
+    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,
@@ -1017,13 +1345,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);
+        }
       }
     }
 
@@ -1043,8 +1376,16 @@ function createFragmentCoordinator(options = {}) {
     // Parent/Child deduplication: if parent & child are both invalidated, parent refresh covers child
     const dedupedInstances = deduplicateParentChildFragments(matchingInstances);
 
+    const batchHookDepth = pendingInvalidateHookDepth;
+    pendingInvalidateHookDepth = 0;
+
     const targets = dedupedInstances.map((inst) => {
       inst.version += 1;
+      if (batchHookDepth > 0) {
+        pendingPatchOptsByKey.set(`${inst.instanceId}:${inst.version}`, {
+          hookChainDepth: batchHookDepth,
+        });
+      }
       return {
         instanceId: inst.instanceId,
         name: inst.name,
@@ -1089,6 +1430,13 @@ function createFragmentCoordinator(options = {}) {
    * @returns {Promise<{ refreshed: string[], skipped?: boolean }>}
    */
   function invalidate(tags, meta = {}) {
+    const activeHook = typeof options.getPatchHookContext === 'function' ? options.getPatchHookContext() : null;
+    if (activeHook) {
+      const nextDepth = (activeHook.depth || 0) + 1;
+      if (nextDepth > pendingInvalidateHookDepth) {
+        pendingInvalidateHookDepth = nextDepth;
+      }
+    }
     const tagList = isArray(tags) ? tags : [tags];
     for (const raw of tagList) {
       if (typeof raw === 'string' && raw.trim()) {
@@ -1179,6 +1527,34 @@ function createFragmentCoordinator(options = {}) {
       inst.abortController = abortController;
       inst.version += 1;
 
+      if (inst.lazy && inst.lazyState === 'idle') {
+        inst.lazyState = 'loading';
+        unobserveLazyFragment(inst);
+      }
+
+      const activeHook = typeof options.getPatchHookContext === 'function' ? options.getPatchHookContext() : null;
+      const hookChainDepth = activeHook ? (activeHook.depth || 0) + 1 : 0;
+
+      if (
+        refreshOpts.mode ||
+        refreshOpts.limit !== undefined ||
+        refreshOpts.target ||
+        refreshOpts.removeKeys ||
+        hookChainDepth > 0 ||
+        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,
+          hookChainDepth,
+          onBeforePatch: refreshOpts.onBeforePatch,
+          onAfterPatch: refreshOpts.onAfterPatch,
+        });
+      }
+
       const candidateInput =
         nextInput && typeof nextInput === 'object'
           ? refreshOpts.replaceInput
@@ -1207,6 +1583,21 @@ function createFragmentCoordinator(options = {}) {
       const result = await executeBatchRefresh(targets, [], abortController.signal, refreshOpts.timeout);
       clearOwnedAbortControllers();
       const enrichedResult = { ok: true, ...result };
+      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);
@@ -1277,6 +1668,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,
@@ -1288,17 +1697,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());
         }
@@ -1311,7 +1731,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;
           }
@@ -1321,17 +1741,19 @@ 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;
@@ -1368,6 +1790,13 @@ function createFragmentCoordinator(options = {}) {
       }
       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);