@dooboostore/simple-web-component 1.0.49 → 1.0.51

package/src/decorators/mutationObserver.ts

@@ -1,9 +1,15 @@
 import { ReflectUtils } from '@dooboostore/core';
 import { SpecialSelector, SwcQueryOptions, SwcSelector, SwcFnSelector, HelperHostSet } from '../types';
+import { buildSwcParameterArgs } from './parameter';
 
 // 공통 옵션 — root·delegate 없음 (MutationObserverInit + filter/removeObserver)
 export interface MutationObserverBaseOptions extends MutationObserverInit {
-  filter?: (matchedEls: HTMLElement[], meta: { currentThis: any, helper: HelperHostSet }) => boolean;
+  /** 매칭 시 핸들러 실행 여부 게이트. Promise<boolean>도 되어 async 판정 가능. false면 스킵. */
+  filter?: (matchedEls: HTMLElement[], meta: { currentThis: any, helper: HelperHostSet }) => boolean | Promise<boolean>;
+  /** filter 통과 후 핸들러 직전 훅. await되고, 리턴값은 @mutationObserverBeforeReturn 으로 핸들러에 주입된다. */
+  before?: (matchedEls: HTMLElement[], meta: { currentThis: any, helper: HelperHostSet }) => any | Promise<any>;
+  /** 핸들러가 성공/실패해도 항상 실행되는 정리 훅. ctx로 결과/에러를 받는다. 에러는 로깅됨. */
+  finally?: (matchedEls: HTMLElement[], meta: { currentThis: any, helper: HelperHostSet }, ctx: { args: any[]; result?: any; error?: any }) => any | Promise<any>;
   // observer 해제(disconnected) 시 호출되는 콜백. 첫 번째 인자는 observe된 target element, 두 번째는 사용자 옵션 객체.
   removeObserver?: (target: Element, optionValue: MutationObserverQueryOptions) => void;
 }
@@ -24,112 +30,124 @@ export interface MutationObserverMetadata {
 
 export const MUTATION_OBSERVER_METADATA_KEY = Symbol.for('simple-web-component:mutation-observer');
 
+const applyMutationObserver = (selector: SwcSelector, options: MutationObserverQueryOptions, targetObj: Object, propertyKey: string | symbol): void => {
+  const constructor = targetObj.constructor;
+  let observers = ReflectUtils.getOwnMetadata(MUTATION_OBSERVER_METADATA_KEY, constructor) as MutationObserverMetadata[] | undefined;
+  if (!observers) {
+    observers = [];
+    ReflectUtils.defineMetadata(MUTATION_OBSERVER_METADATA_KEY, observers, constructor);
+  }
+  observers.push({ propertyKey, selector, options });
+};
+
+const resolveMutationObserverArgs = (
+  selectorOrOptions: SwcSelector | MutationObserverQueryOptions | undefined,
+  maybeOptions: MutationObserverQueryOptions | undefined,
+  extra: Partial<MutationObserverQueryOptions>
+): { selector: SwcSelector; options: MutationObserverQueryOptions } => {
+  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
+    return { selector: selectorOrOptions, options: { ...(maybeOptions ?? {}), ...extra } };
+  }
+  return { selector: '$this', options: { ...(selectorOrOptions ?? {}), ...extra } };
+};
+
+/**
+ * selectorOrOptionsOrTarget/maybeOptionsOrPropertyKey/descriptor을 받아 bare(@decorator)와
+ * factory(@decorator(...), 빈 괄호는 타입에서 막음) 호출을 모두 처리하는 공통 디스패처.
+ * extra는 Light/Shadow/All/Delegate 변형이 강제로 덧씌우는 옵션(root, delegate 등)이다.
+ */
+const dispatchMutationObserver = (
+  selectorOrOptionsOrTarget: SwcSelector | MutationObserverQueryOptions | Object | undefined,
+  maybeOptionsOrPropertyKey: MutationObserverQueryOptions | string | symbol | undefined,
+  descriptor: PropertyDescriptor | undefined,
+  extra: Partial<MutationObserverQueryOptions>
+): MethodDecorator | void => {
+  if ((typeof maybeOptionsOrPropertyKey === 'string' || typeof maybeOptionsOrPropertyKey === 'symbol') && descriptor !== undefined) {
+    // 옵션 없이: @decorator — 자기 자신의 하위 전체(childList + subtree)를 본다. 범위를 좁히려면 옵션을 명시.
+    applyMutationObserver('$this', { subtree: true, ...extra }, selectorOrOptionsOrTarget as Object, maybeOptionsOrPropertyKey);
+    return;
+  }
+  // 옵션과 함께: @decorator(selector, options) / @decorator(options)
+  const { selector, options } = resolveMutationObserverArgs(
+    selectorOrOptionsOrTarget as SwcSelector | MutationObserverQueryOptions | undefined,
+    maybeOptionsOrPropertyKey as MutationObserverQueryOptions | undefined,
+    extra
+  );
+  return (targetObj: Object, propertyKey: string | symbol) => {
+    applyMutationObserver(selector, options, targetObj, propertyKey);
+  };
+};
+
 export function mutationObserver(target: SpecialSelector, options?: MutationObserverQueryOptions): MethodDecorator;
 export function mutationObserver(selector: string, options?: MutationObserverQueryOptions): MethodDecorator;
 export function mutationObserver(selector: SwcFnSelector, options?: MutationObserverNonQueryOptions): MethodDecorator;
-export function mutationObserver(options?: MutationObserverQueryOptions): MethodDecorator;
+export function mutationObserver(options: MutationObserverQueryOptions): MethodDecorator;
+export function mutationObserver(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 /**
  * @mutationObserver decorator to observe DOM mutations.
+ * 옵션 없이 `@mutationObserver` 그대로 붙여도 되고, `@mutationObserver(...)`처럼 셀렉터/옵션을 줄 수도 있다.
  */
-export function mutationObserver(selectorOrOptions?: SwcSelector | MutationObserverQueryOptions, maybeOptions?: MutationObserverQueryOptions): MethodDecorator {
-  return (targetObj: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
-    let selector: SwcSelector = '$this';
-    let options: MutationObserverQueryOptions = {};
-
-    if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-      selector = selectorOrOptions;
-      options = maybeOptions ?? {};
-    } else {
-      selector = '$this';
-      options = selectorOrOptions ?? {};
-    }
-
-    const constructor = targetObj.constructor;
-
-    let observers = ReflectUtils.getMetadata<MutationObserverMetadata[]>(MUTATION_OBSERVER_METADATA_KEY, constructor);
-    if (!observers) {
-      observers = [];
-      ReflectUtils.defineMetadata(MUTATION_OBSERVER_METADATA_KEY, observers, constructor);
-    }
-
-    observers.push({ propertyKey, selector, options });
-  };
+export function mutationObserver(selectorOrOptionsOrTarget?: SwcSelector | MutationObserverQueryOptions | Object, maybeOptionsOrPropertyKey?: MutationObserverQueryOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget, maybeOptionsOrPropertyKey, descriptor, {});
 }
 
-export function mutationObserverThis<TEvent extends Event = Event>(options?: MutationObserverQueryOptions): MethodDecorator {
-  return mutationObserver('$this', options);
-}
 
 // ─── root별 delegate 헬퍼 (addEventListener와 동일 패턴) ───
 
 export function mutationObserverDelegateLight(selector: string, options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegateLight(options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegateLight(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'light', delegate: true});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'light', delegate: true});
+export function mutationObserverDelegateLight(options: MutationObserverBaseOptions): MethodDecorator;
+export function mutationObserverDelegateLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverDelegateLight(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'light', delegate: true });
 }
 
 export function mutationObserverDelegateShadow(selector: string, options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegateShadow(options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegateShadow(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'shadow', delegate: true});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'shadow', delegate: true});
+export function mutationObserverDelegateShadow(options: MutationObserverBaseOptions): MethodDecorator;
+export function mutationObserverDelegateShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverDelegateShadow(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'shadow', delegate: true });
 }
 
 export function mutationObserverDelegateAll(selector: string, options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegateAll(options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegateAll(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'all', delegate: true});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'all', delegate: true});
+export function mutationObserverDelegateAll(options: MutationObserverBaseOptions): MethodDecorator;
+export function mutationObserverDelegateAll(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverDelegateAll(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'all', delegate: true });
 }
 
 export function mutationObserverDelegate(selector: string, options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegate(options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegate(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'auto', delegate: true});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'auto', delegate: true});
+export function mutationObserverDelegate(options: MutationObserverBaseOptions): MethodDecorator;
+export function mutationObserverDelegate(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverDelegate(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'auto', delegate: true });
 }
 
 // ─── root별 일반 헬퍼 (delegate 없이, 셀렉터 생략 시 $this) ───
 
 export function mutationObserverLight(selector: string, options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
-export function mutationObserverLight(options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
-export function mutationObserverLight(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'light'});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'light'});
+export function mutationObserverLight(options: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
+export function mutationObserverLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverLight(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'light' });
 }
 
 export function mutationObserverShadow(selector: string, options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
-export function mutationObserverShadow(options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
-export function mutationObserverShadow(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'shadow'});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'shadow'});
+export function mutationObserverShadow(options: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
+export function mutationObserverShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverShadow(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'shadow' });
 }
 
 export function mutationObserverAll(selector: string, options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
-export function mutationObserverAll(options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
-export function mutationObserverAll(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'all'});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'all'});
+export function mutationObserverAll(options: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
+export function mutationObserverAll(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverAll(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'all' });
 }
 
 export function getMutationObserverMetadata(target: any): MutationObserverMetadata[] | undefined {
-  const constructor = target instanceof Function ? target : target.constructor;
-  return ReflectUtils.getMetadata(MUTATION_OBSERVER_METADATA_KEY, constructor);
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return ReflectUtils.findAllMetadata<any[]>(MUTATION_OBSERVER_METADATA_KEY, constructor).flat();
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -137,20 +155,21 @@ export function getMutationObserverMetadata(target: any): MutationObserverMetada
 // observer 를 직접 생성하지 않고 OnConnectedResult 를 반환한다.
 // elementDefine 이 수집된 MutationObserverSet 으로 observer 를 생성한다.
 // ─────────────────────────────────────────────────────────────────────────────
-import { ElementDefineLifeCycler, MutationObserverSet, MutationObserverSetEntry, ObserverObserveTarget, OnConnectedResult } from '../types';
+import { ElementDefineLifeCycler, inObserverScope, MutationObserverSet, MutationObserverSetEntry, ObserverObserveTarget, ObserverScope, OnConnectedResult, ResizeObserverSet } from '../types';
 import { SwcUtils } from '../utils/Utils';
 
 export class MutationObserverLifeCycler implements ElementDefineLifeCycler {
   private readonly removeObserverCallbacksMap = new WeakMap<Element, Array<{ fn: (target: Element, opts: unknown) => void; target: any; opts: unknown }>>();
 
-  onConnected(helperHostSet: HelperHostSet): OnConnectedResult | void {
+  onConnected(helperHostSet: HelperHostSet, _set?: ResizeObserverSet, scope?: ObserverScope): OnConnectedResult | void {
     const inst = helperHostSet.$this;
     const currentWin = helperHostSet.$w;
 
-    const removeObserverCallbacks: Array<{ fn: (target: Element, opts: unknown) => void; target: any; opts: unknown }> = [];
+    // 'rest' 는 같은 connect 의 'self' 뒤에 오므로 이어 붙이고, 그 외(새 connect)는 새로 시작한다.
+    const removeObserverCallbacks = (scope === 'rest' && this.removeObserverCallbacksMap.get(inst)) || [];
     this.removeObserverCallbacksMap.set(inst, removeObserverCallbacks);
 
-    const allMeta = getMutationObserverMetadata(inst) ?? [];
+    const allMeta = (getMutationObserverMetadata(inst) ?? []).filter(m => inObserverScope(m, scope));
     // 처리할 메타가 없으면 observer 불필요
     if (allMeta.length === 0) return;
 
@@ -180,13 +199,19 @@ export class MutationObserverLifeCycler implements ElementDefineLifeCycler {
         return init;
       };
 
-      const fnObservedSets = new Map<MutationObserverMetadata, WeakSet<Element>>();
+      // non-delegate 메타별 observe 대상. MO 는 인스턴스당 1개를 모든 메타가 공유하므로(옵션도 합집합),
+      // 메타는 자기 대상(subtree 면 그 하위)에서 온 레코드만 받는다.
+      const observedNodes = new Map<MutationObserverMetadata, Node[]>();
+      const owns = (meta: MutationObserverMetadata, m: MutationRecord): boolean =>
+        (observedNodes.get(meta) ?? []).some(o => o === m.target || (!!meta.options.subtree && o.contains(m.target)));
 
       const callback = (mutations: MutationRecord[], obs: MutationObserver) => {
         // ── MutationObserver 메타 콜백 ──
         for (const meta of metas) {
           const { selector, options } = meta;
           let matchedEls: HTMLElement[] = [];
+          // 핸들러에 넘길 레코드 — non-delegate 는 자기 대상 레코드만 (옵저버는 공유라 배치에 다른 대상 레코드가 섞인다)
+          let records = mutations;
 
           const typeMatches = (m: MutationRecord): boolean => {
             const has = !!(options.childList || options.attributes || options.characterData);
@@ -196,8 +221,8 @@ export class MutationObserverLifeCycler implements ElementDefineLifeCycler {
             return true;
           };
 
-          const collect = (matchesSel: (n: any) => boolean) =>
-            mutations.flatMap(m => {
+          const collect = (matchesSel: (n: any) => boolean, records: MutationRecord[] = mutations) =>
+            records.flatMap(m => {
               if (!typeMatches(m)) return [];
               const els: HTMLElement[] = [];
               if (matchesSel(m.target)) els.push(m.target as HTMLElement);
@@ -206,26 +231,27 @@ export class MutationObserverLifeCycler implements ElementDefineLifeCycler {
               return els;
             });
 
-          if (options.delegate && typeof selector === 'string') {
-            const isThis = selector === '$this' || selector === '';
+          if (typeof selector === 'string' && (selector === '$this' || selector === '')) {
+            // 자기 자신을 볼 때는 바뀐/추가된 노드가 아니라 자기 자신 하나 — 해당 종류의 변화가 있었으면 [inst]
+            records = mutations.filter(m => typeMatches(m) && owns(meta, m));
+            matchedEls = records.length ? [inst as HTMLElement] : [];
+          } else if (options.delegate && typeof selector === 'string') {
             matchedEls = collect(n => {
               if (!n || n.nodeType !== 1) return false;
-              if (isThis) return true;
               const el = n as HTMLElement;
               return el.matches?.(selector) || !!el.closest?.(selector);
             });
           } else if (typeof selector === 'string') {
-            const isThis = selector === '$this' || selector === '';
-            matchedEls = collect(n => {
+            records = mutations.filter(m => owns(meta, m));
+            matchedEls = records.length ? collect(n => {
               if (!n || n.nodeType !== 1) return false;
-              if (isThis) return true;
               return (n as HTMLElement).matches?.(selector);
-            });
+            }, records) : [];
           } else if (typeof selector === 'function') {
-            const set = fnObservedSets.get(meta);
-            matchedEls = mutations.filter(m => typeMatches(m))
-              .map(m => m.target as HTMLElement)
-              .filter(t => t && t.nodeType === 1 && (set ? set.has(t) : false));
+            // 레코드가 속한 observe 대상 요소 (subtree 면 하위 변경도 그 대상으로 묶는다)
+            records = mutations.filter(m => typeMatches(m) && owns(meta, m));
+            matchedEls = (observedNodes.get(meta) ?? []).filter(o =>
+              records.some(m => o === m.target || (!!options.subtree && o.contains(m.target)))) as HTMLElement[];
           } else {
             matchedEls = mutations.filter(m => typeMatches(m))
               .map(m => m.target as HTMLElement)
@@ -233,11 +259,24 @@ export class MutationObserverLifeCycler implements ElementDefineLifeCycler {
           }
 
           if (matchedEls.length === 0) continue;
-          if (options.filter) {
-            if (!options.filter(matchedEls, { currentThis: inst, helper: helperHostSet })) continue;
-          }
-          const hostSet = SwcUtils.getHostSet(inst);
-          inst[meta.propertyKey](matchedEls, mutations, obs, { ...hostSet, $root: root });
+          // fire-and-forget async 러너 — filter(async)/before/finally + @mutationObserverBeforeReturn 주입.
+          void (async () => {
+            const helper = SwcUtils.getHelperAndHostSet(inst);
+            if (options.filter && !(await options.filter(matchedEls, { currentThis: inst, helper }))) return;
+            const hostSet = SwcUtils.getHostSet(inst);
+            const helperSet = SwcUtils.getHelperSet(helperHostSet.$w);
+            const legacyArgs = [matchedEls, records, obs, { ...hostSet, $root: root }];
+            const buildArgs = (beforeReturn: any) => buildSwcParameterArgs(inst, meta.propertyKey, {
+              hostSet, helperHostSet: helper, helperSet, mutationObserverBeforeReturn: beforeReturn
+            }, [...legacyArgs, beforeReturn]);
+            let args = buildArgs(undefined);
+            if (options.before) { const br = await options.before(matchedEls, { currentThis: inst, helper }); args = buildArgs(br); }
+            let result: any, error: any;
+            try { result = await inst[meta.propertyKey](...args); }
+            catch (e) { error = e; }
+            finally { if (options.finally) await options.finally(matchedEls, { currentThis: inst, helper }, { args, result, error }); }
+            if (error) throw error;
+          })().catch(e => console.error('[SWC] mutationObserver handler error:', e));
         }
 
       };
@@ -255,20 +294,17 @@ export class MutationObserverLifeCycler implements ElementDefineLifeCycler {
         const { selector, options } = m;
         const mInit = initFrom(options);
         if (typeof selector === 'string') {
-          if (selector === '$this' || selector === '') {
-            observeTargets.push({ target: root, options: mInit });
-          } else {
-            root.querySelectorAll(selector).forEach(el => observeTargets.push({ target: el as Element, options: mInit }));
-          }
+          const nodes: Node[] = selector === '$this' || selector === '' ? [root] : Array.from(root.querySelectorAll(selector));
+          for (const n of nodes) observeTargets.push({ target: n as Element, options: mInit });
+          observedNodes.set(m, nodes);
         } else if (typeof selector === 'function') {
           const res = (selector as any)(inst, helperHostSet);
           let targets: HTMLElement[] = [];
           if (res instanceof currentWin.HTMLElement) targets = [res as HTMLElement];
           else if (res instanceof currentWin.NodeList) targets = Array.from(res as NodeList).filter((e: any) => e instanceof currentWin.HTMLElement) as HTMLElement[];
           else if (Array.isArray(res)) targets = res.filter((e: any) => e instanceof currentWin.HTMLElement) as HTMLElement[];
-          const set = new WeakSet<Element>();
-          for (const el of targets) { set.add(el); observeTargets.push({ target: el, options: mInit }); }
-          fnObservedSets.set(m, set);
+          for (const el of targets) observeTargets.push({ target: el, options: mInit });
+          observedNodes.set(m, targets);
         }
       }
 
@@ -301,4 +337,4 @@ export class MutationObserverLifeCycler implements ElementDefineLifeCycler {
     }
     this.removeObserverCallbacksMap.delete(inst);
   }
-}
+}

package/src/decorators/parameter.ts

@@ -0,0 +1,212 @@
+import { ReflectUtils } from '@dooboostore/core';
+
+/**
+ * @eventObject/@matchedElement/@hostSet/@helperHostSet/@helperSet/@swcAppRouterEvent/@appMessage/@eventBeforeReturn —
+ * @event/lifecycle/subscribeSwcAppRouteChange/subscribeSwcAppMessage
+ * 계열 핸들러의 파라미터를 순서 무관하게 선언할 수 있게 해주는 파라미터 데코레이터.
+ * @dooboostore/simple-boot의 @Inject와 동일한 인덱스 기반 메타데이터 패턴을 따른다:
+ * 데코레이터가 실행되는 순서가 아니라 실제 parameterIndex로 슬롯을 매칭하므로,
+ * 사용자가 파라미터 선언 순서를 자유롭게 바꿔도 된다.
+ */
+export type SwcParamKind = 'eventObject' | 'matchedElement' | 'hostSet' | 'helperHostSet' | 'helperSet' | 'swcAppRouterEvent' | 'appMessage' | 'eventBeforeReturn' | 'appMessageBeforeReturn' | 'routeChangeBeforeReturn' | 'eventMediaBeforeReturn' | 'mutationObserverBeforeReturn' | 'intersectionObserverBeforeReturn' | 'resizeObserverBeforeReturn' | 'changedAttributeBeforeReturn' | 'setTimeoutBeforeReturn' | 'setIntervalBeforeReturn' | 'fetchSettled'
+  | SwcRouteParamKind;
+
+/** 라우트 핸들러 전용 (subscribeSwcAppRouteChange 가 채움). kind 이름 = 데코레이터 이름 */
+export type SwcRouteParamKind =
+  | 'swcAppRouteQueryParam' | 'swcAppRouteFirstQueryParam' | 'swcAppRouteLastQueryParam' | 'swcAppRouteQueryParams'
+  | 'swcAppRouteQueryParamObject' | 'swcAppRouteFirstQueryParamObject' | 'swcAppRouteLastQueryParamObject' | 'swcAppRouteQueryParamsObject'
+  | 'swcAppRouteURLSearchParams'
+  | 'swcAppRoutePathVariable' | 'swcAppRouteFirstPathVariable' | 'swcAppRouteLastPathVariable' | 'swcAppRoutePathVariables'
+  | 'swcAppRoutePathVariableObject' | 'swcAppRouteFirstPathVariableObject' | 'swcAppRouteLastPathVariableObject' | 'swcAppRoutePathVariablesObject';
+
+const SWC_PARAMETER_METADATA_KEY = Symbol.for('simple-web-component:parameter');
+
+/** key: @swcAppRouteQueryParam('q') 처럼 키를 받는 파라미터 데코레이터의 키 */
+type SaveParamConfig = { index: number; kind: SwcParamKind; key?: string };
+
+const registerParam = (kind: SwcParamKind, target: Object, propertyKey: string | symbol | undefined, parameterIndex: number, key?: string) => {
+  if (!propertyKey) return;
+  const constructor = target.constructor;
+  const saves = (ReflectUtils.getOwnMetadata(SWC_PARAMETER_METADATA_KEY, constructor, propertyKey) ?? []) as SaveParamConfig[];
+  saves.push(key === undefined ? { index: parameterIndex, kind } : { index: parameterIndex, kind, key });
+  ReflectUtils.defineMetadata(SWC_PARAMETER_METADATA_KEY, saves, constructor, propertyKey);
+};
+
+/** 이벤트 핸들러의 원본 Event 객체를 주입한다. */
+export function eventObject(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('eventObject', target, propertyKey, parameterIndex);
+}
+
+/** delegate로 매칭된 실제 엘리먼트($matchedElement)를 주입한다. */
+export function matchedElement(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('matchedElement', target, propertyKey, parameterIndex);
+}
+
+/** HostSet(호스트 트리 정보 — $host/$hosts/$firstHost/$appHost 등)을 주입한다. */
+export function hostSet(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('hostSet', target, propertyKey, parameterIndex);
+}
+
+/** HelperHostSet(HelperSet + HostSet + $this 전체 묶음)을 주입한다. */
+export function helperHostSet(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('helperHostSet', target, propertyKey, parameterIndex);
+}
+
+/** HelperSet($d/$w/$q/$qa/$qi 등 순수 DOM/window 헬퍼, 호스트 트리 정보 없음)을 주입한다. */
+export function helperSet(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('helperSet', target, propertyKey, parameterIndex);
+}
+
+/** @subscribeSwcAppRouteChange 핸들러의 라우트 변경 이벤트({...RouterEventType, pathData})를 주입한다. */
+export function swcAppRouterEvent(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('swcAppRouterEvent', target, propertyKey, parameterIndex);
+}
+
+/** @subscribeSwcAppMessage 핸들러의 SwcAppMessage 페이로드를 주입한다. */
+export function appMessage(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('appMessage', target, propertyKey, parameterIndex);
+}
+
+/**
+ * @event 계열의 before 훅이 이번 호출에 리턴한 값을 주입한다.
+ * (before에서 async로 준비한 데이터를 핸들러가 받는 용도. before 없으면 undefined)
+ * 예: @eventClick({ before: () => loadUser() }) onClick(@eventBeforeReturn user) { ... }
+ */
+export function eventBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('eventBeforeReturn', target, propertyKey, parameterIndex);
+}
+
+/**
+ * @subscribeSwcAppMessage 의 before 훅이 이번 호출에 리턴한 값을 주입한다.
+ * (before에서 async로 준비한 데이터를 핸들러가 받는 용도. 없으면 undefined)
+ * 예: onMsg(@appMessage m, @appMessageBeforeReturn prepared) { ... }
+ */
+export function appMessageBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('appMessageBeforeReturn', target, propertyKey, parameterIndex);
+}
+
+/**
+ * @subscribeSwcAppRouteChange 의 before 훅이 이번 호출에 리턴한 값을 주입한다.
+ * (before에서 async 가드/준비한 데이터를 핸들러가 받는 용도. 없으면 undefined)
+ * 예: routeChanged(@swcAppRouterEvent e, @routeChangeBeforeReturn guard) { ... }
+ */
+export function routeChangeBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('routeChangeBeforeReturn', target, propertyKey, parameterIndex);
+}
+
+/**
+ * @eventMedia 의 before 훅이 이번 호출에 리턴한 값을 주입한다. (before 없으면 undefined)
+ * 예: @eventMediaChange('(max-width:600px)', { before: () => ... }) onMobile(@eventMediaBeforeReturn v) { ... }
+ */
+export function eventMediaBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('eventMediaBeforeReturn', target, propertyKey, parameterIndex);
+}
+
+/** @mutationObserver 의 before 훅이 이번 호출에 리턴한 값을 주입한다. (before 없으면 undefined) */
+export function mutationObserverBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('mutationObserverBeforeReturn', target, propertyKey, parameterIndex);
+}
+
+/** @intersectionObserver 의 before 훅이 이번 호출에 리턴한 값을 주입한다. (before 없으면 undefined) */
+export function intersectionObserverBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('intersectionObserverBeforeReturn', target, propertyKey, parameterIndex);
+}
+
+/** @resizeObserver 의 before 훅이 이번 호출에 리턴한 값을 주입한다. (before 없으면 undefined) */
+export function resizeObserverBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('resizeObserverBeforeReturn', target, propertyKey, parameterIndex);
+}
+
+/** @changedAttribute 의 before 훅이 이번 호출에 리턴한 값을 주입한다. (before 없으면 undefined) */
+export function changedAttributeBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('changedAttributeBeforeReturn', target, propertyKey, parameterIndex);
+}
+
+/** @setTimeout(type:'onConnected') 의 before 훅이 이번 호출에 리턴한 값을 주입한다. (before 없으면 undefined) */
+export function setTimeoutBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('setTimeoutBeforeReturn', target, propertyKey, parameterIndex);
+}
+
+/** @setInterval(type:'onConnected') 의 before 훅이 이번 호출에 리턴한 값을 주입한다. (before 없으면 undefined) */
+export function setIntervalBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('setIntervalBeforeReturn', target, propertyKey, parameterIndex);
+}
+
+/**
+ * @fetch(trigger:'before') 의 fetch settled 결과(PromiseSettledResult)를 주입한다.
+ * 예: save(@fetchSettled settled) { ... }
+ */
+export function fetchSettled(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('fetchSettled', target, propertyKey, parameterIndex);
+}
+
+export const getParameterMetadata = (target: any, propertyKey: string | symbol): SaveParamConfig[] => {
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return ReflectUtils.getMetadata(SWC_PARAMETER_METADATA_KEY, constructor, propertyKey) ?? [];
+};
+
+/**
+ * 위 파라미터 데코레이터 메타데이터가 하나라도 있으면 kind별 값을 index 순서에 맞게
+ * 배열로 조립하고, 하나도 없으면 기존 위치 인자(legacyArgs)를 그대로 반환한다 — 완전 하위호환.
+ */
+export const buildSwcParameterArgs = (
+  target: any,
+  propertyKey: string | symbol,
+  kindValues: Partial<Record<SwcParamKind, any>>,
+  legacyArgs: any[]
+): any[] => {
+  const saves = getParameterMetadata(target, propertyKey);
+  if (saves.length === 0) return legacyArgs;
+  const maxIndex = Math.max(...saves.map(s => s.index));
+  const args: any[] = new Array(maxIndex + 1);
+  for (const s of saves) {
+    const value = kindValues[s.kind];
+    // 키를 받는 kind 는 kindValues 에 (key) => 값 resolver 가 들어 있다
+    args[s.index] = s.key !== undefined && typeof value === 'function' ? value(s.key) : value;
+  }
+  return args;
+};
+
+// ─── 라우트 파라미터 (@subscribeSwcAppRouteChange 핸들러) ───
+// 규칙: 접두어 없음 = First, First/Last = 같은 키가 여러 번일 때 첫/마지막 값, 복수형 = 모든 값 배열.
+
+const keyedRouteParam = (kind: SwcRouteParamKind) => (key: string): ParameterDecorator =>
+  (target, propertyKey, parameterIndex) => registerParam(kind, target, propertyKey, parameterIndex, key);
+const routeParam = (kind: SwcRouteParamKind): ParameterDecorator =>
+  (target, propertyKey, parameterIndex) => registerParam(kind, target, propertyKey, parameterIndex);
+
+/** ?tag=a&tag=b → @swcAppRouteQueryParam('tag') = 'a' (없으면 null) */
+export const swcAppRouteQueryParam = keyedRouteParam('swcAppRouteQueryParam');
+/** = swcAppRouteQueryParam */
+export const swcAppRouteFirstQueryParam = keyedRouteParam('swcAppRouteFirstQueryParam');
+/** ?tag=a&tag=b → 'b' */
+export const swcAppRouteLastQueryParam = keyedRouteParam('swcAppRouteLastQueryParam');
+/** ?tag=a&tag=b → ['a', 'b'] */
+export const swcAppRouteQueryParams = keyedRouteParam('swcAppRouteQueryParams');
+/** ?tag=a&tag=b → { tag: 'a' } */
+export const swcAppRouteQueryParamObject = routeParam('swcAppRouteQueryParamObject');
+/** = swcAppRouteQueryParamObject */
+export const swcAppRouteFirstQueryParamObject = routeParam('swcAppRouteFirstQueryParamObject');
+/** ?tag=a&tag=b → { tag: 'b' } */
+export const swcAppRouteLastQueryParamObject = routeParam('swcAppRouteLastQueryParamObject');
+/** ?tag=a&tag=b → { tag: ['a', 'b'] } */
+export const swcAppRouteQueryParamsObject = routeParam('swcAppRouteQueryParamsObject');
+/** URLSearchParams 그대로 */
+export const swcAppRouteURLSearchParams = routeParam('swcAppRouteURLSearchParams');
+
+/** '/a/{id}/b/{id}' ← '/a/1/b/2' → @swcAppRoutePathVariable('id') = '1' */
+export const swcAppRoutePathVariable = keyedRouteParam('swcAppRoutePathVariable');
+/** = swcAppRoutePathVariable */
+export const swcAppRouteFirstPathVariable = keyedRouteParam('swcAppRouteFirstPathVariable');
+/** → '2' */
+export const swcAppRouteLastPathVariable = keyedRouteParam('swcAppRouteLastPathVariable');
+/** → ['1', '2'] */
+export const swcAppRoutePathVariables = keyedRouteParam('swcAppRoutePathVariables');
+/** → { id: '1' } */
+export const swcAppRoutePathVariableObject = routeParam('swcAppRoutePathVariableObject');
+/** = swcAppRoutePathVariableObject */
+export const swcAppRouteFirstPathVariableObject = routeParam('swcAppRouteFirstPathVariableObject');
+/** → { id: '2' } */
+export const swcAppRouteLastPathVariableObject = routeParam('swcAppRouteLastPathVariableObject');
+/** → { id: ['1', '2'] } */
+export const swcAppRoutePathVariablesObject = routeParam('swcAppRoutePathVariablesObject');

package/src/decorators/publishSwcAppMessage.ts

@@ -100,7 +100,6 @@ function createPublishSwcAppMessage(messageType?: string, options?: PublishSwcAp
 // 오버로드 시그니처 - 직접 사용 (괄호 없음)
 export function publishSwcAppMessage(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 // 오버로드 시그니처 - 함수 호출 (괄호 있음)
-export function publishSwcAppMessage(): MethodDecorator;
 export function publishSwcAppMessage(messageType: string): MethodDecorator;
 export function publishSwcAppMessage(messageType: string, options: PublishSwcAppMessageOptions): MethodDecorator;
 export function publishSwcAppMessage(options: PublishSwcAppMessageOptions): MethodDecorator;
@@ -114,7 +113,7 @@ export function publishSwcAppMessage(targetOrMessageTypeOrOptions?: any, propert
     return createPublishSwcAppMessage()(target, propertyKeyOrOptions, descriptor);
   }
 
-  // 함수로 호출된 경우 (괄호 있음): @publishSwcAppMessage() / @publishSwcAppMessage('messageType') / @publishSwcAppMessage({...})
+  // 함수로 호출된 경우 (인자 있음): @publishSwcAppMessage('messageType') / @publishSwcAppMessage({...})
   let messageType: string | undefined;
   let options: PublishSwcAppMessageOptions | undefined;
 
@@ -138,6 +137,6 @@ export const publishMessage = publishSwcAppMessage;
 
 // Helper function to retrieve publish message metadata
 export const getPublishSwcAppMessageMetadata = (target: any): PublishSwcAppMessageMetadata[] | undefined => {
-  const constructor = target instanceof Function ? target : target.constructor;
-  return ReflectUtils.getOwnMetadata(PUBLISH_SWC_APP_MESSAGE_METADATA_KEY, constructor);
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return ReflectUtils.findAllMetadata<any[]>(PUBLISH_SWC_APP_MESSAGE_METADATA_KEY, constructor).flat();
 };