@wsxjs/wsx-core 0.0.23 → 0.0.24

package/src/utils/element-update.ts

@@ -17,6 +17,7 @@ import {
     updateOrCreateTextNode,
     removeNodeIfNotPreserved,
     replaceOrInsertElement,
+    replaceOrInsertElementAtPosition,
     appendNewChild,
     buildNewChildrenMaps,
     deduplicateCacheKeys,
@@ -39,7 +40,16 @@ function removeProp(
 
     // 处理特殊属性
     if (key === "ref") {
-        // ref 是回调，不需要移除
+        // 关键修复：当 ref 被移除时，调用回调并传入 null
+        // 这确保组件可以清理引用，避免使用已移除的元素
+        // 例如：LanguageSwitcher 的 dropdownElement 应该在元素被移除时设置为 null
+        if (typeof oldValue === "function") {
+            try {
+                oldValue(null);
+            } catch {
+                // 忽略回调错误
+            }
+        }
         return;
     }
 
@@ -58,8 +68,17 @@ function removeProp(
     }
 
     if (key.startsWith("on") && typeof oldValue === "function") {
-        // 事件监听器：需要移除（但无法获取原始监听器，所以跳过）
-        // 注意：这可能导致内存泄漏，但在实际使用中，事件监听器通常不会变化
+        // 关键修复：移除事件监听器，避免内存泄漏
+        const eventName = key.slice(2).toLowerCase();
+        const listenerKey = `__wsxListener_${eventName}`;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const savedListener = (element as any)[listenerKey];
+
+        if (savedListener) {
+            element.removeEventListener(eventName, savedListener);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            delete (element as any)[listenerKey];
+        }
         return;
     }
 
@@ -134,9 +153,21 @@ function applySingleProp(
     // 处理事件监听器
     if (key.startsWith("on") && typeof value === "function") {
         const eventName = key.slice(2).toLowerCase();
-        // 注意：这里会重复添加事件监听器，但这是预期的行为
-        // 在实际使用中，事件监听器通常不会频繁变化
+
+        // 关键修复：移除旧的监听器，避免重复添加
+        // 在元素上保存监听器引用，以便后续移除
+        const listenerKey = `__wsxListener_${eventName}`;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const oldListener = (element as any)[listenerKey];
+
+        if (oldListener) {
+            element.removeEventListener(eventName, oldListener);
+        }
+
+        // 添加新监听器并保存引用
         element.addEventListener(eventName, value as EventListener);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (element as any)[listenerKey] = value;
         return;
     }
 
@@ -252,7 +283,7 @@ export function updateChildren(
     element: HTMLElement | SVGElement,
     oldChildren: JSXChildren[],
     newChildren: JSXChildren[],
-    cacheManager?: DOMCacheManager
+    _cacheManager?: DOMCacheManager // 可选参数，保留以保持 API 兼容性
 ): void {
     const flatOld = flattenChildrenSafe(oldChildren);
     const flatNew = flattenChildrenSafe(newChildren);
@@ -263,6 +294,8 @@ export function updateChildren(
     // 更新现有子节点
     const minLength = Math.min(flatOld.length, flatNew.length);
     const domIndex = { value: 0 }; // 使用对象包装，使其可在函数间传递
+    // 跟踪已处理的节点，用于确定正确的位置
+    const processedNodes = new Set<Node>();
 
     for (let i = 0; i < minLength; i++) {
         const oldChild = flatOld[i];
@@ -284,13 +317,20 @@ export function updateChildren(
             }
         } else if (typeof oldChild === "string" || typeof oldChild === "number") {
             oldNode = findTextNode(element, domIndex);
-            // 关键修复：如果 findTextNode 返回 null，尝试从当前 domIndex 位置开始查找文本节点
-            // 这可以处理文本节点存在但 domIndex 不正确的情况
-            // Bug 1 修复：从 domIndex.value 开始搜索，而不是从 0 开始，避免重新处理已处理的节点
+            // RFC-0044 修复：fallback 搜索必须验证文本内容
+            // 在缓存元素复用场景下，不能盲目返回第一个找到的文本节点
+            // 必须确保内容匹配，否则会导致错误的更新
             if (!oldNode && element.childNodes.length > 0) {
+                const oldText = String(oldChild);
                 for (let j = domIndex.value; j < element.childNodes.length; j++) {
                     const node = element.childNodes[j];
-                    if (node.nodeType === Node.TEXT_NODE) {
+                    // 关键修复：只检查直接子文本节点，确保 node.parentNode === element
+                    // 并且必须验证文本内容是否匹配
+                    if (
+                        node.nodeType === Node.TEXT_NODE &&
+                        node.parentNode === element &&
+                        node.textContent === oldText
+                    ) {
                         oldNode = node;
                         // 更新 domIndex 到找到的文本节点之后
                         domIndex.value = j + 1;
@@ -316,10 +356,19 @@ export function updateChildren(
                         oldNode.textContent !== newText);
 
                 if (needsUpdate) {
-                    updateOrCreateTextNode(element, oldNode, newText);
+                    // RFC-0044 修复：使用返回的节点引用直接标记
+                    // updateOrCreateTextNode 现在返回更新/创建的节点
+                    // 这样可以准确标记，避免搜索失败导致的重复创建
+                    const updatedNode = updateOrCreateTextNode(element, oldNode, newText);
+                    if (updatedNode && !processedNodes.has(updatedNode)) {
+                        processedNodes.add(updatedNode);
+                    }
+                } else {
+                    // 即使不需要更新，也要标记为已处理（文本节点已存在且内容正确）
+                    if (oldNode && oldNode.parentNode === element) {
+                        processedNodes.add(oldNode);
+                    }
                 }
-                // 如果文本内容相同且 oldNode 为 null，不需要做任何操作
-                // 因为文本节点可能已经存在于 DOM 中且内容正确，或者不需要创建
             } else {
                 // 类型变化：文本 -> 元素/Fragment
                 removeNodeIfNotPreserved(element, oldNode);
@@ -336,47 +385,74 @@ export function updateChildren(
                 continue; // 跳过保留的元素
             }
 
-            // 关键修复：即使 newChild === oldChild，如果它是元素，h() 应该已经调用了 updateElement 来更新其子元素
-            // 但是，为了确保子元素确实被更新了，我们不应该跳过，而是让后续代码确保元素在正确位置
-            // 如果 h() 已经正确更新了子元素，那么这里只需要确保元素在正确位置即可
-            if (
-                newChild === oldChild &&
-                (newChild instanceof HTMLElement || newChild instanceof SVGElement)
-            ) {
-                // 同一个元素引用，h() 应该已经通过 updateElement 更新了其子元素
-                // 但是，如果 cacheManager 可用，我们可以验证并确保子元素确实被更新了
-                if (cacheManager) {
-                    const childMetadata = cacheManager.getMetadata(newChild);
-                    if (childMetadata) {
-                        // 如果元数据存在，说明 h() 已经更新了子元素
-                        // 只需要确保元素在正确位置
-                        if (oldNode === newChild && newChild.parentNode === element) {
-                            // 元素已经在正确位置，且 h() 应该已经更新了其子元素
-                            // 不需要额外处理
-                            continue;
+            if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
+                // 关键修复：确定正确的位置
+                // 策略：基于 flatNew 数组的顺序来确定位置，而不是 DOM 中的实际顺序
+                // 因为某些元素可能被隐藏（position: absolute），导致 DOM 顺序与数组顺序不同
+
+                // 找到索引 i 之前的所有元素，确定 newChild 应该在这些元素之后
+                let targetNextSibling: Node | null = null;
+                let foundPreviousElement = false;
+
+                // 从后往前查找，找到最后一个在 DOM 中的前一个元素
+                for (let j = i - 1; j >= 0; j--) {
+                    const prevChild = flatNew[j];
+                    if (prevChild instanceof HTMLElement || prevChild instanceof SVGElement) {
+                        if (prevChild.parentNode === element) {
+                            // 找到前一个元素，newChild 应该在它之后
+                            targetNextSibling = prevChild.nextSibling;
+                            foundPreviousElement = true;
+                            break;
                         }
                     }
-                } else {
-                    // 如果没有 cacheManager，假设 h() 已经更新了子元素
-                    if (oldNode === newChild && newChild.parentNode === element) {
-                        continue;
-                    }
                 }
-                // 如果位置不对，需要调整
-            }
 
-            if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
-                // 如果 newChild 已经在 DOM 中且位置正确，不需要替换
-                if (newChild.parentNode === element && oldNode === newChild) {
+                // 如果没有找到前一个元素，newChild 应该在开头
+                if (!foundPreviousElement) {
+                    // 找到第一个非保留、未处理的子节点
+                    const firstChild = Array.from(element.childNodes).find(
+                        (node) => !shouldPreserveElement(node) && !processedNodes.has(node)
+                    );
+                    targetNextSibling = firstChild || null;
+                }
+
+                // 检查 newChild 是否已经在正确位置
+                const isInCorrectPosition =
+                    newChild.parentNode === element && newChild.nextSibling === targetNextSibling;
+
+                // 如果 newChild === oldChild 且位置正确，说明是同一个元素且位置正确
+                if (newChild === oldChild && isInCorrectPosition) {
+                    // 标记为已处理
+                    if (oldNode) processedNodes.add(oldNode);
+                    processedNodes.add(newChild);
                     continue; // 元素已经在正确位置，不需要更新
                 }
-                replaceOrInsertElement(element, newChild, oldNode);
+
+                // 如果 newChild 是从缓存复用的（与 oldChild 不同），或者位置不对，需要调整
+                // 使用 oldNode 作为参考（如果存在），但目标位置基于数组顺序
+                const referenceNode = oldNode && oldNode.parentNode === element ? oldNode : null;
+                replaceOrInsertElementAtPosition(
+                    element,
+                    newChild,
+                    referenceNode,
+                    targetNextSibling
+                );
+
+                // 关键修复：在替换元素后，从 processedNodes 中移除旧的元素引用
+                // 这样可以防止旧的 span 元素内部的文本节点被误判为不应该移除
+                if (oldNode && oldNode !== newChild) {
+                    processedNodes.delete(oldNode);
+                }
+                // 标记新元素为已处理
+                processedNodes.add(newChild);
             } else {
                 // 类型变化：元素 -> 文本/Fragment
                 removeNodeIfNotPreserved(element, oldNode);
                 if (typeof newChild === "string" || typeof newChild === "number") {
                     const newTextNode = document.createTextNode(String(newChild));
                     element.insertBefore(newTextNode, oldNode?.nextSibling || null);
+                    // 关键修复：标记新创建的文本节点为已处理，防止在移除阶段被误删
+                    processedNodes.add(newTextNode);
                 } else if (newChild instanceof DocumentFragment) {
                     element.insertBefore(newChild, oldNode?.nextSibling || null);
                 }
@@ -386,7 +462,7 @@ export function updateChildren(
 
     // 添加新子节点
     for (let i = minLength; i < flatNew.length; i++) {
-        appendNewChild(element, flatNew[i]);
+        appendNewChild(element, flatNew[i], processedNodes);
     }
 
     // 移除多余子节点（使用纯函数简化逻辑）
@@ -397,10 +473,11 @@ export function updateChildren(
     deduplicateCacheKeys(element, cacheKeyMap);
 
     // 步骤 3: 收集需要移除的节点（跳过保留元素和新子元素）
-    const nodesToRemove = collectNodesToRemove(element, elementSet, cacheKeyMap);
+    const nodesToRemove = collectNodesToRemove(element, elementSet, cacheKeyMap, processedNodes);
 
     // 步骤 4: 批量移除节点（从后往前，避免索引变化）
-    removeNodes(element, nodesToRemove);
+    // 传递 cacheManager 以便在移除元素时调用 ref 回调
+    removeNodes(element, nodesToRemove, _cacheManager);
 
     // 步骤 5: 重新插入所有保留的元素到 DOM 末尾
     // 这确保了第三方库注入的元素不会丢失

package/src/utils/update-children-helpers.ts

@@ -81,7 +81,9 @@ export function findTextNode(
 ): Node | null {
     while (domIndex.value < parent.childNodes.length) {
         const node = parent.childNodes[domIndex.value];
-        if (node.nodeType === Node.TEXT_NODE) {
+        // 关键修复：只检查直接子文本节点，确保 node.parentNode === parent
+        // 这样可以防止将元素内部的文本节点（如 span 内部的文本节点）误判为独立的文本节点
+        if (node.nodeType === Node.TEXT_NODE && node.parentNode === parent) {
             const textNode = node;
             domIndex.value++;
             return textNode;
@@ -110,29 +112,47 @@ export function shouldUpdateTextNode(
 
 /**
  * 更新或创建文本节点
+ * @returns 更新后的文本节点（用于标记为已处理）
  */
 export function updateOrCreateTextNode(
     parent: HTMLElement | SVGElement,
     oldNode: Node | null,
     newText: string
-): void {
+): Node {
     if (oldNode && oldNode.nodeType === Node.TEXT_NODE) {
         // 只有当文本内容不同时才更新
         if (oldNode.textContent !== newText) {
             oldNode.textContent = newText;
         }
+        return oldNode;
     } else {
-        // Bug 2 修复：如果 oldNode 为 null，说明 findTextNode 没有找到对应的文本节点
-        // 此时不应该盲目更新第一个找到的文本节点，而应该创建新节点
-        // 因为：
-        // 1. 如果文本内容相同，调用方已经跳过了更新（在 element-update.ts 中）
-        // 2. 如果文本内容不同，应该创建新节点，而不是更新错误的节点
+        // RFC 0048 关键修复：如果 oldNode 为 null，先检查是否已经存在相同内容的直接子文本节点
+        // 这样可以防止重复创建文本节点
+        // 只检查直接子文本节点，不检查元素内部的文本节点
+        if (!oldNode) {
+            for (let i = 0; i < parent.childNodes.length; i++) {
+                const node = parent.childNodes[i];
+                // 关键修复：只检查直接子文本节点，确保 node.parentNode === parent
+                // 这样可以防止将元素内部的文本节点（如 span 内部的文本节点）误判为独立的文本节点
+                if (
+                    node.nodeType === Node.TEXT_NODE &&
+                    node.parentNode === parent &&
+                    node.textContent === newText
+                ) {
+                    // 找到相同内容的直接子文本节点，返回它而不是创建新节点
+                    return node;
+                }
+            }
+        }
+
+        // 如果没有找到相同内容的文本节点，创建新节点
         const newTextNode = document.createTextNode(newText);
         if (oldNode && !shouldPreserveElement(oldNode)) {
             parent.replaceChild(newTextNode, oldNode);
         } else {
             parent.insertBefore(newTextNode, oldNode || null);
         }
+        return newTextNode;
     }
 }
 
@@ -155,38 +175,134 @@ export function replaceOrInsertElement(
     parent: HTMLElement | SVGElement,
     newChild: HTMLElement | SVGElement,
     oldNode: Node | null
+): void {
+    // 确定目标位置：
+    // - 如果 oldNode 是保留元素，应该在 oldNode 之前插入（targetNextSibling = oldNode）
+    // - 否则，应该在 oldNode 的位置（oldNode.nextSibling 之前）
+    const targetNextSibling =
+        oldNode && shouldPreserveElement(oldNode) ? oldNode : oldNode?.nextSibling || null;
+    replaceOrInsertElementAtPosition(parent, newChild, oldNode, targetNextSibling);
+}
+
+/**
+ * 替换或插入元素节点到指定位置
+ * 确保元素在正确的位置，保持 DOM 顺序
+ */
+export function replaceOrInsertElementAtPosition(
+    parent: HTMLElement | SVGElement,
+    newChild: HTMLElement | SVGElement,
+    oldNode: Node | null,
+    targetNextSibling: Node | null
 ): void {
     // 如果新元素已经在其他父元素中，先移除
     if (newChild.parentNode && newChild.parentNode !== parent) {
         newChild.parentNode.removeChild(newChild);
     }
 
-    if (oldNode && !shouldPreserveElement(oldNode)) {
+    // 检查元素是否已经在正确位置
+    const isInCorrectPosition =
+        newChild.parentNode === parent && newChild.nextSibling === targetNextSibling;
+
+    if (isInCorrectPosition) {
+        // 已经在正确位置，不需要移动
+        return;
+    }
+
+    // 如果元素已经在 parent 中但位置不对，需要移动到正确位置
+    if (newChild.parentNode === parent) {
+        // insertBefore 会自动处理：如果元素已经在 DOM 中，会先移除再插入到新位置
+        parent.insertBefore(newChild, targetNextSibling);
+        return;
+    }
+
+    // 元素不在 parent 中，需要插入或替换
+    if (oldNode && oldNode.parentNode === parent && !shouldPreserveElement(oldNode)) {
         if (oldNode !== newChild) {
+            // 关键修复：在替换元素之前，标记旧元素内的所有文本节点为已处理
+            // 这样可以防止在移除阶段被误删
+            // 注意：这里只标记直接子文本节点，不递归处理嵌套元素内的文本节点
+            // 因为 replaceChild 会一起处理元素及其所有子节点
             parent.replaceChild(newChild, oldNode);
         }
-    } else if (newChild.parentNode !== parent) {
-        parent.insertBefore(newChild, oldNode || null);
+    } else {
+        // RFC 0048 关键修复：在插入元素之前，检查是否已经存在相同内容的元素
+        // 如果 newChild 已经在 parent 中，不应该再次插入
+        // 如果 parent 中已经存在相同标签名和内容的元素，也不应该插入
+        // 这样可以防止重复插入相同的元素（特别是从 HTML 字符串解析而来的元素）
+        if (newChild.parentNode === parent) {
+            // 元素已经在 parent 中，不需要再次插入
+            return;
+        }
+        // RFC 0048 关键修复：检查是否已经存在相同内容的元素
+        // 注意：这个检查只适用于从 HTML 字符串解析而来的元素（没有 __wsxCacheKey）
+        // 对于由 h() 创建的元素（有 __wsxCacheKey），应该通过引用匹配，而不是内容匹配
+        // 这样可以避免误判语言切换器等组件（它们由 h() 创建，每次渲染可能有相同内容但不同引用）
+        const newChildCacheKey = getElementCacheKey(newChild);
+        // 只有当 newChild 没有 cache key 时，才进行内容匹配检查
+        // 如果有 cache key，说明是由 h() 创建的，应该通过引用匹配（已经在 elementSet 中检查）
+        if (!newChildCacheKey) {
+            const newChildContent = newChild.textContent || "";
+            const newChildTag = newChild.tagName.toLowerCase();
+            // 检查 parent 中是否已经存在相同标签名和内容的元素（且也没有 cache key）
+            for (let i = 0; i < parent.childNodes.length; i++) {
+                const existingNode = parent.childNodes[i];
+                if (existingNode instanceof HTMLElement || existingNode instanceof SVGElement) {
+                    const existingCacheKey = getElementCacheKey(existingNode);
+                    // 只有当 existingNode 也没有 cache key 时，才进行内容匹配
+                    if (
+                        !existingCacheKey &&
+                        existingNode.tagName.toLowerCase() === newChildTag &&
+                        existingNode.textContent === newChildContent &&
+                        existingNode !== newChild
+                    ) {
+                        // 找到相同内容的元素（且都没有 cache key），不需要插入 newChild
+                        // 这是从 HTML 字符串解析而来的重复元素
+                        return;
+                    }
+                }
+            }
+        }
+        // 插入到目标位置
+        parent.insertBefore(newChild, targetNextSibling);
     }
 }
 
 /**
  * 添加新的子节点到末尾
  */
-export function appendNewChild(parent: HTMLElement | SVGElement, child: JSXChildren): void {
+export function appendNewChild(
+    parent: HTMLElement | SVGElement,
+    child: JSXChildren,
+    processedNodes?: Set<Node>
+): void {
     if (child === null || child === undefined || child === false) {
         return;
     }
 
     if (typeof child === "string" || typeof child === "number") {
-        parent.appendChild(document.createTextNode(String(child)));
+        const newTextNode = document.createTextNode(String(child));
+        parent.appendChild(newTextNode);
+        // 关键修复：标记新创建的文本节点为已处理，防止在移除阶段被误删
+        if (processedNodes) {
+            processedNodes.add(newTextNode);
+        }
     } else if (child instanceof HTMLElement || child instanceof SVGElement) {
+        // RFC 0048 关键修复：在插入元素之前，检查是否已经存在相同的元素
+        // 如果 child 已经在 parent 中，不应该再次插入
+        // 这样可以防止重复插入相同的元素（特别是从 HTML 字符串解析而来的元素）
+        if (child.parentNode === parent) {
+            // 元素已经在 parent 中，不需要再次插入
+            return;
+        }
         // 确保元素不在其他父元素中
         if (child.parentNode && child.parentNode !== parent) {
             child.parentNode.removeChild(child);
         }
-        if (child.parentNode !== parent) {
-            parent.appendChild(child);
+        // 插入到末尾
+        parent.appendChild(child);
+        // RFC 0048 关键修复：标记新添加的元素为已处理，防止在移除阶段被误删
+        if (processedNodes) {
+            processedNodes.add(child);
         }
     } else if (child instanceof DocumentFragment) {
         parent.appendChild(child);
@@ -228,13 +344,34 @@ export function buildNewChildrenMaps(flatNew: JSXChildren[]): {
 export function shouldRemoveNode(
     node: Node,
     elementSet: Set<HTMLElement | SVGElement | DocumentFragment>,
-    cacheKeyMap: Map<string, HTMLElement | SVGElement>
+    cacheKeyMap: Map<string, HTMLElement | SVGElement>,
+    processedNodes?: Set<Node>
 ): boolean {
     // 保留的元素不移除
     if (shouldPreserveElement(node)) {
         return false;
     }
 
+    // 关键修复：如果文本节点已被处理，不应该移除
+    if (node.nodeType === Node.TEXT_NODE && processedNodes && processedNodes.has(node)) {
+        return false;
+    }
+
+    // 关键修复：如果文本节点在已处理的元素内部，不应该移除
+    // 这样可以防止在元素被替换时，元素内部的文本节点被误删
+    // 但是，只有当父元素还在当前 parent 的子树中时才检查
+    if (node.nodeType === Node.TEXT_NODE && processedNodes) {
+        let parent = node.parentNode;
+        while (parent) {
+            // 关键修复：只有当父元素还在 DOM 中并且在当前 parent 的子树中时才检查
+            // 因为如果父元素被 replaceChild 移除了，它就不在 DOM 中了
+            if (processedNodes.has(parent) && parent.parentNode) {
+                return false; // 文本节点在已处理的元素内部，不应该移除
+            }
+            parent = parent.parentNode;
+        }
+    }
+
     // 检查是否在新子元素集合中（通过引用）
     if (
         node instanceof HTMLElement ||
@@ -283,6 +420,14 @@ export function deduplicateCacheKeys(
                 if (child !== newChild) {
                     parent.replaceChild(newChild, child);
                 }
+                // 如果 child === newChild，说明 newChild 已经在正确位置，不需要操作
+            } else if (cacheKey && cacheKeyMap.has(cacheKey) && processedCacheKeys.has(cacheKey)) {
+                // 如果 cache key 已经被处理过，说明有重复，应该移除这个旧元素
+                // 但是，只有当 child 不是 newChild 时才移除
+                const newChild = cacheKeyMap.get(cacheKey)!;
+                if (child !== newChild) {
+                    parent.removeChild(child);
+                }
             }
         }
     }
@@ -294,13 +439,14 @@ export function deduplicateCacheKeys(
 export function collectNodesToRemove(
     parent: HTMLElement | SVGElement,
     elementSet: Set<HTMLElement | SVGElement | DocumentFragment>,
-    cacheKeyMap: Map<string, HTMLElement | SVGElement>
+    cacheKeyMap: Map<string, HTMLElement | SVGElement>,
+    processedNodes?: Set<Node>
 ): Node[] {
     const nodesToRemove: Node[] = [];
 
     for (let i = 0; i < parent.childNodes.length; i++) {
         const node = parent.childNodes[i];
-        if (shouldRemoveNode(node, elementSet, cacheKeyMap)) {
+        if (shouldRemoveNode(node, elementSet, cacheKeyMap, processedNodes)) {
             nodesToRemove.push(node);
         }
     }
@@ -310,11 +456,31 @@ export function collectNodesToRemove(
 
 /**
  * 批量移除节点（从后往前，避免索引变化）
+ * @param parent - 父元素
+ * @param nodes - 要移除的节点列表
+ * @param cacheManager - 可选的缓存管理器，用于获取元素的 ref 回调
  */
-export function removeNodes(parent: HTMLElement | SVGElement, nodes: Node[]): void {
+export function removeNodes(
+    parent: HTMLElement | SVGElement,
+    nodes: Node[],
+    cacheManager?: { getMetadata: (element: Element) => Record<string, unknown> | undefined }
+): void {
     for (let i = nodes.length - 1; i >= 0; i--) {
         const node = nodes[i];
         if (node.parentNode === parent) {
+            // 关键修复：在移除元素之前，检查是否有 ref 回调，如果有，调用它并传入 null
+            // 这确保组件可以清理引用，避免使用已移除的元素
+            if (cacheManager && (node instanceof HTMLElement || node instanceof SVGElement)) {
+                const metadata = cacheManager.getMetadata(node);
+                const refCallback = metadata?.ref;
+                if (typeof refCallback === "function") {
+                    try {
+                        refCallback(null);
+                    } catch {
+                        // 忽略回调错误
+                    }
+                }
+            }
             parent.removeChild(node);
         }
     }