@dooboostore/simple-web-component 1.0.50 → 1.0.51

package/src/decorators/applyProperty.ts

@@ -55,7 +55,7 @@ export const resolvePropertyTargets = (inst: any, selector: PropertySelector, op
   // 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);
   }
 
@@ -182,9 +182,7 @@ export function applyProperty(selector: PropertySelector, targetPropertyKeyOrOpt
       if (resolvedValue === undefined) return resolvedValue;
 
       const targetEls = resolvePropertyTargets(inst, selector, finalOptions);
-      const conf = getElementConfig(inst);
-      const currentWin = conf.window;
-      const hostSet = SwcUtils.getHelperAndHostSet(currentWin, inst);
+      const hostSet = SwcUtils.getHelperAndHostSet(inst);
 
       targetEls.forEach(targetEl => {
         // Apply filter if provided
@@ -219,7 +217,7 @@ export function applyProperty(selector: PropertySelector, targetPropertyKeyOrOpt
          * use that value. Otherwise use the entire return value.
          * 
          * Example:
-         * @setProperty('selector')
+         * @property('selector')
          * myMethod() {
          *   return {
          *     [PROPERTY_METADATA_KEY]: 'property-value',
@@ -251,7 +249,13 @@ export function applyProperty(selector: PropertySelector, targetPropertyKeyOrOpt
       return;
     }
 
-    // Property decorator: define getter/setter to proxy to element properties
+    // Property decorator: define getter/setter to proxy to element properties.
+    // selector가 '$this' + 타겟 키가 자기 필드면 getter/setter 만들지 않고 리턴.
+    // (메타데이터는 위에서 이미 등록됨 → 하이드레이션 수집은 됨.)
+    // 순수 필드로 두는 게 업그레이드 때 값 유지에 안전 (setter 경로 타면 생성자·폴리필에 날아감).
+    if (selector === '$this' && targetPropertyKey === propertyKey) {
+      return;
+    }
     Object.defineProperty(target, propertyKey, {
       configurable: true,
       enumerable: true,
@@ -259,9 +263,7 @@ export function applyProperty(selector: PropertySelector, targetPropertyKeyOrOpt
         ensureInit(this);
         // Read from matched elements
         const targetEls = resolvePropertyTargets(this, selector, finalOptions);
-        const conf = getElementConfig(this);
-        const currentWin = conf.window;
-        const hostSet = SwcUtils.getHelperAndHostSet(currentWin, this);
+        const hostSet = SwcUtils.getHelperAndHostSet(this);
 
         // Apply filter
         const filtered = targetEls.filter(el => {
@@ -292,76 +294,42 @@ export function applyProperty(selector: PropertySelector, targetPropertyKeyOrOpt
 // ============================================
 
 /**
- * @property - Field decorator for binding element properties (read/write)
- * 
- * Usage:
- * - @property('selector', 'propertyName') - Bind to specific property
- * - @property('selector') - Use field name as property name
- * - @property('selector', options) - Bind with options
- * - @property((this, helper) => 'selector', 'propertyName') - Function-based selector
- * - @property - Bare decorator (binds to $this with field name)
- * 
- * Note: This decorator is for FIELDS ONLY. For methods, use @setProperty.
+ * @property - 필드/메서드 공용. 붙은 곳에 따라 동작이 갈린다.
+ * - 필드: 대상 엘리먼트 프로퍼티를 읽고 쓰는 getter/setter ($this + 같은 이름이면 순수 필드로 두고 하이드레이션만 등록)
+ * - 메서드: 리턴값을 대상 엘리먼트 프로퍼티에 대입 (undefined 면 무시)
+ *
+ * 첫 문자열은 항상 셀렉터. 자기 자신의 프로퍼티는 필드 그 자체라 이름만 받는 형태는 의미가 없다.
+ * - @property - $this, 이름은 필드/메서드 이름
+ * - @property('selector') / @property('selector', options) - 대상의 같은 이름 프로퍼티
+ * - @property('selector', 'propertyName', options?) - 대상의 propertyName
+ * - @property((this, helper) => el, 'propertyName') - 함수 셀렉터
+ * - @property(options) - $this, 이름은 options.name 또는 필드/메서드 이름
+ *
+ * Example:
+ * @property('#chart', 'data') chartData: number[];
+ *
+ * @property('button', 'disabled')
+ * lock() { return true; }
  */
-export function property(selector: string, targetPropertyKey: string | symbol, options?: PropertyQueryOptions): PropertyDecorator;
-export function property(selector: PropertyFnSelector, targetPropertyKey: string | symbol, options?: PropertyNonQueryOptions): PropertyDecorator;
-export function property(selector: string, options?: PropertyQueryOptions): PropertyDecorator;
-export function property(selector: PropertyFnSelector, options?: PropertyNonQueryOptions): PropertyDecorator;
+export function property(selector: string, targetPropertyKey: string | symbol, options?: PropertyQueryOptions): MethodDecorator & PropertyDecorator;
+export function property(selector: PropertyFnSelector, targetPropertyKey: string | symbol, options?: PropertyNonQueryOptions): MethodDecorator & PropertyDecorator;
+export function property(selector: string, options?: PropertyQueryOptions): MethodDecorator & PropertyDecorator;
+export function property(selector: PropertyFnSelector, options?: PropertyNonQueryOptions): MethodDecorator & PropertyDecorator;
+export function property(options: PropertyOptions): MethodDecorator & PropertyDecorator;
+// bare(@property) 시그니처는 맨 뒤 — 앞에 있으면 문자열 두 개짜리 호출이 (target, key) 로 먼저 잡혀 TS1240
 export function property(target: Object, propertyKey: string | symbol): void;
 export function property(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
-export function property(selectorOrTarget?: PropertySelector | Object, targetPropertyKeyOrOptions?: any, optionsOrDescriptor?: any): any {
-  // Bare decorator direct invocation: @property on field/method passes (target, key[, descriptor]).
-  // NOTE: (selector-string, key, options) factory form must NOT enter here — target is never string/function.
-  if (optionsOrDescriptor !== undefined
-    && typeof selectorOrTarget !== 'string' && typeof selectorOrTarget !== 'function'
-    && (typeof targetPropertyKeyOrOptions === 'string' || typeof targetPropertyKeyOrOptions === 'symbol')) {
-    return applyProperty('$this', undefined as any, {})(selectorOrTarget as Object, targetPropertyKeyOrOptions, optionsOrDescriptor as PropertyDescriptor);
-  }
-  // With selector
-  if (typeof selectorOrTarget === 'string') {
-    return applyProperty(selectorOrTarget, targetPropertyKeyOrOptions as any, optionsOrDescriptor as PropertyOptions);
-  }
-  // Function selector
-  if (typeof selectorOrTarget === 'function') {
-    return applyProperty(selectorOrTarget as PropertyFnSelector, targetPropertyKeyOrOptions as any, optionsOrDescriptor as PropertyOptions);
-  }
-  // Without selector (defaults to $this)
-  return applyProperty('$this', undefined as any, selectorOrTarget as PropertyOptions);
-}
-
-/**
- * @setProperty - Method decorator for setting element properties from method return value
- * 
- * Usage:
- * - @setProperty('selector', 'propertyName') - Set specific property
- * - @setProperty('selector') - Use method name as property name
- * - @setProperty('selector', options) - Set with options
- * - @setProperty((this, helper) => 'selector', 'propertyName') - Function-based selector
- * - @setProperty - Bare decorator (sets on $this with method name)
- * 
- * Note: This decorator is for METHODS ONLY. For fields, use @property.
- * 
- * Example:
- * @setProperty('selector', 'disabled')
- * disableElement() {
- *   return true;
- * }
- */
-export function setProperty(selector: string, targetPropertyKey: string | symbol, options?: PropertyQueryOptions): MethodDecorator;
-export function setProperty(selector: PropertyFnSelector, targetPropertyKey: string | symbol, options?: PropertyNonQueryOptions): MethodDecorator;
-export function setProperty(selector: string, options?: PropertyQueryOptions): MethodDecorator;
-export function setProperty(selector: PropertyFnSelector, options?: PropertyNonQueryOptions): MethodDecorator;
-export function setProperty(selectorOrOptions?: PropertySelector | PropertyOptions, targetPropertyKeyOrOptions?: any, optionsOrUndefined?: PropertyOptions): MethodDecorator {
-  // With selector
-  if (typeof selectorOrOptions === 'string') {
-    return applyProperty(selectorOrOptions, targetPropertyKeyOrOptions as any, optionsOrUndefined as PropertyOptions) as MethodDecorator;
+export function property(selectorOrTarget?: PropertySelector | PropertyOptions | Object, targetPropertyKeyOrOptions?: any, optionsOrDescriptor?: any): any {
+  // 셀렉터 (문자열 / 함수)
+  if (typeof selectorOrTarget === 'string' || typeof selectorOrTarget === 'function') {
+    return applyProperty(selectorOrTarget as PropertySelector, targetPropertyKeyOrOptions as any, optionsOrDescriptor as PropertyOptions);
   }
-  // Function selector
-  if (typeof selectorOrOptions === 'function') {
-    return applyProperty(selectorOrOptions as PropertyFnSelector, targetPropertyKeyOrOptions as any, optionsOrUndefined as PropertyOptions) as MethodDecorator;
+  // bare: @property — 데코레이터로 바로 호출됨 (target=prototype, key[, descriptor])
+  if (selectorOrTarget && (typeof targetPropertyKeyOrOptions === 'string' || typeof targetPropertyKeyOrOptions === 'symbol')) {
+    return applyProperty('$this', {})(selectorOrTarget as Object, targetPropertyKeyOrOptions, optionsOrDescriptor as PropertyDescriptor);
   }
-  // Without selector (defaults to $this)
-  return applyProperty('$this', undefined as any, selectorOrOptions as PropertyOptions) as MethodDecorator;
+  // 옵션만: $this
+  return applyProperty('$this', selectorOrTarget as PropertyOptions);
 }
 
 /**
@@ -415,7 +383,7 @@ export function callPropertyAll(selector: string, targetMethodKey?: string | sym
 // ============================================
 
 export const findAllPropertyMetadata = (target: any): PropertyMetadata[] => {
-  const actualTarget = target instanceof Function ? target : target.constructor;
+  const actualTarget = typeof target === 'function' ? target : target.constructor;
   return ReflectUtils.findAllMetadata<PropertyMetadata[]>(PROPERTY_METADATA_KEY, actualTarget).flat();
 };
 
@@ -429,7 +397,7 @@ export const findAllPropertyApplyMetadata = (target: any): Map<string | symbol,
 };
 
 // ─── Aliases ───
-// property(필드) / setProperty(메서드)와 구분되는 일반 데코레이터 단축명
+// applyProperty 단축명
 export const prop = applyProperty;
 
 // ─── 편의 헬퍼 (selector/root 생략) ───
@@ -446,22 +414,17 @@ const dispatchPropConvenience = (
   return applyProperty(selector, targetPropertyKeyOrTarget as any, optionsOrPropertyKey as PropertyQueryOptions);
 };
 
-export function propThis(targetPropertyKey?: string | symbol, options?: PropertyQueryOptions): MethodDecorator;
-export function propThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
-export function propThis(targetPropertyKeyOrTarget?: string | symbol | Object, optionsOrPropertyKey?: PropertyQueryOptions | string | symbol, descriptor?: PropertyDescriptor): any {
-  return dispatchPropConvenience('$this', targetPropertyKeyOrTarget, optionsOrPropertyKey, descriptor);
-}
-export function propAppHost(targetPropertyKey?: string | symbol, options?: PropertyQueryOptions): MethodDecorator;
+export function propAppHost(targetPropertyKey: string | symbol, options?: PropertyQueryOptions): MethodDecorator;
 export function propAppHost(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function propAppHost(targetPropertyKeyOrTarget?: string | symbol | Object, optionsOrPropertyKey?: PropertyQueryOptions | string | symbol, descriptor?: PropertyDescriptor): any {
   return dispatchPropConvenience('$appHost', targetPropertyKeyOrTarget, optionsOrPropertyKey, descriptor);
 }
-export function propWindow(targetPropertyKey?: string | symbol, options?: PropertyQueryOptions): MethodDecorator;
+export function propWindow(targetPropertyKey: string | symbol, options?: PropertyQueryOptions): MethodDecorator;
 export function propWindow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function propWindow(targetPropertyKeyOrTarget?: string | symbol | Object, optionsOrPropertyKey?: PropertyQueryOptions | string | symbol, descriptor?: PropertyDescriptor): any {
   return dispatchPropConvenience('$window', targetPropertyKeyOrTarget, optionsOrPropertyKey, descriptor);
 }
-export function propDocument(targetPropertyKey?: string | symbol, options?: PropertyQueryOptions): MethodDecorator;
+export function propDocument(targetPropertyKey: string | symbol, options?: PropertyQueryOptions): MethodDecorator;
 export function propDocument(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function propDocument(targetPropertyKeyOrTarget?: string | symbol | Object, optionsOrPropertyKey?: PropertyQueryOptions | string | symbol, descriptor?: PropertyDescriptor): any {
   return dispatchPropConvenience('$document', targetPropertyKeyOrTarget, optionsOrPropertyKey, descriptor);
@@ -476,25 +439,14 @@ export function propAll(selector: string, targetPropertyKey?: string | symbol, o
   return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'all'});
 }
 
-// ─── setProperty root 별칭 (메서드 리턴값 → 타깃 프로퍼티) ───
-export function setPropertyLight(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
-  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'light'});
-}
-export function setPropertyShadow(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
-  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'shadow'});
-}
-export function setPropertyAll(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
-  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'all'});
-}
-
-// ─── property root 별칭 (필드 프록시) ───
-export function propertyLight(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): PropertyDecorator {
+// ─── property root 별칭 ───
+export function propertyLight(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator & PropertyDecorator {
   return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'light'});
 }
-export function propertyShadow(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): PropertyDecorator {
+export function propertyShadow(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator & PropertyDecorator {
   return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'shadow'});
 }
-export function propertyAll(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): PropertyDecorator {
+export function propertyAll(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator & PropertyDecorator {
   return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'all'});
 }
 

package/src/decorators/applySlot.ts

@@ -114,7 +114,7 @@ export function applySlot(targetId: string, opt: OptionalType<ApplySlotOptions,
       const currentWin = conf.window;
       const swcId = this._swcId;
       const currentDoc = currentWin.document;
-      const hostSet = SwcUtils.getHelperAndHostSet(currentWin, this);
+      const hostSet = SwcUtils.getHelperAndHostSet(this);
       const pos = options.position;
 
       const resToNodes = (res: string | Node) => {
@@ -216,6 +216,6 @@ export function replaceChildrenTextSlot(targetId: string): MethodDecorator {
 
 // export const findAllApplySlotMetadata = (target: any): Map<string | symbol, ApplySlotMetadata> => {
 export const findAllApplySlotMetadata = (target: any): ApplySlotMetadata[] => {
-  const constructor = target instanceof Function ? target : target.constructor;
-  return ReflectUtils.getMetadata(APPLY_SLOT_METADATA_KEY, constructor);
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return ReflectUtils.findAllMetadata<any[]>(APPLY_SLOT_METADATA_KEY, constructor).flat();
 };

package/src/decorators/applyStyle.ts

@@ -39,7 +39,7 @@ export const STYLE_METADATA_KEY = Symbol.for('simple-web-component:style');
  */
 const resolveSelector = (selector: StyleSelector, 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) {
@@ -75,7 +75,7 @@ const getTargetElements = (selector: StyleSelector, 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;
@@ -139,7 +139,7 @@ function createStyleDecorator(action: StyleAction) {
           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 = options.root || 'auto';
             const targetEls = getTargetElements(selector, this, win, r);
 
@@ -183,9 +183,11 @@ function createStyleDecorator(action: StyleAction) {
         };
 
         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;
@@ -266,15 +268,7 @@ export const style = applyStyle;
 
 // ─── 편의 헬퍼 (selector/root 생략) ───
 
-export function styleThis(action?: StyleAction, options?: StyleQueryOptions): MethodDecorator;
-export function styleThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
-export function styleThis(actionOrTarget?: StyleAction | Object, optionsOrPropertyKey?: StyleQueryOptions | string | symbol, descriptor?: PropertyDescriptor): any {
-  if ((typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol') && descriptor !== undefined) {
-    return (applyStyle('$this', undefined as any, {}) as any)(actionOrTarget, optionsOrPropertyKey, descriptor);
-  }
-  return applyStyle('$this', actionOrTarget as any, optionsOrPropertyKey as StyleQueryOptions);
-}
-export function styleAppHost(action?: StyleAction, options?: StyleQueryOptions): MethodDecorator;
+export function styleAppHost(action: StyleAction, options?: StyleQueryOptions): MethodDecorator;
 export function styleAppHost(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function styleAppHost(actionOrTarget?: StyleAction | Object, optionsOrPropertyKey?: StyleQueryOptions | string | symbol, descriptor?: PropertyDescriptor): any {
   if ((typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol') && descriptor !== undefined) {

package/src/decorators/around.ts

@@ -0,0 +1,196 @@
+import { ReflectUtils } from '@dooboostore/core';
+import { ensureInit } from './elementDefine';
+import { SwcUtils } from '../utils/Utils';
+import { HelperHostSet } from '../types';
+
+export const AROUND_METADATA_KEY = Symbol.for('simple-web-component:around');
+
+export interface AroundMetadata {
+  propertyKey: string | symbol;
+}
+
+export interface AroundPropertyOptions<Value = any> {
+  /**
+   * get할 때 (helperHostSet, 저장된 값)을 받아 실제로 읽는 쪽에 돌려줄 값을 리턴한다.
+   * undefined 리턴이면 저장값 그대로 통과. 안 주면 그대로 통과.
+   */
+  get?: (helperHostSet: HelperHostSet, stored: Value) => Value | void;
+  /**
+   * set할 때 (helperHostSet, 대입되는 값)을 받아 실제로 저장할 값을 리턴한다.
+   * 안 주면 그대로 통과.
+   */
+  set?: (helperHostSet: HelperHostSet, incoming: Value) => Value | void;
+}
+export interface AroundOptions<Args extends any[] = any[], Return = any> {
+  /**
+   * 원본 실행 전에, (helperHostSet, 호출자가 넘긴 인자 배열)을 받아
+   * 실제로 원본에 넘길 인자 배열을 리턴한다. undefined 리턴이면 인자 그대로 통과.
+   * 원본이 Promise를 리턴하면 before도 Promise를 리턴할 수 있다 —
+   * resolve된 값으로 원본이 호출된다 (이 경우 래퍼도 Promise 반환).
+   * 원본이 sync면 before도 sync여야 한다 (async를 달면 호출 측이 모르는 Promise가 새어나감).
+   * 안 주면 그대로 통과.
+   *
+   * 제네릭 생략 시(Return=any) 양쪽 다 허용이라 느슨하게 동작하고,
+   * `@around<[number], number>`처럼 명시하면 위 규칙이 검사된다.
+   */
+  before?: (helperHostSet: HelperHostSet, args: Args) => Return extends Promise<any> ? Args | void | Promise<Args | void> : Args | void;
+  /**
+   * 원본 실행 후에, (helperHostSet, 리턴값)을 받아 실제로 호출자에게
+   * 돌려줄 값을 리턴한다.
+   *   원본이 Promise를 리턴하면 resolve된 값(Awaited<Return>)을 넘겨받고,
+   *   after의 리턴값이 그대로 최종 Promise의 resolve 값이 된다.
+   *   after가 Promise를 리턴해도 된다 — resolve된 값이 최종값이 된다.
+   * 안 주면 그대로 통과.
+   *
+   * 제네릭을 명시하면 훅 입출력이 검사된다:
+   * `@around<[string], Promise<string>>({ after: (h, r) => ... })`
+   * (r은 string으로 추론). 생략하면 any로 느슨하게 동작한다.
+   * 단, legacy 데코레이터 한계상 래핑된 메서드의 겉보기 시그니처는 안 바뀌므로
+   * async 훅을 단 sync 메서드는 호출 측에서 Promise로 취급해야 한다.
+   */
+  after?: (helperHostSet: HelperHostSet, result: Awaited<Return>) => Return | Promise<Awaited<Return>>;
+  /**
+   * before/원본/after 실행이 끝나면 성공·실패와 무관하게 항상 실행되는 정리 훅 (try/finally의 finally).
+   * 두 번째 인자로 컨텍스트를 받는다:
+   *   - args: 호출자가 넘긴 원본 인자 배열(before 가공 전)
+   *   - result: 성공 시 최종 리턴값(after 적용 후). 실패 시 없음.
+   *   - error: throw/reject 시 그 에러. 성공 시 없음.
+   * 에러를 삼키지 않는다 — finally를 먼저 돌린 뒤 원래 에러/리턴값이 그대로 전파된다.
+   * sync 원본 + sync finally면 sync로 유지되지만, finally가 Promise를 리턴하면
+   * 래퍼는 Promise를 반환한다(async before/after와 동일 규칙).
+   */
+  finally?: (helperHostSet: HelperHostSet, ctx: { args: Args; result?: Awaited<Return>; error?: any }) => void | Promise<void>;
+}
+
+/** 인스턴스에서 HelperHostSet을 해석한다 — 실패(SSR/미초기화)하면 최소 폴백을 돌려준다. */
+const resolveHelperHostSet = (inst: any): HelperHostSet => {
+  try {
+    ensureInit(inst);
+    return SwcUtils.getHelperAndHostSet(inst);
+  } catch {
+    return { $this: inst } as HelperHostSet;
+  }
+};
+
+/**
+ * 메서드에 걸면 호출을 감싸서 호출 전(인자 가공)/후(리턴값 가공) 훅을 건다 - AOP의 "around advice".
+ *
+ * @around({
+ *   before: (h, args: [number, string]) => [args[0], args[1].toUpperCase()],
+ *   after: (h, r: string) => r + '!'
+ * })
+ * greet(a: number, b: string) { return `${a}:${b}`; }
+ *
+ * 프로퍼티(필드)에 걸면 get/set을 가로챈다 - get은 get, set은 set이 호출된다.
+ * (프로퍼티 경로에서는 값이 배열이 아니라 단일값으로 넘어간다)
+ * 필드 이니셜라이저(`wow = 'x'`)가 있어도 된다 — ensureInit이 state처럼
+ * 초기값을 살려 setter 경유로 정리하므로 초기값에도 set()이 적용된다.
+ * (단, custom element가 아닌 일반 클래스에서는 ensureInit이 안 돌므로
+ * `declare` + 생성자 대입으로 쓸 것)
+ *
+ * @around({
+ *   get: (h, stored: string) => stored?.toUpperCase(),
+ *   set: (h, incoming: string) => incoming?.trim()
+ * })
+ * wow: string = '  hi ';
+ */
+export function around<Args extends any[] = any[], Return = any>(options: AroundOptions<NoInfer<Args>, NoInfer<Return>>): MethodDecorator;
+export function around<Value = any>(options: AroundPropertyOptions<NoInfer<Value>>): PropertyDecorator;
+export function around(options: any = {}): MethodDecorator & PropertyDecorator {
+  return ((target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor) => {
+    // 메서드: descriptor.value가 실제 함수일 때만 (이미 정의된 접근자를 감싸는 건 지원 범위 밖)
+    if (descriptor && typeof descriptor.value === 'function') {
+      const original = descriptor.value;
+      const runAfter = function (this: any, hhs: HelperHostSet, res: any) {
+        if (!options.after) return res;
+        const run = (v: any) => (options.after as any).call(this, hhs, v);
+        // after가 Promise를 리턴하면 resolve된 값이 최종값이 된다 (then 플래트닝).
+        return res && typeof res.then === 'function' ? res.then(run) : run(res);
+      };
+      descriptor.value = function (this: any, ...args: any[]) {
+        const hhs = resolveHelperHostSet(this);
+        const self = this;
+        const callOriginal = (finalArgs: any[]) => runAfter.call(self, hhs, original.apply(self, finalArgs));
+        const runBody = () => {
+          if (options.before) {
+            const mapped = (options.before as any).call(self, hhs, args);
+            if (mapped && typeof mapped.then === 'function') {
+              // async before — resolve된 인자로 원본 호출, 래퍼는 Promise 반환.
+              // (sync 원본 + sync 훅일 때만 sync 반환이 유지된다)
+              return mapped.then((m: any) => {
+                if (Array.isArray(m)) return callOriginal(m);
+                if (m !== undefined) return callOriginal([m]);
+                return callOriginal(args);
+              });
+            }
+            if (Array.isArray(mapped)) return callOriginal(mapped);
+            if (mapped !== undefined) return callOriginal([mapped]);
+          }
+          return callOriginal(args);
+        };
+        if (!options.finally) return runBody();
+        // sync/async 투명성을 지키는 try/finally — 에러는 삼키지 않고 finally 후 전파.
+        const afterFin = (settle: () => any, ctx: { args: any[]; result?: any; error?: any }) => {
+          const f = (options.finally as any).call(self, hhs, ctx);
+          return f && typeof f.then === 'function' ? f.then(settle) : settle();
+        };
+        let out: any;
+        try {
+          out = runBody();
+        } catch (e) {
+          return afterFin(() => { throw e; }, { args, error: e });
+        }
+        if (out && typeof out.then === 'function') {
+          return out.then(
+            (v: any) => afterFin(() => v, { args, result: v }),
+            (e: any) => afterFin(() => { throw e; }, { args, error: e })
+          );
+        }
+        return afterFin(() => out, { args, result: out });
+      };
+      return descriptor;
+    }
+
+    // 프로퍼티: ensureInit에서 own property를 정리할 수 있도록 메타데이터 등록 (state.ts와 동일 패턴).
+    // 필드 이니셜라이저가 있으면 own property가 accessor를 가리므로 getter가 영원히 안 불림 —
+    // getter 안의 자체이주는 마지막 안전망일 뿐, 실질적인 살림은 ensureInit이 한다.
+    const constructor = (target as any).constructor;
+    let aroundList = ReflectUtils.getOwnMetadata(AROUND_METADATA_KEY, constructor) as AroundMetadata[] | undefined;
+    if (!aroundList) {
+      aroundList = [];
+      ReflectUtils.defineMetadata(AROUND_METADATA_KEY, aroundList, constructor);
+    }
+    aroundList.push({ propertyKey });
+
+    // target은 prototype이라 여기 값을 직접 두면 모든 인스턴스가 공유해버린다.
+    // 인스턴스별로 따로 저장되도록 인스턴스 전용 Symbol 슬롯(this[storageKey])에 실제 값을 둔다.
+    const storageKey = Symbol(`around:${String(propertyKey)}`);
+    const getFn = (options as AroundPropertyOptions).get as unknown as ((hhs: HelperHostSet, value: any) => any) | undefined;
+    const setFn = (options as AroundPropertyOptions).set as unknown as ((hhs: HelperHostSet, value: any) => any) | undefined;
+    Object.defineProperty(target, propertyKey, {
+      get(this: any) {
+        // 안전망: 누군가 plain delete로 own을 걷어낸 뒤라면 여기서 슬롯으로 회수한다.
+        // (정상 경로에서는 ensureInit이 이미 setter 경유로 정리했으므로 own이 없음)
+        const own = Object.getOwnPropertyDescriptor(this, propertyKey);
+        if (own && 'value' in own) {
+          delete this[propertyKey];
+          this[storageKey] = setFn ? setFn.call(this, resolveHelperHostSet(this), own.value) : own.value;
+        }
+        const raw = this[storageKey];
+        if (!getFn) return raw;
+        const mapped = getFn.call(this, resolveHelperHostSet(this), raw);
+        return mapped === undefined ? raw : mapped;
+      },
+      set(this: any, value: any) {
+        this[storageKey] = setFn ? setFn.call(this, resolveHelperHostSet(this), value) : value;
+      },
+      enumerable: true,
+      configurable: true
+    });
+  }) as MethodDecorator & PropertyDecorator;
+}
+
+export const findAllAroundMetadata = (target: any): AroundMetadata[] => {
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return ReflectUtils.findAllMetadata<any[]>(AROUND_METADATA_KEY, constructor).flat();
+};

package/src/decorators/changedAttribute.ts

@@ -5,6 +5,12 @@ export const ON_ATTRIBUTE_CHANGED_METADATA_KEY = Symbol.for('simple-web-componen
 export interface ChangedAttributeThisOptions  {
   type?: typeof Number | typeof Boolean | typeof String;
   while?: 'connected';
+  /** 속성 변경 시 핸들러 실행 여부 게이트. Promise<boolean>도 되어 async 판정 가능. false면 스킵. */
+  filter?: (value: any, meta: { currentThis: any; helper: HelperHostSet }) => boolean | Promise<boolean>;
+  /** filter 통과 후 핸들러 직전 훅. await되고, 리턴값은 @changedAttributeBeforeReturn 으로 핸들러에 주입된다. */
+  before?: (value: any, meta: { currentThis: any; helper: HelperHostSet }) => any | Promise<any>;
+  /** 핸들러가 성공/실패해도 항상 실행되는 정리 훅. ctx로 인자/결과/에러를 받는다. 에러는 로깅됨. */
+  finally?: (value: any, meta: { currentThis: any; helper: HelperHostSet }, ctx: { args: any[]; result?: any; error?: any }) => any | Promise<any>;
 }
 
 export interface ChangedAttributeThisMetadata {
@@ -13,13 +19,6 @@ export interface ChangedAttributeThisMetadata {
   options: ChangedAttributeThisOptions;
 }
 
-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;
-  return val;
-};
-
 const applyChangedAttribute = (attributeName: string | undefined, options: ChangedAttributeThisOptions, target: Object, propertyKey: string | symbol): void => {
   const constructor = target.constructor;
   let metaList = ReflectUtils.getOwnMetadata(ON_ATTRIBUTE_CHANGED_METADATA_KEY, constructor) as ChangedAttributeThisMetadata[];
@@ -36,7 +35,7 @@ const applyChangedAttribute = (attributeName: string | undefined, options: Chang
   });
 };
 
-export function changedAttribute(attributeName?: string, options?: ChangedAttributeThisOptions): MethodDecorator;
+export function changedAttribute(attributeName: string, options?: ChangedAttributeThisOptions): MethodDecorator;
 export function changedAttribute(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 /**
  * @changedAttributeThis decorator - fires when any attribute on $this changes.
@@ -48,7 +47,7 @@ export function changedAttribute(attributeNameOrTarget?: string | Object, option
     applyChangedAttribute(undefined, {}, attributeNameOrTarget as Object, optionsOrPropertyKey);
     return;
   }
-  // 옵션과 함께: @changedAttribute() / @changedAttribute('name', options?)
+  // 옵션과 함께: @changedAttribute('name', options?)
   const attributeName = attributeNameOrTarget as string | undefined;
   const options = (optionsOrPropertyKey as ChangedAttributeThisOptions) ?? {};
   return (target: Object, propertyKey: string | symbol) => {
@@ -57,12 +56,12 @@ export function changedAttribute(attributeNameOrTarget?: string | Object, option
 }
 
 export const getChangedAttributeMetadata = (target: any): ChangedAttributeThisMetadata[] | undefined => {
-  const constructor = target instanceof Function ? target : target.constructor;
-  return ReflectUtils.getMetadata(ON_ATTRIBUTE_CHANGED_METADATA_KEY, constructor);
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return ReflectUtils.findAllMetadata<any[]>(ON_ATTRIBUTE_CHANGED_METADATA_KEY, constructor).flat();
 };
 
 export const findAllAttributeChangedMetadata = (target: any): Map<string, ChangedAttributeThisMetadata[]> => {
-  const constructor = target instanceof Function ? target : target.constructor;
+  const constructor = typeof target === 'function' ? target : target.constructor;
   const metaList = ReflectUtils.findAllMetadata<ChangedAttributeThisMetadata[]>(ON_ATTRIBUTE_CHANGED_METADATA_KEY, constructor) || [];
 
   const result = new Map<string, ChangedAttributeThisMetadata[]>();
@@ -85,7 +84,9 @@ export const convertAttributeValue = (val: any, type?: typeof Number | typeof Bo
 // ChangedAttributeLifeCycler
 // ─────────────────────────────────────────────────────────────────────────────
 import { ElementDefineLifeCycler, HelperHostSet } from '../types';
-import { getAttributeValue } from './applyAttribute';
+import { getAttributeValue, convertValue } from './applyAttribute';
+import { SwcUtils } from '../utils/Utils';
+import { buildSwcParameterArgs } from './parameter';
 
 export class ChangedAttributeLifeCycler implements ElementDefineLifeCycler {
   private attrChangeMap: Map<string, ChangedAttributeThisMetadata[]> | null = null;
@@ -109,7 +110,7 @@ export class ChangedAttributeLifeCycler implements ElementDefineLifeCycler {
       for (const meta of metaList) {
         if (meta.options.while === 'connected') {
           const val = getAttributeValue(inst, name, { type: meta.options.type });
-          if (val !== null) inst[meta.propertyKey](val, null, name, helperHostSet);
+          if (val !== null) this.runChanged(helperHostSet, meta, val, null, name);
         }
       }
     }
@@ -122,7 +123,30 @@ export class ChangedAttributeLifeCycler implements ElementDefineLifeCycler {
     if (!metaList) return;
     for (const meta of metaList) {
       if (meta.options.while === 'connected' && !inst.__swc_connected) continue;
-      inst[meta.propertyKey](convertAttributeValue(newVal, meta.options.type), old, name, helperHostSet);
+      this.runChanged(helperHostSet, meta, convertAttributeValue(newVal, meta.options.type), old, name);
     }
   }
+
+  // filter(async)/before/finally + @changedAttributeBeforeReturn 주입. fire-and-forget.
+  private runChanged(helperHostSet: HelperHostSet, meta: ChangedAttributeThisMetadata, value: any, old: string | null, name: string): void {
+    const inst = helperHostSet.$this;
+    const opts = meta.options;
+    void (async () => {
+      const helper = SwcUtils.getHelperAndHostSet(inst);
+      if (opts.filter && !(await opts.filter(value, { currentThis: inst, helper }))) return;
+      const hostSet = SwcUtils.getHostSet(inst);
+      const helperSet = SwcUtils.getHelperSet(helperHostSet.$w);
+      const legacyArgs = [value, old, name, helper];
+      const buildArgs = (beforeReturn: any) => buildSwcParameterArgs(inst, meta.propertyKey, {
+        hostSet, helperHostSet: helper, helperSet, changedAttributeBeforeReturn: beforeReturn
+      }, [...legacyArgs, beforeReturn]);
+      let args = buildArgs(undefined);
+      if (opts.before) { const br = await opts.before(value, { currentThis: inst, helper }); args = buildArgs(br); }
+      let result: any, error: any;
+      try { result = await inst[meta.propertyKey](...args); }
+      catch (e) { error = e; }
+      finally { if (opts.finally) await opts.finally(value, { currentThis: inst, helper }, { args, result, error }); }
+      if (error) throw error;
+    })().catch(e => console.error('[SWC] changedAttribute handler error:', e));
+  }
 }