@dooboostore/simple-web-component 1.0.26 → 1.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dooboostore/simple-web-component",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "license": "MIT",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -92,9 +92,9 @@
     "webpack": "^5.93.0",
     "webpack-cli": "^5.1.4",
     "webpack-dev-server": "^5.2.0",
-    "@dooboostore/core": "1.0.30",
     "@dooboostore/core-node": "1.0.12",
     "@dooboostore/core-web": "1.0.10",
+    "@dooboostore/core": "1.0.30",
     "@dooboostore/simple-boot": "1.0.54"
   },
   "scripts": {

package/src/decorators/addEventListener.ts

@@ -1,5 +1,5 @@
 import { ReflectUtils } from '@dooboostore/core';
-import { SpecialSelector, SwcQueryOptions } from '../types';
+import { SpecialSelector, SwcQueryOptions, HelperHostSet } from '../types';
 
 export interface AddEventListenerBaseOptions extends EventListenerOptions {
   capture?: boolean;
@@ -10,6 +10,7 @@ export interface AddEventListenerBaseOptions extends EventListenerOptions {
   preventDefault?: boolean;
   removeOnDisconnected?: boolean;
   delegate?: boolean;
+  filter?: (target: Event | CustomEvent, helper: HelperHostSet) => boolean;
 }
 
 export interface AddEventListenerMetadata {
@@ -53,3 +54,12 @@ export const getAddEventListenerMetadata = (target: any): AddEventListenerMetada
 export function addEventListenerHost(type: string, options?: AddEventListenerBaseOptions & SwcQueryOptions): MethodDecorator {
   return addEventListener(':host', type, options);
 }
+
+/**
+ * @addEventListenerAppHost decorator - simplified version of @addEventListener for :appHost selector
+ * Usage: @addEventListenerAppHost('click')
+ * Usage: @addEventListenerAppHost('click', { stopPropagation: true })
+ */
+export function addEventListenerAppHost(type: string, options?: AddEventListenerBaseOptions & SwcQueryOptions): MethodDecorator {
+  return addEventListener(':appHost', type, options);
+}

package/src/decorators/attribute.ts

@@ -2,10 +2,9 @@ import {ReflectUtils} from '@dooboostore/core';
 import {ensureInit, getElementConfig} from './elementDefine';
 import {SwcUtils} from '../utils/Utils';
 import {SpecialSelector, SwcQueryOptions} from '../types';
-
 export interface AttributeFieldOptions extends SwcQueryOptions {
   name?: string;
-  connectedInitialize?: boolean;
+  // connectedInitialize?: boolean;
   type?: typeof Number | typeof Boolean | typeof String;
 }
 
@@ -81,9 +80,9 @@ export function attribute(selector: string, options: AttributeFieldOptions = {})
   return (target: Object, propertyKey: string | symbol) => {
     const constructor = target.constructor;
     const privateKey = Symbol(String(propertyKey));
-
+    //
     const designType = (Reflect as any).getMetadata('design:type', target, propertyKey);
-
+    //
     let metaList = ReflectUtils.getOwnMetadata(ATTRIBUTE_FIELD_METADATA_KEY, constructor) as AttributeFieldMetadata[];
     if (!metaList) {
       metaList = [];
@@ -105,56 +104,65 @@ export function attribute(selector: string, options: AttributeFieldOptions = {})
       });
     };
 
-    Object.defineProperty(target, propertyKey, {
-      get(this: any) {
-        const attrName = options.name || String(propertyKey);
-        const conf = getElementConfig(this);
-        const currentWin = this._resolveWindow?.(conf) || ((typeof window !== 'undefined' ? window : undefined) as any);
-        const targetType = options.type || designType;
-
-        if (this.__swc_syncing_init || (options.connectedInitialize && !this.__swc_connected)) {
-          return convertValue(this[privateKey], targetType);
-        }
-
-        const targets = resolveTargetEls(this, selector, options, currentWin);
-        const primaryTarget = targets[0];
-
-        if (primaryTarget && typeof (primaryTarget as any).hasAttribute === 'function') {
-          if ((primaryTarget as any).hasAttribute(attrName)) {
-            const domVal = (primaryTarget as any).getAttribute(attrName);
-            return convertValue(domVal, targetType);
-          }
-          return null;
-        }
-
-        return convertValue(this[privateKey], targetType);
-      },
-      set(this: any, nv: any) {
-        const attrName = options.name || String(propertyKey);
-        const conf = getElementConfig(this);
-        const currentWin = this._resolveWindow?.(conf) || ((typeof window !== 'undefined' ? window : undefined) as any);
+    try {
+      // Own property를 삭제하여 getter가 작동하도록 함
+      // delete target[propertyKey];
+
+      // const defineTarget = target instanceof Function ? target : (target as any).constructor;
+      
+      Object.defineProperty(target, propertyKey, {
+        get(this: any) {
+          // try {
+            const attrName = options.name || String(propertyKey);
+            const conf = getElementConfig(this);
+            const currentWin = this._resolveWindow?.(conf) || ((typeof window !== 'undefined' ? window : undefined) as any);
+            const targetType = options.type || designType;
+          //
+            // connectedInitialize: true이면 privateKey 값만 반환 (DOM 무시)
+            // if (options.connectedInitialize === true && (this as any).__swc_syncing_init) {
+            //   console.log('cccccccc2');
+            //   return this[privateKey];
+            //   // return convertValue(this[privateKey], targetType);
+            // }
 
-        if (this.__swc_syncing_init) {
-          if (options.connectedInitialize === true) {
             const targets = resolveTargetEls(this, selector, options, currentWin);
-            applySetAttribute(this, targets, attrName, nv);
-          } else {
-            this[privateKey] = nv;
-          }
-          return;
-        }
-
-        if (!this.__swc_connected) {
-          this[privateKey] = nv;
-          return;
-        }
-
-        const targets = resolveTargetEls(this, selector, options, currentWin);
-        applySetAttribute(this, targets, attrName, nv);
-      },
-      enumerable: true,
-      configurable: true
-    });
+            const primaryTarget = targets[0];
+
+            if (primaryTarget && typeof (primaryTarget as any).hasAttribute === 'function') {
+              if ((primaryTarget as any).hasAttribute(attrName)) {
+                const domVal = (primaryTarget as any).getAttribute(attrName);
+                return convertValue(domVal, targetType);
+              }
+              return null;
+            }
+
+            return convertValue(this[privateKey], targetType);
+          // } catch (err) {
+          //   console.error('Error in getter:', err);
+          //   throw err;
+          // }
+        },
+        set(this: any, nv: any) {
+          // this[propertyKey] = nv;
+          const attrName = options.name || String(propertyKey);
+          const conf = getElementConfig(this);
+          const currentWin = this._resolveWindow?.(conf) || ((typeof window !== 'undefined' ? window : undefined) as any);
+
+
+          // if (!this.__swc_connected) {
+          //   this[privateKey] = nv;
+          //   return;
+          // }
+
+          const targets = resolveTargetEls(this, selector, options, currentWin);
+          applySetAttribute(this, targets, attrName, nv);
+        },
+        enumerable: true,
+        configurable: true
+      });
+  } catch (err) {
+    console.error('[SWC] defineProperty error:', err);
+  }
   };
 }
 
@@ -187,5 +195,6 @@ export function attributeHost(targetOrAttrOrOptions?: any, propertyKeyOrOptions?
 }
 
 export const findAllAttributeMetadata = (target: any): AttributeFieldMetadata[] => {
-  return ReflectUtils.findAllMetadata<AttributeFieldMetadata[]>(ATTRIBUTE_FIELD_METADATA_KEY, target).flat();
+  const actualTarget = target instanceof Function ? target : target.constructor;
+  return ReflectUtils.findAllMetadata<AttributeFieldMetadata[]>(ATTRIBUTE_FIELD_METADATA_KEY, actualTarget).flat();
 };

package/src/decorators/elementDefine.ts

@@ -1,11 +1,13 @@
 import { ReflectUtils } from '@dooboostore/core';
 import { FunctionUtils } from '@dooboostore/core';
 import { getAddEventListenerMetadata } from './addEventListener';
-import { ON_CONSTRUCTOR_METADATA_KEY, ON_BEFORE_CONNECTED_METADATA_KEY, ON_AFTER_CONNECTED_METADATA_KEY, ON_BEFORE_DISCONNECTED_METADATA_KEY, ON_AFTER_DISCONNECTED_METADATA_KEY, ON_BEFORE_ADOPTED_METADATA_KEY, ON_AFTER_ADOPTED_METADATA_KEY, findAllLifecycleMetadata, getOnConnectedInnerHtmlMetadata } from './lifecycles';
+import { ON_INITIALIZE_METADATA_KEY, ON_BEFORE_CONNECTED_METADATA_KEY, ON_AFTER_CONNECTED_METADATA_KEY, ON_BEFORE_DISCONNECTED_METADATA_KEY, ON_AFTER_DISCONNECTED_METADATA_KEY, ON_BEFORE_ADOPTED_METADATA_KEY, ON_AFTER_ADOPTED_METADATA_KEY, findAllLifecycleMetadata, getOnConnectedInnerHtmlMetadata } from './lifecycles';
 import { getEmitCustomEventMetadataList } from './emitCustomEvent';
 import { findAllAttributeChangedMetadata } from './changedAttributeHost';
 import { findAllAttributeApplyMetadata } from './applyAttribute';
 import { findAllAttributeMetadata } from './attribute';
+import { getQueryMetadata } from './query';
+import { getQueryAllMetadata } from './queryAll';
 import { SwcUtils } from '../utils/Utils';
 import { HTML_TAG_ENTRIES, DOM_EVENT_NAMES } from '../config/config';
 import { SituationTypeContainer, SituationTypeContainers } from '@dooboostore/simple-boot/decorators/inject/Inject';
@@ -39,12 +41,60 @@ export const ensureInit = (inst: any) => {
     inst._boundListeners = [];
     inst.__swc_initialized = true;
 
+    // const attributeList = findAllQ(inst);
+    // attributeList.forEach(meta => {
+    //   delete (inst as any)[meta.propertyKey];
+    // });
+
+    const target = inst instanceof Function ? inst : inst.constructor;
+    
+    // ╔════════════════════════════════════════════════════════════════════════════════╗
+    // ║ decorator 필드의 own property 삭제                                              ║
+    // ║                                                                                ║
+    // ║ 이유:                                                                          ║
+    // ║ 1. TypeScript는 초기값이 있는 필드를 constructor에서 own property로 생성       ║
+    // ║    @attributeHost('id') myId: string = "default"  →  this.myId = "default"    ║
+    // ║                                                                                ║
+    // ║ 2. JavaScript의 property lookup은 own property를 먼저 찾음                      ║
+    // ║    - this.myId 접근                                                           ║
+    // ║    - 1순위: instance의 own property 있나? → 있으면 그것 반환                  ║
+    // ║    - 2순위: prototype의 getter 있나? → 있으면 호출                            ║
+    // ║                                                                                ║
+    // ║ 3. own property가 있으면 prototype의 getter는 절대 호출되지 않음               ║
+    // ║    따라서 getter에서 정의된 DOM 동기화 로직이 작동하지 않음                   ║
+    // ║                                                                                ║
+    // ║ 4. own property를 삭제하면 JavaScript가 prototype의 getter를 찾게 됨          ║
+    // ║    → getter 호출됨 → DOM 속성 값 동기화됨                                     ║
+    // ╚════════════════════════════════════════════════════════════════════════════════╝
+    
+    // @attribute 필드의 own property 삭제 → getter/setter 작동
+    const attributeList = findAllAttributeMetadata(target);
+    attributeList.forEach(meta => {
+      delete (inst as any)[meta.propertyKey];
+    });
+    
+    // @query 필드의 own property 삭제 → getter 작동
+    const queryList = getQueryMetadata(target);
+    if (queryList) {
+      queryList.forEach(meta => {
+        delete (inst as any)[meta.propertyKey];
+      });
+    }
+    
+    // @queryAll 필드의 own property 삭제 → getter 작동
+    const queryAllList = getQueryAllMetadata(target);
+    if (queryAllList) {
+      queryAllList.forEach(meta => {
+        delete (inst as any)[meta.propertyKey];
+      });
+    }
+
     // Call constructor script if present
     const hostSet = SwcUtils.getHostSet(inst);
     inst._executeSwcScript?.('swc-on-constructor', hostSet);
 
-    // Call @onConstructor lifecycle methods
-    const cMethods = findAllLifecycleMetadata(inst, ON_CONSTRUCTOR_METADATA_KEY);
+    // Call @onInitialize lifecycle methods
+    const cMethods = findAllLifecycleMetadata(inst, ON_INITIALIZE_METADATA_KEY);
     if (cMethods) {
       for (const m of cMethods) (inst)._invokeLifecycleMethod(m, hostSet);
     }
@@ -79,9 +129,10 @@ function buildEnv(configWindow?: Window) {
   const doc: Document = win?.document;
   const builtInTagMap = new Map<any, string>();
   for (const [cls, tag] of HTML_TAG_ENTRIES) {
-    if (win?.[cls]) builtInTagMap.set(win[cls], tag);
+    if ((win as any)?.[cls]) builtInTagMap.set((win as any)[cls], tag);
   }
   const domHelpers = SwcUtils.getHelperSet(win);
+  
   return { win, doc, builtInTagMap, domHelpers };
 }
 
@@ -238,15 +289,16 @@ export const elementDefine =
 
     // Collect all observed attributes from all decorators
     const attributeApplyNames = Array.from(applyAttributeMap.values()).map(it => it.options.name).filter(Boolean) as string[];
-    const attributeListNames = attributeList.map(it => it.options.name || String(it.propertyKey));
-    
+    // const attributeListNames = attributeList.map(it => it.options.name || String(it.propertyKey));
+    const hostAttributes = attributeList.filter(it => it.selector === ':host').map(it=>it.options.name || String(it.propertyKey));
+
     const mergedObservedAttributes = [...new Set([
-      ...(metadata.observedAttributes ?? []), 
-      ...attrChangeMap.keys(), 
+      ...(metadata.observedAttributes ?? []),
+      ...attrChangeMap.keys(),
       ...attributeApplyNames,
-      ...attributeListNames, 
-      ...emitHostCustomEventList.map(it => (it.options as any).attributeName).filter(Boolean), 
-      ...swcLifecycleAttributes, 
+      ...hostAttributes,
+      ...emitHostCustomEventList.map(it => (it.options as any).attributeName).filter(Boolean),
+      ...swcLifecycleAttributes,
       ...swcOnEvents
     ])];
 
@@ -259,35 +311,21 @@ export const elementDefine =
     proto.connectedCallback = function () {
       ensureInit(this);
 
+      const hostSet = SwcUtils.getHostSet(this as any);
+      const appHost = hostSet.$appHost;
+      const conf = getElementConfig(this);
+      const currentWin = (this as any)._resolveWindow(conf);
+
       if (connectedInnerHtmlList.some(it => it.options.useShadow === true) && !this.shadowRoot) {
         this.attachShadow({ mode: 'open' });
       }
 
-      const conf = getElementConfig(this);
-      const currentWin = (this as any)._resolveWindow(conf);
-      const hostSet = SwcUtils.getHostSet(this as any);
-
       (this as any)._executeSwcScript('swc-on-before-connected', hostSet);
       const bMethods = findAllLifecycleMetadata(this, ON_BEFORE_CONNECTED_METADATA_KEY);
       if (bMethods) {
         for (const m of bMethods) (this as any)._invokeLifecycleMethod(m, hostSet);
       }
 
-      // Initialize @attribute fields
-      attributeList.forEach(meta => {
-        if (meta.options.connectedInitialize === true) {
-          (this as any).__swc_syncing_init = true;
-          try {
-            const memoryVal = (this as any)[meta.privateKey];
-            if (memoryVal !== undefined) {
-              (this as any)[meta.propertyKey] = memoryVal;
-            }
-          } finally {
-            (this as any).__swc_syncing_init = false;
-          }
-        }
-      });
-
       if (connectedInnerHtmlList.length > 0) {
         let sContent = '',
           lContent = '';
@@ -358,6 +396,13 @@ export const elementDefine =
               const { selector, options } = meta;
               const matchedEl = (event.target as HTMLElement).closest(selector);
               if (matchedEl && (br as any).contains(matchedEl)) {
+                // Apply filter if specified
+                if (options.filter) {
+                  const helper = SwcUtils.getHelperAndHostSet(currentWin, matchedEl);
+                  if (!options.filter(event, helper)) {
+                    continue;  // Skip this listener if filter returns false
+                  }
+                }
                 if (options.stopPropagation) event.stopPropagation();
                 if (options.stopImmediatePropagation) event.stopImmediatePropagation();
                 if (options.preventDefault) event.preventDefault();
@@ -416,6 +461,13 @@ export const elementDefine =
 
         bindTargets.forEach(t => {
           const handler = async (event: Event) => {
+            // Apply filter if specified
+            if (options.filter) {
+              const helper = SwcUtils.getHelperAndHostSet(currentWin, t as HTMLElement);
+              if (!options.filter(event, helper)) {
+                return;  // Skip if filter returns false
+              }
+            }
             if (options.stopPropagation) event.stopPropagation();
             if (options.stopImmediatePropagation) event.stopImmediatePropagation();
             if (options.preventDefault) event.preventDefault();
@@ -439,6 +491,11 @@ export const elementDefine =
       (this as any)._executeSwcScript('swc-on-connected', hostSet);
       (this as any)._executeSwcScript('swc-on-after-connected', hostSet);
       (this as any).__swc_connected = true;
+
+      // Register to appHost LAST when all lifecycle completed
+      if (appHost && typeof (appHost as any)._connected === 'function') {
+        (appHost as any)._connected(this);
+      }
     };
 
     const originalDisconnected = proto.disconnectedCallback;
@@ -464,6 +521,12 @@ export const elementDefine =
       (this as any)._executeSwcScript('swc-on-disconnected', hostSet);
       (this as any)._executeSwcScript('swc-on-after-disconnected', hostSet);
       (this as any).__swc_connected = false;
+      
+      // Remove from appHost LAST when disconnected
+      const appHost = hostSet.$appHost;
+      if (appHost && typeof (appHost as any)._disconnected === 'function') {
+        (appHost as any)._disconnected(this);
+      }
     };
 
     const originalAdopted = proto.adoptedCallback;

package/src/decorators/index.ts

@@ -10,3 +10,4 @@ export * from './queryAll';
 export * from './applyClass';
 export * from './applyStyle';
 export * from './applyAttribute';
+export * from './subscribeSwcAppRouteChange';

package/src/decorators/lifecycles.ts

@@ -1,6 +1,6 @@
 import { ReflectUtils } from '@dooboostore/core';
 
-export const ON_CONSTRUCTOR_METADATA_KEY = Symbol.for('simple-web-component:on-constructor');
+export const ON_INITIALIZE_METADATA_KEY = Symbol.for('simple-web-component:on-constructor');
 export const ON_BEFORE_CONNECTED_METADATA_KEY = Symbol.for('simple-web-component:on-before-connected');
 export const ON_AFTER_CONNECTED_METADATA_KEY = Symbol.for('simple-web-component:on-after-connected');
 export const ON_BEFORE_DISCONNECTED_METADATA_KEY = Symbol.for('simple-web-component:on-before-disconnected');
@@ -33,7 +33,7 @@ function createLifecycleDecorator(metadataKey: symbol): MethodDecorator {
   };
 }
 
-export const onConstructor = createLifecycleDecorator(ON_CONSTRUCTOR_METADATA_KEY);
+export const onInitialize = createLifecycleDecorator(ON_INITIALIZE_METADATA_KEY);
 export const onBeforeConnected = createLifecycleDecorator(ON_BEFORE_CONNECTED_METADATA_KEY);
 export const onAfterConnected = createLifecycleDecorator(ON_AFTER_CONNECTED_METADATA_KEY);
 export const onConnected = onAfterConnected;

package/src/decorators/query.ts

@@ -102,11 +102,6 @@ export function query(selectorOrTarget: string, options: any = {}): PropertyDeco
   };
 }
 
-export const getQueryMetadata = (target: any): QueryMetadata[] | undefined => {
-  const constructor = target instanceof Function ? target : target.constructor;
-  return ReflectUtils.getMetadata(QUERY_METADATA_KEY, constructor);
-};
-
 /**
  * @queryHost decorator - simplified version of @query for :host selector
  * Usage: @queryHost testzzs: HTMLElement | undefined;
@@ -257,3 +252,8 @@ export function lastAppHost(targetOrOptions?: any, propertyKey?: string | symbol
     return query(':lastAppHost', {});
   }
 }
+
+export const getQueryMetadata = (target: any): QueryMetadata[] | undefined => {
+  const constructor = target instanceof Function ? target : target.constructor;
+  return ReflectUtils.getMetadata(QUERY_METADATA_KEY, constructor);
+};

package/src/decorators/queryAll.ts

@@ -102,12 +102,6 @@ export function queryAll(selectorOrTarget: string, options: any = {}): PropertyD
     });
   };
 }
-
-export const getQueryAllMetadata = (target: any): QueryAllMetadata[] | undefined => {
-  const constructor = target instanceof Function ? target : target.constructor;
-  return ReflectUtils.getMetadata(QUERY_ALL_METADATA_KEY, constructor);
-};
-
 /**
  * @hostQueryAll decorator - simplified version of @queryAll for :host selector
  * Usage: @hostQueryAll()
@@ -261,4 +255,11 @@ export function allLastAppHost(targetOrOptions?: any, propertyKey?: string | sym
   } else {
     return queryAll(':lastAppHost', {});
   }
-}
+}
+
+
+export const getQueryAllMetadata = (target: any): QueryAllMetadata[] | undefined => {
+  const constructor = target instanceof Function ? target : target.constructor;
+  return ReflectUtils.getMetadata(QUERY_ALL_METADATA_KEY, constructor);
+};
+

package/src/decorators/subscribeSwcAppRouteChange.ts

@@ -0,0 +1,71 @@
+import { ReflectUtils } from '@dooboostore/core';
+import { Router } from '@dooboostore/core-web';
+
+export const SUBSCRIBE_SWC_APP_ROUTE_CHANGE_METADATA_KEY = Symbol.for('simple-web-component:subscribe-swc-app-route-change');
+
+export interface SwcAppRouteChangeSubscriberMetadata {
+  propertyKey: string | symbol;
+  pathPattern?: string | string[];
+  filter?: (router: Router) => boolean;
+}
+
+export interface SwcAppRouteChangeOptions {
+  path?: string | string[];
+  filter?: (router: Router) => boolean;
+}
+
+function createSwcAppRouteChangeSubscriber(options?: SwcAppRouteChangeOptions): MethodDecorator {
+  return (target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor) => {
+    const pathPattern = options?.path;
+    const filter = options?.filter;
+
+    const constructor = target.constructor;
+    let list = ReflectUtils.getOwnMetadata(SUBSCRIBE_SWC_APP_ROUTE_CHANGE_METADATA_KEY, constructor) as SwcAppRouteChangeSubscriberMetadata[];
+    if (!list) {
+      list = [];
+      ReflectUtils.defineMetadata(SUBSCRIBE_SWC_APP_ROUTE_CHANGE_METADATA_KEY, list, constructor);
+    }
+    list.push({ propertyKey, pathPattern, filter });
+    
+    return descriptor;
+  };
+}
+
+// 오버로드 시그니처 - 직접 사용 (괄호 없음)
+export function subscribeSwcAppRouteChange(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+// 오버로드 시그니처 - 함수 호출 (괄호 있음)
+export function subscribeSwcAppRouteChange(): MethodDecorator;
+export function subscribeSwcAppRouteChange(pathPattern: string): MethodDecorator;
+export function subscribeSwcAppRouteChange(pathPatterns: string[]): MethodDecorator;
+export function subscribeSwcAppRouteChange(options: SwcAppRouteChangeOptions): MethodDecorator;
+
+// 실제 구현 (이중 모드)
+export function subscribeSwcAppRouteChange(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
+  // 직접 데코레이터로 사용된 경우 (괄호 없음): @subscribeSwcAppRouteChange
+  // propertyKey가 string | symbol이고 descriptor가 있으면 직접 사용
+  if (propertyKey && (typeof propertyKey === 'string' || typeof propertyKey === 'symbol')) {
+    return createSwcAppRouteChangeSubscriber({})(targetOrOptions, propertyKey, descriptor);
+  }
+  
+  // 함수로 호출된 경우 (괄호 있음): @subscribeSwcAppRouteChange() / @subscribeSwcAppRouteChange('/path')
+  let options: SwcAppRouteChangeOptions = {};
+
+  if (Array.isArray(targetOrOptions)) {
+    // 배열: @subscribeSwcAppRouteChange(['/path1', '/path2'])
+    options.path = targetOrOptions;
+  } else if (typeof targetOrOptions === 'string') {
+    // 문자열: @subscribeSwcAppRouteChange('/path')
+    options.path = targetOrOptions;
+  } else if (targetOrOptions && typeof targetOrOptions === 'object') {
+    // 객체: @subscribeSwcAppRouteChange({ path: '/path', filter: ... })
+    options = targetOrOptions;
+  }
+
+  return createSwcAppRouteChangeSubscriber(options);
+}
+
+// Helper function to retrieve route change subscribers metadata
+export const getSubscribeSwcAppRouteChangeMetadata = (target: any): SwcAppRouteChangeSubscriberMetadata[] | undefined => {
+  const constructor = target instanceof Function ? target : target.constructor;
+  return ReflectUtils.getOwnMetadata(SUBSCRIBE_SWC_APP_ROUTE_CHANGE_METADATA_KEY, constructor);
+};