@dooboostore/simple-web-component 1.0.54 → 1.0.55

package/src/decorators/parameter.ts

@@ -1,17 +1,23 @@
 import { ReflectUtils } from '@dooboostore/core';
+import { SwcUtils } from '../utils/Utils';
+import { QuerySelector, QueryOptions, QueryBaseOptions, resolveQueryElements, pickElements } from './query';
+import { AttributeOptions, AttributeSelector, getAttributeValue } from './applyAttribute';
+import { PersistOptions, persistRead, persistReadAsync } from './persistState';
+import type { HelperHostSet, SwcAppMessageSubject } from '../types';
 
 /**
- * @eventObject/@matchedElement/@hostSet/@helperHostSet/@helperSet/@swcAppRouterEvent/@appMessage/@eventBeforeReturn —
+ * @eventObject/@matchedElement/@hostSet/@helperHostSet/@helperSet/@swcAppRouterEvent/@swcAppMessage/@eventBeforeReturn —
  * @event/lifecycle/subscribeSwcAppRouteChange/subscribeSwcAppMessage
  * 계열 핸들러의 파라미터를 순서 무관하게 선언할 수 있게 해주는 파라미터 데코레이터.
  * @dooboostore/simple-boot의 @Inject와 동일한 인덱스 기반 메타데이터 패턴을 따른다:
  * 데코레이터가 실행되는 순서가 아니라 실제 parameterIndex로 슬롯을 매칭하므로,
  * 사용자가 파라미터 선언 순서를 자유롭게 바꿔도 된다.
  */
-export type SwcParamKind = 'eventObject' | 'matchedElement' | 'hostSet' | 'helperHostSet' | 'helperSet' | 'swcAppRouterEvent' | 'appMessage' | 'eventBeforeReturn' | 'appMessageBeforeReturn' | 'routeChangeBeforeReturn' | 'eventMediaBeforeReturn' | 'mutationObserverBeforeReturn' | 'intersectionObserverBeforeReturn' | 'resizeObserverBeforeReturn' | 'changedAttributeBeforeReturn' | 'setTimeoutBeforeReturn' | 'setIntervalBeforeReturn' | 'fetchSettled'
+export type SwcParamKind = 'eventObject' | 'matchedElement' | 'hostSet' | 'helperHostSet' | 'helperSet' | 'swcAppRouterEvent' | 'swcAppRouter' | 'swcAppSimpleApplication' | 'swcAppHost' | 'swcAppMessage' | 'eventBeforeReturn' | 'swcAppMessageBeforeReturn' | 'routeChangeBeforeReturn' | 'eventMediaBeforeReturn' | 'mutationObserverBeforeReturn' | 'intersectionObserverBeforeReturn' | 'resizeObserverBeforeReturn' | 'changedAttributeBeforeReturn' | 'setTimeoutBeforeReturn' | 'setIntervalBeforeReturn' | 'fetchPromise'
+  | 'querySelectorParam' | 'querySelectorAllParam' | 'attributeParam' | 'localStorageParam' | 'sessionStorageParam' | 'cookieParam' | 'indexedDbParam' | 'fetchParam'
   | SwcRouteParamKind;
 
-/** 라우트 핸들러 전용 (subscribeSwcAppRouteChange 가 채움). kind 이름 = 데코레이터 이름 */
+/** 라우트 값 (kind 이름 = 데코레이터 이름). 파라미터면 subscribeSwcAppRouteChange 핸들러 인자로, 필드면 SwcApp 이 라우트 변경 때 채운다 */
 export type SwcRouteParamKind =
   | 'swcAppRouteQueryParam' | 'swcAppRouteFirstQueryParam' | 'swcAppRouteLastQueryParam' | 'swcAppRouteQueryParams'
   | 'swcAppRouteQueryParamObject' | 'swcAppRouteFirstQueryParamObject' | 'swcAppRouteLastQueryParamObject' | 'swcAppRouteQueryParamsObject'
@@ -21,10 +27,10 @@ export type SwcRouteParamKind =
 
 const SWC_PARAMETER_METADATA_KEY = Symbol.for('simple-web-component:parameter');
 
-/** key: @swcAppRouteQueryParam('q') 처럼 키를 받는 파라미터 데코레이터의 키 */
-type SaveParamConfig = { index: number; kind: SwcParamKind; key?: string };
+/** key: @swcAppRouteQueryParam('q') 처럼 키를 받는 파라미터 데코레이터의 키 (querySelectorParam/attributeParam은 객체를 담는다) */
+type SaveParamConfig = { index: number; kind: SwcParamKind; key?: any };
 
-const registerParam = (kind: SwcParamKind, target: Object, propertyKey: string | symbol | undefined, parameterIndex: number, key?: string) => {
+const registerParam = (kind: SwcParamKind, target: Object, propertyKey: string | symbol | undefined, parameterIndex: number, key?: any) => {
   if (!propertyKey) return;
   const constructor = target.constructor;
   const saves = (ReflectUtils.getOwnMetadata(SWC_PARAMETER_METADATA_KEY, constructor, propertyKey) ?? []) as SaveParamConfig[];
@@ -62,9 +68,73 @@ export function swcAppRouterEvent(target: Object, propertyKey: string | symbol,
   registerParam('swcAppRouterEvent', target, propertyKey, parameterIndex);
 }
 
-/** @subscribeSwcAppMessage 핸들러의 SwcAppMessage 페이로드를 주입한다. */
-export function appMessage(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
-  registerParam('appMessage', target, propertyKey, parameterIndex);
+/**
+ * Router 인스턴스($appHost.router)를 주입한다 — @Inject(DI) 없이도 router.go()/pathData 등에 바로 접근.
+ * SwcApp 트리 밖(standalone, $appHost 없음)이면 undefined.
+ */
+export function swcAppRouter(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('swcAppRouter', target, propertyKey, parameterIndex);
+}
+
+/**
+ * SimpleApplication(DI 컨테이너) 인스턴스($appHost.simpleApplication)를 주입한다 —
+ * simstanceManager 등 컨테이너 자체를 직접 다뤄야 할 때. 보통은 @inject로 충분하니 그거부터 고려할 것.
+ * SwcApp 트리 밖이거나 DI 컨테이너 없이 쓰는 standalone이면 undefined.
+ */
+export function swcAppSimpleApplication(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('swcAppSimpleApplication', target, propertyKey, parameterIndex);
+}
+
+/**
+ * SwcApp 호스트 엘리먼트 자신($appHost)을 주입한다 — @hostSet으로도 hs.$appHost로 바로 꺼내지지만,
+ * HostSet 전체 말고 호스트 하나만 필요할 때 짧게 쓰는 용도. SwcApp 트리 밖이면 undefined.
+ */
+export function swcAppHost(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('swcAppHost', target, propertyKey, parameterIndex);
+}
+
+// ─── @swcAppMessage: 파라미터(@subscribeSwcAppMessage 핸들러의 메시지) · 필드(발행될 때마다 최신 메시지) ───
+
+/** 필드용 옵션 — @subscribeSwcAppMessage 와 같은 규칙. subject 는 messageType 이 있을 때만 의미가 있다 */
+export type SwcAppMessageFieldOptions = { messageType?: string; subject?: SwcAppMessageSubject };
+export type SwcAppMessageFieldConfig = { propertyKey: string | symbol; messageType?: string; subject?: SwcAppMessageSubject };
+/** 파라미터·필드 겸용 데코레이터. 세 번째 인자가 숫자면 파라미터, 아니면 필드 */
+export type SwcAppMessageDecorator = (target: Object, propertyKey: string | symbol | undefined, parameterIndex?: number) => void;
+
+const SWC_MESSAGE_FIELD_METADATA_KEY = Symbol.for('simple-web-component:message-field');
+
+const applySwcAppMessage = (target: Object, propertyKey: string | symbol | undefined, parameterIndex: number | undefined, options?: SwcAppMessageFieldOptions) => {
+  if (typeof parameterIndex === 'number') return registerParam('swcAppMessage', target, propertyKey, parameterIndex);
+  if (propertyKey === undefined) return;
+  const constructor = target.constructor;
+  const list = (ReflectUtils.getOwnMetadata(SWC_MESSAGE_FIELD_METADATA_KEY, constructor) ?? []) as SwcAppMessageFieldConfig[];
+  list.push({ propertyKey, ...(options?.messageType ? { messageType: options.messageType } : {}), ...(options?.subject ? { subject: options.subject } : {}) });
+  ReflectUtils.defineMetadata(SWC_MESSAGE_FIELD_METADATA_KEY, list, constructor);
+};
+
+/** 상속 체인 전체의 메시지 필드 설정 */
+export const getSwcAppMessageFieldMetadata = (target: any): SwcAppMessageFieldConfig[] => {
+  const constructor = target instanceof Function ? target : target?.constructor;
+  if (!constructor) return [];
+  return (ReflectUtils.findAllMetadata<SwcAppMessageFieldConfig[]>(SWC_MESSAGE_FIELD_METADATA_KEY, constructor) || []).flat();
+};
+
+/**
+ * 파라미터: @subscribeSwcAppMessage 핸들러의 SwcAppMessage 를 주입한다 — onMsg(@swcAppMessage m) { ... }
+ * 필드: SwcApp 이 메시지를 발행할 때마다 그 필드에 최신 SwcAppMessage 를 넣는다 (같은 요소의 구독 핸들러보다 먼저).
+ *   @swcAppMessage last?: SwcAppMessage                              전 타입 (live만)
+ *   @swcAppMessage('login') login?: SwcAppMessage                    login (live만 — subject 기본값)
+ *   @swcAppMessage('login', { subject: 'behavior' }) login?          늦게 붙어도 마지막 1개로 채움
+ *   @swcAppMessage({ messageType: 'login', subject: 'replay' }) ...   버퍼를 시간순으로 넣음 (마지막 값이 남음)
+ */
+export function swcAppMessage(target: Object, propertyKey: string | symbol | undefined, parameterIndex?: number): void;
+export function swcAppMessage(messageType: string, options?: Omit<SwcAppMessageFieldOptions, 'messageType'>): SwcAppMessageDecorator;
+export function swcAppMessage(options: SwcAppMessageFieldOptions): SwcAppMessageDecorator;
+export function swcAppMessage(a: any, b?: any, c?: any): any {
+  // 데코레이터로 바로 불렸으면 (target, propertyKey, …) — propertyKey 는 문자열/심볼
+  if (typeof b === 'string' || typeof b === 'symbol') return applySwcAppMessage(a, b, c);
+  const options: SwcAppMessageFieldOptions = typeof a === 'string' ? { ...(b ?? {}), messageType: a } : { ...(a ?? {}) };
+  return ((target, propertyKey, parameterIndex) => applySwcAppMessage(target, propertyKey, parameterIndex, options)) as SwcAppMessageDecorator;
 }
 
 /**
@@ -79,10 +149,11 @@ export function eventBeforeReturn(target: Object, propertyKey: string | symbol,
 /**
  * @subscribeSwcAppMessage 의 before 훅이 이번 호출에 리턴한 값을 주입한다.
  * (before에서 async로 준비한 데이터를 핸들러가 받는 용도. 없으면 undefined)
- * 예: onMsg(@appMessage m, @appMessageBeforeReturn prepared) { ... }
+ * 예: onMsg(@swcAppMessage m, @swcAppMessageBeforeReturn prepared) { ... }
+ * 핸들러 호출마다 생기는 값이라 파라미터 전용이다 (필드에는 붙이지 않는다).
  */
-export function appMessageBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
-  registerParam('appMessageBeforeReturn', target, propertyKey, parameterIndex);
+export function swcAppMessageBeforeReturn(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('swcAppMessageBeforeReturn', target, propertyKey, parameterIndex);
 }
 
 /**
@@ -133,11 +204,114 @@ export function setIntervalBeforeReturn(target: Object, propertyKey: string | sy
 }
 
 /**
- * @fetch(trigger:'before') 의 fetch settled 결과(PromiseSettledResult)를 주입한다.
- * 예: save(@fetchSettled settled) { ... }
+ * @fetch(before 모드)가 시작한 요청의 Promise 를 주입한다. 메서드는 요청을 기다리지 않고 바로 불리고,
+ * 기다릴지·어떻게 처리할지(then/catch/finally)는 메서드가 정한다. 실패는 reject, 프레임워크가 끊으면 끝나지 않는다.
+ * 예: load(@fetchPromise p: Promise<Post>) { return p.then(post => post.title); }
  */
-export function fetchSettled(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
-  registerParam('fetchSettled', target, propertyKey, parameterIndex);
+export function fetchPromise(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('fetchPromise', target, propertyKey, parameterIndex);
+}
+
+/**
+ * 셀렉터로 찾은 DOM 요소 하나를 주입한다 — 필드용 @query 데코레이터(query.ts)와 같은 탐색 엔진 재사용.
+ * options.root로 'light'/'shadow'/'auto'(기본)/'all' 탐색 범위를 그대로 지정할 수 있다(@query와 동일).
+ * onConnectedAfter/addEventListener/setInterval 등 "자동 트리거" 메서드에서만 채워진다
+ * (buildCommonKindValues를 거치는 호출부 한정 — 임의로 직접 호출하는 메서드에는 못 꽂는다).
+ * URL의 query parameter와 헷갈리지 않도록 "query"가 아니라 "querySelector"로 이름 붙였다.
+ * 예: onReady(@querySelectorParam('#name') input: HTMLInputElement) { ... }
+ */
+export function querySelectorParam(selector: QuerySelector, options?: QueryOptions): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => registerParam('querySelectorParam', target, propertyKey, parameterIndex, { selector, options });
+}
+
+/** @querySelectorParam의 복수형 — 매칭된 모든 요소를 배열로 주입한다(= @queryAll, pick 고정 'all'). */
+export function querySelectorAllParam(selector: QuerySelector, options?: Omit<QueryOptions, 'pick'>): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => registerParam('querySelectorAllParam', target, propertyKey, parameterIndex, { selector, options });
+}
+
+// ─── root별 편의 alias — query.ts의 queryShadow/queryLight/queryAllRoots/queryAllShadow/queryAllLight/queryAllAll과 1:1 대응 ───
+
+/** shadow DOM에서 요소 하나를 찾아 주입한다 (= @querySelectorParam(selector, {root:'shadow'})). */
+export function querySelectorShadowParam(selector: QuerySelector, options?: QueryBaseOptions): ParameterDecorator {
+  return querySelectorParam(selector, { ...(options ?? {}), root: 'shadow' });
+}
+/** light DOM에서 요소 하나를 찾아 주입한다. */
+export function querySelectorLightParam(selector: QuerySelector, options?: QueryBaseOptions): ParameterDecorator {
+  return querySelectorParam(selector, { ...(options ?? {}), root: 'light' });
+}
+/** shadow+light 모두에서 찾아 하나만 주입한다 (pick 기본 'first') — "All"은 탐색 범위가 전부라는 뜻. */
+export function querySelectorAllRootsParam(selector: QuerySelector, options?: QueryBaseOptions): ParameterDecorator {
+  return querySelectorParam(selector, { ...(options ?? {}), root: 'all' });
+}
+/** shadow DOM에서 매칭된 모든 요소를 배열로 주입한다. */
+export function querySelectorAllShadowParam(selector: QuerySelector, options?: Omit<QueryBaseOptions, 'pick'>): ParameterDecorator {
+  return querySelectorAllParam(selector, { ...(options ?? {}), root: 'shadow' });
+}
+/** light DOM에서 매칭된 모든 요소를 배열로 주입한다. */
+export function querySelectorAllLightParam(selector: QuerySelector, options?: Omit<QueryBaseOptions, 'pick'>): ParameterDecorator {
+  return querySelectorAllParam(selector, { ...(options ?? {}), root: 'light' });
+}
+/** shadow+light 모두에서 매칭된 모든 요소를 배열로 주입한다. */
+export function querySelectorAllAllParam(selector: QuerySelector, options?: Omit<QueryBaseOptions, 'pick'>): ParameterDecorator {
+  return querySelectorAllParam(selector, { ...(options ?? {}), root: 'all' });
+}
+// skipped: queryIn처럼 root+pick을 동적으로 조합하는 팩토리형 alias — 필요해지면 그때 추가.
+
+/**
+ * attribute 값을 주입한다 — 필드용 @attribute 데코레이터(applyAttribute.ts)와 같은 엔진 재사용.
+ * - attributeParam('data-x', options?) — 이 엘리먼트 자신의 attribute.
+ * - attributeParam(selector, 'data-x', options?) — selector(+options.root)로 찾은 다른 요소의 attribute.
+ * 필드용 @attribute(selector?, attrName, options?)와 동일한 2-form 시그니처.
+ */
+export function attributeParam(attributeName: string, options?: AttributeOptions): ParameterDecorator;
+export function attributeParam(selector: AttributeSelector, attributeName: string, options?: AttributeOptions): ParameterDecorator;
+export function attributeParam(selectorOrName: AttributeSelector | string, attrNameOrOptions?: string | AttributeOptions, maybeOptions?: AttributeOptions): ParameterDecorator {
+  const withSelector = typeof attrNameOrOptions === 'string';
+  const attributeName = withSelector ? attrNameOrOptions as string : selectorOrName as string;
+  const options = (withSelector ? maybeOptions : attrNameOrOptions as AttributeOptions | undefined) ?? {};
+  const resolved: AttributeOptions & { selector?: AttributeSelector } = withSelector ? { ...options, selector: selectorOrName as AttributeSelector } : options;
+  return (target, propertyKey, parameterIndex) => registerParam('attributeParam', target, propertyKey, parameterIndex, { attributeName, options: resolved });
+}
+
+const keyedStorageParam = (kind: SwcParamKind) => (key: string, options?: Omit<PersistOptions, 'storage'>): ParameterDecorator =>
+  (target, propertyKey, parameterIndex) => registerParam(kind, target, propertyKey, parameterIndex, { key, options });
+
+/** localStorage에 저장된 값을 주입한다 (persistState.ts의 persistRead 재사용). */
+export const localStorageParam = keyedStorageParam('localStorageParam');
+/** sessionStorage에 저장된 값을 주입한다. */
+export const sessionStorageParam = keyedStorageParam('sessionStorageParam');
+/** 쿠키에 저장된 값을 주입한다. */
+export const cookieParam = keyedStorageParam('cookieParam');
+/**
+ * IndexedDB에 저장된 값을 주입한다 — 단, 비동기 백엔드라 (동기 호출 계약상) resolve된 값이 아니라
+ * **Promise 자체**가 꽂힌다. 메서드 쪽에서 타입을 Promise로 받고 await 하면 된다.
+ * 예: async onReady(@indexedDbParam('wow') wow: Promise<string>) { const v = await wow; ... }
+ */
+export const indexedDbParam = keyedStorageParam('indexedDbParam');
+
+/** url/init 자리에 고정값 대신 (currentThis, helper) => ... 콜백을 줄 수 있다 — query.ts 함수 셀렉터·fetch.ts FetchUrlFactory와 동일한 패턴. */
+export type FetchParamUrlFactory = (currentThis: any, helper: HelperHostSet) => RequestInfo | URL;
+export type FetchParamInitFactory = (currentThis: any, helper: HelperHostSet) => RequestInit | undefined;
+
+/**
+ * 간단 버전 fetch — 네이티브 fetch(url, init) 그대로, 성공하면 Content-Type 보고 JSON/텍스트로 파싱한 뒤
+ * **그 Promise를 주입**한다 (indexedDbParam과 동일한 계약 — 비동기라 resolve된 값이 아니라 Promise 자체).
+ * abort/abortPrevious 같은 건 없다 — 그런 게 필요하면 @fetch/@fetchManual + @fetchPromise를 쓴다
+ * (disconnect 시 자동 abort까지 되는 더 안전한 버전). 이건 딱 "그냥 fetch 결과를 파라미터로 받고 싶다"는 경우용.
+ *
+ * url/init은 고정값뿐 아니라 (currentThis, helper) => ... 콜백도 받는다 — 인스턴스 필드를 참조해서
+ * URL이나 body를 동적으로 만들어야 할 때 쓴다.
+ * 예: async onReady(@fetchParam('/api/products/1') p: Promise<Product>) { const data = await p; }
+ * 예: async onSave(@fetchParam(
+ *       (self) => `/api/products/${self.productId}`,
+ *       (self) => ({ method: 'POST', body: JSON.stringify({ qty: self.qty }) })
+ *     ) p: Promise<any>) { const result = await p; }
+ */
+export function fetchParam(
+  input: RequestInfo | URL | FetchParamUrlFactory,
+  init?: RequestInit | FetchParamInitFactory
+): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => registerParam('fetchParam', target, propertyKey, parameterIndex, { input, init });
 }
 
 export const getParameterMetadata = (target: any, propertyKey: string | symbol): SaveParamConfig[] => {
@@ -148,6 +322,8 @@ export const getParameterMetadata = (target: any, propertyKey: string | symbol):
 /**
  * 위 파라미터 데코레이터 메타데이터가 하나라도 있으면 kind별 값을 index 순서에 맞게
  * 배열로 조립하고, 하나도 없으면 기존 위치 인자(legacyArgs)를 그대로 반환한다 — 완전 하위호환.
+ * 데코레이터가 안 붙은 인덱스는 legacyArgs의 같은 자리 값으로 채운다 — 그래야
+ * onId(nv, old, @querySelectorParam('#x') el) 처럼 기존 위치 인자와 섞어 써도 nv/old가 undefined로 날아가지 않는다.
  */
 export const buildSwcParameterArgs = (
   target: any,
@@ -157,8 +333,8 @@ export const buildSwcParameterArgs = (
 ): any[] => {
   const saves = getParameterMetadata(target, propertyKey);
   if (saves.length === 0) return legacyArgs;
-  const maxIndex = Math.max(...saves.map(s => s.index));
-  const args: any[] = new Array(maxIndex + 1);
+  const maxIndex = Math.max(Math.max(...saves.map(s => s.index)), legacyArgs.length - 1);
+  const args: any[] = legacyArgs.slice(0, maxIndex + 1);
   for (const s of saves) {
     const value = kindValues[s.kind];
     // 키를 받는 kind 는 kindValues 에 (key) => 값 resolver 가 들어 있다
@@ -167,46 +343,154 @@ export const buildSwcParameterArgs = (
   return args;
 };
 
-// ─── 라우트 파라미터 (@subscribeSwcAppRouteChange 핸들러) ───
+/** @fetchParam 전용 — 네이티브 fetch, 실패하면 상태코드를 담아 던지고, 성공하면 Content-Type 보고 json/text로 파싱. */
+const simpleFetchJsonOrText = async (win: Window, input: RequestInfo | URL, init?: RequestInit): Promise<any> => {
+  const fetchFn: typeof fetch = typeof (win as any)?.fetch === 'function' ? (win as any).fetch.bind(win) : fetch;
+  const res = await fetchFn(input, init);
+  if (!res.ok) throw new Error(`[SWC] @fetchParam failed: ${res.status} ${String(input)}`);
+  const text = await res.text();
+  if (!text) return undefined;
+  return (res.headers.get('Content-Type') ?? '').includes('json') ? JSON.parse(text) : text;
+};
+
+/**
+ * @querySelectorParam/@querySelectorAllParam/@attributeParam/@local·session·cookie·indexedDb·fetchParam 리졸버만 —
+ * hostSet 3종과 분리해서, 이미 자기만의 hostSet/helperHostSet 계산 방식을 가진 호출부
+ * (예: elementDefine._invokeLifecycleMethod)에서도 기존 계산은 그대로 둔 채 이 kind들만 얹을 수 있게 한다.
+ * indexedDB/fetch는 비동기라 (동기 호출 계약상) resolve된 값이 아니라 Promise 자체를 반환한다 —
+ * 둘 다 async 함수라 호출 즉시 Promise를 반환하므로 await 없이도 동기 리졸버 계약을 지킨다.
+ */
+export const buildDomStorageKindValues = (inst: any, win: Window): Partial<Record<SwcParamKind, any>> => ({
+  querySelectorParam: (cfg: { selector: QuerySelector; options?: QueryOptions }) =>
+    pickElements(resolveQueryElements(inst, cfg.selector, cfg.options ?? {}, win), cfg.options?.pick ?? 'first'),
+  querySelectorAllParam: (cfg: { selector: QuerySelector; options?: Omit<QueryOptions, 'pick'> }) =>
+    pickElements(resolveQueryElements(inst, cfg.selector, cfg.options ?? {}, win), 'all'),
+  attributeParam: (cfg: { attributeName: string; options?: AttributeOptions & { selector?: AttributeSelector } }) =>
+    getAttributeValue(inst, cfg.attributeName, cfg.options),
+  localStorageParam: (cfg: { key: string; options?: Omit<PersistOptions, 'storage'> }) =>
+    persistRead(inst, cfg.key, { ...(cfg.options as any), storage: 'local' }),
+  sessionStorageParam: (cfg: { key: string; options?: Omit<PersistOptions, 'storage'> }) =>
+    persistRead(inst, cfg.key, { ...(cfg.options as any), storage: 'session' }),
+  cookieParam: (cfg: { key: string; options?: Omit<PersistOptions, 'storage'> }) =>
+    persistRead(inst, cfg.key, { ...(cfg.options as any), storage: 'cookie' }),
+  indexedDbParam: (cfg: { key: string; options?: Omit<PersistOptions, 'storage'> }): Promise<any> =>
+    persistReadAsync(inst, cfg.key, { ...(cfg.options as any), storage: 'indexeddb' }),
+  fetchParam: (cfg: { input: RequestInfo | URL | FetchParamUrlFactory; init?: RequestInit | FetchParamInitFactory }): Promise<any> => {
+    const helper = SwcUtils.getHelperAndHostSet(inst, win);
+    const resolvedInput = typeof cfg.input === 'function' ? (cfg.input as FetchParamUrlFactory)(inst, helper) : cfg.input;
+    const resolvedInit = typeof cfg.init === 'function' ? (cfg.init as FetchParamInitFactory)(inst, helper) : cfg.init;
+    return simpleFetchJsonOrText(win, resolvedInput, resolvedInit);
+  },
+});
+
+/**
+ * 트리거 데코레이터(onConnectedAfter/addEventListener/setInterval/setTimeout/옵저버 계열/...)가
+ * 공통으로 필요로 하는 kindValues 베이스 — hostSet/helperSet/helperHostSet 3종 + buildDomStorageKindValues를
+ * 한 번에 만든다. 각 호출부는 자기만의 kind(eventObject, setTimeoutBeforeReturn 등)만 추가로 섞어 쓰면 된다.
+ */
+export const buildCommonKindValues = (inst: any, win: Window): Partial<Record<SwcParamKind, any>> => {
+  const hostSet = SwcUtils.getHostSet(inst);
+  const helperSet = SwcUtils.getHelperSet(win);
+  const helperHostSet = { ...helperSet, ...hostSet, $this: inst };
+  return {
+    hostSet, helperSet, helperHostSet,
+    swcAppRouter: hostSet.$appHost?.router,
+    swcAppSimpleApplication: hostSet.$appHost?.simpleApplication,
+    swcAppHost: hostSet.$appHost,
+    ...buildDomStorageKindValues(inst, win)
+  };
+};
+
+// ─── 라우트 파라미터 (@subscribeSwcAppRouteChange 핸들러 파라미터 · 필드) ───
 // 규칙: 접두어 없음 = First, First/Last = 같은 키가 여러 번일 때 첫/마지막 값, 복수형 = 모든 값 배열.
+// 같은 데코레이터를 파라미터에도, 필드에도 붙인다. 파라미터면 핸들러 인자로, 필드면 SwcApp 이 라우트가 바뀔 때마다
+// (그리고 요소가 붙을 때 마지막 라우트로) 그 필드에 값을 넣는다 — SwcAppMixin._applyRouteFields.
+
+/** 파라미터·필드 겸용 데코레이터. 세 번째 인자가 숫자면 파라미터, 아니면(필드) undefined */
+export type SwcRouteParamDecorator = (target: Object, propertyKey: string | symbol | undefined, parameterIndex?: number) => void;
+/** path 변수 필드용 — 어떤 패턴에서 값을 뽑을지. @subscribeSwcAppRouteChange 의 path 와 같은 형태 */
+export type SwcRouteFieldOptions = { path?: string | string[] | ((currentThis: any) => string | string[]) };
+/** 맨 데코레이터로도(@swcAppRoutePathVariableObject), 옵션을 받는 팩토리로도(@swcAppRoutePathVariableObject({ path })) 쓴다 */
+export type SwcRouteParamDecoratorOrFactory = SwcRouteParamDecorator & ((options?: SwcRouteFieldOptions) => SwcRouteParamDecorator);
+
+export type SwcRouteFieldConfig = { propertyKey: string | symbol; kind: SwcRouteParamKind; key?: string; path?: SwcRouteFieldOptions['path'] };
+const SWC_ROUTE_FIELD_METADATA_KEY = Symbol.for('simple-web-component:route-field');
+
+const isPathKind = (kind: SwcRouteParamKind) => kind.includes('PathVariable');
+
+const registerRouteField = (kind: SwcRouteParamKind, target: Object, propertyKey: string | symbol, key?: string, options?: SwcRouteFieldOptions) => {
+  if (isPathKind(kind) && !options?.path) {
+    // 필드에는 @subscribeSwcAppRouteChange 처럼 매칭할 패턴이 없다 → 늘 비게 된다. 실수일 가능성이 커서 알린다.
+    console.warn(`[SWC] @${kind} on field "${String(propertyKey)}" needs { path } (e.g. { path: '/user/{id}' }) — it will stay empty without it.`);
+  }
+  const constructor = target.constructor;
+  const list = (ReflectUtils.getOwnMetadata(SWC_ROUTE_FIELD_METADATA_KEY, constructor) ?? []) as SwcRouteFieldConfig[];
+  list.push({ propertyKey, kind, ...(key !== undefined ? { key } : {}), ...(options?.path ? { path: options.path } : {}) });
+  ReflectUtils.defineMetadata(SWC_ROUTE_FIELD_METADATA_KEY, list, constructor);
+};
+
+/** 상속 체인 전체의 라우트 필드 설정 (부모 → 자식). 같은 필드를 자식이 다시 선언하면 자식 것이 뒤에 와서 이긴다 */
+export const getSwcRouteFieldMetadata = (target: any): SwcRouteFieldConfig[] => {
+  const constructor = target instanceof Function ? target : target?.constructor;
+  if (!constructor) return [];
+  return (ReflectUtils.findAllMetadata<SwcRouteFieldConfig[]>(SWC_ROUTE_FIELD_METADATA_KEY, constructor) || []).flat();
+};
+
+const applyRouteParam = (kind: SwcRouteParamKind, target: Object, propertyKey: string | symbol | undefined, parameterIndex: number | undefined, key?: string, options?: SwcRouteFieldOptions) => {
+  if (typeof parameterIndex === 'number') return registerParam(kind, target, propertyKey, parameterIndex, key);
+  if (propertyKey !== undefined) registerRouteField(kind, target, propertyKey, key, options);
+};
 
-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);
+/** 키를 받는 query 계열: @swcAppRouteQueryParam('tag') */
+const keyedQueryParam = (kind: SwcRouteParamKind) => (key: string): SwcRouteParamDecorator =>
+  (target, propertyKey, parameterIndex) => applyRouteParam(kind, target, propertyKey, parameterIndex, key);
+/** 키를 받는 path 변수 계열: @swcAppRoutePathVariable('id') · 필드면 @swcAppRoutePathVariable('id', { path: '/user/{id}' }) */
+const keyedPathParam = (kind: SwcRouteParamKind) => (key: string, options?: SwcRouteFieldOptions): SwcRouteParamDecorator =>
+  (target, propertyKey, parameterIndex) => applyRouteParam(kind, target, propertyKey, parameterIndex, key, options);
+/** 키 없는 query 계열 — 맨 데코레이터: @swcAppRouteQueryParamObject */
+const queryParam = (kind: SwcRouteParamKind): SwcRouteParamDecorator =>
+  (target, propertyKey, parameterIndex) => applyRouteParam(kind, target, propertyKey, parameterIndex);
+/** 키 없는 path 변수 계열 — 맨 데코레이터(파라미터) 또는 팩토리(필드: { path }) 둘 다 */
+const pathParam = (kind: SwcRouteParamKind): SwcRouteParamDecoratorOrFactory =>
+  function (this: unknown, ...args: any[]) {
+    // 데코레이터 호출은 (target, propertyKey, …) 로 인자가 2개 이상, 팩토리 호출은 (options?) 하나 이하
+    if (args.length >= 2) return applyRouteParam(kind, args[0], args[1], args[2]);
+    const options = args[0] as SwcRouteFieldOptions | undefined;
+    return ((target, propertyKey, parameterIndex) => applyRouteParam(kind, target, propertyKey, parameterIndex, undefined, options)) as SwcRouteParamDecorator;
+  } as SwcRouteParamDecoratorOrFactory;
 
 /** ?tag=a&tag=b → @swcAppRouteQueryParam('tag') = 'a' (없으면 null) */
-export const swcAppRouteQueryParam = keyedRouteParam('swcAppRouteQueryParam');
+export const swcAppRouteQueryParam = keyedQueryParam('swcAppRouteQueryParam');
 /** = swcAppRouteQueryParam */
-export const swcAppRouteFirstQueryParam = keyedRouteParam('swcAppRouteFirstQueryParam');
+export const swcAppRouteFirstQueryParam = keyedQueryParam('swcAppRouteFirstQueryParam');
 /** ?tag=a&tag=b → 'b' */
-export const swcAppRouteLastQueryParam = keyedRouteParam('swcAppRouteLastQueryParam');
+export const swcAppRouteLastQueryParam = keyedQueryParam('swcAppRouteLastQueryParam');
 /** ?tag=a&tag=b → ['a', 'b'] */
-export const swcAppRouteQueryParams = keyedRouteParam('swcAppRouteQueryParams');
+export const swcAppRouteQueryParams = keyedQueryParam('swcAppRouteQueryParams');
 /** ?tag=a&tag=b → { tag: 'a' } */
-export const swcAppRouteQueryParamObject = routeParam('swcAppRouteQueryParamObject');
+export const swcAppRouteQueryParamObject = queryParam('swcAppRouteQueryParamObject');
 /** = swcAppRouteQueryParamObject */
-export const swcAppRouteFirstQueryParamObject = routeParam('swcAppRouteFirstQueryParamObject');
+export const swcAppRouteFirstQueryParamObject = queryParam('swcAppRouteFirstQueryParamObject');
 /** ?tag=a&tag=b → { tag: 'b' } */
-export const swcAppRouteLastQueryParamObject = routeParam('swcAppRouteLastQueryParamObject');
+export const swcAppRouteLastQueryParamObject = queryParam('swcAppRouteLastQueryParamObject');
 /** ?tag=a&tag=b → { tag: ['a', 'b'] } */
-export const swcAppRouteQueryParamsObject = routeParam('swcAppRouteQueryParamsObject');
+export const swcAppRouteQueryParamsObject = queryParam('swcAppRouteQueryParamsObject');
 /** URLSearchParams 그대로 */
-export const swcAppRouteURLSearchParams = routeParam('swcAppRouteURLSearchParams');
+export const swcAppRouteURLSearchParams = queryParam('swcAppRouteURLSearchParams');
 
-/** '/a/{id}/b/{id}' ← '/a/1/b/2' → @swcAppRoutePathVariable('id') = '1' */
-export const swcAppRoutePathVariable = keyedRouteParam('swcAppRoutePathVariable');
+/** '/a/{id}/b/{id}' ← '/a/1/b/2' → @swcAppRoutePathVariable('id') = '1' · 필드: @swcAppRoutePathVariable('id', { path: '/a/{id}/b/{id}' }) */
+export const swcAppRoutePathVariable = keyedPathParam('swcAppRoutePathVariable');
 /** = swcAppRoutePathVariable */
-export const swcAppRouteFirstPathVariable = keyedRouteParam('swcAppRouteFirstPathVariable');
+export const swcAppRouteFirstPathVariable = keyedPathParam('swcAppRouteFirstPathVariable');
 /** → '2' */
-export const swcAppRouteLastPathVariable = keyedRouteParam('swcAppRouteLastPathVariable');
+export const swcAppRouteLastPathVariable = keyedPathParam('swcAppRouteLastPathVariable');
 /** → ['1', '2'] */
-export const swcAppRoutePathVariables = keyedRouteParam('swcAppRoutePathVariables');
-/** → { id: '1' } */
-export const swcAppRoutePathVariableObject = routeParam('swcAppRoutePathVariableObject');
+export const swcAppRoutePathVariables = keyedPathParam('swcAppRoutePathVariables');
+/** → { id: '1' } · 필드: @swcAppRoutePathVariableObject({ path: '/a/{id}/b/{id}' }) */
+export const swcAppRoutePathVariableObject = pathParam('swcAppRoutePathVariableObject');
 /** = swcAppRoutePathVariableObject */
-export const swcAppRouteFirstPathVariableObject = routeParam('swcAppRouteFirstPathVariableObject');
+export const swcAppRouteFirstPathVariableObject = pathParam('swcAppRouteFirstPathVariableObject');
 /** → { id: '2' } */
-export const swcAppRouteLastPathVariableObject = routeParam('swcAppRouteLastPathVariableObject');
+export const swcAppRouteLastPathVariableObject = pathParam('swcAppRouteLastPathVariableObject');
 /** → { id: ['1', '2'] } */
-export const swcAppRoutePathVariablesObject = routeParam('swcAppRoutePathVariablesObject');
+export const swcAppRoutePathVariablesObject = pathParam('swcAppRoutePathVariablesObject');