@cp949/iframecall 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+이 프로젝트의 모든 주요 변경 사항은 이 파일에 기록됩니다.
+
+형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)을 따르며, 버전 관리는 [Semantic Versioning](https://semver.org/spec/v2.0.0.html)을 준수합니다. 0.x 버전대에서는 호환성이 깨지는 변경도 minor 버전 증가로 처리합니다.
+
+## [0.2.1] - 2026-08-25
+
+### Added
+
+- host controller의 정식 command 실행 API로 `invoke(command, args, options?)`를 추가했습니다.
+
+### Deprecated
+
+- `controller.call()`은 호환성을 위해 유지하지만 다음 major release에서 제거할 예정입니다. `controller.invoke()`를 사용하세요.
+
+## [0.2.0] - 2026-04-28
+
+### Added
+
+- `$` 네임스페이스와 `$onCommandRun` wrap hook 도입 — 명령 실행 전후를 감싸는 미들웨어 형태의 훅을 등록할 수 있습니다.
+
+### Changed
+
+- 라이프사이클/도메인 채널의 책임을 분리하고, 라이프사이클 ready 알림 API를 `sendLifecycleReady`로 정리했습니다. **(Breaking)**
+
+### BREAKING CHANGES
+
+- 라이프사이클 ready 전송 API의 식별자가 `sendLifecycleReady`로 리네임되었습니다. 이전 명칭을 직접 호출하던 코드는 새 이름으로 갱신해야 합니다.
+
+## [0.1.0] - 2026-04-27
+
+### Added
+
+- `@cp949/iframecall` 최초 공개 — 타입 안전한 host ↔ iframe postMessage 호출 라이브러리.
+- React 18/19 호환 진입점(`./host`, `./iframe`) 제공.

package/README.md

@@ -20,16 +20,16 @@ yarn add @cp949/iframecall
 
 `react`, `@types/react`는 peer dependency이다. 프로젝트에 이미 설치되어 있어야 한다.
 
-| peer | 지원 버전 |
-|------|-----------|
-| `react` | `^18.0.0 \|\| ^19.0.0` |
+| peer           | 지원 버전              |
+| -------------- | ---------------------- |
+| `react`        | `^18.0.0 \|\| ^19.0.0` |
 | `@types/react` | `^18.0.0 \|\| ^19.0.0` |
 
 ## 진입점
 
-| import | 용도 |
-|--------|------|
-| `@cp949/iframecall/host` | 부모 페이지(host)에서 iframe을 제어할 때 |
+| import                     | 용도                                              |
+| -------------------------- | ------------------------------------------------- |
+| `@cp949/iframecall/host`   | 부모 페이지(host)에서 iframe을 제어할 때          |
 | `@cp949/iframecall/iframe` | 임베드된 페이지(iframe)에서 host의 호출을 받을 때 |
 
 호스트와 iframe은 서로 다른 origin에서 실행되며, 각 진입점은 그쪽에서만 필요한 API와 타입만 노출한다.
@@ -41,17 +41,19 @@ yarn add @cp949/iframecall
 host와 iframe 양쪽에서 동일하게 사용할 커맨드와 알림 타입을 정의한다.
 
 ```ts
-type DemoCommands = {
+type AppCommands = {
   greet(name: string): Promise<string>;
   add(a: number, b: number): Promise<number>;
   delay(ms: number): Promise<void>;
 };
 
-type DemoEvents = {
-  "status-changed": string;
+type AppNotifications = {
+  "status-changed": "idle" | "processing";
 };
 ```
 
+> 라이프사이클(`ready` / `terminated`)과 도메인 알림은 채널을 분리한다. 도메인 페이로드에 `"ready"`를 넣지 않는다 — `ready`는 transport가 살아 있다는 라이프사이클 신호 전용이다.
+
 > 별도 공유 패키지 없이 양쪽에 같은 타입을 두는 패턴을 권장한다. 모노레포라면 공통 패키지로 빼도 된다.
 
 ### 2. host 측 (부모 페이지)
@@ -66,8 +68,8 @@ const IFRAME_ORIGIN = "https://iframe.example.com";
 
 export function HostPage() {
   const { iframeRef, controller, status } = useIframeCallController<
-    DemoCommands,
-    DemoEvents
+    AppCommands,
+    AppNotifications
   >({
     targetOrigin: IFRAME_ORIGIN,
     allowedOrigins: [IFRAME_ORIGIN],
@@ -82,7 +84,7 @@ export function HostPage() {
 
   const handleGreet = async () => {
     if (!controller) return;
-    const result = await controller.call("greet", ["World"]);
+    const result = await controller.invoke("greet", ["World"]);
     console.log(result); // "Hello, World!"
   };
 
@@ -92,11 +94,7 @@ export function HostPage() {
       <button type="button" onClick={handleGreet} disabled={status !== "ready"}>
         Greet
       </button>
-      <iframe
-        ref={iframeRef}
-        src={IFRAME_ORIGIN}
-        title="iframe demo"
-      />
+      <iframe ref={iframeRef} src={IFRAME_ORIGIN} title="iframe demo" />
     </div>
   );
 }
@@ -104,7 +102,19 @@ export function HostPage() {
 
 ### 3. iframe 측 (임베드된 페이지)
 
-커맨드 구현은 클래스로 정의한다. 생성자는 `iframeHelper`를 인자로 받으며, 메서드 이름이 곧 커맨드 이름이 된다.
+커맨드 구현은 클래스로 정의한다. 생성자는 `iframeHelper`를 인자로 받으며, prototype에 둔 메서드 이름이 곧 커맨드 이름이 된다.
+
+prefix 컨벤션:
+
+| prefix | 의미                                                                                                 |
+| ------ | ---------------------------------------------------------------------------------------------------- |
+| (없음) | host로 dispatch되는 remote command                                                                   |
+| `_`    | 사용자 local-only 메서드. dispatch 대상에서 제외된다. (예: `_sendLifecycleReady`, `_onStatusChange`) |
+| `$`    | 라이브러리 점유 namespace. dispatch에서 제외되며, 라이브러리가 정의한 hook 이름만 의미가 있다.       |
+
+현재 라이브러리가 인식하는 hook은 한 개:
+
+- `$onCommandRun(cmd, args, invoke)` — 매 command dispatch를 wrap한다. `await invoke()`를 try/finally로 감싸 상태 토글·로깅·refcount 등을 한 곳에서 처리한다.
 
 ```tsx
 "use client";
@@ -117,14 +127,53 @@ import { useEffect } from "react";
 
 const HOST_ORIGIN = "https://host.example.com";
 
-class DemoCommandsImpl {
-  constructor(private iframeHelper: IframeHelper<DemoEvents>) {}
+type RunningStatus = "idle" | "processing";
+
+// 클래스 자체가 곧 command 타입이다. 별도 interface를 두지 않는다.
+// `_` prefix는 사용자 local-only(dispatch 제외), `$` prefix는 라이브러리 namespace.
+class AppCommands {
+  private status: RunningStatus = "idle";
+  private inflight = 0;
+  private listeners = new Set<(s: RunningStatus) => void>();
+
+  constructor(private iframeHelper: IframeHelper<AppNotifications>) {}
+
+  _sendLifecycleReady(): void {
+    this.iframeHelper.sendLifecycleReady();
+  }
+
+  _onStatusChange(fn: (s: RunningStatus) => void): () => void {
+    this.listeners.add(fn);
+    return () => {
+      this.listeners.delete(fn);
+    };
+  }
+
+  // 모든 command를 wrap. 동시 dispatch에서 안쪽 호출이 끝나기 전에 idle로 떨어지지 않도록 refcount.
+  async $onCommandRun(
+    _cmd: string,
+    _args: readonly unknown[],
+    invoke: () => Promise<unknown>,
+  ): Promise<unknown> {
+    this.inflight += 1;
+    if (this.inflight === 1) this._setStatus("processing");
+    try {
+      return await invoke();
+    } finally {
+      this.inflight -= 1;
+      if (this.inflight === 0) this._setStatus("idle");
+    }
+  }
+
+  private _setStatus(next: RunningStatus): void {
+    if (this.status === next) return;
+    this.status = next;
+    this.iframeHelper.sendNotificationToHost("status-changed", next);
+    for (const fn of this.listeners) fn(next);
+  }
 
   async greet(name: string): Promise<string> {
-    this.iframeHelper.sendNotificationToHost("status-changed", "processing");
-    const result = `Hello, ${name}!`;
-    this.iframeHelper.sendNotificationToHost("status-changed", "idle");
-    return result;
+    return `Hello, ${name}!`;
   }
 
   async add(a: number, b: number): Promise<number> {
@@ -132,25 +181,27 @@ class DemoCommandsImpl {
   }
 
   async delay(ms: number): Promise<void> {
-    await new Promise((resolve) => setTimeout(resolve, ms));
+    await new Promise<void>((resolve) => setTimeout(resolve, ms));
   }
 }
 
 export function IframePage() {
-  const { iframeHelper, isActive } = useIframeCallRunner<
-    DemoCommands,
-    DemoEvents
+  const { iframeHelper, commands, isActive } = useIframeCallRunner<
+    AppCommands,
+    AppNotifications
   >({
     targetOrigin: HOST_ORIGIN,
     allowedOrigins: [HOST_ORIGIN],
-    Commands: DemoCommandsImpl,
+    Commands: AppCommands,
   });
 
   useEffect(() => {
-    if (!iframeHelper) return;
-    iframeHelper.sendNotificationToHost("status-changed", "ready");
-    iframeHelper.sendReadyToHost();
-  }, [iframeHelper]);
+    if (!iframeHelper || !commands) return;
+    commands._sendLifecycleReady();
+    return commands._onStatusChange((s) => {
+      console.log("local status:", s);
+    });
+  }, [iframeHelper, commands]);
 
   return <p>{isActive ? "active" : "initializing"}</p>;
 }
@@ -163,36 +214,39 @@ host                                    iframe
   │                                       │
   │  <iframe src="...">                   │
   │──────────────────────────────────────▶│ mount
-  │                                       │ sendReadyToHost()
-  │  ◀── ready ───────────────────────────│
+  │                                       │ commands._sendLifecycleReady() → sendLifecycleReady()
+  │  ◀── ready ───────────────────────────│  (lifecycle 채널)
   │  controller.status = "ready"          │
   │                                       │
-  │  controller.call("greet", ["World"])  │
-  │  ── request ─────────────────────────▶│ DemoCommandsImpl.greet("World")
+  │  controller.invoke("greet", ["World"])│
+  │  ── request ─────────────────────────▶│ $onCommandRun → AppCommands.greet("World")
+  │  ◀── notify status-changed:processing │  (도메인 채널, refcount 0→1)
   │  ◀── response: "Hello, World!" ───────│
-  │                                       │
-  │  ◀── notify "status-changed" ─────────│ sendNotificationToHost(...)
+  │  ◀── notify status-changed:idle ──────│  (도메인 채널, refcount 1→0)
 ```
 
-- iframe이 마운트되면 `sendReadyToHost()`로 준비 신호를 보낸다.
-- host의 `controller.call`은 ready 시점까지 대기한 뒤 전송된다 (기본 `ReadyPolicy: "wait"`).
+- iframe이 마운트되면 `commands._sendLifecycleReady()`가 `sendLifecycleReady()`를 통해 transport ready 신호를 보낸다.
+- host의 `controller.invoke`는 ready 시점까지 대기한 뒤 전송된다.
 - 응답은 Promise로 돌아오며, iframe 측 메서드가 throw하면 host 쪽 Promise는 reject된다.
 - iframe → host 단방향 알림은 `sendNotificationToHost`로 보내고, host 쪽에서 `controller.onNotificationFromIframe`으로 받는다.
+- **라이프사이클 채널과 도메인 채널은 책임이 다르다.** `ready`/`terminated`는 transport 신호 전용이고, 도메인 알림(`status-changed` 등)에는 `"ready"` 같은 lifecycle 의미를 담지 않는다.
+- prototype에 `$onCommandRun(cmd, args, invoke)`을 두면 모든 command dispatch가 그 함수로 wrap된다. status 토글·로깅·refcount 같은 횡단 관심사를 한 곳에서 처리할 수 있다.
 
 ## API 개요
 
 ### host 진입점
 
-| export | 종류 | 설명 |
-|--------|------|------|
-| `useIframeCallController` | hook | host용 React 훅. `iframeRef`, `controller`, `status`를 반환한다. |
-| `createIframeCallController` | factory | 훅 없이 컨트롤러를 직접 만들 때 사용 |
-| `createIframeWindowTransport` | factory | 커스텀 트랜스포트 구성용 |
-| `consoleDebugLogger` | util | 디버그 이벤트를 콘솔에 출력하는 로거 |
+| export                        | 종류    | 설명                                                             |
+| ----------------------------- | ------- | ---------------------------------------------------------------- |
+| `useIframeCallController`     | hook    | host용 React 훅. `iframeRef`, `controller`, `status`를 반환한다. |
+| `createIframeCallController`  | factory | 훅 없이 컨트롤러를 직접 만들 때 사용                             |
+| `createIframeWindowTransport` | factory | 커스텀 트랜스포트 구성용                                         |
+| `consoleDebugLogger`          | util    | 디버그 이벤트를 콘솔에 출력하는 로거                             |
 
 훅이 반환하는 `controller`의 주요 멤버:
 
-- `controller.call(command, args, options?)` — iframe의 커맨드 호출, 결과를 Promise로 반환
+- `controller.invoke(command, args, options?)` — iframe의 커맨드 호출, 결과를 Promise로 반환
+- `controller.call(command, args, options?)` — deprecated 호환 alias. `invoke`를 사용하세요.
 - `controller.onNotificationFromIframe(event, handler)` — iframe이 보내는 알림 구독, unsubscribe 함수 반환
 - `controller.ready` — iframe ready 신호 대기용 Promise
 - `controller.terminated` — 종료 사유를 노출하는 Promise (정상 dispose면 `null`)
@@ -201,18 +255,26 @@ host                                    iframe
 
 ### iframe 진입점
 
-| export | 종류 | 설명 |
-|--------|------|------|
-| `useIframeCallRunner` | hook | iframe용 React 훅. `iframeHelper`, `isActive`를 반환한다. |
-| `createIframeCallRunner` | factory | 훅 없이 러너를 직접 만들 때 사용 |
-| `createParentWindowTransport` | factory | 커스텀 트랜스포트 구성용 |
+| export                        | 종류    | 설명                                                                                                               |
+| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
+| `useIframeCallRunner`         | hook    | iframe용 React 훅. `commands`, `iframeHelper`, `isActive`를 반환한다. mount 전 `commands`/`iframeHelper`는 `null`. |
+| `createIframeCallRunner`      | factory | 훅 없이 러너를 직접 만들 때 사용                                                                                   |
+| `createParentWindowTransport` | factory | 커스텀 트랜스포트 구성용                                                                                           |
 
 `iframeHelper`의 주요 멤버:
 
-- `iframeHelper.sendNotificationToHost(event, payload)` — host로 알림 전송 (lifecycle 예약 이름 `ready`/`terminated`는 제외)
-- `iframeHelper.sendReadyToHost()` — host에 ready 신호 전송
+- `iframeHelper.sendNotificationToHost(event, payload)` — host로 도메인 알림 전송 (lifecycle 예약 이름 `ready`/`terminated`는 타입에서 제외)
+- `iframeHelper.sendLifecycleReady()` — host에 transport lifecycle ready 신호 전송. 도메인 알림과는 채널이 다르다.
 - `iframeHelper.debug.subscribe(handler)` — 디버그 스트림 구독
 
+**Commands class prefix 컨벤션:**
+
+- prefix 없는 prototype 메서드 → host에서 호출 가능한 remote command
+- `_` prefix → 사용자 local-only (dispatch 제외)
+- `$` prefix → 라이브러리 namespace (dispatch 제외, 인식되는 hook은 `$onCommandRun`)
+
+`onStatusChange`처럼 prefix가 없으면서 host에서 호출하면 안 되는 메서드는 반드시 `_` prefix를 붙여야 한다. 그렇지 않으면 host가 `controller.invoke("onStatusChange", [...])`로 직접 호출할 수 있다.
+
 > 알림은 iframe → host 단방향이다. host → iframe 알림은 라이브러리 외부에서 `postMessage`로 직접 처리하거나, host에서 커맨드를 호출해 처리한다.
 
 ### 공통 타입
@@ -223,9 +285,9 @@ host                                    iframe
 
 `targetOrigin`과 `allowedOrigins`는 반드시 명시적으로 지정한다. 와일드카드(`*`)는 사용하지 않는다.
 
-| 옵션 | 의미 |
-|------|------|
-| `targetOrigin` | `postMessage` 전송 시 사용할 대상 origin |
+| 옵션             | 의미                                      |
+| ---------------- | ----------------------------------------- |
+| `targetOrigin`   | `postMessage` 전송 시 사용할 대상 origin  |
 | `allowedOrigins` | 수신 시 허용할 origin 화이트리스트 (배열) |
 
 수신 메시지의 `event.origin`이 화이트리스트에 없으면 무시된다.

package/dist/{chunk-UYZXYOI6.js → chunk-RSUK22E2.js}

@@ -111,10 +111,12 @@ function isRecord(value) {
 
 // src/core/transport.ts
 function createIframeWindowTransport(iframe) {
+  var _a;
   return {
-    expectedSource: iframe.contentWindow ?? void 0,
+    expectedSource: (_a = iframe.contentWindow) != null ? _a : void 0,
     post(message, targetOrigin, transfer) {
-      iframe.contentWindow?.postMessage(
+      var _a2;
+      (_a2 = iframe.contentWindow) == null ? void 0 : _a2.postMessage(
         message,
         targetOrigin,
         transfer

package/dist/host.d.ts

@@ -1,5 +1,5 @@
-import { H as HostDebugEvent, C as CommandMap, I as IframeCallControllerOptions, a as IframeCallController, S as SerializedIframeCallError } from './messages-Cg4n93bf.js';
-export { b as CommandArgs, c as CommandHandler, d as CommandResult, e as CommandRunner, f as IframeCallCallOptions, g as IframeCallLogger, h as IframeCallNotify, i as IframeCallRequest, j as IframeCallResponse, k as IframeCallTransferable, l as IframeCallTransport, m as IframeCallTransportEvent, N as NotifyHandler, P as ParsedIframeCallMessage, R as ReadyPolicy, n as ReservedNotificationName, o as createIframeCallError, p as createIframeCallErrorResponse, q as createIframeCallNotify, r as createIframeCallRequest, s as createIframeCallSuccessResponse, t as createIframeWindowTransport, u as isSerializedIframeCallError, v as parseIframeCallMessage, w as serializeIframeCallError } from './messages-Cg4n93bf.js';
+import { H as HostDebugEvent, C as CommandMap, I as IframeCallControllerOptions, a as IframeCallController, S as SerializedIframeCallError } from './messages-uOmcU6eT.js';
+export { b as CommandArgs, c as CommandHandler, d as CommandResult, e as CommandRunner, f as IframeCallCallOptions, g as IframeCallLogger, h as IframeCallNotify, i as IframeCallRequest, j as IframeCallResponse, k as IframeCallTransferable, l as IframeCallTransport, m as IframeCallTransportEvent, N as NotifyHandler, P as ParsedIframeCallMessage, R as ReadyPolicy, n as ReservedNotificationName, o as createIframeCallError, p as createIframeCallErrorResponse, q as createIframeCallNotify, r as createIframeCallRequest, s as createIframeCallSuccessResponse, t as createIframeWindowTransport, u as isSerializedIframeCallError, v as parseIframeCallMessage, w as serializeIframeCallError } from './messages-uOmcU6eT.js';
 
 /** consoleDebugLogger 옵션. prefix를 명시하지 않으면 [iframecall:host]가 기본값이다. */
 type ConsoleDebugLoggerOptions = {

package/dist/host.js

@@ -8,11 +8,12 @@ import {
   isSerializedIframeCallError,
   parseIframeCallMessage,
   serializeIframeCallError
-} from "./chunk-UYZXYOI6.js";
+} from "./chunk-RSUK22E2.js";
 
 // src/host/consoleDebugLogger.ts
 function consoleDebugLogger(options = {}) {
-  const prefix = options.prefix ?? "[iframecall:host]";
+  var _a;
+  const prefix = (_a = options.prefix) != null ? _a : "[iframecall:host]";
   const head = prefix.length > 0 ? `${prefix} ` : "";
   return (event) => {
     switch (event.type) {
@@ -95,7 +96,7 @@ function createControllerLifecycle(options) {
       return;
     }
     cleanupDone = true;
-    onCleanup?.();
+    onCleanup == null ? void 0 : onCleanup();
   }
   return {
     ready,
@@ -117,7 +118,8 @@ function createNotifyHandlerRegistry() {
   const handlers = /* @__PURE__ */ new Map();
   return {
     register(event, handler) {
-      const set = handlers.get(event) ?? /* @__PURE__ */ new Set();
+      var _a;
+      const set = (_a = handlers.get(event)) != null ? _a : /* @__PURE__ */ new Set();
       set.add(handler);
       handlers.set(event, set);
       return () => {
@@ -203,7 +205,8 @@ function createPendingCallRegistry(transport, targetOrigin) {
       pending.clear();
     },
     getCommand(id) {
-      return pending.get(id)?.command;
+      var _a;
+      return (_a = pending.get(id)) == null ? void 0 : _a.command;
     }
   };
 }
@@ -244,24 +247,26 @@ function createReadyQueue() {
 
 // src/host/controller.ts
 function createIframeCallController(options) {
+  var _a, _b, _c, _d, _e, _f, _g;
   const targetOrigin = requireTargetOrigin(options.targetOrigin);
-  const allowedOrigins = new Set(options.allowedOrigins ?? [targetOrigin]);
-  const transport = options.transport ?? createIframeWindowTransport(options.iframe);
-  const generateId = options.generateId ?? crypto.randomUUID.bind(crypto);
-  const defaultTimeoutMs = options.defaultTimeoutMs ?? 3e4;
-  const readyTimeoutMs = options.readyTimeoutMs ?? defaultTimeoutMs;
-  const readyPolicy = options.readyPolicy ?? "queue";
-  const readyQueueLimit = options.readyQueueLimit ?? Number.POSITIVE_INFINITY;
+  const allowedOrigins = new Set((_a = options.allowedOrigins) != null ? _a : [targetOrigin]);
+  const transport = (_b = options.transport) != null ? _b : createIframeWindowTransport(options.iframe);
+  const generateId = (_c = options.generateId) != null ? _c : createDefaultRequestId;
+  const defaultTimeoutMs = (_d = options.defaultTimeoutMs) != null ? _d : 3e4;
+  const readyTimeoutMs = (_e = options.readyTimeoutMs) != null ? _e : defaultTimeoutMs;
+  const readyPolicy = (_f = options.readyPolicy) != null ? _f : "queue";
+  const readyQueueLimit = (_g = options.readyQueueLimit) != null ? _g : Number.POSITIVE_INFINITY;
   const pending = createPendingCallRegistry(transport, targetOrigin);
   const queue = createReadyQueue();
   const notifyRegistry = createNotifyHandlerRegistry();
   const debugSubscribers = /* @__PURE__ */ new Set();
   function emitDebug(event) {
+    var _a2;
     for (const handler of debugSubscribers) {
       try {
         handler(event);
       } catch (error) {
-        options.logger?.warn("iframecall debug subscriber threw.", error);
+        (_a2 = options.logger) == null ? void 0 : _a2.warn("iframecall debug subscriber threw.", error);
       }
     }
   }
@@ -289,68 +294,67 @@ function createIframeCallController(options) {
     unsubscribeTransport();
     notifyRegistry.clear();
   });
-  const controller = {
-    ready: lifecycle.ready,
-    terminated: lifecycle.terminated,
-    call(cmd, args, callOptions) {
-      const terminatedError = lifecycle.getTerminatedError();
-      if (terminatedError !== null) {
-        return Promise.reject(terminatedError);
-      }
-      if (!lifecycle.isReady() && readyPolicy === "reject") {
-        return Promise.reject(
-          createIframeCallError("not_ready", "Iframe is not ready.", {
-            command: cmd
+  const invoke = (cmd, args, callOptions) => {
+    var _a2;
+    const terminatedError = lifecycle.getTerminatedError();
+    if (terminatedError !== null) {
+      return Promise.reject(terminatedError);
+    }
+    if (!lifecycle.isReady() && readyPolicy === "reject") {
+      return Promise.reject(
+        createIframeCallError("not_ready", "Iframe is not ready.", {
+          command: cmd
+        })
+      );
+    }
+    const id = generateId();
+    const timeoutMs = (_a2 = callOptions == null ? void 0 : callOptions.timeoutMs) != null ? _a2 : defaultTimeoutMs;
+    return new Promise((resolve, reject) => {
+      const timeoutId = timeoutMs === 0 || timeoutMs === Number.POSITIVE_INFINITY ? null : setTimeout(() => {
+        pending.delete(id);
+        queue.delete(id);
+        reject(
+          createIframeCallError("timeout", "Command timed out.", {
+            command: cmd,
+            details: { timeoutMs }
           })
         );
-      }
-      const id = generateId();
-      const timeoutMs = callOptions?.timeoutMs ?? defaultTimeoutMs;
-      return new Promise((resolve, reject) => {
-        const timeoutId = timeoutMs === 0 || timeoutMs === Number.POSITIVE_INFINITY ? null : setTimeout(() => {
-          pending.delete(id);
-          queue.delete(id);
+      }, timeoutMs);
+      const call = {
+        command: cmd,
+        timeoutId,
+        resolve,
+        reject
+      };
+      if (!lifecycle.isReady()) {
+        if (queue.size() >= readyQueueLimit) {
+          if (timeoutId !== null) clearTimeout(timeoutId);
           reject(
-            createIframeCallError("timeout", "Command timed out.", {
+            createIframeCallError("queue_overflow", "Ready queue overflow.", {
               command: cmd,
-              details: { timeoutMs }
+              details: { readyQueueLimit }
             })
           );
-        }, timeoutMs);
-        const call = {
-          command: cmd,
-          timeoutId,
-          resolve,
-          reject
-        };
-        if (!lifecycle.isReady()) {
-          if (queue.size() >= readyQueueLimit) {
-            if (timeoutId !== null) {
-              clearTimeout(timeoutId);
-            }
-            reject(
-              createIframeCallError(
-                "queue_overflow",
-                "Ready queue overflow.",
-                {
-                  command: cmd,
-                  details: { readyQueueLimit }
-                }
-              )
-            );
-            return;
-          }
-          queue.add(id, {
-            ...call,
-            args,
-            transfer: callOptions?.transfer
-          });
           return;
         }
-        emitDebug({ type: "commandSentToIframe", command: cmd, args });
-        pending.add(id, call);
-        pending.post(id, cmd, args, callOptions?.transfer);
-      });
+        queue.add(id, {
+          ...call,
+          args,
+          transfer: callOptions == null ? void 0 : callOptions.transfer
+        });
+        return;
+      }
+      emitDebug({ type: "commandSentToIframe", command: cmd, args });
+      pending.add(id, call);
+      pending.post(id, cmd, args, callOptions == null ? void 0 : callOptions.transfer);
+    });
+  };
+  const controller = {
+    ready: lifecycle.ready,
+    terminated: lifecycle.terminated,
+    invoke,
+    call(cmd, args, callOptions) {
+      return invoke(cmd, args, callOptions);
     },
     onNotificationFromIframe(event, handler) {
       return notifyRegistry.register(
@@ -367,6 +371,7 @@ function createIframeCallController(options) {
       }
     },
     async dispose(reason = "host_requested") {
+      var _a2;
       if (lifecycle.isTerminated()) {
         lifecycle.cleanup();
         return;
@@ -384,7 +389,7 @@ function createIframeCallController(options) {
           targetOrigin
         );
       } catch (error) {
-        options.logger?.warn("iframecall dispose message failed.", error);
+        (_a2 = options.logger) == null ? void 0 : _a2.warn("iframecall dispose message failed.", error);
       } finally {
         lifecycle.terminate(lifecycleError);
         lifecycle.cleanup();
@@ -393,6 +398,14 @@ function createIframeCallController(options) {
   };
   return controller;
 }
+function createDefaultRequestId() {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  let id = "";
+  for (const byte of bytes) {
+    id += byte.toString(16).padStart(2, "0");
+  }
+  return id;
+}
 function createTransportRouter(deps) {
   const {
     lifecycle,
@@ -411,7 +424,7 @@ function createTransportRouter(deps) {
       return;
     }
     const parsed = parseIframeCallMessage(event.data);
-    if (parsed?.type === "response") {
+    if ((parsed == null ? void 0 : parsed.type) === "response") {
       const responseMessage = parsed.message;
       const command = pending.getCommand(responseMessage.id);
       pending.settle(responseMessage.id, responseMessage);
@@ -432,7 +445,7 @@ function createTransportRouter(deps) {
       }
       return;
     }
-    if (parsed?.type !== "notify") return;
+    if ((parsed == null ? void 0 : parsed.type) !== "notify") return;
     const { event: notifyEvent, payload } = parsed.message;
     if (notifyEvent === "ready") {
       handleReadyNotify(payload, lifecycle, queue, pending, logger, emitDebug);
@@ -445,7 +458,7 @@ function createTransportRouter(deps) {
       emitDebug({
         type: "terminatedReceived",
         reason,
-        error: cause ?? null
+        error: cause != null ? cause : null
       });
       lifecycle.terminate(
         createIframeCallError("terminated", "Iframe terminated.", {
@@ -465,7 +478,7 @@ function createTransportRouter(deps) {
 }
 function handleReadyNotify(payload, lifecycle, queue, pending, logger, emitDebug) {
   if (lifecycle.isReady()) {
-    logger?.warn("iframecall duplicate ready ignored.", payload);
+    logger == null ? void 0 : logger.warn("iframecall duplicate ready ignored.", payload);
     return;
   }
   if (!isSupportedReadyPayload(payload)) {

package/dist/iframe.d.ts

@@ -1,5 +1,5 @@
-import { x as IframeDebugEvent, C as CommandMap, y as IframeCallRunnerOptions, z as IframeCallRunnerHandle, A as CommandsConstructor, B as IframeCallRunnerClassOptions, D as IframeHelper } from './messages-Cg4n93bf.js';
-export { b as CommandArgs, c as CommandHandler, d as CommandResult, e as CommandRunner, E as DomainNotificationKey, f as IframeCallCallOptions, g as IframeCallLogger, h as IframeCallNotify, i as IframeCallRequest, j as IframeCallResponse, k as IframeCallTransferable, l as IframeCallTransport, m as IframeCallTransportEvent, N as NotifyHandler, P as ParsedIframeCallMessage, R as ReadyPolicy, n as ReservedNotificationName, S as SerializedIframeCallError, o as createIframeCallError, p as createIframeCallErrorResponse, q as createIframeCallNotify, r as createIframeCallRequest, s as createIframeCallSuccessResponse, F as createParentWindowTransport, u as isSerializedIframeCallError, v as parseIframeCallMessage, w as serializeIframeCallError } from './messages-Cg4n93bf.js';
+import { x as IframeDebugEvent, C as CommandMap, y as IframeCallRunnerOptions, z as IframeCallRunnerHandle, A as CommandsConstructor, B as IframeCallRunnerClassOptions, D as IframeHelper } from './messages-uOmcU6eT.js';
+export { b as CommandArgs, c as CommandHandler, d as CommandResult, e as CommandRunner, E as DomainNotificationKey, f as IframeCallCallOptions, g as IframeCallLogger, h as IframeCallNotify, i as IframeCallRequest, j as IframeCallResponse, k as IframeCallTransferable, l as IframeCallTransport, m as IframeCallTransportEvent, N as NotifyHandler, P as ParsedIframeCallMessage, R as ReadyPolicy, n as ReservedNotificationName, S as SerializedIframeCallError, o as createIframeCallError, p as createIframeCallErrorResponse, q as createIframeCallNotify, r as createIframeCallRequest, s as createIframeCallSuccessResponse, F as createParentWindowTransport, u as isSerializedIframeCallError, v as parseIframeCallMessage, w as serializeIframeCallError } from './messages-uOmcU6eT.js';
 
 /** consoleDebugLogger 옵션. prefix를 명시하지 않으면 [iframecall:iframe]가 기본값이다. */
 type ConsoleDebugLoggerOptions = {
@@ -40,15 +40,15 @@ type UseIframeCallRunnerOptions<TCommands, TNotificationsToHost = Record<string,
 } & Pick<IframeCallRunnerClassOptions<TCommands, TNotificationsToHost>, "logger" | "onHostDispose" | "transport">;
 /**
  * useIframeCallRunner가 반환하는 handle.
- * mount 전에는 모든 값이 undefined / false이며, mount 후 runner가 생성되면 채워진다.
+ * mount 전에는 commands/iframeHelper가 null이며, mount 후 runner가 생성되면 채워진다.
+ * runner handle 전체는 더 이상 노출하지 않고 도메인 코드가 필요로 하는
+ * commands 인스턴스와 iframeHelper만 외부로 흘려보낸다.
  */
 type UseIframeCallRunnerResult<TCommands, TNotificationsToHost = Record<string, unknown>> = {
-    /** runner가 생성한 Commands 인스턴스. mount 전 undefined. */
-    readonly commands: TCommands | undefined;
-    /** Commands constructor에 주입된 iframeHelper. mount 전 undefined. */
-    readonly iframeHelper: IframeHelper<TNotificationsToHost> | undefined;
-    /** runner handle 전체. mount 전 undefined. */
-    readonly runner: IframeCallRunnerHandle<TCommands, TNotificationsToHost> | undefined;
+    /** runner가 생성한 Commands 인스턴스. mount 전 null. */
+    readonly commands: TCommands | null;
+    /** Commands constructor에 주입된 iframeHelper. mount 전 null. */
+    readonly iframeHelper: IframeHelper<TNotificationsToHost> | null;
     /** runner가 활성화되어 있으면 true. mount 전 false. */
     readonly isActive: boolean;
 };

package/dist/iframe.js

@@ -8,11 +8,12 @@ import {
   isSerializedIframeCallError,
   parseIframeCallMessage,
   serializeIframeCallError
-} from "./chunk-UYZXYOI6.js";
+} from "./chunk-RSUK22E2.js";
 
 // src/iframe/consoleDebugLogger.ts
 function consoleDebugLogger(options = {}) {
-  const prefix = options.prefix ?? "[iframecall:iframe]";
+  var _a;
+  const prefix = (_a = options.prefix) != null ? _a : "[iframecall:iframe]";
   const head = prefix.length > 0 ? `${prefix} ` : "";
   return (event) => {
     switch (event.type) {
@@ -38,18 +39,20 @@ function consoleDebugLogger(options = {}) {
 // src/iframe/runner.ts
 var RESERVED_COMMAND_NAMES = /* @__PURE__ */ new Set(["constructor", "host:dispose"]);
 function createIframeCallRunner(options) {
+  var _a, _b;
   const targetOrigin = requireTargetOrigin(options.targetOrigin);
-  const allowedOrigins = new Set(options.allowedOrigins ?? [targetOrigin]);
-  const transport = options.transport ?? createParentWindowTransport();
+  const allowedOrigins = new Set((_a = options.allowedOrigins) != null ? _a : [targetOrigin]);
+  const transport = (_b = options.transport) != null ? _b : createParentWindowTransport();
   let disposing = false;
   let disposed = false;
   const debugSubscribers = /* @__PURE__ */ new Set();
   function emitDebug(event) {
+    var _a2;
     for (const handler of debugSubscribers) {
       try {
         handler(event);
       } catch (error) {
-        options.logger?.warn("iframecall debug subscriber threw.", error);
+        (_a2 = options.logger) == null ? void 0 : _a2.warn("iframecall debug subscriber threw.", error);
       }
     }
   }
@@ -59,7 +62,7 @@ function createIframeCallRunner(options) {
       safePost(createIframeCallNotify(event, payload));
       emitDebug({ type: "notificationSentToHost", event, payload });
     },
-    sendReadyToHost() {
+    sendLifecycleReady() {
       if (disposing || disposed) return;
       safePost(createIframeCallNotify("ready", { protocolVersion: 1 }));
     },
@@ -73,7 +76,7 @@ function createIframeCallRunner(options) {
     }
   };
   const iframeHelper = helperInternal;
-  const { commands, dispatch } = resolveCommandSource(options, iframeHelper);
+  const { commands, dispatch, commandRunHook } = resolveCommandSource(options, iframeHelper);
   const unsubscribeTransport = transport.subscribe((event) => {
     if (disposing || disposed) return;
     if (!allowedOrigins.has(event.origin)) {
@@ -83,7 +86,7 @@ function createIframeCallRunner(options) {
       return;
     }
     const parsed = parseIframeCallMessage(event.data);
-    if (parsed?.type === "notify") {
+    if ((parsed == null ? void 0 : parsed.type) === "notify") {
       emitDebug({
         type: "notificationReceivedFromHost",
         event: parsed.message.event,
@@ -91,7 +94,7 @@ function createIframeCallRunner(options) {
       });
       return;
     }
-    if (parsed?.type !== "request") {
+    if ((parsed == null ? void 0 : parsed.type) !== "request") {
       return;
     }
     if (parsed.message.cmd === "host:dispose") {
@@ -105,19 +108,21 @@ function createIframeCallRunner(options) {
     );
   });
   function safePost(message, transfer) {
+    var _a2;
     try {
       transport.post(message, targetOrigin, transfer);
     } catch (error) {
-      options.logger?.warn("iframecall postMessage failed.", error);
+      (_a2 = options.logger) == null ? void 0 : _a2.warn("iframecall postMessage failed.", error);
     }
   }
   async function handleHostDispose(reason) {
+    var _a2, _b2;
     if (disposing || disposed) return;
     disposing = true;
     try {
-      await options.onHostDispose?.(reason);
+      await ((_a2 = options.onHostDispose) == null ? void 0 : _a2.call(options, reason));
     } catch (error) {
-      options.logger?.warn("iframecall host dispose handler failed.", error);
+      (_b2 = options.logger) == null ? void 0 : _b2.warn("iframecall host dispose handler failed.", error);
     } finally {
       safePost(createIframeCallNotify("terminated", { reason }));
       disposed = true;
@@ -139,7 +144,8 @@ function createIframeCallRunner(options) {
       return;
     }
     try {
-      const value = await handler(...args);
+      const invoke = () => Promise.resolve(handler(...args));
+      const value = commandRunHook ? await commandRunHook(cmd, args, invoke) : await invoke();
       if (disposing || disposed) return;
       safePost(createIframeCallSuccessResponse(id, value));
       emitDebug({ type: "commandResultSentToHost", command: cmd, value });
@@ -159,8 +165,8 @@ function createIframeCallRunner(options) {
     commands,
     iframeHelper,
     sendNotificationToHost: sendNotificationToHostUntyped,
-    sendReadyToHost() {
-      iframeHelper.sendReadyToHost();
+    sendLifecycleReady() {
+      iframeHelper.sendLifecycleReady();
     },
     terminated(reason, error) {
       if (disposing || disposed) return;
@@ -197,11 +203,13 @@ function resolveCommandSource(options, iframeHelper) {
   const Ctor = rawOptions.Commands;
   const instance = new Ctor(iframeHelper);
   const handlerCache = buildPrototypeCommandHandlers(instance);
+  const commandRunHook = resolveCommandRunHook(instance);
   return {
     commands: instance,
     dispatch(cmd) {
       return handlerCache.get(cmd);
-    }
+    },
+    commandRunHook
   };
 }
 function buildPrototypeCommandHandlers(instance) {
@@ -212,6 +220,7 @@ function buildPrototypeCommandHandlers(instance) {
       if (typeof key !== "string") continue;
       if (RESERVED_COMMAND_NAMES.has(key)) continue;
       if (key.startsWith("_")) continue;
+      if (key.startsWith("$")) continue;
       if (handlers.has(key)) continue;
       const descriptor = Object.getOwnPropertyDescriptor(proto, key);
       if (descriptor === void 0) continue;
@@ -225,6 +234,18 @@ function buildPrototypeCommandHandlers(instance) {
   }
   return handlers;
 }
+function resolveCommandRunHook(instance) {
+  let proto = Object.getPrototypeOf(instance);
+  while (proto !== null && proto !== Object.prototype) {
+    const descriptor = Object.getOwnPropertyDescriptor(proto, "$onCommandRun");
+    if (descriptor !== void 0 && typeof descriptor.value === "function") {
+      const hook = descriptor.value;
+      return hook.bind(instance);
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+  return void 0;
+}
 function requireTargetOrigin(targetOrigin) {
   if (targetOrigin.length === 0 || targetOrigin === "*" || targetOrigin === "null") {
     throw createIframeCallError(
@@ -244,6 +265,7 @@ function getDisposeReason(payload) {
 // src/iframe/useIframeCallRunner.tsx
 import { useEffect, useRef, useState } from "react";
 function useIframeCallRunner(options) {
+  var _a, _b;
   const optionsRef = useRef(options);
   optionsRef.current = options;
   const runnerRef = useRef(null);
@@ -277,9 +299,8 @@ function useIframeCallRunner(options) {
   }, []);
   const runner = runnerRef.current;
   return {
-    commands: runner?.commands,
-    iframeHelper: runner?.iframeHelper,
-    runner: runner ?? void 0,
+    commands: (_a = runner == null ? void 0 : runner.commands) != null ? _a : null,
+    iframeHelper: (_b = runner == null ? void 0 : runner.iframeHelper) != null ? _b : null,
     isActive
   };
 }

package/dist/{messages-Cg4n93bf.d.ts → messages-uOmcU6eT.d.ts}

@@ -107,7 +107,7 @@ type IframeCallControllerOptions<TCommands extends CommandMap<TCommands>> = {
     readonly readyPolicy?: ReadyPolicy;
     /** queue 정책일 때 대기열 최대 크기. 초과 호출은 queue_overflow 에러로 거부한다. */
     readonly readyQueueLimit?: number;
-    /** call() 호출별 timeout 기본값(ms). 0 또는 Infinity면 timeout을 적용하지 않는다. */
+    /** invoke() 호출별 timeout 기본값(ms). 0 또는 Infinity면 timeout을 적용하지 않는다. */
     readonly defaultTimeoutMs?: number;
     /** ready 신호 대기 timeout(ms). 미지정이면 defaultTimeoutMs를 따른다. */
     readonly readyTimeoutMs?: number;
@@ -141,7 +141,7 @@ type IframeHelper<TNotificationsToHost = Record<string, unknown>> = {
     /** 도메인 notification을 host로 전송한다. lifecycle 예약 이름은 받지 않는다. */
     sendNotificationToHost: IsWildcardNotificationMap<TNotificationsToHost> extends true ? (event: string, payload: unknown) => void : <K extends DomainNotificationKey<TNotificationsToHost>>(event: K, payload: TNotificationsToHost[K]) => void;
     /** transport lifecycle ready 신호를 host로 전송한다. payload는 라이브러리가 고정한다. */
-    sendReadyToHost(): void;
+    sendLifecycleReady(): void;
     /** 개발/디버그 패널이 iframecall 통신 흐름을 관찰할 수 있도록 raw event를 흘려준다. */
     readonly debug: {
         subscribe(handler: (event: IframeDebugEvent) => void): () => void;
@@ -230,10 +230,12 @@ type IframeCallController<TCommands extends CommandMap<TCommands>, TNotification
     /** 종료 사유를 노출하는 promise. 정상 dispose면 null, 비정상 종료면 직렬화된 에러로 resolve된다. */
     readonly terminated: Promise<SerializedIframeCallError | null>;
     /**
-     * iframe에 등록된 command를 호출한다.
-     * ready 이전 호출은 readyPolicy에 따라 queue되거나 즉시 거부된다.
-     * timeout/transfer는 호출별 options로 지정한다.
+     * iframe에 등록된 command를 실행한다.
+     * ready 이전 실행은 readyPolicy에 따라 queue되거나 즉시 거부된다.
+     * timeout/transfer는 실행별 options로 지정한다.
      */
+    invoke<K extends keyof TCommands & string>(cmd: K, args: CommandArgs<TCommands[K]>, options?: IframeCallCallOptions): Promise<CommandResult<TCommands[K]>>;
+    /** @deprecated `invoke()`를 사용한다. 다음 major release에서 제거될 예정이다. */
     call<K extends keyof TCommands & string>(cmd: K, args: CommandArgs<TCommands[K]>, options?: IframeCallCallOptions): Promise<CommandResult<TCommands[K]>>;
     /**
      * iframe이 host로 보낸 notification을 event 이름과 payload로 구독한다.
@@ -272,7 +274,7 @@ type IframeCallRunnerHandle<TCommands = Record<string, CommandHandler>, TNotific
     /** iframeHelper.sendNotificationToHost와 동일한 동작을 runner handle에서 노출한다. */
     sendNotificationToHost: IsWildcardNotificationMap<TNotificationsToHost> extends true ? (event: string, payload: unknown) => void : <K extends DomainNotificationKey<TNotificationsToHost>>(event: K, payload: TNotificationsToHost[K]) => void;
     /** transport lifecycle ready 신호. payload는 `{ protocolVersion: 1 }`로 고정된다. */
-    sendReadyToHost(): void;
+    sendLifecycleReady(): void;
     terminated(reason: string, error?: SerializedIframeCallError): void;
     /** local transport subscription을 즉시 정리하고 이후 inbound/outbound를 모두 no-op으로 만든다. */
     dispose(reason?: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cp949/iframecall",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "타입 안전한 host ↔ iframe postMessage 호출 라이브러리 (React 18/19 지원)",
   "keywords": [
     "iframe",
@@ -24,9 +24,14 @@
   },
   "type": "module",
   "sideEffects": false,
+  "browserslist": [
+    "chrome 75",
+    "firefox 67"
+  ],
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "exports": {
@@ -42,25 +47,29 @@
   "publishConfig": {
     "access": "public"
   },
-  "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "@types/react": "^18.0.0 || ^19.0.0"
-  },
-  "devDependencies": {
-    "@testing-library/dom": "^10.4.0",
-    "@testing-library/react": "^16.3.0",
-    "@types/react": "19.2.2",
-    "jsdom": "^25.0.1",
-    "react": "^19.2.0",
-    "typescript": "6.0.3",
-    "tsup": "^8.0.0",
-    "vitest": "^4.1.5",
-    "@repo/typescript-config": "0.0.0"
-  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "lint": "eslint . --max-warnings 0",
     "check-types": "tsc --noEmit",
-    "test": "vitest run tests/unit --passWithNoTests"
+    "test": "vitest run tests/unit --passWithNoTests",
+    "prepublishOnly": "pnpm run build"
+  },
+  "peerDependencies": {
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "workspace:*",
+    "@repo/typescript-config": "workspace:*",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "19.2.18",
+    "eslint": "^9.39.5",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.8",
+    "tsup": "^8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "^4.1.11"
   }
-}
+}