@cp949/iframecall 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cp949
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# @cp949/iframecall
+
+타입 안전한 host ↔ iframe `postMessage` 호출 라이브러리. host에서 iframe의 메서드를 함수처럼 호출하고, iframe에서 host로 알림(notification)을 보낼 수 있다. React 18/19 모두 지원한다.
+
+- 양방향 통신: host → iframe RPC 호출, iframe → host 알림
+- 타입 안전: 커맨드 시그니처와 알림 페이로드를 제네릭으로 고정
+- React 훅 제공: `useIframeCallController` (host), `useIframeCallRunner` (iframe)
+- ESM 전용, 브라우저 환경 전용
+- origin 화이트리스트와 ready 핸드셰이크 내장
+
+## 설치
+
+```sh
+pnpm add @cp949/iframecall
+# 또는
+npm install @cp949/iframecall
+# 또는
+yarn add @cp949/iframecall
+```
+
+`react`, `@types/react`는 peer dependency이다. 프로젝트에 이미 설치되어 있어야 한다.
+
+| peer | 지원 버전 |
+|------|-----------|
+| `react` | `^18.0.0 \|\| ^19.0.0` |
+| `@types/react` | `^18.0.0 \|\| ^19.0.0` |
+
+## 진입점
+
+| import | 용도 |
+|--------|------|
+| `@cp949/iframecall/host` | 부모 페이지(host)에서 iframe을 제어할 때 |
+| `@cp949/iframecall/iframe` | 임베드된 페이지(iframe)에서 host의 호출을 받을 때 |
+
+호스트와 iframe은 서로 다른 origin에서 실행되며, 각 진입점은 그쪽에서만 필요한 API와 타입만 노출한다.
+
+## 빠른 시작
+
+### 1. 공유 타입 정의
+
+host와 iframe 양쪽에서 동일하게 사용할 커맨드와 알림 타입을 정의한다.
+
+```ts
+type DemoCommands = {
+  greet(name: string): Promise<string>;
+  add(a: number, b: number): Promise<number>;
+  delay(ms: number): Promise<void>;
+};
+
+type DemoEvents = {
+  "status-changed": string;
+};
+```
+
+> 별도 공유 패키지 없이 양쪽에 같은 타입을 두는 패턴을 권장한다. 모노레포라면 공통 패키지로 빼도 된다.
+
+### 2. host 측 (부모 페이지)
+
+```tsx
+"use client";
+
+import { useIframeCallController } from "@cp949/iframecall/host";
+import { useEffect } from "react";
+
+const IFRAME_ORIGIN = "https://iframe.example.com";
+
+export function HostPage() {
+  const { iframeRef, controller, status } = useIframeCallController<
+    DemoCommands,
+    DemoEvents
+  >({
+    targetOrigin: IFRAME_ORIGIN,
+    allowedOrigins: [IFRAME_ORIGIN],
+  });
+
+  useEffect(() => {
+    if (!controller) return;
+    return controller.onNotificationFromIframe("status-changed", (payload) => {
+      console.log("iframe status:", payload);
+    });
+  }, [controller]);
+
+  const handleGreet = async () => {
+    if (!controller) return;
+    const result = await controller.call("greet", ["World"]);
+    console.log(result); // "Hello, World!"
+  };
+
+  return (
+    <div>
+      <p>status: {status}</p>
+      <button type="button" onClick={handleGreet} disabled={status !== "ready"}>
+        Greet
+      </button>
+      <iframe
+        ref={iframeRef}
+        src={IFRAME_ORIGIN}
+        title="iframe demo"
+      />
+    </div>
+  );
+}
+```
+
+### 3. iframe 측 (임베드된 페이지)
+
+커맨드 구현은 클래스로 정의한다. 생성자는 `iframeHelper`를 인자로 받으며, 메서드 이름이 곧 커맨드 이름이 된다.
+
+```tsx
+"use client";
+
+import {
+  type IframeHelper,
+  useIframeCallRunner,
+} from "@cp949/iframecall/iframe";
+import { useEffect } from "react";
+
+const HOST_ORIGIN = "https://host.example.com";
+
+class DemoCommandsImpl {
+  constructor(private iframeHelper: IframeHelper<DemoEvents>) {}
+
+  async greet(name: string): Promise<string> {
+    this.iframeHelper.sendNotificationToHost("status-changed", "processing");
+    const result = `Hello, ${name}!`;
+    this.iframeHelper.sendNotificationToHost("status-changed", "idle");
+    return result;
+  }
+
+  async add(a: number, b: number): Promise<number> {
+    return a + b;
+  }
+
+  async delay(ms: number): Promise<void> {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+export function IframePage() {
+  const { iframeHelper, isActive } = useIframeCallRunner<
+    DemoCommands,
+    DemoEvents
+  >({
+    targetOrigin: HOST_ORIGIN,
+    allowedOrigins: [HOST_ORIGIN],
+    Commands: DemoCommandsImpl,
+  });
+
+  useEffect(() => {
+    if (!iframeHelper) return;
+    iframeHelper.sendNotificationToHost("status-changed", "ready");
+    iframeHelper.sendReadyToHost();
+  }, [iframeHelper]);
+
+  return <p>{isActive ? "active" : "initializing"}</p>;
+}
+```
+
+## 동작 흐름
+
+```text
+host                                    iframe
+  │                                       │
+  │  <iframe src="...">                   │
+  │──────────────────────────────────────▶│ mount
+  │                                       │ sendReadyToHost()
+  │  ◀── ready ───────────────────────────│
+  │  controller.status = "ready"          │
+  │                                       │
+  │  controller.call("greet", ["World"])  │
+  │  ── request ─────────────────────────▶│ DemoCommandsImpl.greet("World")
+  │  ◀── response: "Hello, World!" ───────│
+  │                                       │
+  │  ◀── notify "status-changed" ─────────│ sendNotificationToHost(...)
+```
+
+- iframe이 마운트되면 `sendReadyToHost()`로 준비 신호를 보낸다.
+- host의 `controller.call`은 ready 시점까지 대기한 뒤 전송된다 (기본 `ReadyPolicy: "wait"`).
+- 응답은 Promise로 돌아오며, iframe 측 메서드가 throw하면 host 쪽 Promise는 reject된다.
+- iframe → host 단방향 알림은 `sendNotificationToHost`로 보내고, host 쪽에서 `controller.onNotificationFromIframe`으로 받는다.
+
+## API 개요
+
+### host 진입점
+
+| export | 종류 | 설명 |
+|--------|------|------|
+| `useIframeCallController` | hook | host용 React 훅. `iframeRef`, `controller`, `status`를 반환한다. |
+| `createIframeCallController` | factory | 훅 없이 컨트롤러를 직접 만들 때 사용 |
+| `createIframeWindowTransport` | factory | 커스텀 트랜스포트 구성용 |
+| `consoleDebugLogger` | util | 디버그 이벤트를 콘솔에 출력하는 로거 |
+
+훅이 반환하는 `controller`의 주요 멤버:
+
+- `controller.call(command, args, options?)` — iframe의 커맨드 호출, 결과를 Promise로 반환
+- `controller.onNotificationFromIframe(event, handler)` — iframe이 보내는 알림 구독, unsubscribe 함수 반환
+- `controller.ready` — iframe ready 신호 대기용 Promise
+- `controller.terminated` — 종료 사유를 노출하는 Promise (정상 dispose면 `null`)
+- `controller.debug.subscribe(handler)` — 송수신 이벤트 디버그 스트림 구독
+- `controller.dispose(reason?)` — 명시적 정리 (훅을 쓰면 자동 호출됨)
+
+### iframe 진입점
+
+| export | 종류 | 설명 |
+|--------|------|------|
+| `useIframeCallRunner` | hook | iframe용 React 훅. `iframeHelper`, `isActive`를 반환한다. |
+| `createIframeCallRunner` | factory | 훅 없이 러너를 직접 만들 때 사용 |
+| `createParentWindowTransport` | factory | 커스텀 트랜스포트 구성용 |
+
+`iframeHelper`의 주요 멤버:
+
+- `iframeHelper.sendNotificationToHost(event, payload)` — host로 알림 전송 (lifecycle 예약 이름 `ready`/`terminated`는 제외)
+- `iframeHelper.sendReadyToHost()` — host에 ready 신호 전송
+- `iframeHelper.debug.subscribe(handler)` — 디버그 스트림 구독
+
+> 알림은 iframe → host 단방향이다. host → iframe 알림은 라이브러리 외부에서 `postMessage`로 직접 처리하거나, host에서 커맨드를 호출해 처리한다.
+
+### 공통 타입
+
+`CommandMap`, `IframeCallController`, `IframeCallRunnerHandle`, `IframeCallTransport`, `ReadyPolicy`, `SerializedIframeCallError` 등 핵심 타입은 `host`/`iframe` 양쪽에서 모두 export된다.
+
+## 보안: origin 검증
+
+`targetOrigin`과 `allowedOrigins`는 반드시 명시적으로 지정한다. 와일드카드(`*`)는 사용하지 않는다.
+
+| 옵션 | 의미 |
+|------|------|
+| `targetOrigin` | `postMessage` 전송 시 사용할 대상 origin |
+| `allowedOrigins` | 수신 시 허용할 origin 화이트리스트 (배열) |
+
+수신 메시지의 `event.origin`이 화이트리스트에 없으면 무시된다.
+
+## 디버깅
+
+훅 옵션에 `debugLog: true`를 주면 송수신 이벤트가 콘솔에 출력된다. 또는 `consoleDebugLogger`를 직접 전달할 수도 있다.
+
+```ts
+useIframeCallController({
+  targetOrigin: IFRAME_ORIGIN,
+  allowedOrigins: [IFRAME_ORIGIN],
+  debugLog: true,
+});
+```
+
+세밀한 제어가 필요하면 `controller.debug.subscribe` / `iframeHelper.debug.subscribe`로 이벤트 스트림을 직접 구독한다.
+
+## 데모
+
+레포에는 동일 시나리오를 React 18/19로 각각 구현한 4개 데모 앱이 있다.
+
+```sh
+# React 19 한 쌍 (host: 3300, iframe: 3301)
+pnpm dev:r19
+
+# React 18 한 쌍 (host: 3302, iframe: 3303)
+pnpm dev:r18
+```
+
+## 라이선스
+
+MIT

package/dist/chunk-UYZXYOI6.js

@@ -0,0 +1,175 @@
+// src/core/errors.ts
+function createIframeCallError(code, message, options = {}) {
+  return {
+    code,
+    message,
+    ...options.command === void 0 ? {} : { command: options.command },
+    ...options.details === void 0 ? {} : { details: options.details },
+    ...options.cause === void 0 ? {} : { cause: options.cause }
+  };
+}
+function serializeIframeCallError(value, command) {
+  if (isSerializedIframeCallError(value)) {
+    return {
+      ...value,
+      ...value.command === void 0 && command !== void 0 ? { command } : {}
+    };
+  }
+  if (value instanceof Error) {
+    return createIframeCallError("command_failed", value.message, {
+      command,
+      details: { name: value.name }
+    });
+  }
+  return createIframeCallError("command_failed", String(value), {
+    command,
+    details: value
+  });
+}
+function isSerializedIframeCallError(value) {
+  return typeof value === "object" && value !== null && "code" in value && "message" in value && typeof value.code === "string" && typeof value.message === "string";
+}
+
+// src/core/messages.ts
+function createIframeCallRequest(id, cmd, args) {
+  return {
+    protocol: "iframecall",
+    version: 1,
+    id,
+    cmd,
+    args
+  };
+}
+function createIframeCallSuccessResponse(id, value) {
+  return {
+    protocol: "iframecall",
+    version: 1,
+    id,
+    ok: true,
+    value
+  };
+}
+function createIframeCallErrorResponse(id, error) {
+  return {
+    protocol: "iframecall",
+    version: 1,
+    id,
+    ok: false,
+    error
+  };
+}
+function createIframeCallNotify(event, payload) {
+  return {
+    protocol: "iframecall",
+    version: 1,
+    event,
+    payload
+  };
+}
+function parseIframeCallMessage(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  if (value.protocol !== "iframecall" || value.version !== 1) {
+    return null;
+  }
+  if (isIframeCallRequest(value)) {
+    return { type: "request", message: value };
+  }
+  if (isIframeCallResponse(value)) {
+    return { type: "response", message: value };
+  }
+  if (isIframeCallNotify(value)) {
+    return { type: "notify", message: value };
+  }
+  return null;
+}
+function isIframeCallRequest(value) {
+  return typeof value.id === "string" && typeof value.cmd === "string" && Array.isArray(value.args) && !("ok" in value) && !("event" in value) && !("payload" in value);
+}
+function isIframeCallResponse(value) {
+  if (typeof value.id !== "string" || !("ok" in value)) {
+    return false;
+  }
+  if (value.ok === true) {
+    return "value" in value && !("cmd" in value) && !("event" in value) && !("args" in value);
+  }
+  if (value.ok === false) {
+    return isSerializedIframeCallError2(value.error) && !("cmd" in value) && !("event" in value) && !("args" in value) && !("value" in value);
+  }
+  return false;
+}
+function isIframeCallNotify(value) {
+  return typeof value.event === "string" && !("id" in value) && !("cmd" in value) && !("ok" in value) && "payload" in value;
+}
+function isSerializedIframeCallError2(value) {
+  return isRecord(value) && typeof value.code === "string" && typeof value.message === "string";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/core/transport.ts
+function createIframeWindowTransport(iframe) {
+  return {
+    expectedSource: iframe.contentWindow ?? void 0,
+    post(message, targetOrigin, transfer) {
+      iframe.contentWindow?.postMessage(
+        message,
+        targetOrigin,
+        transfer
+      );
+    },
+    subscribe(handler) {
+      const listener = (event) => {
+        handler({
+          data: event.data,
+          origin: event.origin,
+          source: event.source
+        });
+      };
+      window.addEventListener("message", listener);
+      return () => {
+        window.removeEventListener("message", listener);
+      };
+    }
+  };
+}
+function createParentWindowTransport() {
+  return {
+    expectedSource: window.parent,
+    post(message, targetOrigin, transfer) {
+      window.parent.postMessage(
+        message,
+        targetOrigin,
+        transfer
+      );
+    },
+    subscribe(handler) {
+      const listener = (event) => {
+        handler({
+          data: event.data,
+          origin: event.origin,
+          source: event.source
+        });
+      };
+      window.addEventListener("message", listener);
+      return () => {
+        window.removeEventListener("message", listener);
+      };
+    }
+  };
+}
+
+export {
+  createIframeCallError,
+  serializeIframeCallError,
+  isSerializedIframeCallError,
+  createIframeCallRequest,
+  createIframeCallSuccessResponse,
+  createIframeCallErrorResponse,
+  createIframeCallNotify,
+  parseIframeCallMessage,
+  createIframeWindowTransport,
+  createParentWindowTransport
+};

package/dist/host.d.ts

@@ -0,0 +1,52 @@
+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';
+
+/** consoleDebugLogger 옵션. prefix를 명시하지 않으면 [iframecall:host]가 기본값이다. */
+type ConsoleDebugLoggerOptions = {
+    readonly prefix?: string;
+};
+/**
+ * host controller.debug.subscribe에 그대로 넘길 수 있는 console.debug 출력 함수.
+ * event type별로 핵심 식별자(command/event/reason)를 첫 인자에 포함하고,
+ * raw payload(args/value/error/payload)를 두 번째 인자로 전달해 DevTools에서 펼쳐 볼 수 있게 한다.
+ */
+declare function consoleDebugLogger(options?: ConsoleDebugLoggerOptions): (event: HostDebugEvent) => void;
+
+/**
+ * iframecall host controller를 생성한다.
+ * 옵션을 정규화하고 transport를 구독해 ready/notify/response 이벤트를 dispatch하는 controller 객체를 돌려준다.
+ * 두 번째 generic은 iframe -> host notify의 payload 타입 추론에 사용한다.
+ */
+declare function createIframeCallController<TCommands extends CommandMap<TCommands>, TNotificationsFromIframe = Record<string, unknown>>(options: IframeCallControllerOptions<TCommands>): IframeCallController<TCommands, TNotificationsFromIframe>;
+
+/** controller가 거치는 lifecycle 단계. host shell이 직접 화면에 노출하기 좋은 단계로 좁힌다. */
+type IframeCallControllerStatus = "pending" | "ready" | "failed" | "terminated";
+/** debugLog 옵션. true면 자동 구독, prefix override 가능. false/undefined면 미구독. */
+type UseIframeCallControllerDebugLog = boolean | {
+    readonly prefix?: string;
+};
+/**
+ * useIframeCallController에 전달하는 옵션.
+ * iframe element는 callback ref로 받으므로 controller 생성 옵션에서 제외한다.
+ */
+type UseIframeCallControllerOptions<TCommands extends CommandMap<TCommands>> = {
+    readonly targetOrigin: string;
+    readonly debugLog?: UseIframeCallControllerDebugLog;
+} & Pick<IframeCallControllerOptions<TCommands>, "allowedOrigins" | "defaultTimeoutMs" | "generateId" | "logger" | "readyPolicy" | "readyQueueLimit" | "readyTimeoutMs" | "transport">;
+/** useIframeCallController가 반환하는 handle. mount 전에는 controller가 null이다. */
+type UseIframeCallControllerResult<TCommands extends CommandMap<TCommands>, TNotificationsFromIframe = Record<string, unknown>> = {
+    readonly iframeRef: (node: HTMLIFrameElement | null) => void;
+    readonly controller: IframeCallController<TCommands, TNotificationsFromIframe> | null;
+    readonly status: IframeCallControllerStatus;
+    readonly terminationError: SerializedIframeCallError | null;
+    readonly readyError: unknown;
+};
+/**
+ * iframecall host controller를 React lifecycle에 묶는 hook.
+ * mount 시 한 번 controller를 생성하고, unmount 시 dispose한다.
+ * 옵션 reference 변경은 무시되므로 호출처는 옵션을 매 render마다 새로 생성해도 안전하다.
+ * 새 controller가 필요한 경우 부모 컴포넌트에서 key prop을 변경해 hook 인스턴스를 리마운트한다.
+ */
+declare function useIframeCallController<TCommands extends CommandMap<TCommands>, TNotificationsFromIframe = Record<string, unknown>>(options: UseIframeCallControllerOptions<TCommands>): UseIframeCallControllerResult<TCommands, TNotificationsFromIframe>;
+
+export { CommandMap, HostDebugEvent, IframeCallController, IframeCallControllerOptions, type IframeCallControllerStatus, SerializedIframeCallError, type UseIframeCallControllerDebugLog, type UseIframeCallControllerOptions, type UseIframeCallControllerResult, consoleDebugLogger, createIframeCallController, useIframeCallController };