@wsxjs/wsx-core 0.0.19 → 0.0.21

package/dist/index.js

@@ -37,6 +37,170 @@ __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 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,62 +313,301 @@ 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
-function h(tag, props = {}, ...children) {
-  if (typeof tag === "function") {
-    return tag(props, children);
+// src/utils/props-utils.ts
+var logger2 = createLogger("Props Utilities");
+function isFrameworkInternalProp(key) {
+  if (key === "key") {
+    return true;
   }
-  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;
+  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([
+    // 全局属性
+    "id",
+    "class",
+    "className",
+    "style",
+    "title",
+    "lang",
+    "dir",
+    "hidden",
+    "tabindex",
+    "accesskey",
+    "contenteditable",
+    "draggable",
+    "spellcheck",
+    "translate",
+    "autocapitalize",
+    "autocorrect",
+    // 表单属性
+    "name",
+    "value",
+    "type",
+    "placeholder",
+    "required",
+    "disabled",
+    "readonly",
+    "checked",
+    "selected",
+    "multiple",
+    "min",
+    "max",
+    "step",
+    "autocomplete",
+    "autofocus",
+    "form",
+    "formaction",
+    "formenctype",
+    "formmethod",
+    "formnovalidate",
+    "formtarget",
+    // 链接属性
+    "href",
+    "target",
+    "rel",
+    "download",
+    "hreflang",
+    "ping",
+    // 媒体属性
+    "src",
+    "alt",
+    "width",
+    "height",
+    "poster",
+    "preload",
+    "controls",
+    "autoplay",
+    "loop",
+    "muted",
+    "playsinline",
+    "crossorigin",
+    // ARIA 属性（部分常见）
+    "role"
+  ]);
+  const lowerKey = key.toLowerCase();
+  if (standardAttributes.has(lowerKey)) {
+    return true;
+  }
+  if (lowerKey.startsWith("data-")) {
+    return true;
+  }
+  if (lowerKey.startsWith("aria-")) {
+    return true;
+  }
+  if (key.startsWith("xml:") || key.startsWith("xlink:")) {
+    return true;
+  }
+  return false;
+}
+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, tag) {
+  const isSVG = shouldUseSVGNamespace(tag);
+  if (isSpecialProperty(key, value)) {
+    return;
+  }
+  if (isStandardHTMLAttribute(key)) {
+    const attributeName = isSVG ? getSVGAttributeName(key) : key;
+    if (typeof value === "object" && value !== null) {
+      try {
+        const serialized = JSON.stringify(value);
+        if (serialized.length > 1024 * 1024) {
+          logger2.warn(
+            `[WSX] Attribute "${key}" value too large, consider using a non-standard property name instead`
+          );
         }
-      } 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, "");
+        element.setAttribute(attributeName, serialized);
+      } catch (error) {
+        logger2.warn(`Cannot serialize attribute "${key}":`, error);
+      }
+    } else {
+      element.setAttribute(attributeName, String(value));
+    }
+    return;
+  }
+  if (element instanceof SVGElement) {
+    const attributeName = getSVGAttributeName(key);
+    if (typeof value === "object" && value !== null) {
+      try {
+        const serialized = JSON.stringify(value);
+        element.setAttribute(attributeName, serialized);
+      } catch (error) {
+        logger2.warn(`Cannot serialize SVG attribute "${key}":`, error);
+      }
+    } else {
+      element.setAttribute(attributeName, String(value));
+    }
+    return;
+  }
+  const hasProperty = key in element || Object.prototype.hasOwnProperty.call(element, key);
+  if (hasProperty) {
+    let isReadOnly = false;
+    try {
+      const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(element), key);
+      if (descriptor) {
+        isReadOnly = descriptor.get !== void 0 && descriptor.set === void 0 || descriptor.writable === false && descriptor.set === void 0;
+      }
+    } catch {
+    }
+    if (isReadOnly) {
+      const attributeName = isSVG ? getSVGAttributeName(key) : key;
+      if (typeof value === "object" && value !== null) {
+        try {
+          const serialized = JSON.stringify(value);
+          element.setAttribute(attributeName, serialized);
+        } catch (error) {
+          logger2.warn(`Cannot serialize readonly property "${key}":`, error);
         }
-      } else if (key === "value") {
-        if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) {
-          element.value = String(value);
+      } else {
+        element.setAttribute(attributeName, String(value));
+      }
+    } else {
+      try {
+        element[key] = value;
+      } catch {
+        const attributeName = isSVG ? getSVGAttributeName(key) : key;
+        if (typeof value === "object" && value !== null) {
+          try {
+            const serialized = JSON.stringify(value);
+            element.setAttribute(attributeName, serialized);
+          } catch (error) {
+            logger2.warn(
+              `[WSX] Cannot serialize property "${key}" for attribute:`,
+              error
+            );
+          }
         } else {
-          const attributeName = isSVG ? getSVGAttributeName(key) : key;
           element.setAttribute(attributeName, String(value));
         }
-      } else {
-        const attributeName = isSVG ? getSVGAttributeName(key) : key;
-        element.setAttribute(attributeName, String(value));
       }
-    });
+    }
+  } else {
+    const attributeName = isSVG ? getSVGAttributeName(key) : key;
+    if (typeof value === "object" && value !== null) {
+      try {
+        const serialized = JSON.stringify(value);
+        if (serialized.length > 1024 * 1024) {
+          logger2.warn(
+            `[WSX] Property "${key}" value too large for attribute, consider using a JavaScript property instead`
+          );
+        }
+        element.setAttribute(attributeName, serialized);
+      } catch (error) {
+        logger2.warn(`Cannot serialize property "${key}" for attribute:`, error);
+      }
+    } else {
+      element.setAttribute(attributeName, String(value));
+    }
   }
+}
+
+// src/utils/element-creation.ts
+function applySingleProp(element, key, value, tag, isSVG) {
+  if (value === null || value === void 0 || value === false) {
+    return;
+  }
+  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) {
@@ -218,60 +621,278 @@ 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);
-              } else {
-                result.push(node);
-              }
+    }
+    if (typeof oldValue === "object" && oldValue !== null && typeof newValue === "object" && newValue !== null) {
+      if (JSON.stringify(oldValue) === JSON.stringify(newValue)) {
+        continue;
+      }
+    }
+    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);
+  for (let i = 0; i < minLength; i++) {
+    const oldChild = flatOld[i];
+    const newChild = flatNew[i];
+    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);
+          }
+        }
+      } 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);
+        } else if (newChild instanceof DocumentFragment) {
+          element.appendChild(newChild);
+        }
+      }
+    } 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 {
-            result.push(child);
+            if (newChild.parentNode !== element) {
+              element.appendChild(newChild);
+            }
+          }
+        } else {
+          if (newChild.parentNode !== element) {
+            element.appendChild(newChild);
           }
-        } catch (error) {
-          console.warn("[WSX] Failed to parse HTML string, treating as text:", error);
-          result.push(child);
         }
       } else {
-        result.push(child);
+        const oldNode = element.childNodes[i];
+        if (oldNode) {
+          if (!shouldPreserveElement(oldNode)) {
+            element.removeChild(oldNode);
+          }
+        }
+        if (typeof newChild === "string" || typeof newChild === "number") {
+          element.appendChild(document.createTextNode(String(newChild)));
+        } else if (newChild instanceof DocumentFragment) {
+          element.appendChild(newChild);
+        }
       }
-    } 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) {
+        element.appendChild(newChild);
+      }
+    } else if (newChild instanceof DocumentFragment) {
+      element.appendChild(newChild);
+    }
+  }
+  const nodesToRemove = [];
+  for (let i = flatNew.length; i < element.childNodes.length; i++) {
+    const child = element.childNodes[i];
+    if (!shouldPreserveElement(child)) {
+      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 || [];
+  updateProps(element, oldProps, newProps, tag);
+  updateChildren(element, oldChildren, newChildren);
+  cacheManager.setMetadata(element, {
+    props: newProps || {},
+    children: 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);
+  }
+  return createElementWithPropsAndChildren(tag, props, children);
+}
+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);
+      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 {
+  }
+  return createElementWithPropsAndChildren(tag, props, children);
 }
 function Fragment(_props, children) {
   const fragment = document.createDocumentFragment();
@@ -333,7 +954,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();
@@ -362,7 +983,7 @@ var UpdateScheduler = class {
       try {
         callback();
       } catch (error) {
-        logger.error("[WSX Reactive] Error in callback:", error);
+        logger4.error("[WSX Reactive] Error in callback:", error);
       }
     });
   }
@@ -504,7 +1125,7 @@ var ReactiveDebug = {
    */
   log(message, ...args) {
     if (this.isEnabled()) {
-      logger.info(`[WSX Reactive] ${message}`, ...args);
+      logger4.info(`[WSX Reactive] ${message}`, ...args);
     }
   }
 };
@@ -552,6 +1173,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 = {}) {
@@ -559,6 +1282,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() 方法管理
@@ -623,6 +1351,13 @@ var BaseComponent = class extends HTMLElement {
   static get observedAttributes() {
     return [];
   }
+  /**
+   * Gets the DOMCacheManager instance.
+   * @internal
+   */
+  getDomCache() {
+    return this._domCache;
+  }
   /**
    * Web Component生命周期：属性变化
    */
@@ -930,7 +1665,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 = {}) {
@@ -979,7 +1714,7 @@ var WebComponent = class extends BaseComponent {
         });
       }
     } catch (error) {
-      logger2.error(`Error in connectedCallback:`, error);
+      logger6.error(`Error in connectedCallback:`, error);
       this.renderError(error);
     }
   }
@@ -1032,7 +1767,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}"]`
@@ -1060,7 +1795,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;
     }
@@ -1088,7 +1823,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 = {}) {
@@ -1130,7 +1865,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);
@@ -1144,7 +1879,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);
     }
   }
@@ -1192,7 +1927,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}"]`
@@ -1249,7 +1984,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;
     }
@@ -1371,6 +2106,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;