@wsxjs/wsx-core 0.0.20 → 0.0.22

package/dist/index.js

@@ -37,6 +37,174 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/utils/dom-utils.ts
+function parseHTMLToNodes(html) {
+  if (!html) return [];
+  const temp = document.createElement("div");
+  temp.innerHTML = html;
+  return Array.from(temp.childNodes).map((node) => {
+    if (node instanceof HTMLElement || node instanceof SVGElement) {
+      return node;
+    } else {
+      return node.textContent || "";
+    }
+  });
+}
+function isHTMLString(str) {
+  const trimmed = str.trim();
+  if (!trimmed) return false;
+  const htmlTagPattern = /<[a-z][a-z0-9]*(\s[^>]*)?(\/>|>)/i;
+  const looksLikeMath = /^[^<]*<[^>]*>[^>]*$/.test(trimmed) && !htmlTagPattern.test(trimmed);
+  if (looksLikeMath) return false;
+  return htmlTagPattern.test(trimmed);
+}
+function flattenChildren(children, skipHTMLDetection = false, depth = 0) {
+  if (depth > 10) {
+    console.warn(
+      "[WSX] flattenChildren: Maximum depth exceeded, treating remaining children as text"
+    );
+    return children.filter(
+      (child) => typeof child === "string" || typeof child === "number"
+    );
+  }
+  const result = [];
+  for (const child of children) {
+    if (child === null || child === void 0 || child === false) {
+      continue;
+    } else if (Array.isArray(child)) {
+      result.push(...flattenChildren(child, skipHTMLDetection, depth + 1));
+    } else if (typeof child === "string") {
+      if (skipHTMLDetection) {
+        result.push(child);
+      } else if (isHTMLString(child)) {
+        try {
+          const nodes = parseHTMLToNodes(child);
+          if (nodes.length > 0) {
+            for (const node of nodes) {
+              if (typeof node === "string") {
+                result.push(node);
+              } else {
+                result.push(node);
+              }
+            }
+          } else {
+            result.push(child);
+          }
+        } catch (error) {
+          console.warn("[WSX] Failed to parse HTML string, treating as text:", error);
+          result.push(child);
+        }
+      } else {
+        result.push(child);
+      }
+    } else {
+      result.push(child);
+    }
+  }
+  return result;
+}
+
+// src/render-context.ts
+var _RenderContext = class _RenderContext {
+  /**
+   * Executes a function within the context of a component.
+   * @param component The component instance currently rendering.
+   * @param fn The function to execute (usually the render method).
+   */
+  static runInContext(component, fn) {
+    const prev = _RenderContext.current;
+    _RenderContext.current = component;
+    try {
+      return fn();
+    } finally {
+      _RenderContext.current = prev;
+    }
+  }
+  /**
+   * Gets the currently rendering component.
+   */
+  static getCurrentComponent() {
+    return _RenderContext.current;
+  }
+  /**
+   * Gets the current component's DOM cache.
+   */
+  static getDOMCache() {
+    return _RenderContext.current?.getDomCache();
+  }
+};
+_RenderContext.current = null;
+var RenderContext = _RenderContext;
+
+// src/utils/cache-key.ts
+var POSITION_ID_KEY = "__wsxPositionId";
+var INDEX_KEY = "__wsxIndex";
+var componentElementCounters = /* @__PURE__ */ new WeakMap();
+var componentIdCache = /* @__PURE__ */ new WeakMap();
+function generateCacheKey(tag, props, componentId, component) {
+  const positionId = props?.[POSITION_ID_KEY];
+  const userKey = props?.key;
+  const index = props?.[INDEX_KEY];
+  if (userKey !== void 0 && userKey !== null) {
+    return `${componentId}:${tag}:key-${String(userKey)}`;
+  }
+  if (index !== void 0 && index !== null) {
+    return `${componentId}:${tag}:idx-${String(index)}`;
+  }
+  if (positionId !== void 0 && positionId !== null && positionId !== "no-id") {
+    return `${componentId}:${tag}:${String(positionId)}`;
+  }
+  if (component) {
+    let counter = componentElementCounters.get(component) || 0;
+    counter++;
+    componentElementCounters.set(component, counter);
+    return `${componentId}:${tag}:auto-${counter}`;
+  }
+  return `${componentId}:${tag}:fallback-${Date.now()}-${Math.random()}`;
+}
+function getComponentId() {
+  const component = RenderContext.getCurrentComponent();
+  if (component) {
+    let cachedId = componentIdCache.get(component);
+    if (cachedId) {
+      return cachedId;
+    }
+    const instanceId = component._instanceId || "default";
+    cachedId = `${component.constructor.name}:${instanceId}`;
+    componentIdCache.set(component, cachedId);
+    return cachedId;
+  }
+  return "unknown";
+}
+
+// src/utils/element-marking.ts
+var CACHE_KEY_PROP = "__wsxCacheKey";
+function markElement(element, cacheKey) {
+  element[CACHE_KEY_PROP] = cacheKey;
+}
+function getElementCacheKey(element) {
+  const key = element[CACHE_KEY_PROP];
+  return key !== void 0 ? String(key) : null;
+}
+function isCreatedByH(element) {
+  if (!(element instanceof HTMLElement || element instanceof SVGElement)) {
+    return false;
+  }
+  return element[CACHE_KEY_PROP] !== void 0;
+}
+function shouldPreserveElement(element) {
+  if (!(element instanceof HTMLElement || element instanceof SVGElement)) {
+    return true;
+  }
+  if (!isCreatedByH(element)) {
+    return true;
+  }
+  if (element.hasAttribute("data-wsx-preserve")) {
+    return true;
+  }
+  return false;
+}
+
 // src/utils/svg-utils.ts
 var SVG_NAMESPACE = "http://www.w3.org/2000/svg";
 var SVG_ONLY_ELEMENTS = /* @__PURE__ */ new Set([
@@ -149,21 +317,63 @@ function getSVGAttributeName(attributeName) {
   return SVG_ATTRIBUTE_MAP.get(attributeName) || attributeName;
 }
 
-// src/utils/dom-utils.ts
-function parseHTMLToNodes(html) {
-  if (!html) return [];
-  const temp = document.createElement("div");
-  temp.innerHTML = html;
-  return Array.from(temp.childNodes).map((node) => {
-    if (node instanceof HTMLElement || node instanceof SVGElement) {
-      return node;
-    } else {
-      return node.textContent || "";
+// src/utils/logger.ts
+var WSXLogger = class {
+  constructor(prefix = "[WSX]", enabled = true, level = "info") {
+    this.prefix = prefix;
+    this.enabled = enabled;
+    this.level = level;
+  }
+  shouldLog(level) {
+    if (!this.enabled) return false;
+    const levels = ["debug", "info", "warn", "error"];
+    const currentLevelIndex = levels.indexOf(this.level);
+    const messageLevelIndex = levels.indexOf(level);
+    return messageLevelIndex >= currentLevelIndex;
+  }
+  debug(message, ...args) {
+    if (this.shouldLog("debug")) {
+      console.debug(`${this.prefix} ${message}`, ...args);
     }
-  });
+  }
+  info(message, ...args) {
+    if (this.shouldLog("info")) {
+      console.info(`${this.prefix} ${message}`, ...args);
+    }
+  }
+  warn(message, ...args) {
+    if (this.shouldLog("warn")) {
+      console.warn(`${this.prefix} ${message}`, ...args);
+    }
+  }
+  error(message, ...args) {
+    if (this.shouldLog("error")) {
+      console.error(`${this.prefix} ${message}`, ...args);
+    }
+  }
+};
+var logger = new WSXLogger();
+function createLogger(componentName) {
+  return new WSXLogger(`[WSX:${componentName}]`);
 }
 
-// src/jsx-factory.ts
+// src/utils/props-utils.ts
+var logger2 = createLogger("Props Utilities");
+function isFrameworkInternalProp(key) {
+  if (key === "key") {
+    return true;
+  }
+  if (key === "__wsxPositionId" || key === "__wsxIndex") {
+    return true;
+  }
+  if (key === "__testId") {
+    return true;
+  }
+  if (key === "ref") {
+    return true;
+  }
+  return false;
+}
 function isStandardHTMLAttribute(key) {
   const standardAttributes = /* @__PURE__ */ new Set([
     // 全局属性
@@ -246,7 +456,8 @@ function isStandardHTMLAttribute(key) {
 function isSpecialProperty(key, value) {
   return key === "ref" || key === "className" || key === "class" || key === "style" || key.startsWith("on") && typeof value === "function" || typeof value === "boolean" || key === "value";
 }
-function setSmartProperty(element, key, value, isSVG = false) {
+function setSmartProperty(element, key, value, tag) {
+  const isSVG = shouldUseSVGNamespace(tag);
   if (isSpecialProperty(key, value)) {
     return;
   }
@@ -256,13 +467,13 @@ function setSmartProperty(element, key, value, isSVG = false) {
       try {
         const serialized = JSON.stringify(value);
         if (serialized.length > 1024 * 1024) {
-          console.warn(
+          logger2.warn(
             `[WSX] Attribute "${key}" value too large, consider using a non-standard property name instead`
           );
         }
         element.setAttribute(attributeName, serialized);
       } catch (error) {
-        console.warn(`[WSX] Cannot serialize attribute "${key}":`, error);
+        logger2.warn(`Cannot serialize attribute "${key}":`, error);
       }
     } else {
       element.setAttribute(attributeName, String(value));
@@ -276,7 +487,7 @@ function setSmartProperty(element, key, value, isSVG = false) {
         const serialized = JSON.stringify(value);
         element.setAttribute(attributeName, serialized);
       } catch (error) {
-        console.warn(`[WSX] Cannot serialize SVG attribute "${key}":`, error);
+        logger2.warn(`Cannot serialize SVG attribute "${key}":`, error);
       }
     } else {
       element.setAttribute(attributeName, String(value));
@@ -300,7 +511,7 @@ function setSmartProperty(element, key, value, isSVG = false) {
           const serialized = JSON.stringify(value);
           element.setAttribute(attributeName, serialized);
         } catch (error) {
-          console.warn(`[WSX] Cannot serialize readonly property "${key}":`, error);
+          logger2.warn(`Cannot serialize readonly property "${key}":`, error);
         }
       } else {
         element.setAttribute(attributeName, String(value));
@@ -315,7 +526,7 @@ function setSmartProperty(element, key, value, isSVG = false) {
             const serialized = JSON.stringify(value);
             element.setAttribute(attributeName, serialized);
           } catch (error) {
-            console.warn(
+            logger2.warn(
               `[WSX] Cannot serialize property "${key}" for attribute:`,
               error
             );
@@ -331,59 +542,76 @@ function setSmartProperty(element, key, value, isSVG = false) {
       try {
         const serialized = JSON.stringify(value);
         if (serialized.length > 1024 * 1024) {
-          console.warn(
+          logger2.warn(
             `[WSX] Property "${key}" value too large for attribute, consider using a JavaScript property instead`
           );
         }
         element.setAttribute(attributeName, serialized);
       } catch (error) {
-        console.warn(`[WSX] Cannot serialize property "${key}" for attribute:`, error);
+        logger2.warn(`Cannot serialize property "${key}" for attribute:`, error);
       }
     } else {
       element.setAttribute(attributeName, String(value));
     }
   }
 }
-function h(tag, props = {}, ...children) {
-  if (typeof tag === "function") {
-    return tag(props, children);
+
+// src/utils/element-creation.ts
+function applySingleProp(element, key, value, tag, isSVG) {
+  if (value === null || value === void 0 || value === false) {
+    return;
   }
-  const element = createElement(tag);
-  if (props) {
-    const isSVG = shouldUseSVGNamespace(tag);
-    Object.entries(props).forEach(([key, value]) => {
-      if (value === null || value === void 0 || value === false) {
-        return;
-      }
-      if (key === "ref" && typeof value === "function") {
-        value(element);
-      } else if (key === "className" || key === "class") {
-        if (isSVG) {
-          element.setAttribute("class", value);
-        } else {
-          element.className = value;
-        }
-      } else if (key === "style" && typeof value === "string") {
-        element.setAttribute("style", value);
-      } else if (key.startsWith("on") && typeof value === "function") {
-        const eventName = key.slice(2).toLowerCase();
-        element.addEventListener(eventName, value);
-      } else if (typeof value === "boolean") {
-        if (value) {
-          element.setAttribute(key, "");
-        }
-      } else if (key === "value") {
-        if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) {
-          element.value = String(value);
-        } else {
-          const attributeName = isSVG ? getSVGAttributeName(key) : key;
-          element.setAttribute(attributeName, String(value));
-        }
-      } else {
-        setSmartProperty(element, key, value, isSVG);
-      }
-    });
+  if (key === "ref" && typeof value === "function") {
+    value(element);
+    return;
+  }
+  if (key === "className" || key === "class") {
+    if (isSVG) {
+      element.setAttribute("class", value);
+    } else {
+      element.className = value;
+    }
+    return;
   }
+  if (key === "style" && typeof value === "string") {
+    element.setAttribute("style", value);
+    return;
+  }
+  if (key.startsWith("on") && typeof value === "function") {
+    const eventName = key.slice(2).toLowerCase();
+    element.addEventListener(eventName, value);
+    return;
+  }
+  if (typeof value === "boolean") {
+    if (value) {
+      element.setAttribute(key, "");
+    }
+    return;
+  }
+  if (key === "value") {
+    if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) {
+      element.value = String(value);
+    } else {
+      const attributeName = isSVG ? getSVGAttributeName(key) : key;
+      element.setAttribute(attributeName, String(value));
+    }
+    return;
+  }
+  if (isFrameworkInternalProp(key)) {
+    return;
+  }
+  setSmartProperty(element, key, value, tag);
+}
+function applyPropsToElement(element, props, tag) {
+  if (!props) {
+    return;
+  }
+  const isSVG = shouldUseSVGNamespace(tag);
+  Object.entries(props).forEach(([key, value]) => {
+    applySingleProp(element, key, value, tag, isSVG);
+  });
+}
+function appendChildrenToElement(element, children) {
   const flatChildren = flattenChildren(children);
   flatChildren.forEach((child) => {
     if (child === null || child === void 0 || child === false) {
@@ -397,60 +625,458 @@ function h(tag, props = {}, ...children) {
       element.appendChild(child);
     }
   });
+}
+function createElementWithPropsAndChildren(tag, props, children) {
+  const element = createElement(tag);
+  applyPropsToElement(element, props, tag);
+  appendChildrenToElement(element, children);
   return element;
 }
-function isHTMLString(str) {
-  const trimmed = str.trim();
-  if (!trimmed) return false;
-  const htmlTagPattern = /<[a-z][a-z0-9]*(\s[^>]*)?(\/>|>)/i;
-  const looksLikeMath = /^[^<]*<[^>]*>[^>]*$/.test(trimmed) && !htmlTagPattern.test(trimmed);
-  if (looksLikeMath) return false;
-  return htmlTagPattern.test(trimmed);
+
+// src/utils/element-update.ts
+function removeProp(element, key, oldValue, tag) {
+  const isSVG = shouldUseSVGNamespace(tag);
+  if (key === "ref") {
+    return;
+  }
+  if (key === "className" || key === "class") {
+    if (isSVG) {
+      element.removeAttribute("class");
+    } else {
+      element.className = "";
+    }
+    return;
+  }
+  if (key === "style") {
+    element.removeAttribute("style");
+    return;
+  }
+  if (key.startsWith("on") && typeof oldValue === "function") {
+    return;
+  }
+  if (key === "value") {
+    if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) {
+      element.value = "";
+    } else {
+      const attributeName2 = isSVG ? getSVGAttributeName(key) : key;
+      element.removeAttribute(attributeName2);
+    }
+    return;
+  }
+  if (isFrameworkInternalProp(key)) {
+    return;
+  }
+  const attributeName = isSVG ? getSVGAttributeName(key) : key;
+  element.removeAttribute(attributeName);
+  try {
+    delete element[key];
+  } catch {
+  }
 }
-function flattenChildren(children, skipHTMLDetection = false, depth = 0) {
-  if (depth > 10) {
-    console.warn(
-      "[WSX] flattenChildren: Maximum depth exceeded, treating remaining children as text"
-    );
-    return children.filter(
-      (child) => typeof child === "string" || typeof child === "number"
-    );
+function applySingleProp2(element, key, value, tag, isSVG) {
+  if (value === null || value === void 0 || value === false) {
+    return;
   }
-  const result = [];
-  for (const child of children) {
-    if (child === null || child === void 0 || child === false) {
+  if (key === "ref" && typeof value === "function") {
+    value(element);
+    return;
+  }
+  if (key === "className" || key === "class") {
+    if (isSVG) {
+      element.setAttribute("class", value);
+    } else {
+      element.className = value;
+    }
+    return;
+  }
+  if (key === "style" && typeof value === "string") {
+    element.setAttribute("style", value);
+    return;
+  }
+  if (key.startsWith("on") && typeof value === "function") {
+    const eventName = key.slice(2).toLowerCase();
+    element.addEventListener(eventName, value);
+    return;
+  }
+  if (typeof value === "boolean") {
+    if (value) {
+      element.setAttribute(key, "");
+    }
+    return;
+  }
+  if (key === "value") {
+    if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) {
+      element.value = String(value);
+    } else {
+      const attributeName = isSVG ? getSVGAttributeName(key) : key;
+      element.setAttribute(attributeName, String(value));
+    }
+    return;
+  }
+  if (isFrameworkInternalProp(key)) {
+    return;
+  }
+  setSmartProperty(element, key, value, tag);
+}
+function updateProps(element, oldProps, newProps, tag) {
+  const isSVG = shouldUseSVGNamespace(tag);
+  const old = oldProps || {};
+  const new_ = newProps || {};
+  for (const key in old) {
+    if (!(key in new_)) {
+      removeProp(element, key, old[key], tag);
+    }
+  }
+  for (const key in new_) {
+    const oldValue = old[key];
+    const newValue = new_[key];
+    if (oldValue === newValue) {
       continue;
-    } else if (Array.isArray(child)) {
-      result.push(...flattenChildren(child, skipHTMLDetection, depth + 1));
-    } else if (typeof child === "string") {
-      if (skipHTMLDetection) {
-        result.push(child);
-      } else if (isHTMLString(child)) {
-        try {
-          const nodes = parseHTMLToNodes(child);
-          if (nodes.length > 0) {
-            for (const node of nodes) {
-              if (typeof node === "string") {
-                result.push(node);
+    }
+    if (oldValue === void 0) {
+      applySingleProp2(element, key, newValue, tag, isSVG);
+      continue;
+    }
+    if (typeof oldValue === "object" && oldValue !== null && typeof newValue === "object" && newValue !== null) {
+      try {
+        const oldJson = JSON.stringify(oldValue);
+        const newJson = JSON.stringify(newValue);
+        if (oldJson === newJson) {
+          continue;
+        }
+      } catch {
+      }
+    }
+    applySingleProp2(element, key, newValue, tag, isSVG);
+  }
+}
+function updateChildren(element, oldChildren, newChildren) {
+  const flatOld = flattenChildren(oldChildren);
+  const flatNew = flattenChildren(newChildren);
+  const minLength = Math.min(flatOld.length, flatNew.length);
+  let domIndex = 0;
+  for (let i = 0; i < minLength; i++) {
+    const oldChild = flatOld[i];
+    const newChild = flatNew[i];
+    let oldNode = null;
+    if (oldChild instanceof HTMLElement || oldChild instanceof SVGElement) {
+      if (oldChild.parentNode === element) {
+        if (!shouldPreserveElement(oldChild)) {
+          oldNode = oldChild;
+        }
+      } else {
+        const oldCacheKey = getElementCacheKey(oldChild);
+        if (oldCacheKey) {
+          for (let j = 0; j < element.childNodes.length; j++) {
+            const domChild = element.childNodes[j];
+            if (domChild instanceof HTMLElement || domChild instanceof SVGElement) {
+              if (shouldPreserveElement(domChild)) {
+                continue;
+              }
+              const domCacheKey = getElementCacheKey(domChild);
+              if (domCacheKey === oldCacheKey) {
+                oldNode = domChild;
+                break;
+              }
+            }
+          }
+        }
+      }
+    } else if (typeof oldChild === "string" || typeof oldChild === "number") {
+      while (domIndex < element.childNodes.length) {
+        const node = element.childNodes[domIndex];
+        if (node.nodeType === Node.TEXT_NODE) {
+          oldNode = node;
+          domIndex++;
+          break;
+        } else if (node.nodeType === Node.ELEMENT_NODE) {
+          domIndex++;
+        } else {
+          domIndex++;
+        }
+      }
+    }
+    if (typeof oldChild === "string" || typeof oldChild === "number") {
+      if (typeof newChild === "string" || typeof newChild === "number") {
+        const oldText = String(oldChild);
+        const newText = String(newChild);
+        const needsUpdate = oldText !== newText || oldNode && oldNode.nodeType === Node.TEXT_NODE && oldNode.textContent !== newText;
+        if (!needsUpdate) {
+          continue;
+        }
+        if (oldNode && oldNode.nodeType === Node.TEXT_NODE) {
+          oldNode.textContent = newText;
+        } else {
+          const newTextNode = document.createTextNode(newText);
+          if (oldNode && !shouldPreserveElement(oldNode)) {
+            element.replaceChild(newTextNode, oldNode);
+          } else {
+            element.insertBefore(newTextNode, oldNode || null);
+          }
+        }
+      } else {
+        if (oldNode && !shouldPreserveElement(oldNode)) {
+          element.removeChild(oldNode);
+        }
+        if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
+          if (newChild.parentNode !== element) {
+            element.insertBefore(newChild, oldNode || null);
+          }
+        } else if (newChild instanceof DocumentFragment) {
+          element.insertBefore(newChild, oldNode || null);
+        }
+      }
+    } else if (oldChild instanceof HTMLElement || oldChild instanceof SVGElement) {
+      if (oldNode && shouldPreserveElement(oldNode)) {
+        continue;
+      }
+      if (newChild === oldChild) {
+        continue;
+      } else if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
+        const oldCacheKey = oldNode && (oldNode instanceof HTMLElement || oldNode instanceof SVGElement) ? getElementCacheKey(oldNode) : null;
+        const newCacheKey = getElementCacheKey(newChild);
+        const hasSameCacheKey = oldCacheKey && newCacheKey && oldCacheKey === newCacheKey;
+        if (oldNode) {
+          if (!shouldPreserveElement(oldNode)) {
+            if (oldNode !== newChild) {
+              if (newChild.parentNode === element) {
+                if (hasSameCacheKey) {
+                  if (newChild !== oldNode) {
+                    element.replaceChild(newChild, oldNode);
+                  }
+                } else {
+                  element.removeChild(newChild);
+                  element.replaceChild(newChild, oldNode);
+                }
+              } else if (newChild.parentNode) {
+                newChild.parentNode.removeChild(newChild);
+                element.replaceChild(newChild, oldNode);
               } else {
-                result.push(node);
+                element.replaceChild(newChild, oldNode);
               }
             }
           } else {
-            result.push(child);
+            if (newChild.parentNode !== element) {
+              if (newChild.parentNode) {
+                newChild.parentNode.removeChild(newChild);
+              }
+              element.insertBefore(newChild, oldNode.nextSibling);
+            }
+          }
+        } else {
+          if (newChild.parentNode !== element) {
+            if (newChild.parentNode) {
+              newChild.parentNode.removeChild(newChild);
+            }
+            element.appendChild(newChild);
           }
-        } catch (error) {
-          console.warn("[WSX] Failed to parse HTML string, treating as text:", error);
-          result.push(child);
         }
       } else {
-        result.push(child);
+        if (oldNode && !shouldPreserveElement(oldNode)) {
+          element.removeChild(oldNode);
+        }
+        if (typeof newChild === "string" || typeof newChild === "number") {
+          const newTextNode = document.createTextNode(String(newChild));
+          element.insertBefore(newTextNode, oldNode?.nextSibling || null);
+        } else if (newChild instanceof DocumentFragment) {
+          element.insertBefore(newChild, oldNode?.nextSibling || null);
+        }
       }
-    } else {
-      result.push(child);
     }
   }
-  return result;
+  for (let i = minLength; i < flatNew.length; i++) {
+    const newChild = flatNew[i];
+    if (newChild === null || newChild === void 0 || newChild === false) {
+      continue;
+    }
+    if (typeof newChild === "string" || typeof newChild === "number") {
+      element.appendChild(document.createTextNode(String(newChild)));
+    } else if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
+      if (newChild.parentNode === element) {
+        const currentIndex = Array.from(element.childNodes).indexOf(newChild);
+        const expectedIndex = element.childNodes.length - 1;
+        if (currentIndex !== expectedIndex) {
+          element.removeChild(newChild);
+          element.appendChild(newChild);
+        }
+        continue;
+      } else if (newChild.parentNode) {
+        newChild.parentNode.removeChild(newChild);
+      }
+      element.appendChild(newChild);
+    } else if (newChild instanceof DocumentFragment) {
+      element.appendChild(newChild);
+    }
+  }
+  const nodesToRemove = [];
+  const newChildSet = /* @__PURE__ */ new Set();
+  const newChildCacheKeyMap = /* @__PURE__ */ new Map();
+  for (const child of flatNew) {
+    if (child instanceof HTMLElement || child instanceof SVGElement || child instanceof DocumentFragment) {
+      newChildSet.add(child);
+      if (child instanceof HTMLElement || child instanceof SVGElement) {
+        const cacheKey = getElementCacheKey(child);
+        if (cacheKey) {
+          newChildCacheKeyMap.set(cacheKey, child);
+        }
+      }
+    }
+  }
+  const processedCacheKeys = /* @__PURE__ */ new Set();
+  const newChildToIndexMap = /* @__PURE__ */ new Map();
+  for (let i = 0; i < flatNew.length; i++) {
+    const child = flatNew[i];
+    if (child instanceof HTMLElement || child instanceof SVGElement) {
+      newChildToIndexMap.set(child, i);
+    }
+  }
+  for (let i = element.childNodes.length - 1; i >= 0; i--) {
+    const child = element.childNodes[i];
+    if (child instanceof HTMLElement || child instanceof SVGElement) {
+      if (shouldPreserveElement(child)) {
+        continue;
+      }
+      const cacheKey = getElementCacheKey(child);
+      if (cacheKey && newChildCacheKeyMap.has(cacheKey) && !processedCacheKeys.has(cacheKey)) {
+        processedCacheKeys.add(cacheKey);
+        const newChild = newChildCacheKeyMap.get(cacheKey);
+        if (child !== newChild) {
+          if (newChild.parentNode === element) {
+            element.replaceChild(newChild, child);
+          } else {
+            element.replaceChild(newChild, child);
+          }
+        } else {
+        }
+      }
+    }
+  }
+  for (let i = 0; i < element.childNodes.length; i++) {
+    const child = element.childNodes[i];
+    if (shouldPreserveElement(child)) {
+      continue;
+    }
+    if (child instanceof HTMLElement || child instanceof SVGElement) {
+      if (newChildSet.has(child)) {
+        continue;
+      }
+      const cacheKey = getElementCacheKey(child);
+      if (cacheKey && newChildCacheKeyMap.has(cacheKey)) {
+        continue;
+      }
+    } else if (child instanceof DocumentFragment) {
+      if (newChildSet.has(child)) {
+        continue;
+      }
+    }
+    nodesToRemove.push(child);
+  }
+  for (let i = nodesToRemove.length - 1; i >= 0; i--) {
+    const node = nodesToRemove[i];
+    if (node.parentNode === element) {
+      element.removeChild(node);
+    }
+  }
+}
+function updateElement(element, newProps, newChildren, tag, cacheManager) {
+  const oldMetadata = cacheManager.getMetadata(element);
+  const oldProps = oldMetadata?.props || null;
+  const oldChildren = oldMetadata?.children || [];
+  cacheManager.setMetadata(element, {
+    props: newProps || {},
+    children: newChildren
+  });
+  updateProps(element, oldProps, newProps, tag);
+  updateChildren(element, oldChildren, newChildren);
+}
+
+// src/jsx-factory.ts
+var logger3 = createLogger("JSX Factory");
+function h(tag, props = {}, ...children) {
+  if (typeof tag === "function") {
+    return tag(props, children);
+  }
+  const context = RenderContext.getCurrentComponent();
+  const cacheManager = context ? RenderContext.getDOMCache() : null;
+  if (context && cacheManager) {
+    return tryUseCacheOrCreate(tag, props, children, context, cacheManager);
+  }
+  try {
+    const nodeEnv = typeof globalThis.process !== "undefined" && // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    globalThis.process.env?.NODE_ENV;
+    if (nodeEnv === "development") {
+      if (!context) {
+        logger3.debug(
+          `h() called without render context. Tag: "${tag}", ComponentId: "${getComponentId()}"`,
+          {
+            tag,
+            props: props ? Object.keys(props) : [],
+            hasCacheManager: !!cacheManager
+          }
+        );
+      } else if (!cacheManager) {
+        logger3.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);
+  const componentId = getComponentId();
+  const cacheKey = generateCacheKey(tag, props, componentId, context || void 0);
+  markElement(element, cacheKey);
+  return element;
+}
+function tryUseCacheOrCreate(tag, props, children, context, cacheManager) {
+  try {
+    const componentId = getComponentId();
+    const cacheKey = generateCacheKey(tag, props, componentId, context);
+    const cachedElement = cacheManager.get(cacheKey);
+    if (cachedElement) {
+      const element2 = cachedElement;
+      updateElement(element2, props, children, tag, cacheManager);
+      const isCustomElement = tag.includes("-") && customElements.get(tag);
+      if (isCustomElement && element2.isConnected) {
+        const parent = element2.parentNode;
+        if (parent) {
+          parent.removeChild(element2);
+          parent.appendChild(element2);
+        }
+      }
+      return element2;
+    }
+    const element = createElementWithPropsAndChildren(tag, props, children);
+    cacheManager.set(cacheKey, element);
+    markElement(element, cacheKey);
+    cacheManager.setMetadata(element, {
+      props: props || {},
+      children
+    });
+    return element;
+  } catch (error) {
+    return handleCacheError(error, tag, props, children);
+  }
+}
+function handleCacheError(error, tag, props, children) {
+  try {
+    const nodeEnv = typeof globalThis.process !== "undefined" && // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    globalThis.process.env?.NODE_ENV;
+    if (nodeEnv === "development") {
+      logger3.warn("[WSX DOM Cache] Cache error, falling back to create new element:", error);
+    }
+  } catch {
+  }
+  const element = createElementWithPropsAndChildren(tag, props, children);
+  const context = RenderContext.getCurrentComponent();
+  const componentId = getComponentId();
+  const cacheKey = generateCacheKey(tag, props, componentId, context || void 0);
+  markElement(element, cacheKey);
+  return element;
 }
 function Fragment(_props, children) {
   const fragment = document.createDocumentFragment();
@@ -512,7 +1138,7 @@ StyleManager.styleSheets = /* @__PURE__ */ new Map();
 
 // src/utils/reactive.ts
 var import_wsx_logger = require("@wsxjs/wsx-logger");
-var logger = (0, import_wsx_logger.createLogger)("ReactiveSystem");
+var logger4 = (0, import_wsx_logger.createLogger)("ReactiveSystem");
 var UpdateScheduler = class {
   constructor() {
     this.pendingCallbacks = /* @__PURE__ */ new Set();
@@ -541,7 +1167,7 @@ var UpdateScheduler = class {
       try {
         callback();
       } catch (error) {
-        logger.error("[WSX Reactive] Error in callback:", error);
+        logger4.error("[WSX Reactive] Error in callback:", error);
       }
     });
   }
@@ -683,7 +1309,7 @@ var ReactiveDebug = {
    */
   log(message, ...args) {
     if (this.isEnabled()) {
-      logger.info(`[WSX Reactive] ${message}`, ...args);
+      logger4.info(`[WSX Reactive] ${message}`, ...args);
     }
   }
 };
@@ -731,6 +1357,108 @@ function reactiveWithDebug(obj, onChange, debugName) {
   });
 }
 
+// src/dom-cache-manager.ts
+var logger5 = createLogger("DOMCacheManager");
+var DOMCacheManager = class {
+  constructor() {
+    // Map<CacheKey, DOMElement>
+    this.cache = /* @__PURE__ */ new Map();
+    // Map<DOMElement, Metadata>
+    // Stores metadata (props, children) for cached elements to support diffing
+    this.metadata = /* @__PURE__ */ new WeakMap();
+    // Track key-parent relationships to detect duplicate keys in all environments
+    // Map<CacheKey, ParentInfo>
+    this.keyParentMap = /* @__PURE__ */ new Map();
+    // Flag to enable duplicate key warnings (enabled by default, critical for correctness)
+    this.warnDuplicateKeys = true;
+  }
+  /**
+   * Retrieves an element from the cache.
+   * @param key The unique cache key.
+   */
+  get(key) {
+    return this.cache.get(key);
+  }
+  /**
+   * Stores an element in the cache.
+   * @param key The unique cache key.
+   * @param element The DOM element to cache.
+   */
+  set(key, element) {
+    if (this.warnDuplicateKeys) {
+      this.checkDuplicateKey(key, element);
+    }
+    this.cache.set(key, element);
+  }
+  /**
+   * Checks if a cache key is being reused in a different parent container.
+   * Runs in all environments to help developers catch key conflicts early.
+   * This is critical for correctness and helps prevent subtle bugs.
+   */
+  checkDuplicateKey(key, element) {
+    const existing = this.keyParentMap.get(key);
+    const currentParent = element.parentElement;
+    if (existing && currentParent) {
+      const currentParentInfo = this.getParentInfo(currentParent);
+      const existingParentInfo = `${existing.parentTag}${existing.parentClass ? "." + existing.parentClass : ""}`;
+      if (currentParentInfo !== existingParentInfo) {
+        logger5.warn(
+          `Duplicate key "${key}" detected in different parent containers!
+  Previous parent: ${existingParentInfo}
+  Current parent:  ${currentParentInfo}
+
+This may cause elements to appear in wrong containers or be moved unexpectedly.
+
+Solution: Use unique key prefixes for different locations:
+  Example: <wsx-link key="nav-0"> vs <wsx-link key="overflow-0">
+
+See https://wsxjs.dev/docs/guide/DOM_CACHE_GUIDE for best practices.`
+        );
+      }
+    }
+    if (currentParent) {
+      this.keyParentMap.set(key, {
+        parentTag: currentParent.tagName.toLowerCase(),
+        parentClass: currentParent.className,
+        element
+      });
+    }
+  }
+  /**
+   * Gets a formatted parent container description.
+   */
+  getParentInfo(parent) {
+    const tag = parent.tagName.toLowerCase();
+    const className = parent.className;
+    return `${tag}${className ? "." + className.split(" ")[0] : ""}`;
+  }
+  /**
+   * Checks if a key exists in the cache.
+   */
+  has(key) {
+    return this.cache.has(key);
+  }
+  /**
+   * Clears the cache.
+   * Should be called when component is disconnected or cache is invalidated.
+   */
+  clear() {
+    this.cache.clear();
+  }
+  /**
+   * Stores metadata for an element (e.g. previous props).
+   */
+  setMetadata(element, meta) {
+    this.metadata.set(element, meta);
+  }
+  /**
+   * Retrieves metadata for an element.
+   */
+  getMetadata(element) {
+    return this.metadata.get(element);
+  }
+};
+
 // src/base-component.ts
 var BaseComponent = class extends HTMLElement {
   constructor(config = {}) {
@@ -738,6 +1466,11 @@ var BaseComponent = class extends HTMLElement {
     this.connected = false;
     this._isDebugEnabled = false;
     this._reactiveStates = /* @__PURE__ */ new Map();
+    /**
+     * DOM Cache Manager for fine-grained updates (RFC 0037)
+     * @internal
+     */
+    this._domCache = new DOMCacheManager();
     /**
      * 当前捕获的焦点状态（用于在 render 时使用捕获的值）
      * @internal - 由 rerender() 方法管理
@@ -802,6 +1535,13 @@ var BaseComponent = class extends HTMLElement {
   static get observedAttributes() {
     return [];
   }
+  /**
+   * Gets the DOMCacheManager instance.
+   * @internal
+   */
+  getDomCache() {
+    return this._domCache;
+  }
   /**
    * Web Component生命周期：属性变化
    */
@@ -1109,7 +1849,7 @@ var BaseComponent = class extends HTMLElement {
 
 // src/web-component.ts
 var import_wsx_logger2 = require("@wsxjs/wsx-logger");
-var logger2 = (0, import_wsx_logger2.createLogger)("WebComponent");
+var logger6 = (0, import_wsx_logger2.createLogger)("WebComponent");
 var WebComponent = class extends BaseComponent {
   // Initialized by BaseComponent constructor
   constructor(config = {}) {
@@ -1147,7 +1887,7 @@ var WebComponent = class extends BaseComponent {
           const styleName = this.config.styleName || this.constructor.name;
           StyleManager.applyStyles(this.shadowRoot, styleName, stylesToApply);
         }
-        const content = this.render();
+        const content = RenderContext.runInContext(this, () => this.render());
         this.shadowRoot.appendChild(content);
       }
       this.initializeEventListeners();
@@ -1158,7 +1898,7 @@ var WebComponent = class extends BaseComponent {
         });
       }
     } catch (error) {
-      logger2.error(`Error in connectedCallback:`, error);
+      logger6.error(`Error in connectedCallback:`, error);
       this.renderError(error);
     }
   }
@@ -1211,7 +1951,7 @@ var WebComponent = class extends BaseComponent {
           StyleManager.applyStyles(this.shadowRoot, styleName, stylesToApply);
         }
       }
-      const content = this.render();
+      const content = RenderContext.runInContext(this, () => this.render());
       if (focusState && focusState.key && focusState.value !== void 0) {
         const target = content.querySelector(
           `[data-wsx-key="${focusState.key}"]`
@@ -1227,9 +1967,18 @@ var WebComponent = class extends BaseComponent {
       }
       requestAnimationFrame(() => {
         this.shadowRoot.appendChild(content);
-        const oldChildren = Array.from(this.shadowRoot.children).filter(
-          (child) => child !== content
-        );
+        const oldChildren = Array.from(this.shadowRoot.children).filter((child) => {
+          if (child === content) {
+            return false;
+          }
+          if (child instanceof HTMLStyleElement) {
+            return false;
+          }
+          if (shouldPreserveElement(child)) {
+            return false;
+          }
+          return true;
+        });
         oldChildren.forEach((child) => child.remove());
         requestAnimationFrame(() => {
           this.restoreFocusState(focusState);
@@ -1239,7 +1988,7 @@ var WebComponent = class extends BaseComponent {
         });
       });
     } catch (error) {
-      logger2.error("Error in _rerender:", error);
+      logger6.error("Error in _rerender:", error);
       this.renderError(error);
       this._isRendering = false;
     }
@@ -1267,7 +2016,7 @@ var WebComponent = class extends BaseComponent {
 
 // src/light-component.ts
 var import_wsx_logger3 = require("@wsxjs/wsx-logger");
-var logger3 = (0, import_wsx_logger3.createLogger)("LightComponent");
+var logger7 = (0, import_wsx_logger3.createLogger)("LightComponent");
 var LightComponent = class extends BaseComponent {
   // Initialized by BaseComponent constructor
   constructor(config = {}) {
@@ -1309,7 +2058,7 @@ var LightComponent = class extends BaseComponent {
           (child) => child !== styleElement
         );
         childrenToRemove.forEach((child) => child.remove());
-        const content = this.render();
+        const content = RenderContext.runInContext(this, () => this.render());
         this.appendChild(content);
         if (styleElement && styleElement !== this.firstChild) {
           this.insertBefore(styleElement, this.firstChild);
@@ -1323,7 +2072,7 @@ var LightComponent = class extends BaseComponent {
         });
       }
     } catch (error) {
-      logger3.error(`[${this.constructor.name}] Error in connectedCallback:`, error);
+      logger7.error(`[${this.constructor.name}] Error in connectedCallback:`, error);
       this.renderError(error);
     }
   }
@@ -1371,7 +2120,7 @@ var LightComponent = class extends BaseComponent {
     this._pendingFocusState = focusState;
     const jsxChildren = this.getJSXChildren();
     try {
-      const content = this.render();
+      const content = RenderContext.runInContext(this, () => this.render());
       if (focusState && focusState.key && focusState.value !== void 0) {
         const target = content.querySelector(
           `[data-wsx-key="${focusState.key}"]`
@@ -1409,6 +2158,9 @@ var LightComponent = class extends BaseComponent {
           if (child instanceof HTMLElement && jsxChildren.includes(child)) {
             return false;
           }
+          if (shouldPreserveElement(child)) {
+            return false;
+          }
           return true;
         });
         oldChildren.forEach((child) => child.remove());
@@ -1428,7 +2180,7 @@ var LightComponent = class extends BaseComponent {
         });
       });
     } catch (error) {
-      logger3.error(`[${this.constructor.name}] Error in _rerender:`, error);
+      logger7.error(`[${this.constructor.name}] Error in _rerender:`, error);
       this.renderError(error);
       this._isRendering = false;
     }
@@ -1550,6 +2302,10 @@ To fix this, please:
 See: https://github.com/wsxjs/wsxjs#setup for more details.`;
 }
 function state(targetOrContext, propertyKey) {
+  const globalProcess = typeof globalThis !== "undefined" ? globalThis.process : void 0;
+  if (globalProcess?.env?.NODE_ENV === "test") {
+    return;
+  }
   let propertyName = "unknown";
   const propertyKeyIsObject = typeof propertyKey === "object" && propertyKey !== null;
   const targetIsObject = typeof targetOrContext === "object" && targetOrContext !== null;