@wsxjs/wsx-core 0.0.27 → 0.0.28

package/src/utils/element-update.ts

@@ -16,8 +16,6 @@ import {
     findTextNode,
     updateOrCreateTextNode,
     removeNodeIfNotPreserved,
-    replaceOrInsertElement,
-    replaceOrInsertElementAtPosition,
     appendNewChild,
     buildNewChildrenMaps,
     deduplicateCacheKeys,
@@ -324,7 +322,8 @@ export function updateChildren(
 
     // 更新现有子节点
     const minLength = Math.min(flatOld.length, flatNew.length);
-    const domIndex = { value: 0 }; // 使用对象包装，使其可在函数间传递
+    const domIndex = { value: 0 }; // 搜索旧节点的索引
+    const insertionIndex = { value: 0 }; // 逻辑插入位置的索引
     // 跟踪已处理的节点，用于确定正确的位置
     const processedNodes = new Set<Node>();
 
@@ -347,86 +346,79 @@ export function updateChildren(
                 }
             }
         } else if (typeof oldChild === "string" || typeof oldChild === "number") {
-            oldNode = findTextNode(element, domIndex);
-            // 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];
-                    // 关键修复：只检查直接子文本节点，确保 node.parentNode === element
-                    // 并且必须验证文本内容是否匹配
-                    if (
-                        node.nodeType === Node.TEXT_NODE &&
-                        node.parentNode === element &&
-                        node.textContent === oldText
-                    ) {
-                        oldNode = node;
-                        // 更新 domIndex 到找到的文本节点之后
-                        domIndex.value = j + 1;
-                        break;
+            // RFC 0048 & RFC 0053 关键修复：如果 element 是保留元素（第三方组件），跳过文本节点查找
+            // 防止框架错误地管理第三方组件内部的文本节点
+            if (shouldPreserveElement(element)) {
+                // 对于保留元素，不查找文本节点，直接设置为 null
+                oldNode = null;
+            } else {
+                oldNode = findTextNode(element, domIndex, processedNodes);
+                if (oldNode) {
+                    const nodeIndex = Array.from(element.childNodes).indexOf(oldNode as ChildNode);
+                    if (nodeIndex !== -1 && nodeIndex >= domIndex.value) {
+                        domIndex.value = nodeIndex + 1;
                     }
                 }
+                // RFC 0048 & RFC 0053 关键修复：移除 fallback 内容匹配搜索
+                // ...
             }
         }
 
         // 处理文本节点（oldChild 是字符串/数字）
         if (typeof oldChild === "string" || typeof oldChild === "number") {
             if (typeof newChild === "string" || typeof newChild === "number") {
-                const oldText = String(oldChild);
                 const newText = String(newChild);
 
-                // Bug 2 修复：只有当文本内容确实需要更新时才调用 updateOrCreateTextNode
-                // 如果 oldText === newText 且 oldNode 为 null，说明文本节点可能已经存在且内容正确
-                // 或者不需要创建，因此不应该调用 updateOrCreateTextNode
-                const needsUpdate =
-                    oldText !== newText ||
-                    (oldNode &&
-                        oldNode.nodeType === Node.TEXT_NODE &&
-                        oldNode.textContent !== newText);
-
-                if (needsUpdate) {
-                    // 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);
-                    } else if (!oldNode && oldText === newText) {
-                        // 关键修复：如果 oldNode 为 null 但 oldText === newText，
-                        // 说明 DOM 中可能已经存在一个匹配的文本节点，只是没有被 findTextNode 找到
-                        // 我们需要查找并标记它，避免在清理阶段被误删
-                        // 这种情况可能发生在文本节点和元素节点混合排列时，domIndex 位置不准确
-                        // 从 domIndex.value 开始搜索，因为这是 findTextNode 停止的位置
-                        // 这样可以更准确地找到对应的文本节点
-                        for (let j = domIndex.value; j < element.childNodes.length; j++) {
-                            const node = element.childNodes[j];
-                            if (
-                                node.nodeType === Node.TEXT_NODE &&
-                                node.parentNode === element &&
-                                node.textContent === newText &&
-                                !processedNodes.has(node)
-                            ) {
-                                // 找到匹配的文本节点，标记为已处理
-                                processedNodes.add(node);
-                                break; // 只标记第一个匹配的节点
-                            }
-                        }
-                    }
+                // RFC 0048 & RFC 0053 关键修复：在调用 updateOrCreateTextNode 之前，检查 element 是否是保留元素
+                if (shouldPreserveElement(element)) {
+                    // 跳过保留元素的文本节点处理
+                    continue;
+                }
+
+                // 计算插入位置
+                const insertBeforeNode =
+                    insertionIndex.value < element.childNodes.length
+                        ? element.childNodes[insertionIndex.value]
+                        : null;
+
+                const updatedNode = updateOrCreateTextNode(
+                    element,
+                    oldNode,
+                    newText,
+                    insertBeforeNode
+                );
+                if (updatedNode) {
+                    processedNodes.add(updatedNode);
+                    // 无论是否复用旧节点，逻辑上我们都占据了一个位置
+                    insertionIndex.value++;
                 }
             } else {
                 // 类型变化：文本 -> 元素/Fragment
-                removeNodeIfNotPreserved(element, oldNode);
+                const targetNode =
+                    insertionIndex.value < element.childNodes.length
+                        ? element.childNodes[insertionIndex.value]
+                        : null;
+
                 if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
-                    replaceOrInsertElement(element, newChild, oldNode);
+                    // 如果 oldNode 就在当前位置，直接替换
+                    if (oldNode && oldNode === targetNode && oldNode.parentNode === element) {
+                        element.replaceChild(newChild, oldNode);
+                    } else {
+                        // 否则在目标位置插入，然后移除旧节点（如果需要）
+                        element.insertBefore(newChild, targetNode);
+                        removeNodeIfNotPreserved(element, oldNode);
+                    }
+                    processedNodes.add(newChild);
+                    insertionIndex.value++;
                 } else if (newChild instanceof DocumentFragment) {
-                    element.insertBefore(newChild, oldNode || null);
+                    // 关键修复：跟踪 Fragment 中的所有子节点
+                    if (processedNodes) {
+                        for (let i = 0; i < newChild.childNodes.length; i++) {
+                            processedNodes.add(newChild.childNodes[i]);
+                        }
+                    }
+                    element.insertBefore(newChild, targetNode);
+                    removeNodeIfNotPreserved(element, oldNode);
                 }
             }
         }
@@ -437,75 +429,56 @@ export function updateChildren(
             }
 
             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;
-                        }
+                // 计算目标插入位置 (insertBeforeNode)
+                const insertBeforeNode =
+                    insertionIndex.value < element.childNodes.length
+                        ? element.childNodes[insertionIndex.value]
+                        : null;
+
+                // 即使 newChild === oldNode，如果位置不对也需要移动
+                // 使用 insertBeforeNode 确保它在正确的位置
+                if (newChild === oldNode) {
+                    if (newChild.nextSibling !== insertBeforeNode) {
+                        element.insertBefore(newChild, insertBeforeNode);
                     }
+                } else {
+                    // RFC 0053 关键修复：直接使用 insertBefore 确保插入到正确位置
+                    // replaceOrInsertElement 会尝试基于 oldNode (此处为 insertBeforeNode) 的 nextSibling 插入，
+                    // 这对于旨在基于位置插入的场景会导致 Off-By-One 错误（插入到了后面）
+                    element.insertBefore(newChild, insertBeforeNode);
                 }
 
-                // 如果没有找到前一个元素，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; // 元素已经在正确位置，不需要更新
-                }
-
-                // 如果 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);
+                insertionIndex.value++;
             } else {
                 // 类型变化：元素 -> 文本/Fragment
-                removeNodeIfNotPreserved(element, oldNode);
+                const targetNode =
+                    insertionIndex.value < element.childNodes.length
+                        ? element.childNodes[insertionIndex.value]
+                        : null;
+
                 if (typeof newChild === "string" || typeof newChild === "number") {
                     const newTextNode = document.createTextNode(String(newChild));
-                    element.insertBefore(newTextNode, oldNode?.nextSibling || null);
-                    // 关键修复：标记新创建的文本节点为已处理，防止在移除阶段被误删
+                    (newTextNode as any).__wsxManaged = true; // 标记为框架管理
+                    // 优先替换或插入
+                    if (oldNode && oldNode === targetNode && oldNode.parentNode === element) {
+                        element.replaceChild(newTextNode, oldNode);
+                    } else {
+                        element.insertBefore(newTextNode, targetNode);
+                        removeNodeIfNotPreserved(element, oldNode);
+                    }
                     processedNodes.add(newTextNode);
+                    insertionIndex.value++;
                 } else if (newChild instanceof DocumentFragment) {
-                    element.insertBefore(newChild, oldNode?.nextSibling || null);
+                    // 关键修复：跟踪 Fragment 中的所有子节点，防止被误删
+                    if (processedNodes) {
+                        for (let i = 0; i < newChild.childNodes.length; i++) {
+                            processedNodes.add(newChild.childNodes[i]);
+                        }
+                    }
+                    element.insertBefore(newChild, targetNode);
+                    removeNodeIfNotPreserved(element, oldNode);
                 }
             }
         }

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

@@ -15,6 +15,14 @@ export function collectPreservedElements(element: HTMLElement | SVGElement): Nod
     const preserved: Node[] = [];
     for (let i = 0; i < element.childNodes.length; i++) {
         const child = element.childNodes[i];
+
+        // RFC 0048 & RFC 0053 关键修复：文本节点通常不应该被 collectPreservedElements 捕获
+        // 因为它们会通过 updateChildren 的主循环进行 reconcile
+        // 只有当父元素本身是保留元素时，文本节点才应该被保留（但在 updateChildren 中，这种情况会跳过处理）
+        if (child.nodeType === Node.TEXT_NODE) {
+            continue;
+        }
+
         if (shouldPreserveElement(child)) {
             preserved.push(child);
         }
@@ -77,20 +85,20 @@ export function findElementNode(
  */
 export function findTextNode(
     parent: HTMLElement | SVGElement,
-    domIndex: { value: number }
+    domIndex: { value: number },
+    processedNodes: Set<Node>
 ): Node | null {
-    while (domIndex.value < parent.childNodes.length) {
-        const node = parent.childNodes[domIndex.value];
-        // 关键修复：只检查直接子文本节点，确保 node.parentNode === parent
-        // 这样可以防止将元素内部的文本节点（如 span 内部的文本节点）误判为独立的文本节点
-        if (node.nodeType === Node.TEXT_NODE && node.parentNode === parent) {
-            const textNode = node;
-            domIndex.value++;
-            return textNode;
+    // RFC 0053: 从当前索引开始查找第一个未被处理的、框架管理的文本节点
+    for (let i = domIndex.value; i < parent.childNodes.length; i++) {
+        const node = parent.childNodes[i];
+        if (
+            node.nodeType === Node.TEXT_NODE &&
+            (node as any).__wsxManaged === true &&
+            !processedNodes.has(node)
+        ) {
+            domIndex.value = i + 1;
+            return node;
         }
-        // 跳过元素节点和其他类型的节点（它们会在自己的迭代中处理）
-        // 关键：必须递增 domIndex，否则会无限循环
-        domIndex.value++;
     }
     return null;
 }
@@ -117,45 +125,52 @@ export function shouldUpdateTextNode(
 export function updateOrCreateTextNode(
     parent: HTMLElement | SVGElement,
     oldNode: Node | null,
-    newText: string
+    newText: string,
+    insertBeforeNode?: Node | null
 ): Node {
+    // RFC 0048 & RFC 0053 关键修复：如果 parent 是保留元素（第三方组件），跳过处理
+    // 防止框架错误地管理第三方组件内部的文本节点
+    if (shouldPreserveElement(parent)) {
+        // 如果 parent 是保留元素，直接返回 oldNode（如果存在）或创建新节点但不插入
+        // 注意：这种情况下，文本节点应该由第三方组件自己管理
+        if (oldNode && oldNode.nodeType === Node.TEXT_NODE) {
+            return oldNode;
+        }
+        // 对于保留元素，我们不应该插入文本节点，但为了兼容性，返回一个虚拟节点
+        // 实际上，这种情况不应该发生，因为保留元素的子节点不应该被框架处理
+        return document.createTextNode(newText);
+    }
+
     if (oldNode && oldNode.nodeType === Node.TEXT_NODE) {
         // 只有当文本内容不同时才更新
         if (oldNode.textContent !== newText) {
             oldNode.textContent = newText;
         }
-        return oldNode;
-    } else {
-        // 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;
-                }
+        // RFC 0053 扩展：确保节点在正确的位置
+        // 如果指定了插入位置且当前节点不在该位置，则移动它
+        if (insertBeforeNode !== undefined) {
+            if (oldNode !== insertBeforeNode && oldNode.nextSibling !== insertBeforeNode) {
+                parent.insertBefore(oldNode, insertBeforeNode);
             }
         }
+        return oldNode;
+    } else {
+        // RFC 0048 & RFC 0053 关键修复：文本节点应该基于位置匹配，而不是内容匹配
+        // 当 oldNode 为 null 时，直接创建新节点，不进行内容匹配搜索
+        // 这防止了日历等场景中相同内容在不同位置被错误匹配的问题
+        // 例如：3 月的 "30" 在底部行，4 月的第一个日期是 "1"，不应该将 "30" 错误匹配到 "1" 的位置
+        // 如果 oldNode 为 null，说明在当前位置没有找到对应的文本节点，应该创建新节点
 
-        // 如果没有找到相同内容的文本节点，创建新节点
         const newTextNode = document.createTextNode(newText);
+        (newTextNode as any).__wsxManaged = true; // 标记为框架管理
         if (oldNode && !shouldPreserveElement(oldNode)) {
             parent.replaceChild(newTextNode, oldNode);
         } else {
-            parent.insertBefore(newTextNode, oldNode || null);
+            parent.insertBefore(newTextNode, insertBeforeNode ?? null);
         }
         return newTextNode;
     }
 }
-
 /**
  * 移除节点（如果不应该保留）
  */
@@ -281,6 +296,7 @@ export function appendNewChild(
 
     if (typeof child === "string" || typeof child === "number") {
         const newTextNode = document.createTextNode(String(child));
+        (newTextNode as any).__wsxManaged = true; // 标记为框架管理
         parent.appendChild(newTextNode);
         // 关键修复：标记新创建的文本节点为已处理，防止在移除阶段被误删
         if (processedNodes) {
@@ -305,6 +321,13 @@ export function appendNewChild(
             processedNodes.add(child);
         }
     } else if (child instanceof DocumentFragment) {
+        // 关键修复：记录 Fragment 中的所有子节点为已处理
+        // 否则它们会被后续的 collectNodesToRemove 误删
+        if (processedNodes) {
+            for (let i = 0; i < child.childNodes.length; i++) {
+                processedNodes.add(child.childNodes[i]);
+            }
+        }
         parent.appendChild(child);
     }
 }
@@ -347,32 +370,49 @@ export function shouldRemoveNode(
     cacheKeyMap: Map<string, HTMLElement | SVGElement>,
     processedNodes?: Set<Node>
 ): boolean {
-    // 保留的元素不移除
-    if (shouldPreserveElement(node)) {
-        return false;
+    // RFC 0048 & RFC 0053 关键修复：文本节点应该由框架管理，不应该被 shouldPreserveElement 保留
+    // 文本节点本身不是元素，shouldPreserveElement 对文本节点总是返回 true
+    // 但是，如果文本节点的父元素是由框架管理的，文本节点也应该由框架管理
+    // 只有当文本节点的父元素是保留元素时，文本节点才应该被保留
+    if (node.nodeType === Node.TEXT_NODE) {
+        // 如果是框架管理的文本节点
+        if ((node as any).__wsxManaged === true) {
+            // 如果已被处理过，保留
+            if (processedNodes && processedNodes.has(node)) {
+                return false;
+            }
+            // 否则移除
+            return true;
+        }
+
+        // 如果是非框架管理的文本节点（第三方注入）
+        // 检查其父元素是否被保留
+        const parent = node.parentNode;
+        if (parent && (parent instanceof HTMLElement || parent instanceof SVGElement)) {
+            if (shouldPreserveElement(parent)) {
+                // 如果父元素是保留元素，文本节点也应该被保留
+                return false;
+            }
+        }
+        // 对于未标记且父元素未保留的文本，默认移除以防止泄漏
+        return true;
+    } else {
+        // 对于元素节点，使用原有的逻辑
+        if (shouldPreserveElement(node)) {
+            return false;
+        }
     }
 
-    // 关键修复：如果文本节点已被处理，不应该移除
-    if (node.nodeType === Node.TEXT_NODE && processedNodes && processedNodes.has(node)) {
+    const isProcessed = processedNodes && processedNodes.has(node);
+
+    if (shouldPreserveElement(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.nodeType === Node.TEXT_NODE && isProcessed) {
+        return false;
     }
 
-    // 检查是否在新子元素集合中（通过引用）
     if (
         node instanceof HTMLElement ||
         node instanceof SVGElement ||
@@ -382,7 +422,6 @@ export function shouldRemoveNode(
             return false;
         }
 
-        // 检查是否通过 cache key 匹配
         if (node instanceof HTMLElement || node instanceof SVGElement) {
             const cacheKey = getElementCacheKey(node);
             if (cacheKey && cacheKeyMap.has(cacheKey)) {
@@ -446,7 +485,8 @@ export function collectNodesToRemove(
 
     for (let i = 0; i < parent.childNodes.length; i++) {
         const node = parent.childNodes[i];
-        if (shouldRemoveNode(node, elementSet, cacheKeyMap, processedNodes)) {
+        const removed = shouldRemoveNode(node, elementSet, cacheKeyMap, processedNodes);
+        if (removed) {
             nodesToRemove.push(node);
         }
     }

package/src/web-component.ts

@@ -225,9 +225,10 @@ export abstract class WebComponent extends BaseComponent {
                 this.shadowRoot.appendChild(content);
             }
 
-            // 移除旧内容（保留样式元素和未标记元素）
-            // 关键修复：使用 shouldPreserveElement() 来保护第三方库注入的元素
-            const oldChildren = Array.from(this.shadowRoot.children).filter((child) => {
+            // 移除旧内容（保留样式元素、未标记元素和新渲染的内容）
+            // 关键修复 (RFC-0042): 使用 childNodes 而不是 children，确保文本节点也被清理
+            // 否则，在 Shadow DOM 根部的文本节点会发生泄漏
+            const oldNodes = Array.from(this.shadowRoot.childNodes).filter((child) => {
                 // 保留新添加的内容（或已经在 shadowRoot 中的 content）
                 if (child === content) {
                     return false;
@@ -237,13 +238,13 @@ export abstract class WebComponent extends BaseComponent {
                     return false;
                 }
                 // 保留未标记的元素（第三方库注入的元素、自定义元素）
-                // 这是 RFC 0037 Phase 5 的核心：保护未标记元素
+                // 对于文本节点，shouldPreserveElement 逻辑已在 element-marking.ts 中优化
                 if (shouldPreserveElement(child)) {
                     return false;
                 }
                 return true;
             });
-            oldChildren.forEach((child) => child.remove());
+            oldNodes.forEach((node) => node.remove());
 
             // 7. 恢复 adopted stylesheets（在 DOM 操作之后，确保样式不被意外移除）
             // 关键修复：在 DOM 操作之后恢复样式，防止样式在 DOM 操作过程中被意外清空