@dooboostore/simple-web-component 1.0.49 → 1.0.51

package/src/decorators/applyAttribute.ts

@@ -43,48 +43,19 @@ export const ATTRIBUTE_METADATA_KEY = Symbol.for('simple-web-component:attribute
 // Utilities
 // ============================================
 
-/**
- * Determine if a string is a CSS selector or an attribute name
- * 
- * CSS selectors typically:
- * - Start with: #, ., [, :, >, +, ~
- * - Contain special chars: >, +, ~, :, [, ]
- * - Are special keywords: $this, $host, $parentHost, etc.
- * 
- * Attribute names are typically:
- * - kebab-case (lowercase with hyphens)
- * - No special selector syntax
- * 
- * @param str - String to check
- * @returns true if it's a CSS selector, false if it's an attribute name
- */
-const isCssSelector = (str: string): boolean => {
-  if (!str) return false;
-  
-  // Special keywords
-  if (str.startsWith('$')) return true;
-  
-  // CSS selector syntax
-  if (/^[#.\[\:>+~]/.test(str)) return true;
-  
-  // Contains CSS combinator or pseudo-selector syntax
-  if (/[>+~:\[\]]/.test(str)) return true;
-  
-  return false;
-};
 
-const convertValue = (val: string | null, type: any): any => {
+// 문자열(attribute 원문)은 'false'/'0' 만 false. {{= }} 결과처럼 이미 JS 값이면 그 값의 참/거짓을 따른다
+const convertValue = (val: any, type: any): any => {
   if (val === null || val === undefined) return val;
   if (type === Number) return Number(val);
-  if (type === Boolean) return val === 'false' || val === '0' ? false : true;
+  if (type === Boolean) return typeof val === 'string' ? !(val === 'false' || val === '0') : Boolean(val);
   return val;
 };
 
 export {convertValue};
 
 export const getAttributeValue = (inst: any, attrName: string, options?: AttributeOptions & { selector?: AttributeSelector }): any => {
-  const conf = getElementConfig(inst);
-  const currentWin = inst._resolveWindow?.(conf) || ((typeof window !== 'undefined' ? window : undefined) as any);
+  const currentWin = SwcUtils.resolveWindow(inst);
 
   // If selector is not provided, use inst itself
   const targets = options?.selector ? resolveAttributeTargets(inst, options.selector, options) : [inst];
@@ -102,7 +73,7 @@ export const getAttributeValue = (inst: any, attrName: string, options?: Attribu
         const result = FunctionUtils.executeReturn({
           script: ConvertUtils.decodeHtmlEntity(expr.script, currentWin.document),
           context: inst,
-          args: SwcUtils.getHelperAndHostSet(currentWin, inst)
+          args: SwcUtils.getHelperAndHostSet(inst)
         });
         return convertValue(result, options?.type);
       } catch (err) {
@@ -132,7 +103,7 @@ export const resolveAttributeTargets = (inst: any, selector: AttributeSelector,
   // Resolve selector if it's a function
   let resolvedSelector: string | Node | Element | NodeList | Element[] | null = selector as any;
   if (typeof selector === 'function') {
-    const hostSet = SwcUtils.getHelperAndHostSet(currentWin, inst);
+    const hostSet = SwcUtils.getHelperAndHostSet(inst);
     resolvedSelector = selector(inst, hostSet);
   }
 
@@ -253,10 +224,8 @@ export function applyAttribute(selector: AttributeSelector, targetAttributeNameO
 
     // Helper: Apply resolved value to targets
     const applyValueToTargets = (inst: any, resolvedValue: any) => {
-      const conf = getElementConfig(inst);
-      const currentWin = conf.window;
       const targetEls = resolveAttributeTargets(inst, selector, finalOptions);
-      const hostSet = SwcUtils.getHelperAndHostSet(currentWin, inst);
+      const hostSet = SwcUtils.getHelperAndHostSet(inst);
 
       targetEls.forEach(targetEl => {
         // Apply filter if provided
@@ -292,8 +261,8 @@ export function applyAttribute(selector: AttributeSelector, targetAttributeNameO
          * Uses valueKey from options if provided, otherwise uses ATTRIBUTE_METADATA_KEY.
          * 
          * Example:
-         * @setAttribute('selector1', { valueKey: 'attr1' })
-         * @setAttribute('selector2', { valueKey: 'attr2' })
+         * @attribute('selector1', 'attr1-name', { valueKey: 'attr1' })
+         * @attribute('selector2', 'attr2-name', { valueKey: 'attr2' })
          * myMethod() {
          *   return {
          *     attr1: 'attribute-value1',
@@ -354,102 +323,79 @@ export function applyAttribute(selector: AttributeSelector, targetAttributeNameO
 // ============================================
 
 /**
- * @attribute - Field decorator for binding element attributes (read/write)
- * 
- * Intelligently distinguishes between attribute names and CSS selectors:
- * 
- * Usage patterns:
- * - @attribute('product-id') - Attribute name on $this (auto-detected)
- * - @attribute('#user', 'product-id') - Attribute name on selector
- * - @attribute('product-id', options) - Attribute name on $this with options
- * - @attribute('#user', 'product-id', options) - Attribute name on selector with options
- * - @attribute((this, helper) => 'selector', 'product-id') - Function-based selector
- * - @attribute - Bare decorator (uses property name as attribute on $this)
- * 
- * Note: This decorator is for FIELDS ONLY. For methods, use @setAttribute.
+ * @attribute - 필드/메서드 공용. 붙은 곳에 따라 동작이 갈린다.
+ * - 필드: 엘리먼트 attribute 를 읽고 쓰는 getter/setter
+ * - 메서드: 리턴값을 엘리먼트 attribute 에 적용 (null 이면 제거, undefined 면 무시)
+ *
+ * 문자열이 하나면 자기 자신($this)의 attribute 이름, 둘이면 (셀렉터, attribute 이름).
+ * - @attribute - $this 의 attribute, 이름은 필드/메서드 이름
+ * - @attribute('product-id') / @attribute('product-id', options) - $this 의 product-id
+ * - @attribute('#user', 'product-id', options?) - 셀렉터 대상의 product-id
+ * - @attribute((this, helper) => el, 'product-id') - 함수 셀렉터
+ * - @attribute(options) - $this, 이름은 options.name 또는 필드/메서드 이름
+ *
+ * Example:
+ * @attribute('product-id') productId: string;
+ *
+ * @attribute('.card', 'data-status')
+ * updateStatus() { return 'active'; }
  */
-export function attribute(target: Object, propertyKey: string | symbol):  void;
+export function attribute(attributeName: string, options?: AttributeQueryOptions): MethodDecorator & PropertyDecorator;
+export function attribute(selector: string, attributeName: string, options?: AttributeQueryOptions): MethodDecorator & PropertyDecorator;
+export function attribute(selector: AttributeFnSelector, attributeName: string, options?: AttributeNonQueryOptions): MethodDecorator & PropertyDecorator;
+export function attribute(options: AttributeOptions): MethodDecorator & PropertyDecorator;
+// bare(@attribute) 시그니처는 맨 뒤 — 앞에 있으면 문자열 두 개짜리 호출이 (target, key) 로 먼저 잡혀 TS1240
+export function attribute(target: Object, propertyKey: string | symbol): void;
 export function attribute(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
-export function attribute(attributeName: string, options?: AttributeQueryOptions): PropertyDecorator;
-export function attribute(selector: string, attributeName: string, options?: AttributeQueryOptions): PropertyDecorator;
-export function attribute(selector: AttributeFnSelector, attributeName: string, options?: AttributeNonQueryOptions): PropertyDecorator;
-export function attribute(selectorOrAttributeOrTarget?: AttributeSelector | Object, attributeNameOrOptions?: any, optionsOrDescriptor?: any): any {
-  // Bare decorator: @attribute
-  if (optionsOrDescriptor !== undefined && (typeof attributeNameOrOptions === 'string' || typeof attributeNameOrOptions === 'symbol')) {
-    return applyAttribute('$this', undefined as any, {})(selectorOrAttributeOrTarget as Object, attributeNameOrOptions, optionsOrDescriptor as PropertyDescriptor);
-  }
-  
-  // With string as first parameter
+export function attribute(selectorOrAttributeOrTarget?: AttributeSelector | AttributeOptions | Object, attributeNameOrOptions?: any, optionsOrDescriptor?: any): any {
+  // 문자열: 하나면 $this 의 attribute 이름, 둘이면 (셀렉터, attribute 이름)
   if (typeof selectorOrAttributeOrTarget === 'string') {
-    // Check if first parameter is a CSS selector or attribute name
-    const isSelector = isCssSelector(selectorOrAttributeOrTarget);
-    
-    if (isSelector) {
-      // First param is a selector: @attribute('#user', 'product-id', options?)
-      return applyAttribute(selectorOrAttributeOrTarget, attributeNameOrOptions as any, optionsOrDescriptor as AttributeOptions);
-    } else {
-      // First param is an attribute name: @attribute('product-id', options?)
-      // Treat as attribute name on $this
-      const options = (typeof attributeNameOrOptions === 'object' && attributeNameOrOptions !== null) 
-        ? attributeNameOrOptions 
-        : {};
-      return applyAttribute('$this', selectorOrAttributeOrTarget, options);
+    if (typeof attributeNameOrOptions !== 'string') {
+      return applyAttribute('$this', selectorOrAttributeOrTarget, attributeNameOrOptions as AttributeOptions);
     }
+    return applyAttribute(selectorOrAttributeOrTarget, attributeNameOrOptions, optionsOrDescriptor as AttributeOptions);
+  }
+  // 함수 셀렉터
+  if (typeof selectorOrAttributeOrTarget === 'function') {
+    return applyAttribute(selectorOrAttributeOrTarget as AttributeFnSelector, attributeNameOrOptions, optionsOrDescriptor as AttributeOptions);
   }
-  
-  // Without selector (defaults to $this with options)
-  return applyAttribute('$this', undefined as any, selectorOrAttributeOrTarget as AttributeOptions);
+  // bare: @attribute — 데코레이터로 바로 호출됨 (target=prototype, key[, descriptor])
+  if (selectorOrAttributeOrTarget && (typeof attributeNameOrOptions === 'string' || typeof attributeNameOrOptions === 'symbol')) {
+    return applyAttribute('$this', {})(selectorOrAttributeOrTarget as Object, attributeNameOrOptions, optionsOrDescriptor as PropertyDescriptor);
+  }
+  // 옵션만: $this
+  return applyAttribute('$this', selectorOrAttributeOrTarget as AttributeOptions);
 }
 
 /**
- * @setAttribute - Method decorator for setting element attributes from method return value
- * 
- * Intelligently distinguishes between attribute names and CSS selectors:
- * 
- * Usage patterns:
- * - @setAttribute('data-id') - Attribute name on $this (auto-detected)
- * - @setAttribute('#user', 'data-id') - Attribute name on selector
- * - @setAttribute('data-id', options) - Attribute name on $this with options
- * - @setAttribute('#user', 'data-id', options) - Attribute name on selector with options
- * - @setAttribute((this, helper) => 'selector', 'data-id') - Function-based selector
- * - @setAttribute - Bare decorator (uses method name as attribute on $this)
- * 
- * Note: This decorator is for METHODS ONLY. For fields, use @attribute.
- * 
- * Example:
- * @setAttribute('data-status')
- * updateStatus() {
- *   return 'active';
- * }
+ * @removeAttribute - 메서드 실행 시 엘리먼트 속성 제거 (반환값 그대로 통과).
+ * 라우트 구독처럼 값을 리턴하면 안 되는 곳에서 @attribute 에 null 을 리턴하는 대신 명시적으로 사용.
+ *
+ * Usage:
+ * - @removeAttribute('nav', 'href') - Remove attribute from selector
+ * - @removeAttribute('$this', 'href') - Remove attribute from $this
  */
-export function setAttribute(selector: string, attributeName: string, options?: AttributeQueryOptions): MethodDecorator;
-export function setAttribute(selector: AttributeFnSelector, attributeName: string, options?: AttributeNonQueryOptions): MethodDecorator;
-export function setAttribute(attributeName: string, options?: AttributeQueryOptions): MethodDecorator;
-export function setAttribute(selectorOrAttributeOrOptions?: AttributeSelector | AttributeOptions, attributeNameOrOptions?: any, optionsOrUndefined?: AttributeOptions): MethodDecorator {
-  // Function selector: @setAttribute((c, helper) => ..., 'attr', options?)
-  if (typeof selectorOrAttributeOrOptions === 'function') {
-    return applyAttribute(selectorOrAttributeOrOptions as AttributeSelector, attributeNameOrOptions as any, optionsOrUndefined as AttributeOptions) as MethodDecorator;
-  }
-  // With string as first parameter
-  if (typeof selectorOrAttributeOrOptions === 'string') {
-    // Check if first parameter is a CSS selector or attribute name
-    const isSelector = isCssSelector(selectorOrAttributeOrOptions);
-    
-    if (isSelector) {
-      // First param is a selector: @setAttribute('#user', 'data-id', options?)
-      return applyAttribute(selectorOrAttributeOrOptions, attributeNameOrOptions as any, optionsOrUndefined as AttributeOptions) as MethodDecorator;
-    } else {
-      // First param is an attribute name: @setAttribute('data-id', options?)
-      // Treat as attribute name on $this
-      const options = (typeof attributeNameOrOptions === 'object' && attributeNameOrOptions !== null) 
-        ? attributeNameOrOptions 
-        : {};
-      return applyAttribute('$this', selectorOrAttributeOrOptions, options) as MethodDecorator;
-    }
-  }
-  
-  // Without selector (defaults to $this with options)
-  return applyAttribute('$this', undefined as any, selectorOrAttributeOrOptions as AttributeOptions) as MethodDecorator;
+export function removeAttribute(selector: string, attributeName: string, options?: AttributeQueryOptions): MethodDecorator;
+export function removeAttribute(selector: AttributeFnSelector, attributeName: string, options?: AttributeNonQueryOptions): MethodDecorator;
+export function removeAttribute(selector: AttributeSelector, attributeName: string, options?: AttributeOptions): MethodDecorator {
+  return (target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+    const original = descriptor.value;
+    descriptor.value = function (...args: any[]) {
+      const res = (original as any).apply(this, args);
+      const doRemove = () => {
+        resolveAttributeTargets(this, selector, options ?? {}).forEach((el) => el.removeAttribute(attributeName));
+      };
+      if (res instanceof Promise) {
+        return res.then((v: any) => {
+          doRemove();
+          return v;
+        });
+      }
+      doRemove();
+      return res;
+    };
+    return descriptor;
+  };
 }
 
 // ============================================
@@ -457,7 +403,7 @@ export function setAttribute(selectorOrAttributeOrOptions?: AttributeSelector |
 // ============================================
 
 export const findAllAttributeMetadata = (target: any): AttributeMetadata[] => {
-  const actualTarget = target instanceof Function ? target : target.constructor;
+  const actualTarget = typeof target === 'function' ? target : target.constructor;
   return ReflectUtils.findAllMetadata<AttributeMetadata[]>(ATTRIBUTE_METADATA_KEY, actualTarget).flat();
 };
 
@@ -471,16 +417,18 @@ export const findAllAttributeApplyMetadata = (target: any): Map<string | symbol,
 };
 
 // ─── Aliases ───
-// attribute(필드) / setAttribute(메서드)와 구분되는 일반 데코레이터 단축명
+// applyAttribute 단축명
 export const attr = applyAttribute;
 
 // ─── 편의 헬퍼 (selector/root 생략) ───
 
-export function attrThis(targetAttributeName?: string, options?: AttributeQueryOptions): MethodDecorator {
-  return applyAttribute('$this', targetAttributeName, options);
-}
-export function attrAppHost(targetAttributeName?: string, options?: AttributeQueryOptions): MethodDecorator {
-  return applyAttribute('$appHost', targetAttributeName, options);
+export function attrAppHost(targetAttributeName: string, options?: AttributeQueryOptions): MethodDecorator;
+export function attrAppHost(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function attrAppHost(targetAttributeNameOrTarget?: string | Object, optionsOrPropertyKey?: AttributeQueryOptions | string | symbol, descriptor?: PropertyDescriptor): any {
+  if ((typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol') && descriptor !== undefined) {
+    return (applyAttribute('$appHost', undefined as any, {}) as any)(targetAttributeNameOrTarget, optionsOrPropertyKey, descriptor);
+  }
+  return applyAttribute('$appHost', targetAttributeNameOrTarget as any, optionsOrPropertyKey as AttributeQueryOptions);
 }
 export function attrLight(selector: string, targetAttributeName?: string, options?: Omit<AttributeQueryOptions, 'root'>): MethodDecorator {
   return applyAttribute(selector, targetAttributeName, {...options ?? {}, root: 'light'});

package/src/decorators/applyClass.ts

@@ -13,7 +13,7 @@ export type ClassAction = 'set' | 'update' | 'add' | 'remove' | 'toggle';
  */
 const resolveSelector = (selector: ClassSelector, inst: any, win: Window): string | HTMLElement[] => {
   if (typeof selector === 'function') {
-    const hostSet = SwcUtils.getHelperAndHostSet(win, inst);
+    const hostSet = SwcUtils.getHelperAndHostSet(inst);
     const result = selector(inst, hostSet);
     
     if (result instanceof win.Element) {
@@ -49,7 +49,7 @@ const getTargetElements = (selector: ClassSelector, inst: any, win: Window, root
   const stringSelector = resolved as string;
   const targetEls: HTMLElement[] = [];
   const host = inst as unknown as HTMLElement;
-  const hostSet = SwcUtils.getHelperAndHostSet(win, inst);
+  const hostSet = SwcUtils.getHelperAndHostSet(inst);
 
   const applyRoot = (t: any) => {
     if (!t || !(t instanceof win.HTMLElement)) return;
@@ -149,7 +149,7 @@ function createClassDecorator(action: ClassAction) {
           if (resolvedValue !== undefined) {
             const win = (this as any).ownerDocument?.defaultView || window;
             const host = this as unknown as HTMLElement;
-            const hostSet = { ...SwcUtils.getHelperAndHostSet(win, host), $this: this };
+            const hostSet = { ...SwcUtils.getHelperAndHostSet(host), $this: this };
             const r = finalOptions.root || 'auto';
             const targetEls = getTargetElements(selector, this, win, r);
 
@@ -209,9 +209,11 @@ function createClassDecorator(action: ClassAction) {
         };
 
         if (res instanceof Promise) {
-          return res.then((v: any) => handleResult(extractValue(v)));
+          // 자기 몫(valueKey)만 적용하고 원래 반환값은 그대로 위로 넘긴다 — 위에 쌓인 다른 아웃풋도 자기 키를 찾게
+          return res.then((v: any) => { handleResult(extractValue(v)); return v; });
         } else {
-          return handleResult(extractValue(res));
+          handleResult(extractValue(res));
+          return res;
         }
       };
       return descriptor;
@@ -325,11 +327,13 @@ export const cls = applyClass;
 
 // ─── 편의 헬퍼 (selector/root 생략) ───
 
-export function clsThis(action?: ClassAction, options?: ClassQueryOptions): MethodDecorator {
-  return applyClass('$this', action, options);
-}
-export function clsAppHost(action?: ClassAction, options?: ClassQueryOptions): MethodDecorator {
-  return applyClass('$appHost', action, options);
+export function clsAppHost(action: ClassAction, options?: ClassQueryOptions): MethodDecorator;
+export function clsAppHost(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function clsAppHost(actionOrTarget?: ClassAction | Object, optionsOrPropertyKey?: ClassQueryOptions | string | symbol, descriptor?: PropertyDescriptor): any {
+  if ((typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol') && descriptor !== undefined) {
+    return (applyClass('$appHost', undefined as any, {}) as any)(actionOrTarget, optionsOrPropertyKey, descriptor);
+  }
+  return applyClass('$appHost', actionOrTarget as any, optionsOrPropertyKey as ClassQueryOptions);
 }
 export function clsLight(selector: string, action?: ClassAction, options?: Omit<ClassQueryOptions, 'root'>): MethodDecorator;
 export function clsLight(selector: string, options?: Omit<ClassQueryOptions, 'root'>): MethodDecorator;

package/src/decorators/applyNode.ts

@@ -1,5 +1,5 @@
 import { ReflectUtils } from '@dooboostore/core';
-import { ensureInit, getElementConfig } from './elementDefine';
+import { ensureInit } from './elementDefine';
 import {SpecialSelector, SwcQueryOptions, SwcFnSelector, SwcSelector, HelperHostSet, SwcRootType} from '../types';
 import { SwcUtils} from "../utils/Utils";
 import {findAllStateMetadata} from "./state";
@@ -49,7 +49,7 @@ export const APPLY_NODE_METADATA_KEY = Symbol.for('simple-web-component:apply-no
  */
 const resolveSelector = (selector: ApplyNodeSelector, inst: any, win: Window): string | HTMLElement | null => {
   if (typeof selector === 'function') {
-    const hostSet = SwcUtils.getHelperAndHostSet(win, inst);
+    const hostSet = SwcUtils.getHelperAndHostSet(inst);
     const result = selector(inst, hostSet);
     
     if (result instanceof win.Element) {
@@ -78,7 +78,7 @@ const resolveSelector = (selector: ApplyNodeSelector, inst: any, win: Window): s
 //   });
 // };
 
-const applyToDom = (currentThis: any, targetEl: HTMLElement, res: Node | string, pos: ApplyNodePosition, win: Window, host?: any) => {
+const applyToDom = (currentThis: any, targetEl: HTMLElement, res: Node | string | (Node | string)[] | NodeList, pos: ApplyNodePosition, win: Window, host?: any) => {
   if (!targetEl) return;
   
   // Handle clearChildren - ignore return value and always clear
@@ -88,20 +88,21 @@ const applyToDom = (currentThis: any, targetEl: HTMLElement, res: Node | string,
   }
   
   const doc = win.document;
-  const hostSet = SwcUtils.getHelperAndHostSet(win, currentThis);
+  const hostSet = SwcUtils.getHelperAndHostSet(currentThis);
   const id = currentThis._swcId;
 
-  const nodes: Node[] = [];
-
-  if (res instanceof win.Node) {
-    nodes.push(res);
-  } else if (typeof res === 'string' && pos === 'innerHtml') {
-    const t = win.document.createElement('template');
-    t.innerHTML = res;
-    nodes.push(...Array.from(t.content.childNodes));
-  } else if (typeof res === 'string' && pos === 'innerText') {
-    nodes.push(win.document.createTextNode(res));
-  }
+  // 리턴값 → 노드: Node 그대로 / 문자열은 innerText 면 텍스트, 그 외 위치는 HTML / 배열·NodeList 는 항목마다.
+  // Node 판단은 nodeType 으로 — 다른 window(iframe) 에서 만든 노드는 instanceof win.Node 가 false 라서.
+  const toNodes = (v: any): Node[] => {
+    if (v === null || v === undefined || v === false) return [];
+    if (typeof v === 'object' && typeof v.nodeType === 'number') return [v];
+    if (typeof v === 'object' && typeof v.length === 'number') return Array.from(v as ArrayLike<any>).flatMap(toNodes);
+    if (pos === 'innerText') return [doc.createTextNode(String(v))];
+    const t = doc.createElement('template');
+    t.innerHTML = String(v);
+    return Array.from(t.content.childNodes);
+  };
+  const nodes: Node[] = toNodes(res);
 
   SwcUtils.projectProcessHtml(id, nodes, doc);
 
@@ -170,10 +171,9 @@ export function applyNode(selectorOrOptions: ApplyNodeSelector | ApplyNodeOption
     descriptor.value = function (...args: any[]) {
       ensureInit(this);
 
-      const conf = getElementConfig(this);
-      const currentWin = (this as any)._resolveWindow?.(conf) || ((typeof window !== 'undefined' ? window : undefined) as Window);
+      const currentWin = SwcUtils.resolveWindow(this);
       const currentDoc = currentWin.document;
-      const hostSet = SwcUtils.getHelperAndHostSet(currentWin, this);
+      const hostSet = SwcUtils.getHelperAndHostSet(this);
 
       const getTarget = () => {
         const r = options.root || 'auto';
@@ -306,7 +306,7 @@ export function replaceChildren(selectorOrOptions?: ApplyNodeSelector | Omit<App
  * - @clearChildrenNode - Bare decorator, clears children of $this
  */
 export function clearChildrenNode(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
-export function clearChildrenNode(options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function clearChildrenNode(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
 export function clearChildrenNode(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function clearChildrenNode(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @clearChildrenNode
@@ -332,7 +332,7 @@ export const clearNode = clearChildrenNode;
  * - @innerHtmlNode - Bare decorator, sets innerHTML of $this
  */
 export function innerHtml(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
-export function innerHtml(options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function innerHtml(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
 export function innerHtml(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function innerHtml(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @innerHtmlNode
@@ -358,7 +358,7 @@ export function innerHtml(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNode
  * - @innerHtmlLightNode - Bare decorator, sets innerHTML of $this in light DOM
  */
 export function innerHtmlLight(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function innerHtmlLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerHtmlLight(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
 export function innerHtmlLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function innerHtmlLight(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @innerHtmlLightNode
@@ -382,7 +382,7 @@ export function innerHtmlLight(selectorOrOptions?: ApplyNodeSelector | Omit<Appl
  * - @innerHtmlShadowNode - Bare decorator, sets innerHTML of $this in shadow DOM
  */
 export function innerHtmlShadow(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function innerHtmlShadow(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerHtmlShadow(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
 export function innerHtmlShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function innerHtmlShadow(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @innerHtmlShadowNode
@@ -406,7 +406,7 @@ export function innerHtmlShadow(selectorOrOptions?: ApplyNodeSelector | Omit<App
  * - @innerTextNode - Bare decorator, sets innerText of $this
  */
 export function innerText(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
-export function innerText(options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function innerText(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
 export function innerText(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function innerText(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @innerTextNode
@@ -430,7 +430,7 @@ export function innerText(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNode
  * - @innerTextLightNode - Bare decorator, sets innerText of $this in light DOM
  */
 export function innerTextLight(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function innerTextLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerTextLight(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
 export function innerTextLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function innerTextLight(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @innerTextLightNode
@@ -453,7 +453,7 @@ export function innerTextLight(selectorOrOptions?: ApplyNodeSelector | Omit<Appl
  * - @innerTextShadowNode - Bare decorator, sets innerText of $this in shadow DOM
  */
 export function innerTextShadow(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function innerTextShadow(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerTextShadow(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
 export function innerTextShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function innerTextShadow(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @innerTextShadowNode
@@ -476,7 +476,7 @@ export function innerTextShadow(selectorOrOptions?: ApplyNodeSelector | Omit<App
  * - @beforeEndNode - Bare decorator, appends to $this
  */
 export function insertBeforeEnd(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
-export function insertBeforeEnd(options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function insertBeforeEnd(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
 export function insertBeforeEnd(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function insertBeforeEnd(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @beforeEndNode
@@ -500,7 +500,7 @@ export function insertBeforeEnd(selectorOrOptions?: ApplyNodeSelector | Omit<App
  * - @beforeEndLightNode - Bare decorator, appends to $this in light DOM
  */
 export function insertBeforeEndLight(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function insertBeforeEndLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function insertBeforeEndLight(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
 export function insertBeforeEndLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function insertBeforeEndLight(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @beforeEndLightNode
@@ -524,7 +524,7 @@ export function insertBeforeEndLight(selectorOrOptions?: ApplyNodeSelector | Omi
  * - @beforeEndShadowNode - Bare decorator, appends to $this in shadow DOM
  */
 export function insertBeforeEndShadow(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function insertBeforeEndShadow(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function insertBeforeEndShadow(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
 export function insertBeforeEndShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function insertBeforeEndShadow(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @beforeEndShadowNode
@@ -548,7 +548,7 @@ export function insertBeforeEndShadow(selectorOrOptions?: ApplyNodeSelector | Om
  * - @afterBeginNode - Bare decorator, prepends to $this
  */
 export function insertAfterBegin(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
-export function insertAfterBegin(options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function insertAfterBegin(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
 export function insertAfterBegin(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function insertAfterBegin(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @afterBeginNode
@@ -572,7 +572,7 @@ export function insertAfterBegin(selectorOrOptions?: ApplyNodeSelector | Omit<Ap
  * - @afterBeginLightNode - Bare decorator, prepends to $this in light DOM
  */
 export function insertAfterBeginLight(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function insertAfterBeginLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function insertAfterBeginLight(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
 export function insertAfterBeginLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function insertAfterBeginLight(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @afterBeginLightNode
@@ -596,7 +596,7 @@ export function insertAfterBeginLight(selectorOrOptions?: ApplyNodeSelector | Om
  * - @replaceChildrenLightNode - Bare decorator, replaces children of $this in light DOM
  */
 export function replaceChildrenLight(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function replaceChildrenLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function replaceChildrenLight(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
 export function replaceChildrenLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function replaceChildrenLight(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @replaceChildrenLightNode
@@ -619,7 +619,7 @@ export function replaceChildrenLight(selectorOrOptions?: ApplyNodeSelector | Omi
  * - @clearChildrenLightNode - Bare decorator, clears children of $this in light DOM
  */
 export function clearChildrenLight(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function clearChildrenLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function clearChildrenLight(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
 export function clearChildrenLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function clearChildrenLight(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @clearChildrenLightNode
@@ -642,11 +642,13 @@ export const node = applyNode;
 
 // ─── 편의 헬퍼 (selector/root 생략) ───
 
-export function applyThis(options?: ApplyNodeQueryOptions): MethodDecorator {
-  return applyNode('$this', options);
-}
-export function applyAppHost(options?: ApplyNodeQueryOptions): MethodDecorator {
-  return applyNode('$appHost', options);
+export function applyAppHost(options: ApplyNodeQueryOptions): MethodDecorator;
+export function applyAppHost(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function applyAppHost(optionsOrTarget?: ApplyNodeQueryOptions | Object, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  if ((typeof propertyKey === 'string' || typeof propertyKey === 'symbol') && descriptor !== undefined) {
+    return (applyNode('$appHost', {}) as any)(optionsOrTarget, propertyKey, descriptor);
+  }
+  return applyNode('$appHost', optionsOrTarget as ApplyNodeQueryOptions);
 }
 export function applyLight(selector: string, options?: Omit<ApplyNodeQueryOptions, 'root'>): MethodDecorator {
   return applyNode(selector, {...options ?? {}, root: 'light'});