@dooboostore/simple-web-component 1.0.50 → 1.0.52

package/src/decorators/parameter.ts

@@ -1,35 +1,45 @@
 import { ReflectUtils } from '@dooboostore/core';
 
 /**
- * @eventObject/@matchedElement/@hostSet/@helperHostSet/@helperSet/@routerEvent/@appMessage —
- * @addEventListener/lifecycle/subscribeSwcAppRouteChangeWhileConnected/subscribeSwcAppMessageWhileConnected
+ * @eventObject/@matchedElement/@hostSet/@helperHostSet/@helperSet/@swcAppRouterEvent/@appMessage/@eventBeforeReturn —
+ * @event/lifecycle/subscribeSwcAppRouteChange/subscribeSwcAppMessage
  * 계열 핸들러의 파라미터를 순서 무관하게 선언할 수 있게 해주는 파라미터 데코레이터.
  * @dooboostore/simple-boot의 @Inject와 동일한 인덱스 기반 메타데이터 패턴을 따른다:
  * 데코레이터가 실행되는 순서가 아니라 실제 parameterIndex로 슬롯을 매칭하므로,
  * 사용자가 파라미터 선언 순서를 자유롭게 바꿔도 된다.
  */
-export type SwcParamKind = 'event' | 'matched' | 'hostSet' | 'helperHostSet' | 'helperSet' | 'routerEvent' | 'appMessage';
+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');
 
-type SaveParamConfig = { index: number; kind: SwcParamKind };
+/** key: @swcAppRouteQueryParam('q') 처럼 키를 받는 파라미터 데코레이터의 키 */
+type SaveParamConfig = { index: number; kind: SwcParamKind; key?: string };
 
-const registerParam = (kind: SwcParamKind, target: Object, propertyKey: string | symbol | undefined, parameterIndex: number) => {
+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({ index: parameterIndex, kind });
+  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('event', target, propertyKey, parameterIndex);
+  registerParam('eventObject', target, propertyKey, parameterIndex);
 }
 
 /** delegate로 매칭된 실제 엘리먼트($matchedElement)를 주입한다. */
 export function matchedElement(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
-  registerParam('matched', target, propertyKey, parameterIndex);
+  registerParam('matchedElement', target, propertyKey, parameterIndex);
 }
 
 /** HostSet(호스트 트리 정보 — $host/$hosts/$firstHost/$appHost 등)을 주입한다. */
@@ -47,18 +57,91 @@ export function helperSet(target: Object, propertyKey: string | symbol, paramete
   registerParam('helperSet', target, propertyKey, parameterIndex);
 }
 
-/** @subscribeSwcAppRouteChangeWhileConnected 핸들러의 라우트 변경 이벤트({...RouterEventType, pathData})를 주입한다. */
-export function routerEvent(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
-  registerParam('routerEvent', target, propertyKey, parameterIndex);
+/** @subscribeSwcAppRouteChange 핸들러의 라우트 변경 이벤트({...RouterEventType, pathData})를 주입한다. */
+export function swcAppRouterEvent(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('swcAppRouterEvent', target, propertyKey, parameterIndex);
 }
 
-/** @subscribeSwcAppMessageWhileConnected 핸들러의 SwcAppMessage 페이로드를 주입한다. */
+/** @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 = target instanceof Function ? target : target.constructor;
+  const constructor = typeof target === 'function' ? target : target.constructor;
   return ReflectUtils.getMetadata(SWC_PARAMETER_METADATA_KEY, constructor, propertyKey) ?? [];
 };
 
@@ -76,6 +159,54 @@ export const buildSwcParameterArgs = (
   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) args[s.index] = kindValues[s.kind];
+  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();
 };

package/src/decorators/query.ts

@@ -39,7 +39,7 @@ export const resolveQueryElements = (
   options: QueryOptions,
   win: Window
 ): HTMLElement[] => {
-  const hostSet = SwcUtils.getHelperAndHostSet(win, inst);
+  const hostSet = SwcUtils.getHelperAndHostSet(inst);
   let all: HTMLElement[] = [];
 
   if (typeof selector === 'function') {
@@ -95,10 +95,11 @@ export const pickElements = (
   return all.length ? all[0] : null;
 };
 
-export function query(target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor): PropertyDescriptor | void;
 export function query(selector: string, options?: QueryOptions): PropertyDecorator;
 export function query(selector: QueryFnSelector, options?: QueryNonQueryOptions): PropertyDecorator;
-export function query(options?: QueryOptions): PropertyDecorator;
+export function query(options: QueryOptions): PropertyDecorator;
+// bare(@query) 시그니처는 맨 뒤 — @attribute 와 같은 이유 (TS1240/TS1271)
+export function query(target: Object, propertyKey: string | symbol): void;
 /**
  * @query decorator — 클래스 필드에 요소를 주입한다.
  *
@@ -111,6 +112,10 @@ export function query(selectorOrTarget?: string | ((currentThis: any, helper: He
   if (descriptor !== undefined && (typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol')) {
     throw new Error(`@query decorator cannot be used on methods. (Method: ${String(optionsOrPropertyKey)})`);
   }
+  // bare: @query — 자기 자신($this). 빈 괄호 @query() 는 타입에서 막는다 (인자가 없으면 괄호도 없다)
+  if (selectorOrTarget && (typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol')) {
+    return query('$this')(selectorOrTarget, optionsOrPropertyKey);
+  }
   // With selector
   if (typeof selectorOrTarget === 'string' || typeof selectorOrTarget === 'function') {
     return (targetObj: Object, propertyKey: string | symbol, descriptor?: never): void => {
@@ -119,7 +124,7 @@ export function query(selectorOrTarget?: string | ((currentThis: any, helper: He
       }
 
       const constructor = targetObj.constructor;
-      let queries = ReflectUtils.getMetadata<QueryMetadata[]>(QUERY_METADATA_KEY, constructor);
+      let queries = ReflectUtils.getOwnMetadata(QUERY_METADATA_KEY, constructor) as QueryMetadata[] | undefined;
       if (!queries) {
         queries = [];
         ReflectUtils.defineMetadata(QUERY_METADATA_KEY, queries, constructor);
@@ -157,26 +162,29 @@ export function query(selectorOrTarget?: string | ((currentThis: any, helper: He
       });
     };
   }
-  // Without selector (defaults to $this)
+  // 옵션만: $this
   return query('$this', selectorOrTarget as QueryOptions);
 }
 
 export const getQueryMetadata = (target: any): QueryMetadata[]  => {
-  const constructor = target instanceof Function ? target : target.constructor;
-  return ReflectUtils.getMetadata(QUERY_METADATA_KEY, constructor) ?? [];
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return ReflectUtils.findAllMetadata<any[]>(QUERY_METADATA_KEY, constructor).flat();
 };
 
 // ─── queryAll (query의 pick:'all' 편의 래퍼 — 호환용) ───
 export const QUERY_ALL_METADATA_KEY = QUERY_METADATA_KEY;
 
-export function queryAll(target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor): PropertyDescriptor | void;
 export function queryAll(selector: string, options?: Omit<QueryOptions, 'pick'>): PropertyDecorator;
 export function queryAll(selector: QueryFnSelector, options?: Omit<QueryNonQueryOptions, 'pick'>): PropertyDecorator;
-export function queryAll(options?: Omit<QueryOptions, 'pick'>): PropertyDecorator;
+export function queryAll(options: Omit<QueryOptions, 'pick'>): PropertyDecorator;
+export function queryAll(target: Object, propertyKey: string | symbol): void;
 export function queryAll(selectorOrTarget?: any, optionsOrPropertyKey?: any, descriptor?: PropertyDescriptor): any {
-  // bare(필드 직접 적용)는 query로 위임
   if (descriptor !== undefined && (typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol')) {
-    return query(selectorOrTarget, optionsOrPropertyKey, descriptor);
+    throw new Error(`@queryAll decorator cannot be used on methods. (Method: ${String(optionsOrPropertyKey)})`);
+  }
+  // bare: @queryAll — [$this]. 빈 괄호 @queryAll() 는 타입에서 막는다
+  if (selectorOrTarget && (typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol')) {
+    return query('$this', { pick: 'all' })(selectorOrTarget, optionsOrPropertyKey);
   }
   if (typeof selectorOrTarget === 'string' || typeof selectorOrTarget === 'function') {
     return query(selectorOrTarget, {...(optionsOrPropertyKey ?? {}), pick: 'all'});
@@ -235,9 +243,9 @@ export function queryAllAll(selector: string | QueryFnSelector, options?: QueryB
  * first/last/even/odd/all/number를 모두 지원하는 데코레이터를 생성한다.
  *
  * @example
- * @queryIn('shadow', 'even')('.item')   // shadow DOM 짝수 인덱스들
- * @queryIn('light', 2)('.item')         // light DOM 3번째 요소
- * @queryIn('all')('.item')              // root all, pick 기본 first
+ * @(queryIn('shadow', 'even')('.item'))   // shadow DOM 짝수 인덱스들 (호출이 이어지면 바깥 괄호 필요)
+ * @(queryIn('light', 2)('.item'))         // light DOM 3번째 요소
+ * @(queryIn('all')('.item'))              // root all, pick 기본 first
  */
 export const queryIn = (root: SwcRootType, pick?: QueryPick) =>
   (selector: string | QueryFnSelector, options?: QueryBaseOptions): PropertyDecorator =>

package/src/decorators/requestAnimationFrame.ts

@@ -1,5 +1,5 @@
 import { ReflectUtils } from '@dooboostore/core';
-import { ensureInit, getElementConfig } from './elementDefine';
+import { ensureInit } from './elementDefine';
 import { SwcUtils } from '../utils/Utils';
 import { ElementDefineLifeCycler, HelperHostSet } from '../types';
 
@@ -38,15 +38,7 @@ export interface RequestAnimationFrameMetadata {
  */
 export type FrameCallback = (timestamp: number, prevValue?: any) => any;
 
-const activeMap = new WeakMap<any, number[]>();
-const getActiveEntries = (inst: any): number[] => {
-  let entries = activeMap.get(inst);
-  if (!entries) {
-    entries = [];
-    activeMap.set(inst, entries);
-  }
-  return entries;
-};
+const getActiveEntries = (inst: any): number[] => (inst.__swc_requestAnimationFrameIds ??= []);
 
 const startFrameLoop = (win: Window, entries: number[], frameFn: FrameCallback): number => {
   let currentId = 0;
@@ -94,10 +86,9 @@ const applyRequestAnimationFrame = (options: RequestAnimationFrameOptions, targe
 
     if (frameFn) {
       ensureInit(this);
-      const conf = getElementConfig(this);
-      const win = (this as any)._resolveWindow?.(conf) || ((typeof window !== 'undefined' ? window : undefined) as Window);
+      const win = SwcUtils.resolveWindow(this);
       const id = startFrameLoop(win, getActiveEntries(this), frameFn);
-      normalizedOptions.created?.(SwcUtils.getHelperAndHostSet(win, this), id);
+      normalizedOptions.created?.(SwcUtils.getHelperAndHostSet(this), id);
     }
     return res;
   };
@@ -112,7 +103,7 @@ const applyRequestAnimationFrame = (options: RequestAnimationFrameOptions, targe
  *
  * 옵션 없이 `@requestAnimationFrame` 그대로 붙여도 되고, `@requestAnimationFrame({...})`처럼 옵션을 줄 수도 있다.
  */
-export function requestAnimationFrame(options?: RequestAnimationFrameOptions): MethodDecorator;
+export function requestAnimationFrame(options: RequestAnimationFrameOptions): MethodDecorator;
 export function requestAnimationFrame(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 export function requestAnimationFrame(optionsOrTarget?: RequestAnimationFrameOptions | Object, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
   if (propertyKey !== undefined) {
@@ -120,21 +111,21 @@ export function requestAnimationFrame(optionsOrTarget?: RequestAnimationFrameOpt
     applyRequestAnimationFrame({}, optionsOrTarget as Object, propertyKey, descriptor);
     return;
   }
-  // 옵션과 함께: @requestAnimationFrame() 또는 @requestAnimationFrame({...})
+  // 옵션과 함께: @requestAnimationFrame({...})
   return (target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor) => {
     return applyRequestAnimationFrame((optionsOrTarget as RequestAnimationFrameOptions) ?? {}, target, propertyKey, descriptor);
   };
 }
 
 export const findAllRequestAnimationFrameMetadata = (target: any): RequestAnimationFrameMetadata[] => {
-  const constructor = target instanceof Function ? target : target.constructor;
+  const constructor = typeof target === 'function' ? target : target.constructor;
   return (ReflectUtils.findAllMetadata<RequestAnimationFrameMetadata[]>(REQUEST_ANIMATION_FRAME_METADATA_KEY, constructor) || []).flat();
 };
 
 export class RequestAnimationFrameLifeCycler implements ElementDefineLifeCycler {
   onConnected(helperHostSet: HelperHostSet): void {
     const inst = helperHostSet.$this;
-    activeMap.delete(inst); // 재연결 대비 리셋
+    inst.__swc_requestAnimationFrameIds = []; // 재연결 대비 리셋
     const entries = getActiveEntries(inst);
     for (const meta of findAllRequestAnimationFrameMetadata(inst)) {
       if (meta.options.type !== 'onConnected') continue; // returnValue 타입은 수동 호출을 기다림
@@ -146,13 +137,13 @@ export class RequestAnimationFrameLifeCycler implements ElementDefineLifeCycler
 
   onDisconnected(helperHostSet: HelperHostSet): void {
     const inst = helperHostSet.$this;
-    for (const id of activeMap.get(inst) ?? []) {
+    for (const id of inst.__swc_requestAnimationFrameIds ?? []) {
       try {
         helperHostSet.$w.cancelAnimationFrame(id);
       } catch (e) {
         console.error('[SWC] cancelAnimationFrame error:', e);
       }
     }
-    activeMap.delete(inst);
+    inst.__swc_requestAnimationFrameIds = [];
   }
 }

package/src/decorators/resizeObserver.ts

@@ -1,10 +1,16 @@
 import { ReflectUtils } from '@dooboostore/core';
 import { SpecialSelector, SwcQueryOptions, SwcFnSelector, SwcSelector, HelperHostSet } from '../types';
+import { buildSwcParameterArgs } from './parameter';
 
 // 공통 옵션 — root·delegate 없음
 export interface ResizeObserverBaseOptions {
   box?: 'content-box' | 'border-box' | 'device-pixel-content-box';
-  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되고, 리턴값은 @resizeObserverBeforeReturn 으로 핸들러에 주입된다. */
+  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>;
   removeObserver?: (target: Element, optionValue: ResizeObserverOptions) => void;
 }
 
@@ -28,7 +34,7 @@ export const RESIZE_OBSERVER_METADATA_KEY = Symbol.for('simple-web-component:res
 
 const applyResizeObserver = (selector: SwcSelector, options: ResizeObserverOptions, targetObj: Object, propertyKey: string | symbol): void => {
   const constructor = targetObj.constructor;
-  let observers = ReflectUtils.getMetadata<ResizeObserverMetadata[]>(RESIZE_OBSERVER_METADATA_KEY, constructor);
+  let observers = ReflectUtils.getOwnMetadata(RESIZE_OBSERVER_METADATA_KEY, constructor) as ResizeObserverMetadata[] | undefined;
   if (!observers) {
     observers = [];
     ReflectUtils.defineMetadata(RESIZE_OBSERVER_METADATA_KEY, observers, constructor);
@@ -48,7 +54,7 @@ const resolveResizeObserverArgs = (
 };
 
 /**
- * bare(@decorator)와 factory(@decorator()/@decorator(...)) 호출을 모두 처리하는 공통 디스패처.
+ * bare(@decorator)와 factory(@decorator(...), 빈 괄호는 타입에서 막음) 호출을 모두 처리하는 공통 디스패처.
  * extra는 Light/Shadow/All/Delegate 변형이 강제로 덧씌우는 옵션(root, delegate 등)이다.
  */
 const dispatchResizeObserver = (
@@ -62,7 +68,7 @@ const dispatchResizeObserver = (
     applyResizeObserver('$this', { ...extra }, selectorOrOptionsOrTarget as Object, maybeOptionsOrPropertyKey);
     return;
   }
-  // 옵션과 함께: @decorator() / @decorator(selector, options) / @decorator(options)
+  // 옵션과 함께: @decorator(selector, options) / @decorator(options)
   const { selector, options } = resolveResizeObserverArgs(
     selectorOrOptionsOrTarget as SwcSelector | ResizeObserverOptions | undefined,
     maybeOptionsOrPropertyKey as ResizeObserverOptions | undefined,
@@ -76,7 +82,7 @@ const dispatchResizeObserver = (
 export function resizeObserver(target: SpecialSelector, options?: ResizeObserverQueryOptions): MethodDecorator;
 export function resizeObserver(selector: string, options?: ResizeObserverQueryOptions): MethodDecorator;
 export function resizeObserver(selector: SwcFnSelector, options?: ResizeObserverNonQueryOptions): MethodDecorator;
-export function resizeObserver(options?: ResizeObserverQueryOptions): MethodDecorator;
+export function resizeObserver(options: ResizeObserverQueryOptions): MethodDecorator;
 export function resizeObserver(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 /**
  * @resizeObserver decorator to observe element size changes.
@@ -86,37 +92,32 @@ export function resizeObserver(selectorOrOptionsOrTarget?: SwcSelector | ResizeO
   return dispatchResizeObserver(selectorOrOptionsOrTarget, maybeOptionsOrPropertyKey, descriptor, {});
 }
 
-export function resizeObserverThis(options?: ResizeObserverQueryOptions): MethodDecorator;
-export function resizeObserverThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function resizeObserverThis(optionsOrTarget?: ResizeObserverQueryOptions | Object, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
-  return dispatchResizeObserver(optionsOrTarget, propertyKey, descriptor, {});
-}
 
 // ─── root별 delegate 헬퍼 (root 주입 → 문자열 셀렉터 전용) ───
 
 export function resizeObserverDelegateLight(selector: string, options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function resizeObserverDelegateLight(options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
+export function resizeObserverDelegateLight(options: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function resizeObserverDelegateLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 export function resizeObserverDelegateLight(selectorOrOptionsOrTarget?: string | Omit<ResizeObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<ResizeObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
   return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'light', delegate: true });
 }
 
 export function resizeObserverDelegateShadow(selector: string, options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function resizeObserverDelegateShadow(options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
+export function resizeObserverDelegateShadow(options: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function resizeObserverDelegateShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 export function resizeObserverDelegateShadow(selectorOrOptionsOrTarget?: string | Omit<ResizeObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<ResizeObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
   return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'shadow', delegate: true });
 }
 
 export function resizeObserverDelegateAll(selector: string, options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function resizeObserverDelegateAll(options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
+export function resizeObserverDelegateAll(options: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function resizeObserverDelegateAll(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 export function resizeObserverDelegateAll(selectorOrOptionsOrTarget?: string | Omit<ResizeObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<ResizeObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
   return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'all', delegate: true });
 }
 
 export function resizeObserverDelegate(selector: string, options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function resizeObserverDelegate(options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
+export function resizeObserverDelegate(options: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function resizeObserverDelegate(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 export function resizeObserverDelegate(selectorOrOptionsOrTarget?: string | Omit<ResizeObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<ResizeObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
   return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'auto', delegate: true });
@@ -125,29 +126,29 @@ export function resizeObserverDelegate(selectorOrOptionsOrTarget?: string | Omit
 // ─── root별 일반 헬퍼 (delegate 없이, 셀렉터 생략 시 $this) ───
 
 export function resizeObserverLight(selector: string, options?: ResizeObserverQueryOptions): MethodDecorator;
-export function resizeObserverLight(options?: ResizeObserverQueryOptions): MethodDecorator;
+export function resizeObserverLight(options: ResizeObserverQueryOptions): MethodDecorator;
 export function resizeObserverLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 export function resizeObserverLight(selectorOrOptionsOrTarget?: string | ResizeObserverQueryOptions | Object, maybeOptionsOrPropertyKey?: ResizeObserverQueryOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
   return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'light' });
 }
 
 export function resizeObserverShadow(selector: string, options?: ResizeObserverQueryOptions): MethodDecorator;
-export function resizeObserverShadow(options?: ResizeObserverQueryOptions): MethodDecorator;
+export function resizeObserverShadow(options: ResizeObserverQueryOptions): MethodDecorator;
 export function resizeObserverShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 export function resizeObserverShadow(selectorOrOptionsOrTarget?: string | ResizeObserverQueryOptions | Object, maybeOptionsOrPropertyKey?: ResizeObserverQueryOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
   return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'shadow' });
 }
 
 export function resizeObserverAll(selector: string, options?: ResizeObserverQueryOptions): MethodDecorator;
-export function resizeObserverAll(options?: ResizeObserverQueryOptions): MethodDecorator;
+export function resizeObserverAll(options: ResizeObserverQueryOptions): MethodDecorator;
 export function resizeObserverAll(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 export function resizeObserverAll(selectorOrOptionsOrTarget?: string | ResizeObserverQueryOptions | Object, maybeOptionsOrPropertyKey?: ResizeObserverQueryOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
   return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'all' });
 }
 
 export function getResizeObserverMetadata(target: any): ResizeObserverMetadata[] | undefined {
-  const constructor = target instanceof Function ? target : target.constructor;
-  return ReflectUtils.getMetadata(RESIZE_OBSERVER_METADATA_KEY, constructor);
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return ReflectUtils.findAllMetadata<any[]>(RESIZE_OBSERVER_METADATA_KEY, constructor).flat();
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -156,20 +157,21 @@ export function getResizeObserverMetadata(target: any): ResizeObserverMetadata[]
 // elementDefine 이 수집된 ResizeObserverSet 으로 observer 를 생성하고,
 // observe/unobserve 함수를 주입해 MutationObserver delegate 추적이 사용할 수 있게 한다.
 // ─────────────────────────────────────────────────────────────────────────────
-import { ElementDefineLifeCycler, OnConnectedResult, ResizeObserverSet, ResizeObserverSetEntry } from '../types';
+import { ElementDefineLifeCycler, inObserverScope, ObserverScope, OnConnectedResult, ResizeObserverSet, ResizeObserverSetEntry } from '../types';
 import { SwcUtils } from '../utils/Utils';
 
 export class ResizeObserverLifeCycler 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 = getResizeObserverMetadata(inst) ?? [];
+    const allMeta = (getResizeObserverMetadata(inst) ?? []).filter(m => inObserverScope(m, scope));
     if (allMeta.length === 0) return;
 
     const root: HTMLElement | ShadowRoot = inst.shadowRoot || inst;
@@ -179,6 +181,9 @@ export class ResizeObserverLifeCycler implements ElementDefineLifeCycler {
       if (m.options.removeObserver) removeObserverCallbacks.push({ fn: m.options.removeObserver, target: root, opts: m.options });
     }
 
+    // non-delegate 메타별 observe 대상 — 콜백은 모든 메타가 공유하므로, 엔트리를 자기 대상에만 배달한다.
+    const metaTargets = new Map<typeof allMeta[number], WeakSet<Element>>();
+
     // ── ResizeObserver 콜백 ──
     const callback: ResizeObserverSetEntry['callback'] = (entries, obs) => {
       for (const m of allMeta) {
@@ -191,14 +196,29 @@ export class ResizeObserverLifeCycler implements ElementDefineLifeCycler {
             return el.matches?.(m.selector as string) || !!el.closest?.(m.selector as string);
           });
         } else {
-          matchedEls = entries.map(e => e.target as HTMLElement).filter(t => t && t.nodeType === 1);
+          const set = metaTargets.get(m);
+          matchedEls = entries.map(e => e.target as HTMLElement).filter(t => t && t.nodeType === 1 && !!set?.has(t));
         }
         if (matchedEls.length === 0) continue;
-        if (m.options.filter) {
-          if (!m.options.filter(matchedEls, { currentThis: inst, helper: helperHostSet })) continue;
-        }
-        const hostSet = SwcUtils.getHostSet(inst);
-        inst[m.propertyKey](matchedEls, entries, obs, { ...hostSet, $root: root });
+        const opts = m.options;
+        void (async () => {
+          const helper = SwcUtils.getHelperAndHostSet(inst);
+          if (opts.filter && !(await opts.filter(matchedEls, { currentThis: inst, helper }))) return;
+          const hostSet = SwcUtils.getHostSet(inst);
+          const helperSet = SwcUtils.getHelperSet(helperHostSet.$w);
+          // entries 도 이 메서드 대상 것만 (옵저버는 공유라 배치에 다른 대상 엔트리가 섞인다)
+          const legacyArgs = [matchedEls, entries.filter(e => matchedEls.includes(e.target as HTMLElement)), obs, { ...hostSet, $root: root }];
+          const buildArgs = (beforeReturn: any) => buildSwcParameterArgs(inst, m.propertyKey, {
+            hostSet, helperHostSet: helper, helperSet, resizeObserverBeforeReturn: beforeReturn
+          }, [...legacyArgs, beforeReturn]);
+          let args = buildArgs(undefined);
+          if (opts.before) { const br = await opts.before(matchedEls, { currentThis: inst, helper }); args = buildArgs(br); }
+          let result: any, error: any;
+          try { result = await inst[m.propertyKey](...args); }
+          catch (e) { error = e; }
+          finally { if (opts.finally) await opts.finally(matchedEls, { currentThis: inst, helper }, { args, result, error }); }
+          if (error) throw error;
+        })().catch(e => console.error('[SWC] resizeObserver handler error:', e));
       }
     };
 
@@ -235,6 +255,7 @@ export class ResizeObserverLifeCycler implements ElementDefineLifeCycler {
           }
         }
       }
+      metaTargets.set(m, new WeakSet(targets));
       for (const el of targets) resizeObserverSet.push({ target: el, options: m.options.box ? { box: m.options.box } : undefined, callback });
     }