@wsxjs/wsx-core 0.0.21 → 0.0.23

package/src/jsx-factory.ts

@@ -56,7 +56,44 @@ export function h(
     }
 
     // 无上下文：使用旧逻辑（向后兼容）
-    return createElementWithPropsAndChildren(tag, props, children);
+    // 关键修复：即使没有上下文，也要标记元素，以便框架能够正确管理它
+    // 否则，未标记的元素会被 shouldPreserveElement() 保留，导致重复元素
+    // 调试日志：记录上下文丢失的情况，帮助定位问题（仅在开发环境输出）
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const nodeEnv = (typeof (globalThis as any).process !== "undefined" &&
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (globalThis as any).process.env?.NODE_ENV) as string | undefined;
+        if (nodeEnv === "development") {
+            if (!context) {
+                logger.debug(
+                    `h() called without render context. Tag: "${tag}", ComponentId: "${getComponentId()}"`,
+                    {
+                        tag,
+                        props: props ? Object.keys(props) : [],
+                        hasCacheManager: !!cacheManager,
+                    }
+                );
+            } else if (!cacheManager) {
+                logger.debug(
+                    `h() called with context but no cache manager. Tag: "${tag}", Component: "${context.constructor.name}"`,
+                    {
+                        tag,
+                        component: context.constructor.name,
+                    }
+                );
+            }
+        }
+    } catch {
+        // 忽略环境变量检查错误
+    }
+
+    const element = createElementWithPropsAndChildren(tag, props, children);
+    // 生成一个简单的 cache key（即使没有上下文）
+    const componentId = getComponentId();
+    const cacheKey = generateCacheKey(tag, props, componentId, context || undefined);
+    markElement(element, cacheKey);
+    return element;
 }
 
 /**
@@ -79,7 +116,28 @@ function tryUseCacheOrCreate(
             // 缓存键已经确保了唯一性（componentId + tag + position/key/index）
             // 不需要再检查标签名（可能导致错误复用）
             const element = cachedElement as HTMLElement | SVGElement;
+
             updateElement(element, props, children, tag, cacheManager);
+
+            // 关键修复（RFC-0039）：检测自定义元素（Web Components）并重新触发生命周期
+            // 自定义元素有 connectedCallback 和 disconnectedCallback 方法
+            // 当它们被缓存复用时，需要模拟断开/重连以触发初始化逻辑
+            // 这确保了即使组件缺少 super.onConnected() 调用，框架层面也能保证正确的生命周期
+            const isCustomElement = tag.includes("-") && customElements.get(tag);
+            if (isCustomElement && element.isConnected) {
+                // 临时从 DOM 断开以触发 disconnectedCallback
+                const parent = element.parentNode;
+                if (parent) {
+                    parent.removeChild(element);
+                    // disconnectedCallback 会在 removeChild 时自动调用
+
+                    // 立即重新添加以触发 connectedCallback
+                    // 这确保生命周期在返回元素之前就已经完成
+                    parent.appendChild(element);
+                    // connectedCallback 会在 appendChild 时自动调用
+                }
+            }
+
             return element;
         }
 
@@ -120,7 +178,13 @@ function handleCacheError(
     } catch {
         // 忽略环境变量检查错误
     }
-    return createElementWithPropsAndChildren(tag, props, children);
+    // 关键修复：即使缓存失败，也要标记元素，以便框架能够正确管理它
+    const element = createElementWithPropsAndChildren(tag, props, children);
+    const context = RenderContext.getCurrentComponent();
+    const componentId = getComponentId();
+    const cacheKey = generateCacheKey(tag, props, componentId, context || undefined);
+    markElement(element, cacheKey);
+    return element;
 }
 
 /**

package/src/light-component.ts

@@ -10,6 +10,7 @@
 import { h, type JSXChildren } from "./jsx-factory";
 import { BaseComponent, type BaseComponentConfig } from "./base-component";
 import { RenderContext } from "./render-context";
+import { shouldPreserveElement } from "./utils/element-marking";
 import { createLogger } from "@wsxjs/wsx-logger";
 
 const logger = createLogger("LightComponent");
@@ -222,7 +223,8 @@ export abstract class LightComponent extends BaseComponent {
                 // 先添加新内容
                 this.appendChild(content);
 
-                // 移除旧内容（保留 JSX children 和样式元素）
+                // 移除旧内容（保留 JSX children、样式元素和未标记元素）
+                // 关键修复：使用 shouldPreserveElement() 来保护手动创建的元素（如第三方库注入的元素）
                 const oldChildren = Array.from(this.children).filter((child) => {
                     // 保留新添加的内容
                     if (child === content) {
@@ -236,10 +238,15 @@ export abstract class LightComponent extends BaseComponent {
                     ) {
                         return false;
                     }
-                    // 保留 JSX children（关键修复）
+                    // 保留 JSX children（通过 JSX factory 直接添加的 children）
                     if (child instanceof HTMLElement && jsxChildren.includes(child)) {
                         return false;
                     }
+                    // 保留未标记的元素（手动创建的元素、第三方库注入的元素）
+                    // 这是 RFC 0037 Phase 5 的核心：保护未标记元素
+                    if (shouldPreserveElement(child)) {
+                        return false;
+                    }
                     return true;
                 });
                 oldChildren.forEach((child) => child.remove());

package/src/utils/element-update.ts

@@ -6,10 +6,25 @@
  */
 
 import { shouldUseSVGNamespace, getSVGAttributeName } from "./svg-utils";
-import { flattenChildren, type JSXChildren } from "./dom-utils";
+import { type JSXChildren } from "./dom-utils";
 import { setSmartProperty, isFrameworkInternalProp } from "./props-utils";
 import { shouldPreserveElement } from "./element-marking";
 import type { DOMCacheManager } from "../dom-cache-manager";
+import {
+    collectPreservedElements,
+    findElementNode,
+    findTextNode,
+    updateOrCreateTextNode,
+    removeNodeIfNotPreserved,
+    replaceOrInsertElement,
+    appendNewChild,
+    buildNewChildrenMaps,
+    deduplicateCacheKeys,
+    collectNodesToRemove,
+    removeNodes,
+    reinsertPreservedElements,
+    flattenChildrenSafe,
+} from "./update-children-helpers";
 
 /**
  * Removes a property from an element.
@@ -189,16 +204,38 @@ export function updateProps(
             continue;
         }
 
-        // 深度比较：对于对象和数组，进行浅比较
+        // 如果 oldValue 是 undefined，说明是新增属性，需要设置
+        if (oldValue === undefined) {
+            applySingleProp(element, key, newValue, tag, isSVG);
+            continue;
+        }
+
+        // 深度比较：对于对象和数组，使用 JSON.stringify 进行深度比较
+        // 注意：JSON.stringify 会进行完整的深度比较，不仅仅是第一层
+        // 关键修复：即使 JSON.stringify 结果相同，如果引用不同，也应该更新
+        // 因为对象可能包含函数、Symbol 等无法序列化的内容，或者对象引用变化意味着需要更新
         if (
             typeof oldValue === "object" &&
             oldValue !== null &&
             typeof newValue === "object" &&
             newValue !== null
         ) {
-            // 浅比较：只比较第一层属性
-            if (JSON.stringify(oldValue) === JSON.stringify(newValue)) {
-                continue;
+            // 深度比较：使用 JSON.stringify 比较整个对象结构
+            // 这样可以检测到嵌套对象（如 navigation.items[].label）的变化
+            try {
+                const oldJson = JSON.stringify(oldValue);
+                const newJson = JSON.stringify(newValue);
+                if (oldJson === newJson) {
+                    // JSON 字符串相同，但引用不同
+                    // 对于自定义元素的属性（如 navigation），即使 JSON 相同，引用变化也可能需要更新
+                    // 因为 setter 可能会触发其他逻辑
+                    // 但是，为了性能，我们只在 JSON 不同时才更新
+                    // 如果 JSON 相同但引用不同，可能是同一个对象的不同引用，不需要更新
+                    continue;
+                }
+            } catch {
+                // 如果 JSON.stringify 失败（如循环引用），认为对象已变化
+                // 继续执行，更新属性
             }
         }
 
@@ -214,92 +251,134 @@ export function updateProps(
 export function updateChildren(
     element: HTMLElement | SVGElement,
     oldChildren: JSXChildren[],
-    newChildren: JSXChildren[]
+    newChildren: JSXChildren[],
+    cacheManager?: DOMCacheManager
 ): void {
-    const flatOld = flattenChildren(oldChildren);
-    const flatNew = flattenChildren(newChildren);
+    const flatOld = flattenChildrenSafe(oldChildren);
+    const flatNew = flattenChildrenSafe(newChildren);
 
-    // 阶段 4 简化版：只处理相同数量的子节点
-    const minLength = Math.min(flatOld.length, flatNew.length);
+    // 收集需要保留的元素（第三方库注入的元素）
+    const preservedElements = collectPreservedElements(element);
 
     // 更新现有子节点
+    const minLength = Math.min(flatOld.length, flatNew.length);
+    const domIndex = { value: 0 }; // 使用对象包装，使其可在函数间传递
+
     for (let i = 0; i < minLength; i++) {
         const oldChild = flatOld[i];
         const newChild = flatNew[i];
 
-        // 如果是文本节点，更新文本内容
+        // 查找对应的 DOM 节点
+        let oldNode: Node | null = null;
+        if (oldChild instanceof HTMLElement || oldChild instanceof SVGElement) {
+            oldNode = findElementNode(oldChild, element);
+            // 关键修复：当处理元素节点时，需要更新 domIndex 以跳过该元素
+            // 这样，下一个文本节点的查找位置才是正确的
+            if (oldNode && oldNode.parentNode === element) {
+                // 找到 oldNode 在 DOM 中的位置
+                const nodeIndex = Array.from(element.childNodes).indexOf(oldNode as ChildNode);
+                if (nodeIndex !== -1 && nodeIndex >= domIndex.value) {
+                    // 更新 domIndex 到 oldNode 之后的位置
+                    domIndex.value = nodeIndex + 1;
+                }
+            }
+        } else if (typeof oldChild === "string" || typeof oldChild === "number") {
+            oldNode = findTextNode(element, domIndex);
+            // 关键修复：如果 findTextNode 返回 null，尝试从当前 domIndex 位置开始查找文本节点
+            // 这可以处理文本节点存在但 domIndex 不正确的情况
+            // Bug 1 修复：从 domIndex.value 开始搜索，而不是从 0 开始，避免重新处理已处理的节点
+            if (!oldNode && element.childNodes.length > 0) {
+                for (let j = domIndex.value; j < element.childNodes.length; j++) {
+                    const node = element.childNodes[j];
+                    if (node.nodeType === Node.TEXT_NODE) {
+                        oldNode = node;
+                        // 更新 domIndex 到找到的文本节点之后
+                        domIndex.value = j + 1;
+                        break;
+                    }
+                }
+            }
+        }
+
+        // 处理文本节点（oldChild 是字符串/数字）
         if (typeof oldChild === "string" || typeof oldChild === "number") {
             if (typeof newChild === "string" || typeof newChild === "number") {
-                const textNode = element.childNodes[i];
-                if (textNode && textNode.nodeType === Node.TEXT_NODE) {
-                    textNode.textContent = String(newChild);
-                } else {
-                    // 替换为新的文本节点
-                    const newTextNode = document.createTextNode(String(newChild));
-                    if (textNode) {
-                        element.replaceChild(newTextNode, textNode);
-                    } else {
-                        element.appendChild(newTextNode);
-                    }
+                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) {
+                    updateOrCreateTextNode(element, oldNode, newText);
                 }
+                // 如果文本内容相同且 oldNode 为 null，不需要做任何操作
+                // 因为文本节点可能已经存在于 DOM 中且内容正确，或者不需要创建
             } else {
-                // 类型变化：替换节点
-                const textNode = element.childNodes[i];
-                if (textNode) {
-                    // 检查是否应该保留旧节点
-                    if (!shouldPreserveElement(textNode)) {
-                        element.removeChild(textNode);
-                    }
-                    // 如果应该保留，不删除（但可能仍需要添加新节点）
-                }
-                if (typeof newChild === "string" || typeof newChild === "number") {
-                    element.appendChild(document.createTextNode(String(newChild)));
-                } else if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
-                    element.appendChild(newChild);
+                // 类型变化：文本 -> 元素/Fragment
+                removeNodeIfNotPreserved(element, oldNode);
+                if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
+                    replaceOrInsertElement(element, newChild, oldNode);
                 } else if (newChild instanceof DocumentFragment) {
-                    element.appendChild(newChild);
+                    element.insertBefore(newChild, oldNode || null);
                 }
             }
-        } else if (oldChild instanceof HTMLElement || oldChild instanceof SVGElement) {
-            // 如果是元素节点，检查是否是同一个元素
-            if (newChild === oldChild) {
-                // 同一个元素，不需要更新
-                continue;
-            } else if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
-                // 不同的元素，替换
-                const oldNode = element.childNodes[i];
-                if (oldNode) {
-                    // 检查是否应该保留旧节点
-                    if (!shouldPreserveElement(oldNode)) {
-                        // 只有当新子元素不在当前位置时才替换
-                        if (oldNode !== newChild) {
-                            element.replaceChild(newChild, oldNode);
-                        }
-                    } else {
-                        // 应该保留旧节点，只添加新节点（不替换）
-                        if (newChild.parentNode !== element) {
-                            element.appendChild(newChild);
+        }
+        // 处理元素节点（oldChild 是元素）
+        else if (oldChild instanceof HTMLElement || oldChild instanceof SVGElement) {
+            if (oldNode && shouldPreserveElement(oldNode)) {
+                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;
                         }
                     }
                 } else {
-                    if (newChild.parentNode !== element) {
-                        element.appendChild(newChild);
+                    // 如果没有 cacheManager，假设 h() 已经更新了子元素
+                    if (oldNode === newChild && newChild.parentNode === element) {
+                        continue;
                     }
                 }
-            } else {
-                // 类型变化：替换节点
-                const oldNode = element.childNodes[i];
-                if (oldNode) {
-                    // 检查是否应该保留旧节点
-                    if (!shouldPreserveElement(oldNode)) {
-                        element.removeChild(oldNode);
-                    }
-                    // 如果应该保留，不删除（但可能仍需要添加新节点）
+                // 如果位置不对，需要调整
+            }
+
+            if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
+                // 如果 newChild 已经在 DOM 中且位置正确，不需要替换
+                if (newChild.parentNode === element && oldNode === newChild) {
+                    continue; // 元素已经在正确位置，不需要更新
                 }
+                replaceOrInsertElement(element, newChild, oldNode);
+            } else {
+                // 类型变化：元素 -> 文本/Fragment
+                removeNodeIfNotPreserved(element, oldNode);
                 if (typeof newChild === "string" || typeof newChild === "number") {
-                    element.appendChild(document.createTextNode(String(newChild)));
+                    const newTextNode = document.createTextNode(String(newChild));
+                    element.insertBefore(newTextNode, oldNode?.nextSibling || null);
                 } else if (newChild instanceof DocumentFragment) {
-                    element.appendChild(newChild);
+                    element.insertBefore(newChild, oldNode?.nextSibling || null);
                 }
             }
         }
@@ -307,44 +386,25 @@ export function updateChildren(
 
     // 添加新子节点
     for (let i = minLength; i < flatNew.length; i++) {
-        const newChild = flatNew[i];
-        if (newChild === null || newChild === undefined || newChild === false) {
-            continue;
-        }
-
-        if (typeof newChild === "string" || typeof newChild === "number") {
-            element.appendChild(document.createTextNode(String(newChild)));
-        } else if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
-            // 确保子元素正确添加到当前父容器
-            // appendChild 会自动从旧父容器移除并添加到新父容器
-            // 但我们需要确保不重复添加已存在的子元素
-            if (newChild.parentNode !== element) {
-                element.appendChild(newChild);
-            }
-        } else if (newChild instanceof DocumentFragment) {
-            element.appendChild(newChild);
-        }
+        appendNewChild(element, flatNew[i]);
     }
 
-    // 移除多余子节点（阶段 5：正确处理元素保留）
-    // 关键：需要跳过"应该保留"的元素（第三方库注入的元素）
-    const nodesToRemove: Node[] = [];
-    for (let i = flatNew.length; i < element.childNodes.length; i++) {
-        const child = element.childNodes[i];
-        if (!shouldPreserveElement(child)) {
-            // 只有不应该保留的节点才添加到移除列表
-            nodesToRemove.push(child);
-        }
-        // 如果应该保留，跳过（不添加到移除列表）
-    }
+    // 移除多余子节点（使用纯函数简化逻辑）
+    // 步骤 1: 构建新子元素的引用集合和 cache key 映射
+    const { elementSet, cacheKeyMap } = buildNewChildrenMaps(flatNew);
 
-    // 统一移除（从后往前移除，避免索引变化）
-    for (let i = nodesToRemove.length - 1; i >= 0; i--) {
-        const node = nodesToRemove[i];
-        if (node.parentNode === element) {
-            element.removeChild(node);
-        }
-    }
+    // 步骤 2: 处理重复的 cache key（确保每个 cache key 在 DOM 中只出现一次）
+    deduplicateCacheKeys(element, cacheKeyMap);
+
+    // 步骤 3: 收集需要移除的节点（跳过保留元素和新子元素）
+    const nodesToRemove = collectNodesToRemove(element, elementSet, cacheKeyMap);
+
+    // 步骤 4: 批量移除节点（从后往前，避免索引变化）
+    removeNodes(element, nodesToRemove);
+
+    // 步骤 5: 重新插入所有保留的元素到 DOM 末尾
+    // 这确保了第三方库注入的元素不会丢失
+    reinsertPreservedElements(element, preservedElements);
 }
 
 /**
@@ -363,15 +423,17 @@ export function updateElement(
     const oldProps = (oldMetadata?.props as Record<string, unknown>) || null;
     const oldChildren = (oldMetadata?.children as JSXChildren[]) || [];
 
-    // 更新 props
-    updateProps(element, oldProps, newProps, tag);
-
-    // 更新 children
-    updateChildren(element, oldChildren, newChildren);
-
-    // 保存新的元数据
+    // 关键修复：在更新 DOM 之前先保存新的元数据
+    // 这样可以防止竞态条件：如果在更新过程中触发了另一个渲染，
+    // 新渲染会读取到正确的元数据，而不是过时的数据
     cacheManager.setMetadata(element, {
         props: newProps || {},
         children: newChildren,
     });
+
+    // 更新 props
+    updateProps(element, oldProps, newProps, tag);
+
+    // 更新 children
+    updateChildren(element, oldChildren, newChildren, cacheManager);
 }