@wsxjs/wsx-core 0.0.8 → 0.0.10

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   Fragment,
   h
-} from "./chunk-VZQT7HU5.mjs";
+} from "./chunk-CZII6RG2.mjs";
 
 // src/styles/style-manager.ts
 var StyleManager = class {
@@ -113,35 +113,107 @@ var UpdateScheduler = class {
       try {
         callback();
       } catch (error) {
-        console.error("[WSX Reactive] Error in callback:", error);
+        logger2.error("[WSX Reactive] Error in callback:", error);
       }
     });
   }
 };
 var scheduler = new UpdateScheduler();
+var proxyCache = /* @__PURE__ */ new WeakMap();
+var originalCache = /* @__PURE__ */ new WeakMap();
+var unwrappingSet = /* @__PURE__ */ new WeakSet();
+function unwrapProxy(value) {
+  if (value == null || typeof value !== "object") {
+    return value;
+  }
+  let original = value;
+  if (originalCache.has(value)) {
+    original = originalCache.get(value);
+  }
+  if (unwrappingSet.has(original)) {
+    return null;
+  }
+  unwrappingSet.add(original);
+  try {
+    if (Array.isArray(original)) {
+      return original.map((item) => unwrapProxy(item));
+    }
+    const result = {};
+    for (const key in original) {
+      if (Object.prototype.hasOwnProperty.call(original, key)) {
+        const propValue = original[key];
+        if (propValue != null && typeof propValue === "object" && originalCache.has(propValue)) {
+          result[key] = unwrapProxy(originalCache.get(propValue));
+        } else {
+          result[key] = unwrapProxy(propValue);
+        }
+      }
+    }
+    return result;
+  } finally {
+    unwrappingSet.delete(original);
+  }
+}
+var ARRAY_MUTATION_METHODS = [
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "splice",
+  "sort",
+  "reverse"
+];
 function reactive(obj, onChange) {
-  return new Proxy(obj, {
+  if (proxyCache.has(obj)) {
+    return proxyCache.get(obj);
+  }
+  const isArray = Array.isArray(obj);
+  const proxy = new Proxy(obj, {
     set(target, key, value) {
       const oldValue = target[key];
-      if (oldValue !== value) {
-        target[key] = value;
+      const oldOriginal = originalCache.get(oldValue) || oldValue;
+      const newOriginal = value != null && typeof value === "object" ? originalCache.get(value) || value : value;
+      if (oldOriginal !== newOriginal) {
+        if (value != null && typeof value === "object") {
+          const reactiveValue = reactive(value, onChange);
+          target[key] = reactiveValue;
+        } else {
+          target[key] = value;
+        }
         scheduler.schedule(onChange);
       }
       return true;
     },
     get(target, key) {
-      return target[key];
+      if (key === "toJSON") {
+        return function() {
+          return unwrapProxy(obj);
+        };
+      }
+      const value = target[key];
+      if (isArray && typeof key === "string" && ARRAY_MUTATION_METHODS.includes(key)) {
+        return function(...args) {
+          const arrayMethod = Array.prototype[key];
+          const result = arrayMethod.apply(target, args);
+          scheduler.schedule(onChange);
+          return result;
+        };
+      }
+      if (value != null && typeof value === "object") {
+        if (proxyCache.has(value)) {
+          return proxyCache.get(value);
+        }
+        return reactive(value, onChange);
+      }
+      return value;
     },
     has(target, key) {
       return key in target;
-    },
-    ownKeys(target) {
-      return Reflect.ownKeys(target);
-    },
-    getOwnPropertyDescriptor(target, key) {
-      return Reflect.getOwnPropertyDescriptor(target, key);
     }
   });
+  proxyCache.set(obj, proxy);
+  originalCache.set(proxy, obj);
+  return proxy;
 }
 function createState(initialValue, onChange) {
   let currentValue = initialValue;
@@ -189,6 +261,7 @@ var ReactiveDebug = {
 };
 function reactiveWithDebug(obj, onChange, debugName) {
   const name = debugName || obj.constructor.name || "Unknown";
+  const isArray = Array.isArray(obj);
   return new Proxy(obj, {
     set(target, key, value) {
       const oldValue = target[key];
@@ -204,7 +277,28 @@ function reactiveWithDebug(obj, onChange, debugName) {
       return true;
     },
     get(target, key) {
-      return target[key];
+      if (key === "toJSON") {
+        return function() {
+          return unwrapProxy(obj);
+        };
+      }
+      const value = target[key];
+      if (isArray && typeof key === "string" && ARRAY_MUTATION_METHODS.includes(key)) {
+        return function(...args) {
+          ReactiveDebug.log(`Array mutation in ${name}:`, {
+            method: key,
+            args
+          });
+          const arrayMethod = Array.prototype[key];
+          const result = arrayMethod.apply(target, args);
+          scheduler.schedule(onChange);
+          return result;
+        };
+      }
+      if (value != null && typeof value === "object") {
+        return reactiveWithDebug(value, onChange, `${name}.${String(key)}`);
+      }
+      return value;
     }
   });
 }
@@ -216,6 +310,43 @@ var BaseComponent = class extends HTMLElement {
     this.connected = false;
     this._isDebugEnabled = false;
     this._reactiveStates = /* @__PURE__ */ new Map();
+    /**
+     * 当前捕获的焦点状态（用于在 render 时使用捕获的值）
+     * @internal - 由 rerender() 方法管理
+     */
+    this._pendingFocusState = null;
+    /**
+     * 防抖定时器，用于延迟重渲染（当用户正在输入时）
+     * @internal
+     */
+    this._rerenderDebounceTimer = null;
+    /**
+     * 待处理的重渲染标志（当用户正在输入时，标记需要重渲染但延迟执行）
+     * @internal
+     */
+    this._pendingRerender = false;
+    /**
+     * 处理 blur 事件，在用户停止输入时执行待处理的重渲染
+     * @internal
+     */
+    this.handleGlobalBlur = (event) => {
+      const root = this.getActiveRoot();
+      const target = event.target;
+      if (target && root.contains(target)) {
+        if (this._pendingRerender && this.connected) {
+          if (this._rerenderDebounceTimer !== null) {
+            clearTimeout(this._rerenderDebounceTimer);
+            this._rerenderDebounceTimer = null;
+          }
+          requestAnimationFrame(() => {
+            if (this._pendingRerender && this.connected) {
+              this._pendingRerender = false;
+              this.rerender();
+            }
+          });
+        }
+      }
+    };
     this._isDebugEnabled = config.debug ?? false;
     const host = this;
     const originalStyles = config.styles;
@@ -279,11 +410,65 @@ var BaseComponent = class extends HTMLElement {
   /**
    * 调度重渲染
    * 这个方法被响应式系统调用，开发者通常不需要直接调用
+   * 使用 queueMicrotask 进行异步调度，与 reactive() 系统保持一致
    */
   scheduleRerender() {
-    if (this.connected) {
-      this.rerender();
+    if (!this.connected) {
+      if (this._rerenderDebounceTimer !== null) {
+        clearTimeout(this._rerenderDebounceTimer);
+        this._rerenderDebounceTimer = null;
+      }
+      return;
+    }
+    const root = this.getActiveRoot();
+    let activeElement = null;
+    if (root instanceof ShadowRoot) {
+      activeElement = root.activeElement;
+    } else {
+      const docActiveElement = document.activeElement;
+      if (docActiveElement && root.contains(docActiveElement)) {
+        activeElement = docActiveElement;
+      }
+    }
+    if (activeElement) {
+      const isInputElement = activeElement instanceof HTMLInputElement || activeElement instanceof HTMLTextAreaElement || activeElement instanceof HTMLSelectElement || activeElement.hasAttribute("contenteditable");
+      const forceRender = activeElement.hasAttribute("data-wsx-force-render");
+      if (isInputElement && !forceRender) {
+        this._pendingRerender = true;
+        if (this._rerenderDebounceTimer !== null) {
+          clearTimeout(this._rerenderDebounceTimer);
+          this._rerenderDebounceTimer = null;
+        }
+        return;
+      }
+    }
+    if (this._pendingRerender) {
+      this._pendingRerender = false;
+    }
+    queueMicrotask(() => {
+      if (this.connected) {
+        this.rerender();
+      }
+    });
+  }
+  /**
+   * 清理资源（在组件断开连接时调用）
+   * @internal
+   */
+  cleanup() {
+    if (this._rerenderDebounceTimer !== null) {
+      clearTimeout(this._rerenderDebounceTimer);
+      this._rerenderDebounceTimer = null;
     }
+    document.removeEventListener("blur", this.handleGlobalBlur, true);
+    this._pendingRerender = false;
+  }
+  /**
+   * 初始化事件监听器（在组件连接时调用）
+   * @internal
+   */
+  initializeEventListeners() {
+    document.addEventListener("blur", this.handleGlobalBlur, true);
   }
   /**
    * 获取配置值
@@ -346,15 +531,136 @@ var BaseComponent = class extends HTMLElement {
   cleanupReactiveStates() {
     this._reactiveStates.clear();
   }
+  /**
+   * 获取当前活动的 DOM 根（Shadow DOM 或 Light DOM）
+   * @returns 活动的 DOM 根元素
+   */
+  getActiveRoot() {
+    if ("shadowRoot" in this && this.shadowRoot) {
+      return this.shadowRoot;
+    }
+    return this;
+  }
+  /**
+   * 捕获当前焦点状态（在重渲染之前调用）
+   * @returns 焦点状态，如果没有焦点元素则返回 null
+   */
+  captureFocusState() {
+    const root = this.getActiveRoot();
+    let activeElement = null;
+    if (root instanceof ShadowRoot) {
+      activeElement = root.activeElement;
+    } else {
+      const docActiveElement = document.activeElement;
+      if (docActiveElement && root.contains(docActiveElement)) {
+        activeElement = docActiveElement;
+      }
+    }
+    if (!activeElement || !(activeElement instanceof HTMLElement)) {
+      return null;
+    }
+    const key = activeElement.getAttribute("data-wsx-key");
+    if (!key) {
+      return null;
+    }
+    const tagName = activeElement.tagName.toLowerCase();
+    const state2 = {
+      key,
+      elementType: tagName
+    };
+    if (activeElement instanceof HTMLInputElement || activeElement instanceof HTMLTextAreaElement) {
+      state2.value = activeElement.value;
+      state2.selectionStart = activeElement.selectionStart ?? void 0;
+      state2.selectionEnd = activeElement.selectionEnd ?? void 0;
+      if (activeElement instanceof HTMLTextAreaElement) {
+        state2.scrollTop = activeElement.scrollTop;
+      }
+    } else if (activeElement instanceof HTMLSelectElement) {
+      state2.elementType = "select";
+      state2.selectedIndex = activeElement.selectedIndex;
+    } else if (activeElement.hasAttribute("contenteditable")) {
+      state2.elementType = "contenteditable";
+      const selection = window.getSelection();
+      if (selection && selection.rangeCount > 0) {
+        const range = selection.getRangeAt(0);
+        state2.selectionStart = range.startOffset;
+        state2.selectionEnd = range.endOffset;
+      }
+    }
+    return state2;
+  }
+  /**
+   * 恢复焦点状态（在重渲染之后调用）
+   * @param state - 之前捕获的焦点状态
+   */
+  restoreFocusState(state2) {
+    if (!state2 || !state2.key) {
+      return;
+    }
+    const root = this.getActiveRoot();
+    const target = root.querySelector(`[data-wsx-key="${state2.key}"]`);
+    if (!target) {
+      return;
+    }
+    if (state2.value !== void 0) {
+      if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+        target.value = state2.value;
+      }
+    }
+    if (state2.selectedIndex !== void 0 && target instanceof HTMLSelectElement) {
+      target.selectedIndex = state2.selectedIndex;
+    }
+    requestAnimationFrame(() => {
+      const currentTarget = root.querySelector(
+        `[data-wsx-key="${state2.key}"]`
+      );
+      if (!currentTarget) {
+        return;
+      }
+      if (state2.value !== void 0) {
+        if (currentTarget instanceof HTMLInputElement || currentTarget instanceof HTMLTextAreaElement) {
+          if (currentTarget.value !== state2.value) {
+            currentTarget.value = state2.value;
+          }
+        }
+      }
+      currentTarget.focus({ preventScroll: true });
+      if (state2.selectionStart !== void 0) {
+        if (currentTarget instanceof HTMLInputElement || currentTarget instanceof HTMLTextAreaElement) {
+          const start = state2.selectionStart;
+          const end = state2.selectionEnd ?? start;
+          currentTarget.setSelectionRange(start, end);
+          if (state2.scrollTop !== void 0 && currentTarget instanceof HTMLTextAreaElement) {
+            currentTarget.scrollTop = state2.scrollTop;
+          }
+        } else if (currentTarget.hasAttribute("contenteditable")) {
+          const selection = window.getSelection();
+          if (selection) {
+            const range = document.createRange();
+            const textNode = currentTarget.childNodes[0];
+            if (textNode && textNode.nodeType === Node.TEXT_NODE) {
+              const maxPos = Math.min(
+                state2.selectionStart,
+                textNode.textContent?.length || 0
+              );
+              range.setStart(textNode, maxPos);
+              range.setEnd(textNode, state2.selectionEnd ?? maxPos);
+              selection.removeAllRanges();
+              selection.addRange(range);
+            }
+          }
+        }
+      }
+    });
+  }
 };
 
 // src/web-component.ts
+var logger3 = createLogger("WebComponent");
 var WebComponent = class extends BaseComponent {
+  // Initialized by BaseComponent constructor
   constructor(config = {}) {
     super(config);
-    // Initialized by BaseComponent constructor
-    this._preserveFocus = true;
-    this._preserveFocus = config.preserveFocus ?? true;
     this.attachShadow({ mode: "open" });
   }
   /**
@@ -363,16 +669,17 @@ var WebComponent = class extends BaseComponent {
   connectedCallback() {
     this.connected = true;
     try {
-      const stylesToApply = this._getAutoStyles?.() || this.config.styles;
+      const stylesToApply = this._autoStyles || this.config.styles;
       if (stylesToApply) {
         const styleName = this.config.styleName || this.constructor.name;
         StyleManager.applyStyles(this.shadowRoot, styleName, stylesToApply);
       }
       const content = this.render();
       this.shadowRoot.appendChild(content);
+      this.initializeEventListeners();
       this.onConnected?.();
     } catch (error) {
-      console.error(`[${this.constructor.name}] Error in connectedCallback:`, error);
+      logger3.error(`Error in connectedCallback:`, error);
       this.renderError(error);
     }
   }
@@ -381,6 +688,7 @@ var WebComponent = class extends BaseComponent {
    */
   disconnectedCallback() {
     this.connected = false;
+    this.cleanup();
     this.onDisconnected?.();
   }
   /**
@@ -406,118 +714,48 @@ var WebComponent = class extends BaseComponent {
    */
   rerender() {
     if (!this.connected) {
-      console.warn(
-        `[${this.constructor.name}] Component is not connected, skipping rerender.`
-      );
+      logger3.warn("Component is not connected, skipping rerender.");
       return;
     }
-    let focusData = null;
-    if (this._preserveFocus && this.shadowRoot) {
-      const activeElement = this.shadowRoot.activeElement;
-      focusData = this.saveFocusState(activeElement);
-    }
+    const focusState = this.captureFocusState();
+    this._pendingFocusState = focusState;
     const adoptedStyleSheets = this.shadowRoot.adoptedStyleSheets || [];
-    this.shadowRoot.innerHTML = "";
-    if (this.shadowRoot.adoptedStyleSheets) {
-      this.shadowRoot.adoptedStyleSheets = adoptedStyleSheets;
-    }
-    if (adoptedStyleSheets.length === 0) {
-      const stylesToApply = this._autoStyles || this.config.styles;
-      if (stylesToApply) {
-        const styleName = this.config.styleName || this.constructor.name;
-        StyleManager.applyStyles(this.shadowRoot, styleName, stylesToApply);
-      }
-    }
     try {
-      const content = this.render();
-      this.shadowRoot.appendChild(content);
-    } catch (error) {
-      console.error(`[${this.constructor.name}] Error in rerender:`, error);
-      this.renderError(error);
-    }
-    if (this._preserveFocus && focusData && this.shadowRoot) {
-      this.restoreFocusState(focusData);
-    }
-  }
-  /**
-   * 保存焦点状态
-   */
-  saveFocusState(activeElement) {
-    if (!activeElement) {
-      return null;
-    }
-    const focusData = {
-      tagName: activeElement.tagName.toLowerCase(),
-      className: activeElement.className
-    };
-    if (activeElement.hasAttribute("contenteditable")) {
-      const selection = window.getSelection();
-      if (selection && selection.rangeCount > 0) {
-        const range = selection.getRangeAt(0);
-        focusData.selectionStart = range.startOffset;
-        focusData.selectionEnd = range.endOffset;
-      }
-    }
-    if (activeElement instanceof HTMLInputElement || activeElement instanceof HTMLSelectElement) {
-      focusData.value = activeElement.value;
-      if ("selectionStart" in activeElement) {
-        focusData.selectionStart = activeElement.selectionStart ?? void 0;
-        focusData.selectionEnd = activeElement.selectionEnd ?? void 0;
+      if (adoptedStyleSheets.length === 0) {
+        const stylesToApply = this._autoStyles || this.config.styles;
+        if (stylesToApply) {
+          const styleName = this.config.styleName || this.constructor.name;
+          StyleManager.applyStyles(this.shadowRoot, styleName, stylesToApply);
+        }
       }
-    }
-    return focusData;
-  }
-  /**
-   * 恢复焦点状态
-   */
-  restoreFocusState(focusData) {
-    if (!focusData) return;
-    try {
-      let targetElement = null;
-      if (focusData.className) {
-        targetElement = this.shadowRoot.querySelector(
-          `.${focusData.className.split(" ")[0]}`
+      const content = this.render();
+      if (focusState && focusState.key && focusState.value !== void 0) {
+        const target = content.querySelector(
+          `[data-wsx-key="${focusState.key}"]`
         );
-      }
-      if (!targetElement) {
-        targetElement = this.shadowRoot.querySelector(focusData.tagName);
-      }
-      if (targetElement) {
-        targetElement.focus({ preventScroll: true });
-        if (focusData.selectionStart !== void 0) {
-          if (targetElement instanceof HTMLInputElement) {
-            targetElement.setSelectionRange(
-              focusData.selectionStart,
-              focusData.selectionEnd ?? focusData.selectionStart
-            );
-          } else if (targetElement instanceof HTMLSelectElement) {
-            targetElement.value = focusData.value ?? "";
-          } else if (targetElement.hasAttribute("contenteditable")) {
-            this.setCursorPosition(targetElement, focusData.selectionStart);
+        if (target) {
+          if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+            target.value = focusState.value;
           }
         }
       }
-    } catch {
-    }
-  }
-  /**
-   * 设置光标位置
-   */
-  setCursorPosition(element, position) {
-    try {
-      const selection = window.getSelection();
-      if (selection) {
-        const range = document.createRange();
-        const textNode = element.childNodes[0];
-        if (textNode) {
-          const maxPos = Math.min(position, textNode.textContent?.length || 0);
-          range.setStart(textNode, maxPos);
-          range.setEnd(textNode, maxPos);
-          selection.removeAllRanges();
-          selection.addRange(range);
-        }
+      if (this.shadowRoot.adoptedStyleSheets) {
+        this.shadowRoot.adoptedStyleSheets = adoptedStyleSheets;
       }
-    } catch {
+      requestAnimationFrame(() => {
+        this.shadowRoot.appendChild(content);
+        const oldChildren = Array.from(this.shadowRoot.children).filter(
+          (child) => child !== content
+        );
+        oldChildren.forEach((child) => child.remove());
+        requestAnimationFrame(() => {
+          this.restoreFocusState(focusState);
+          this._pendingFocusState = null;
+        });
+      });
+    } catch (error) {
+      logger3.error("Error in rerender:", error);
+      this.renderError(error);
     }
   }
   /**
@@ -542,7 +780,7 @@ var WebComponent = class extends BaseComponent {
 };
 
 // src/light-component.ts
-var logger3 = createLogger("LightComponent");
+var logger4 = createLogger("LightComponent");
 var LightComponent = class extends BaseComponent {
   // Initialized by BaseComponent constructor
   constructor(config = {}) {
@@ -561,9 +799,10 @@ var LightComponent = class extends BaseComponent {
       }
       const content = this.render();
       this.appendChild(content);
+      this.initializeEventListeners();
       this.onConnected?.();
     } catch (error) {
-      logger3.error(`[${this.constructor.name}] Error in connectedCallback:`, error);
+      logger4.error(`[${this.constructor.name}] Error in connectedCallback:`, error);
       this.renderError(error);
     }
   }
@@ -571,6 +810,8 @@ var LightComponent = class extends BaseComponent {
    * Web Component生命周期：从DOM断开
    */
   disconnectedCallback() {
+    this.connected = false;
+    this.cleanup();
     this.cleanupReactiveStates();
     this.cleanupStyles();
     this.onDisconnected?.();
@@ -598,32 +839,67 @@ var LightComponent = class extends BaseComponent {
    */
   rerender() {
     if (!this.connected) {
-      logger3.warn(
+      logger4.warn(
         `[${this.constructor.name}] Component is not connected, skipping rerender.`
       );
       return;
     }
-    this.innerHTML = "";
-    if (this.config.styles) {
-      const styleName = this.config.styleName || this.constructor.name;
-      const styleElement = document.createElement("style");
-      styleElement.setAttribute("data-wsx-light-component", styleName);
-      styleElement.textContent = this.config.styles;
-      this.appendChild(styleElement);
-    }
+    const focusState = this.captureFocusState();
+    this._pendingFocusState = focusState;
     try {
       const content = this.render();
-      this.appendChild(content);
-      if (this.config.styles && this.children.length > 1) {
-        const styleElement = this.querySelector(
-          `style[data-wsx-light-component="${this.config.styleName || this.constructor.name}"]`
+      if (focusState && focusState.key && focusState.value !== void 0) {
+        const target = content.querySelector(
+          `[data-wsx-key="${focusState.key}"]`
         );
-        if (styleElement && styleElement !== this.firstChild) {
+        if (target) {
+          if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+            target.value = focusState.value;
+          }
+        }
+      }
+      const stylesToApply = this._autoStyles || this.config.styles;
+      if (stylesToApply) {
+        const styleName = this.config.styleName || this.constructor.name;
+        let styleElement = this.querySelector(
+          `style[data-wsx-light-component="${styleName}"]`
+        );
+        if (!styleElement) {
+          styleElement = document.createElement("style");
+          styleElement.setAttribute("data-wsx-light-component", styleName);
+          styleElement.textContent = stylesToApply;
           this.insertBefore(styleElement, this.firstChild);
+        } else if (styleElement.textContent !== stylesToApply) {
+          styleElement.textContent = stylesToApply;
         }
       }
+      requestAnimationFrame(() => {
+        this.appendChild(content);
+        const oldChildren = Array.from(this.children).filter((child) => {
+          if (child === content) {
+            return false;
+          }
+          if (stylesToApply && child instanceof HTMLStyleElement && child.getAttribute("data-wsx-light-component") === (this.config.styleName || this.constructor.name)) {
+            return false;
+          }
+          return true;
+        });
+        oldChildren.forEach((child) => child.remove());
+        if (stylesToApply && this.children.length > 1) {
+          const styleElement = this.querySelector(
+            `style[data-wsx-light-component="${this.config.styleName || this.constructor.name}"]`
+          );
+          if (styleElement && styleElement !== this.firstChild) {
+            this.insertBefore(styleElement, this.firstChild);
+          }
+        }
+        requestAnimationFrame(() => {
+          this.restoreFocusState(focusState);
+          this._pendingFocusState = null;
+        });
+      });
     } catch (error) {
-      logger3.error(`[${this.constructor.name}] Error in rerender:`, error);
+      logger4.error(`[${this.constructor.name}] Error in rerender:`, error);
       this.renderError(error);
     }
   }
@@ -705,7 +981,21 @@ function state(target, propertyKey) {
     const propertyKeyStr = String(propertyKey);
     if (propertyKeyStr === "[object Object]") {
       throw new Error(
-        `@state decorator: Invalid propertyKey. This usually means the build tool doesn't support decorators properly. Please ensure Babel plugin is configured in vite.config.ts`
+        `@state decorator: Invalid propertyKey detected. 
+
+The @state decorator MUST be processed by Babel plugin at compile time. It appears the Babel plugin is not configured in your build setup.
+
+To fix this, please:
+1. Install @wsxjs/wsx-vite-plugin: npm install @wsxjs/wsx-vite-plugin
+2. Configure it in vite.config.ts:
+   import { wsx } from '@wsxjs/wsx-vite-plugin';
+   export default defineConfig({ plugins: [wsx()] });
+3. Configure TypeScript (recommended: use @wsxjs/wsx-tsconfig):
+   npm install --save-dev @wsxjs/wsx-tsconfig
+   Then in tsconfig.json: { "extends": "@wsxjs/wsx-tsconfig/tsconfig.base.json" }
+   Or manually: { "compilerOptions": { "experimentalDecorators": true, "useDefineForClassFields": false } }
+
+See: https://github.com/wsxjs/wsxjs#setup for more details.`
       );
     }
     normalizedPropertyKey = propertyKeyStr;
@@ -713,7 +1003,21 @@ function state(target, propertyKey) {
   if (target == null) {
     const propertyKeyStr = typeof normalizedPropertyKey === "string" ? normalizedPropertyKey : normalizedPropertyKey.toString();
     throw new Error(
-      `@state decorator: Cannot access property "${propertyKeyStr}". Target is ${target === null ? "null" : "undefined"}. Please ensure Babel plugin is configured in vite.config.ts`
+      `@state decorator: Cannot access property "${propertyKeyStr}". Target is ${target === null ? "null" : "undefined"}.
+
+The @state decorator MUST be processed by Babel plugin at compile time. It appears the Babel plugin is not configured in your build setup.
+
+To fix this, please:
+1. Install @wsxjs/wsx-vite-plugin: npm install @wsxjs/wsx-vite-plugin
+2. Configure it in vite.config.ts:
+   import { wsx } from '@wsxjs/wsx-vite-plugin';
+   export default defineConfig({ plugins: [wsx()] });
+3. Configure TypeScript (recommended: use @wsxjs/wsx-tsconfig):
+   npm install --save-dev @wsxjs/wsx-tsconfig
+   Then in tsconfig.json: { "extends": "@wsxjs/wsx-tsconfig/tsconfig.base.json" }
+   Or manually: { "compilerOptions": { "experimentalDecorators": true, "useDefineForClassFields": false } }
+
+See: https://github.com/wsxjs/wsxjs#setup for more details.`
     );
   }
   if (typeof target !== "object") {