@cp949/iframecall 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# 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.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

@@ -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],
@@ -104,7 +106,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 +131,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 +185,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,21 +218,23 @@ host                                    iframe
   │                                       │
   │  <iframe src="...">                   │
   │──────────────────────────────────────▶│ mount
-  │                                       │ sendReadyToHost()
-  │  ◀── ready ───────────────────────────│
+  │                                       │ commands._sendLifecycleReady() → sendLifecycleReady()
+  │  ◀── ready ───────────────────────────│  (lifecycle 채널)
   │  controller.status = "ready"          │
   │                                       │
   │  controller.call("greet", ["World"])  │
-  │  ── request ─────────────────────────▶│ DemoCommandsImpl.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.call`은 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 개요
 
@@ -203,16 +260,24 @@ host                                    iframe
 
 | export | 종류 | 설명 |
 |--------|------|------|
-| `useIframeCallRunner` | hook | iframe용 React 훅. `iframeHelper`, `isActive`를 반환한다. |
+| `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.call("onStatusChange", [...])`로 직접 호출할 수 있다.
+
 > 알림은 iframe → host 단방향이다. host → iframe 알림은 라이브러리 외부에서 `postMessage`로 직접 처리하거나, host에서 커맨드를 호출해 처리한다.
 
 ### 공통 타입

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-BuRipoIx.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-BuRipoIx.js';
 
 /** consoleDebugLogger 옵션. prefix를 명시하지 않으면 [iframecall:host]가 기본값이다. */
 type ConsoleDebugLoggerOptions = {

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-BuRipoIx.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-BuRipoIx.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

@@ -59,7 +59,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 +73,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)) {
@@ -139,7 +139,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 +160,8 @@ function createIframeCallRunner(options) {
     commands,
     iframeHelper,
     sendNotificationToHost: sendNotificationToHostUntyped,
-    sendReadyToHost() {
-      iframeHelper.sendReadyToHost();
+    sendLifecycleReady() {
+      iframeHelper.sendLifecycleReady();
     },
     terminated(reason, error) {
       if (disposing || disposed) return;
@@ -197,11 +198,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 +215,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 +229,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(
@@ -277,9 +293,8 @@ function useIframeCallRunner(options) {
   }, []);
   const runner = runnerRef.current;
   return {
-    commands: runner?.commands,
-    iframeHelper: runner?.iframeHelper,
-    runner: runner ?? void 0,
+    commands: runner?.commands ?? null,
+    iframeHelper: runner?.iframeHelper ?? null,
     isActive
   };
 }

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

@@ -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;
@@ -272,7 +272,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.0",
   "description": "타입 안전한 host ↔ iframe postMessage 호출 라이브러리 (React 18/19 지원)",
   "keywords": [
     "iframe",
@@ -27,6 +27,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "exports": {