@dooboostore/simple-web-component 1.0.50 → 1.0.51

package/src/decorators/setInterval.ts

@@ -1,6 +1,7 @@
 import { ReflectUtils } from '@dooboostore/core';
-import { ensureInit, getElementConfig } from './elementDefine';
+import { ensureInit } from './elementDefine';
 import { SwcUtils } from '../utils/Utils';
+import { buildSwcParameterArgs } from './parameter';
 import { ElementDefineLifeCycler, HelperHostSet } from '../types';
 
 export const SET_INTERVAL_METADATA_KEY = Symbol.for('simple-web-component:set-interval');
@@ -18,6 +19,12 @@ export interface SetIntervalOptions {
   parameter?: (set: HelperHostSet) => any[];
   /** 타이머 등록 직후 1회 호출 (디버깅/로깅용). id는 실제 setInterval 반환값 - cleanup은 자동으로 처리되므로 직접 clear할 필요 없음. */
   created?: (set: HelperHostSet, id: number) => void;
+  /** [type:'onConnected' 전용] 매 tick 실행 여부 게이트. Promise<boolean>도 가능. false면 이 tick 스킵. */
+  filter?: (set: HelperHostSet) => boolean | Promise<boolean>;
+  /** [type:'onConnected' 전용] tick 핸들러 직전 훅. await되고, 리턴값은 @setIntervalBeforeReturn 으로 주입된다. */
+  before?: (set: HelperHostSet) => any | Promise<any>;
+  /** [type:'onConnected' 전용] tick 핸들러가 성공/실패해도 항상 실행되는 정리 훅. ctx로 인자/결과/에러. */
+  finally?: (set: HelperHostSet, ctx: { args: any[]; result?: any; error?: any }) => any | Promise<any>;
   /**
    * type:'onConnected' - 매 tick마다 데코레이트된 메서드의 리턴값이 객체이고 이 키의 값이 함수이면 (id: number)로 호출한다.
    * type:'returnValue' - 리턴값이 함수면 그 자체를, 객체면 이 키의 값이 함수일 때 그 값을 "실제로 반복 실행될 함수"로 사용한다.
@@ -33,15 +40,7 @@ export interface SetIntervalMetadata {
   options: SetIntervalOptions;
 }
 
-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_intervalIds ??= []);
 
 /**
  * type:'onConnected' - connect 시 자동으로 setInterval을 걸고, disconnect 시 자동으로 clearInterval 한다.
@@ -76,8 +75,7 @@ export function setInterval(interval: number, options: SetIntervalOptions = {}):
 
       if (tickFn) {
         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 = win.setInterval(() => {
           try {
             tickFn(id);
@@ -85,7 +83,7 @@ export function setInterval(interval: number, options: SetIntervalOptions = {}):
             console.error('[SWC] setInterval tick error:', e);
           }
         }, interval);
-        normalizedOptions.created?.(SwcUtils.getHelperAndHostSet(win, this), id);
+        normalizedOptions.created?.(SwcUtils.getHelperAndHostSet(this), id);
         getActiveEntries(this).push(id);
       }
       return res;
@@ -95,27 +93,40 @@ export function setInterval(interval: number, options: SetIntervalOptions = {}):
 }
 
 export const findAllSetIntervalMetadata = (target: any): SetIntervalMetadata[] => {
-  const constructor = target instanceof Function ? target : target.constructor;
+  const constructor = typeof target === 'function' ? target : target.constructor;
   return (ReflectUtils.findAllMetadata<SetIntervalMetadata[]>(SET_INTERVAL_METADATA_KEY, constructor) || []).flat();
 };
 
 export class SetIntervalLifeCycler implements ElementDefineLifeCycler {
   onConnected(helperHostSet: HelperHostSet): void {
     const inst = helperHostSet.$this;
-    activeMap.delete(inst); // 재연결 대비 리셋
+    inst.__swc_intervalIds = []; // 재연결 대비 리셋
     for (const meta of findAllSetIntervalMetadata(inst)) {
       if (meta.options.type !== 'onConnected') continue; // returnValue 타입은 수동 호출을 기다림
       const id = helperHostSet.$w.setInterval(() => {
-        const args = meta.options.parameter?.(helperHostSet) ?? [];
-        try {
-          const res = inst[meta.propertyKey](...args);
-          const vk = meta.options.valueKey ?? SET_INTERVAL_METADATA_KEY;
-          if (res && typeof res === 'object' && typeof res[vk] === 'function') {
-            res[vk](id);
+        void (async () => {
+          const helper = SwcUtils.getHelperAndHostSet(inst);
+          if (meta.options.filter && !(await meta.options.filter(helper))) return;
+          const paramArgs = meta.options.parameter?.(helperHostSet) ?? [];
+          const hostSet = SwcUtils.getHostSet(inst);
+          const helperSet = SwcUtils.getHelperSet(helperHostSet.$w);
+          const buildArgs = (beforeReturn: any) => buildSwcParameterArgs(inst, meta.propertyKey, {
+            hostSet, helperHostSet: helper, helperSet, setIntervalBeforeReturn: beforeReturn
+          }, [...paramArgs, beforeReturn]);
+          let args = buildArgs(undefined);
+          if (meta.options.before) { const br = await meta.options.before(helper); args = buildArgs(br); }
+          let result: any, error: any;
+          try {
+            result = await inst[meta.propertyKey](...args);
+            const vk = meta.options.valueKey ?? SET_INTERVAL_METADATA_KEY;
+            if (result && typeof result === 'object' && typeof result[vk] === 'function') result[vk](id);
+          } catch (e) {
+            error = e;
+          } finally {
+            if (meta.options.finally) await meta.options.finally(helper, { args, result, error });
           }
-        } catch (e) {
-          console.error('[SWC] setInterval tick error:', e);
-        }
+          if (error) console.error('[SWC] setInterval tick error:', error);
+        })().catch(e => console.error('[SWC] setInterval tick error:', e));
       }, meta.interval);
       meta.options.created?.(helperHostSet, id);
       getActiveEntries(inst).push(id);
@@ -124,13 +135,13 @@ export class SetIntervalLifeCycler implements ElementDefineLifeCycler {
 
   onDisconnected(helperHostSet: HelperHostSet): void {
     const inst = helperHostSet.$this;
-    for (const id of activeMap.get(inst) ?? []) {
+    for (const id of inst.__swc_intervalIds ?? []) {
       try {
         helperHostSet.$w.clearInterval(id);
       } catch (e) {
         console.error('[SWC] clearInterval error:', e);
       }
     }
-    activeMap.delete(inst);
+    inst.__swc_intervalIds = [];
   }
 }

package/src/decorators/setTimeout.ts

@@ -1,6 +1,7 @@
 import { ReflectUtils } from '@dooboostore/core';
-import { ensureInit, getElementConfig } from './elementDefine';
+import { ensureInit } from './elementDefine';
 import { SwcUtils } from '../utils/Utils';
+import { buildSwcParameterArgs } from './parameter';
 import { ElementDefineLifeCycler, HelperHostSet } from '../types';
 
 export const SET_TIMEOUT_METADATA_KEY = Symbol.for('simple-web-component:set-timeout');
@@ -18,6 +19,12 @@ export interface SetTimeoutOptions {
   parameter?: (set: HelperHostSet) => any[];
   /** 타이머 등록 직후 1회 호출 (디버깅/로깅용). id는 실제 setTimeout 반환값 - cleanup은 자동으로 처리되므로 직접 clear할 필요 없음. */
   created?: (set: HelperHostSet, id: number) => void;
+  /** [type:'onConnected' 전용] 발화 여부 게이트. Promise<boolean>도 가능. false면 스킵. */
+  filter?: (set: HelperHostSet) => boolean | Promise<boolean>;
+  /** [type:'onConnected' 전용] 핸들러 직전 훅. await되고, 리턴값은 @setTimeoutBeforeReturn 으로 주입된다. */
+  before?: (set: HelperHostSet) => any | Promise<any>;
+  /** [type:'onConnected' 전용] 핸들러가 성공/실패해도 항상 실행되는 정리 훅. ctx로 인자/결과/에러. */
+  finally?: (set: HelperHostSet, ctx: { args: any[]; result?: any; error?: any }) => any | Promise<any>;
   /**
    * type:'onConnected' - fire 시 데코레이트된 메서드의 리턴값이 객체이고 이 키의 값이 함수이면 (id: number)로 호출한다.
    * type:'returnValue' - 리턴값이 함수면 그 자체를, 객체면 이 키의 값이 함수일 때 그 값을 "실제로 실행될 함수"로 사용한다.
@@ -33,15 +40,7 @@ export interface SetTimeoutMetadata {
   options: SetTimeoutOptions;
 }
 
-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_timeoutIds ??= []);
 
 /**
  * type:'onConnected' - connect 시 자동으로 setTimeout을 걸고, disconnect 시 (아직 실행 전이라면) 자동으로 clearTimeout 한다.
@@ -76,8 +75,7 @@ export function setTimeout(delay: number, options: SetTimeoutOptions = {}): Meth
 
       if (tickFn) {
         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 = win.setTimeout(() => {
           const entries = getActiveEntries(this);
           const idx = entries.indexOf(id);
@@ -88,7 +86,7 @@ export function setTimeout(delay: number, options: SetTimeoutOptions = {}): Meth
             console.error('[SWC] setTimeout fire error:', e);
           }
         }, delay);
-        normalizedOptions.created?.(SwcUtils.getHelperAndHostSet(win, this), id);
+        normalizedOptions.created?.(SwcUtils.getHelperAndHostSet(this), id);
         getActiveEntries(this).push(id);
       }
       return res;
@@ -98,27 +96,40 @@ export function setTimeout(delay: number, options: SetTimeoutOptions = {}): Meth
 }
 
 export const findAllSetTimeoutMetadata = (target: any): SetTimeoutMetadata[] => {
-  const constructor = target instanceof Function ? target : target.constructor;
+  const constructor = typeof target === 'function' ? target : target.constructor;
   return (ReflectUtils.findAllMetadata<SetTimeoutMetadata[]>(SET_TIMEOUT_METADATA_KEY, constructor) || []).flat();
 };
 
 export class SetTimeoutLifeCycler implements ElementDefineLifeCycler {
   onConnected(helperHostSet: HelperHostSet): void {
     const inst = helperHostSet.$this;
-    activeMap.delete(inst); // 재연결 대비 리셋
+    inst.__swc_timeoutIds = []; // 재연결 대비 리셋
     for (const meta of findAllSetTimeoutMetadata(inst)) {
       if (meta.options.type !== 'onConnected') continue; // returnValue 타입은 수동 호출을 기다림
       const id = helperHostSet.$w.setTimeout(() => {
-        const args = meta.options.parameter?.(helperHostSet) ?? [];
-        try {
-          const res = inst[meta.propertyKey](...args);
-          const vk = meta.options.valueKey ?? SET_TIMEOUT_METADATA_KEY;
-          if (res && typeof res === 'object' && typeof res[vk] === 'function') {
-            res[vk](id);
+        void (async () => {
+          const helper = SwcUtils.getHelperAndHostSet(inst);
+          if (meta.options.filter && !(await meta.options.filter(helper))) return;
+          const paramArgs = meta.options.parameter?.(helperHostSet) ?? [];
+          const hostSet = SwcUtils.getHostSet(inst);
+          const helperSet = SwcUtils.getHelperSet(helperHostSet.$w);
+          const buildArgs = (beforeReturn: any) => buildSwcParameterArgs(inst, meta.propertyKey, {
+            hostSet, helperHostSet: helper, helperSet, setTimeoutBeforeReturn: beforeReturn
+          }, [...paramArgs, beforeReturn]);
+          let args = buildArgs(undefined);
+          if (meta.options.before) { const br = await meta.options.before(helper); args = buildArgs(br); }
+          let result: any, error: any;
+          try {
+            result = await inst[meta.propertyKey](...args);
+            const vk = meta.options.valueKey ?? SET_TIMEOUT_METADATA_KEY;
+            if (result && typeof result === 'object' && typeof result[vk] === 'function') result[vk](id);
+          } catch (e) {
+            error = e;
+          } finally {
+            if (meta.options.finally) await meta.options.finally(helper, { args, result, error });
           }
-        } catch (e) {
-          console.error('[SWC] setTimeout fire error:', e);
-        }
+          if (error) console.error('[SWC] setTimeout fire error:', error);
+        })().catch(e => console.error('[SWC] setTimeout fire error:', e));
       }, meta.delay);
       meta.options.created?.(helperHostSet, id);
       getActiveEntries(inst).push(id);
@@ -127,13 +138,13 @@ export class SetTimeoutLifeCycler implements ElementDefineLifeCycler {
 
   onDisconnected(helperHostSet: HelperHostSet): void {
     const inst = helperHostSet.$this;
-    for (const id of activeMap.get(inst) ?? []) {
+    for (const id of inst.__swc_timeoutIds ?? []) {
       try {
         helperHostSet.$w.clearTimeout(id);
       } catch (e) {
         console.error('[SWC] clearTimeout error:', e);
       }
     }
-    activeMap.delete(inst);
+    inst.__swc_timeoutIds = [];
   }
 }

package/src/decorators/state.ts

@@ -1,7 +1,6 @@
 import {ReflectUtils} from '@dooboostore/core';
 import {ElementApply} from "@dooboostore/core-web";
 import {SwcUtils} from "../utils/Utils";
-import {getElementConfig} from "./elementDefine";
 
 export interface StateMetadata {
   propertyKey: string | symbol;
@@ -15,23 +14,22 @@ export const STATE_METADATA_KEY = Symbol.for('simple-web-component:state');
 export function state(target: Object, propertyKey: string | symbol): void;
 export function state(name: string): PropertyDecorator;
 /**
- * Supports both forms:
+ * Forms (빈 괄호 @state() 는 타입 에러):
  * - @state
- * - @state()
  * - @state('selector')
  */
 export function state(nameOrTarget?: string | Object, propertyKey?: string | symbol): any {
 
   const stateDefine = (targetObj: any, stateMetadata: StateMetadata) => {
 
-    let storage = targetObj[stateMetadata.propertyKey];
-    // console.log('ssssssssssssssss', storage, stateMetadata.propertyKey)
+    // around.ts와 동일: 클로저 변수에 두면 모든 인스턴스가 공유해버리므로
+    // 인스턴스 전용 Symbol 슬롯에 실제 값을 둔다.
+    const storageKey = Symbol(`state:${String(stateMetadata.propertyKey)}`);
     Object.defineProperty(targetObj, stateMetadata.propertyKey, {
       set(this: any, nv: string) {
-        storage = nv;
-        const config = getElementConfig(this)
+        this[storageKey] = nv;
         const ea = new ElementApply(this, {id: this._swcId});
-        const helperHostSet = SwcUtils.getHelperAndHostSet(config.window, this);
+        const helperHostSet = SwcUtils.getHelperAndHostSet(this);
         const stateContext: any = {...helperHostSet};
         findAllStateMetadata(this).forEach(it => {
           stateContext[it.name] = this[it.propertyKey]
@@ -39,7 +37,15 @@ export function state(nameOrTarget?: string | Object, propertyKey?: string | sym
         ea.apply({context:stateContext, targetVariableName: stateMetadata.name, bind: this});
       },
       get(this: any) {
-        return storage;
+        // 안전망: 필드 이니셜라이저의 own property가 남아있다면(ensureInit이 안 돈
+        // 일반 클래스 등) 슬롯으로 회수한다. setter 경유는 안 함 — setter의 DOM
+        // 동기화는 초기화 전에 돌면 안 되므로 직접 슬롯에 둔다.
+        const own = Object.getOwnPropertyDescriptor(this, stateMetadata.propertyKey);
+        if (own && 'value' in own) {
+          delete this[stateMetadata.propertyKey];
+          this[storageKey] = own.value;
+        }
+        return this[storageKey];
       },
       enumerable: true,
       configurable: true
@@ -51,7 +57,7 @@ export function state(nameOrTarget?: string | Object, propertyKey?: string | sym
     const targetObj = nameOrTarget as Object;
     const name = String(propertyKey);
     const constructor = (targetObj as any).constructor;
-    let states = ReflectUtils.getMetadata<StateMetadata[]>(STATE_METADATA_KEY, constructor);
+    let states = ReflectUtils.getOwnMetadata(STATE_METADATA_KEY, constructor) as StateMetadata[] | undefined;
     if (!states) {
       states = [];
       ReflectUtils.defineMetadata(STATE_METADATA_KEY, states, constructor);
@@ -66,7 +72,7 @@ export function state(nameOrTarget?: string | Object, propertyKey?: string | sym
   return (targetObj: Object, propertyKey: string | symbol): void => {
     const name = String(nameOrTarget);
     const constructor = targetObj.constructor;
-    let states = ReflectUtils.getMetadata<StateMetadata[]>(STATE_METADATA_KEY, constructor);
+    let states = ReflectUtils.getOwnMetadata(STATE_METADATA_KEY, constructor) as StateMetadata[] | undefined;
     if (!states) {
       states = [];
       ReflectUtils.defineMetadata(STATE_METADATA_KEY, states, constructor);
@@ -78,6 +84,6 @@ export function state(nameOrTarget?: string | Object, propertyKey?: string | sym
 }
 
 export const findAllStateMetadata = (target: any): StateMetadata[] => {
-  const constructor = target instanceof Function ? target : target.constructor;
-  return ReflectUtils.getMetadata(STATE_METADATA_KEY, constructor) ?? [];
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return ReflectUtils.findAllMetadata<any[]>(STATE_METADATA_KEY, constructor).flat();
 };

package/src/decorators/subscribeSwcAppMessage.ts

@@ -0,0 +1,106 @@
+import { ReflectUtils } from '@dooboostore/core';
+import { SwcAppMessage, SwcAppMessageSubject, SpecialSelector, SwcQueryOptions, HelperHostSet } from '../types';
+
+export const SUBSCRIBE_SWC_APP_MESSAGE_METADATA_KEY = Symbol.for('simple-web-component:subscribe-swc-app-message');
+
+export interface SwcAppMessageOptions<Data = any, BeforeReturn = any, Result = any> {
+  /** 메시지 수신 시 핸들러 실행 여부 게이트. Promise<boolean>도 되어 async 판정 가능. false면 스킵. */
+  filter?: (message: SwcAppMessage<Data>, currentThis: any) => boolean | Promise<boolean>;
+  /** filter 통과 후 핸들러 직전 훅. await되고, 리턴값은 @appMessageBeforeReturn 으로 핸들러에 주입된다. */
+  before?: (message: SwcAppMessage<Data>, currentThis: any) => BeforeReturn | Promise<BeforeReturn>;
+  /** 핸들러가 성공/실패해도 항상 실행되는 정리 훅. ctx로 핸들러 인자/결과/에러를 받는다. 에러는 삼키지 않고 전파. */
+  finally?: (message: SwcAppMessage<Data>, currentThis: any, ctx: { args: any[]; result?: Result; error?: any }) => any | Promise<any>;
+  /**
+   * 늦게 연결된 경우 과거 메시지 재생 방식. 이미 연결된 구독자에게는 항상 live로 쏨.
+   * - 미지정/'subject': live만. 지나간 건 못 받음 (기본값, 기존 동작)
+   * - 'behavior': 마지막 1개 재생
+   * - 'replay': 버퍼 전체 시간순 재생
+   */
+  subject?: SwcAppMessageSubject;
+  /**
+   * 재생 시점. 기본 'connected' (연결 즉시).
+   * - 'connectedDone': 엘리먼트 render 완료 후 (_connectedDone). @innerHtml 등
+   *   DOM 타겟이 필요한 핸들러는 이걸로 (replay가 render보다 먼저 와서 증발하는 레이스 방지).
+   */
+  trigger?: 'connected' | 'connectedDone';
+}
+
+export interface SwcAppMessageSubscriberMetadata extends SwcAppMessageOptions {
+  propertyKey: string | symbol;
+  messageType?: string;
+}
+
+function createSubscribeSwcAppMessage(options?: SwcAppMessageOptions, messageType?: string): MethodDecorator {
+  return (target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor) => {
+    const constructor = target.constructor;
+    let list = ReflectUtils.getOwnMetadata(SUBSCRIBE_SWC_APP_MESSAGE_METADATA_KEY, constructor) as SwcAppMessageSubscriberMetadata[];
+    if (!list) {
+      list = [];
+      ReflectUtils.defineMetadata(SUBSCRIBE_SWC_APP_MESSAGE_METADATA_KEY, list, constructor);
+    }
+    list.push({ propertyKey, messageType, filter: options?.filter, before: options?.before, finally: options?.finally, subject: options?.subject, trigger: options?.trigger });
+    
+    return descriptor;
+  };
+}
+
+// 오버로드 시그니처 - 직접 사용 (괄호 없음)
+export function subscribeSwcAppMessage(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+// 오버로드 시그니처 - 함수 호출 (괄호 있음) - 메시지 타입만
+export function subscribeSwcAppMessage(messageType: string): MethodDecorator;
+// 오버로드 시그니처 - 함수 호출 (괄호 있음) - 옵션만
+export function subscribeSwcAppMessage<Data = any, BeforeReturn = any, Result = any>(options: SwcAppMessageOptions<NoInfer<Data>, NoInfer<BeforeReturn>, NoInfer<Result>>): MethodDecorator;
+// 오버로드 시그니처 - 함수 호출 (괄호 있음) - 메시지 타입 + 옵션
+export function subscribeSwcAppMessage<Data = any, BeforeReturn = any, Result = any>(messageType: string, options: SwcAppMessageOptions<NoInfer<Data>, NoInfer<BeforeReturn>, NoInfer<Result>>): MethodDecorator;
+
+export function subscribeSwcAppMessage(targetOrMessageTypeOrOptions?: any, optionsOrPropertyKey?: any, descriptor?: PropertyDescriptor): any {
+  // 직접 데코레이터로 사용된 경우 (괄호 없음): @subscribeSwcAppMessage
+  if (targetOrMessageTypeOrOptions && typeof targetOrMessageTypeOrOptions === 'object' && 
+      optionsOrPropertyKey && (typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol') &&
+      descriptor) {
+    const target = targetOrMessageTypeOrOptions;
+    const propertyKey = optionsOrPropertyKey;
+    return createSubscribeSwcAppMessage({})(target, propertyKey, descriptor);
+  }
+
+  // 함수로 호출된 경우 (괄호 있음)
+  let messageType: string | undefined;
+  let options: SwcAppMessageOptions = {};
+
+  if (typeof targetOrMessageTypeOrOptions === 'string') {
+    // 메시지 타입 전달: @subscribeSwcAppMessage('messageType') 또는 @subscribeSwcAppMessage('messageType', options)
+    messageType = targetOrMessageTypeOrOptions;
+    if (optionsOrPropertyKey && typeof optionsOrPropertyKey === 'object') {
+      options = optionsOrPropertyKey;
+    }
+  } else if (targetOrMessageTypeOrOptions && typeof targetOrMessageTypeOrOptions === 'object') {
+    // 옵션만 전달: @subscribeSwcAppMessage({ filter: ... })
+    options = targetOrMessageTypeOrOptions;
+  }
+
+  return createSubscribeSwcAppMessage(options, messageType);
+}
+
+export const receiveMessage = subscribeSwcAppMessage;
+// Helper function to retrieve message subscribers metadata
+export const getSubscribeSwcAppMessageMetadata = (target: any): SwcAppMessageSubscriberMetadata[] | undefined => {
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return ReflectUtils.findAllMetadata<any[]>(SUBSCRIBE_SWC_APP_MESSAGE_METADATA_KEY, constructor).flat();
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MessageSubscribeLifeCycler
+// NOTE: 실제 구독 로직은 SwcAppMixin._connected 에서 처리된다.
+// ─────────────────────────────────────────────────────────────────────────────
+import { ElementDefineLifeCycler } from '../types';
+
+export class MessageSubscribeLifeCycler implements ElementDefineLifeCycler {
+  onConnected(_helperHostSet: HelperHostSet): void {
+    // 실제 구독은 SwcAppMixin._connected 에서 처리
+  }
+
+  /** SwcAppMixin 이 구독 대상 메타를 꺼낼 때 사용 */
+  getMetadata(helperHostSet: HelperHostSet): SwcAppMessageSubscriberMetadata[] | undefined {
+    return getSubscribeSwcAppMessageMetadata(helperHostSet.$this);
+  }
+}

package/src/decorators/subscribeSwcAppRouteChange.ts

@@ -0,0 +1,131 @@
+import {ReflectUtils} from '@dooboostore/core';
+import {Router} from '@dooboostore/core-web';
+import {HelperHostSet} from '../types';
+
+export const SUBSCRIBE_SWC_APP_ROUTE_CHANGE_METADATA_KEY = Symbol.for('simple-web-component:subscribe-swc-app-route-change');
+
+export type RoutePathType = string | string[] | ((currentThis: any) => string | string[]);
+
+export interface SwcAppRouteChangeSubscriberMetadata {
+  propertyKey: string | symbol;
+  options?: SwcAppRouteChangeOptions;
+}
+
+export interface SwcAppRouteChangeOptions<BeforeReturn = any, Result = any> {
+  path?: RoutePathType;
+  /** 라우트 변경 시 핸들러 실행 여부 게이트. Promise<boolean>도 되어 async 가드(인증 체크 등) 가능. false면 스킵. */
+  filter?: (router: Router, meta: { currentThis: any; helper: HelperHostSet }) => boolean | Promise<boolean>;
+  /** filter 통과 후 핸들러 직전 훅. await되고, 리턴값은 @routeChangeBeforeReturn 으로 핸들러에 주입된다. */
+  before?: (router: Router, meta: { currentThis: any; helper: HelperHostSet }) => BeforeReturn | Promise<BeforeReturn>;
+  /** 핸들러가 성공/실패해도 항상 실행되는 정리 훅. ctx로 핸들러 인자/결과/에러를 받는다. 에러는 삼키지 않고 전파. */
+  finally?: (router: Router, meta: { currentThis: any; helper: HelperHostSet }, ctx: { args: any[]; result?: Result; error?: any }) => any | Promise<any>;
+  order?: number;
+  valueKey?: symbol | string;
+  /**
+   * 늦게 붙은 인스턴스에 마지막 라우트 재생 시점. 기본 'connected'.
+   * - 'connectedDone': render 완료 후 (_connectedDone). DOM 타겟 필요한 핸들러용.
+   * - live 라우트 변경(전체 방송) 때는 항상 실행. replay에만 적용.
+   */
+  trigger?: 'connected' | 'connectedDone';
+  /**
+   * 언제 실행할지. 기본 'match'(경로가 맞을 때마다 — 기존 동작).
+   * - 'enter': 안 맞다가 맞게 됐을 때 (처음 붙을 때의 재생 포함)
+   * - 'update': 계속 맞는데 경로나 query 가 바뀌었을 때
+   * - 'leave': 맞다가 안 맞게 됐을 때 (요소가 붙어 있을 때만 — 교체되는 페이지는 onDisconnected 가 담당)
+   * - 'beforeLeave': 이 경로를 떠나기 전. false(또는 Promise<false>)를 리턴하면 이동 취소 (router.go / 뒤로·앞으로 가기)
+   */
+  on?: 'match' | 'enter' | 'update' | 'leave' | 'beforeLeave';
+}
+
+function createSubscribeSwcAppRouteChange(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, options });
+
+    return descriptor;
+  };
+}
+
+// 오버로드 시그니처 - 직접 사용 (괄호 없음)
+export function subscribeSwcAppRouteChange(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+// 오버로드 시그니처 - 함수 호출 (괄호 있음)
+export function subscribeSwcAppRouteChange(pathPattern: RoutePathType): MethodDecorator;
+export function subscribeSwcAppRouteChange<BeforeReturn = any, Result = any>(pathPattern: RoutePathType, config: Omit<SwcAppRouteChangeOptions<NoInfer<BeforeReturn>, NoInfer<Result>>, 'path'>): MethodDecorator;
+export function subscribeSwcAppRouteChange<BeforeReturn = any, Result = any>(options: SwcAppRouteChangeOptions<NoInfer<BeforeReturn>, NoInfer<Result>>): MethodDecorator;
+
+// 실제 구현 (이중 모드)
+export function subscribeSwcAppRouteChange(targetOrOptions?: any, propertyKeyOrConfig?: any, descriptor?: PropertyDescriptor): any {
+  // 직접 데코레이터로 사용된 경우 (괄호 없음): @subscribeSwcAppRouteChange
+  // propertyKey가 string | symbol이고 descriptor가 있으면 직접 사용
+  if (propertyKeyOrConfig && (typeof propertyKeyOrConfig === 'string' || typeof propertyKeyOrConfig === 'symbol')) {
+    return createSubscribeSwcAppRouteChange({})(targetOrOptions, propertyKeyOrConfig, descriptor);
+  }
+
+  // 함수로 호출된 경우 (인자 있음): @subscribeSwcAppRouteChange('/path')
+  let options: SwcAppRouteChangeOptions = {};
+
+  if (Array.isArray(targetOrOptions)) {
+    // 배열: @subscribeSwcAppRouteChange(['/path1', '/path2'])
+    // 또는: @subscribeSwcAppRouteChange(['/path1', '/path2'], { order: 1 })
+    options.path = targetOrOptions;
+    if (propertyKeyOrConfig && typeof propertyKeyOrConfig === 'object') {
+      options = { ...options, ...propertyKeyOrConfig };
+    }
+  } else if (typeof targetOrOptions === 'string' || typeof targetOrOptions === 'function') {
+    // 문자열 또는 함수: @subscribeSwcAppRouteChange('/path')
+    // 또는: @subscribeSwcAppRouteChange('/path', { order: 1 })
+    options.path = targetOrOptions;
+    if (propertyKeyOrConfig && typeof propertyKeyOrConfig === 'object') {
+      options = { ...options, ...propertyKeyOrConfig };
+    }
+  } else if (targetOrOptions && typeof targetOrOptions === 'object') {
+    // 객체: @subscribeSwcAppRouteChange({ path: '/path', filter: ..., order: 1 })
+    options = targetOrOptions;
+  }
+
+  return createSubscribeSwcAppRouteChange(options);
+}
+export const changedRoute = subscribeSwcAppRouteChange;
+
+// 늦게 붙은 인스턴스도 렌더 완료 후 마지막 라우트를 재생 — DOM 타겟 핸들러용.
+// @subscribeSwcAppRouteChange(path, { trigger: 'connectedDone' }) 의 단축형.
+export function subscribeSwcAppRouteChangeConnectedDone<BeforeReturn = any, Result = any>(pathPattern: RoutePathType, config?: Omit<SwcAppRouteChangeOptions<NoInfer<BeforeReturn>, NoInfer<Result>>, 'path' | 'trigger'>): MethodDecorator {
+  return subscribeSwcAppRouteChange(pathPattern, { ...config, trigger: 'connectedDone' });
+}
+
+// Helper function to retrieve route change subscribers metadata
+export const getSubscribeSwcAppRouteChangeMetadata = (target: any): SwcAppRouteChangeSubscriberMetadata[] => {
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  const results = ReflectUtils.findAllMetadata<any[]>(SUBSCRIBE_SWC_APP_ROUTE_CHANGE_METADATA_KEY, constructor).flat();
+  if (!results) return [];
+  
+  // Sort by order (default 0 if not specified)
+  return [...results].sort((a, b) => (a.options?.order ?? 0) - (b.options?.order ?? 0));
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RouteSubscribeLifeCycler
+// NOTE: 실제 구독 로직은 SwcAppMixin._connected 에서 처리된다.
+//       이 cycler 는 메타데이터 접근 진입점 역할만 하며,
+//       향후 SwcAppMixin 에서 로직을 분리할 때 이 클래스로 이전한다.
+// ─────────────────────────────────────────────────────────────────────────────
+import { ElementDefineLifeCycler } from '../types';
+
+export class RouteSubscribeLifeCycler implements ElementDefineLifeCycler {
+  onConnected(_helperHostSet: HelperHostSet): void {
+    // 실제 구독은 SwcAppMixin._connected 에서 처리
+  }
+
+  /** SwcAppMixin 이 구독 대상 메타를 꺼낼 때 사용 */
+  getMetadata(helperHostSet: HelperHostSet): SwcAppRouteChangeSubscriberMetadata[] {
+    return getSubscribeSwcAppRouteChangeMetadata(helperHostSet.$this);
+  }
+}