@cp949/iframecall 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@
 
 형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)을 따르며, 버전 관리는 [Semantic Versioning](https://semver.org/spec/v2.0.0.html)을 준수합니다. 0.x 버전대에서는 호환성이 깨지는 변경도 minor 버전 증가로 처리합니다.
 
+## [Unreleased]
+
+## [0.3.0] - 2026-09-23
+
+### Added
+
+- host controller와 `useIframeCallController`에 `opaqueOrigin: true` 옵션을 추가했습니다. `sandbox`로 격리된 opaque origin(`"null"`) iframe과 통신합니다. 송신은 `"*"`, 수신은 origin `"null"`과 `contentWindow` source가 모두 일치할 때만 받습니다.
+- `IframeCallControllerOriginOptions` 타입을 export합니다.
+- ready 재요청 handshake를 추가했습니다. host controller는 구독 직후 `host:ready-query` notify를 보내고, 이미 ready를 보낸 runner는 `requested: true` ready로 다시 응답합니다. iframe이 host보다 먼저 로드되어 첫 ready가 유실되던 문제(controller가 `pending`에 머묾)를 해결합니다. 이전 버전 host/runner와 섞여도 동작은 기존과 같습니다(`protocolVersion` 1 유지).
+
+### Changed
+
+- host controller가 생성 시 `host:ready-query` notify를 한 번 전송합니다. `requested: true`가 붙은 중복 ready는 경고 없이 무시합니다.
+- `opaqueOrigin` 모드에서 `targetOrigin`/`allowedOrigins`를 함께 지정하거나 transport에 `expectedSource`가 없으면 `invalid_origin`을 던집니다. 기존 모드의 wildcard 거부 동작은 그대로입니다.
+
+## [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

package/README.md

@@ -20,19 +20,19 @@ 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와 타입만 노출한다.
+host와 iframe은 서로 다른 origin에서도 동작하며, 각 진입점은 그쪽에서만 필요한 API와 타입만 노출한다.
 
 ## 빠른 시작
 
@@ -84,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!"
   };
 
@@ -94,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>
   );
 }
@@ -110,11 +106,11 @@ export function HostPage() {
 
 prefix 컨벤션:
 
-| prefix | 의미 |
-|--------|------|
-| (없음) | host로 dispatch되는 remote command |
-| `_` | 사용자 local-only 메서드. dispatch 대상에서 제외된다. (예: `_sendLifecycleReady`, `_onStatusChange`) |
-| `$` | 라이브러리 점유 namespace. dispatch에서 제외되며, 라이브러리가 정의한 hook 이름만 의미가 있다. |
+| prefix | 의미                                                                                                 |
+| ------ | ---------------------------------------------------------------------------------------------------- |
+| (없음) | host로 dispatch되는 remote command                                                                   |
+| `_`    | 사용자 local-only 메서드. dispatch 대상에서 제외된다. (예: `_sendLifecycleReady`, `_onStatusChange`) |
+| `$`    | 라이브러리 점유 namespace. dispatch에서 제외되며, 라이브러리가 정의한 hook 이름만 의미가 있다.       |
 
 현재 라이브러리가 인식하는 hook은 한 개:
 
@@ -216,13 +212,15 @@ export function IframePage() {
 ```text
 host                                    iframe
   │                                       │
+  │  controller 생성 (listener 등록)       │
+  │  ── notify host:ready-query ─────────▶│ (ready 전이면 무시)
   │  <iframe src="...">                   │
   │──────────────────────────────────────▶│ mount
   │                                       │ commands._sendLifecycleReady() → sendLifecycleReady()
   │  ◀── ready ───────────────────────────│  (lifecycle 채널)
   │  controller.status = "ready"          │
   │                                       │
-  │  controller.call("greet", ["World"])  │
+  │  controller.invoke("greet", ["World"])│
   │  ── request ─────────────────────────▶│ $onCommandRun → AppCommands.greet("World")
   │  ◀── notify status-changed:processing │  (도메인 채널, refcount 0→1)
   │  ◀── response: "Hello, World!" ───────│
@@ -230,7 +228,9 @@ host                                    iframe
 ```
 
 - iframe이 마운트되면 `commands._sendLifecycleReady()`가 `sendLifecycleReady()`를 통해 transport ready 신호를 보낸다.
-- host의 `controller.call`은 ready 시점까지 대기한 뒤 전송된다.
+- ready 전에 호출한 `controller.invoke`는 기본값(`readyPolicy: "queue"`)에서 ready까지 대기한 뒤 전송된다. `readyPolicy: "reject"`면 즉시 거부된다.
+- **ready 재요청(ready-query)**: controller는 `message` listener를 등록한 직후 iframe에 `host:ready-query` notify를 한 번 보낸다. 이미 `sendLifecycleReady()`를 호출한 runner는 ready(`requested: true`)로 다시 응답한다. 그래서 SSR된 `<iframe src>`처럼 iframe이 host hydration보다 먼저 로드되어 첫 ready가 유실돼도 controller가 ready에 도달한다. 앱이 아직 ready 전이면 runner는 query를 무시하고, 이후 앱이 보내는 ready로 연결된다.
+  - host와 runner가 모두 이 기능을 포함한 버전일 때만 복구된다. 이전 버전 runner는 query를 무시하므로, 그 경우에는 iframe `src`를 controller가 생긴 뒤 설정한다(`src={controller ? IFRAME_URL : undefined}`). 같은 요소의 `src` 변경은 `contentWindow` identity를 유지하므로 source 검사에 영향이 없다.
 - 응답은 Promise로 돌아오며, iframe 측 메서드가 throw하면 host 쪽 Promise는 reject된다.
 - iframe → host 단방향 알림은 `sendNotificationToHost`로 보내고, host 쪽에서 `controller.onNotificationFromIframe`으로 받는다.
 - **라이프사이클 채널과 도메인 채널은 책임이 다르다.** `ready`/`terminated`는 transport 신호 전용이고, 도메인 알림(`status-changed` 등)에는 `"ready"` 같은 lifecycle 의미를 담지 않는다.
@@ -240,16 +240,17 @@ host                                    iframe
 
 ### host 진입점
 
-| export | 종류 | 설명 |
-|--------|------|------|
-| `useIframeCallController` | hook | host용 React 훅. `iframeRef`, `controller`, `status`를 반환한다. |
-| `createIframeCallController` | factory | 훅 없이 컨트롤러를 직접 만들 때 사용 |
-| `createIframeWindowTransport` | factory | 커스텀 트랜스포트 구성용 |
-| `consoleDebugLogger` | util | 디버그 이벤트를 콘솔에 출력하는 로거 |
+| export                        | 종류    | 설명                                                                                               |
+| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `useIframeCallController`     | hook    | host용 React 훅. `iframeRef`, `controller`, `status`, `terminationError`, `readyError`를 반환한다. |
+| `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`)
@@ -258,11 +259,11 @@ host                                    iframe
 
 ### iframe 진입점
 
-| export | 종류 | 설명 |
-|--------|------|------|
-| `useIframeCallRunner` | hook | iframe용 React 훅. `commands`, `iframeHelper`, `isActive`를 반환한다. mount 전 `commands`/`iframeHelper`는 `null`. |
-| `createIframeCallRunner` | factory | 훅 없이 러너를 직접 만들 때 사용 |
-| `createParentWindowTransport` | factory | 커스텀 트랜스포트 구성용 |
+| export                        | 종류    | 설명                                                                                                               |
+| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
+| `useIframeCallRunner`         | hook    | iframe용 React 훅. `commands`, `iframeHelper`, `isActive`를 반환한다. mount 전 `commands`/`iframeHelper`는 `null`. |
+| `createIframeCallRunner`      | factory | 훅 없이 러너를 직접 만들 때 사용                                                                                   |
+| `createParentWindowTransport` | factory | 커스텀 트랜스포트 구성용                                                                                           |
 
 `iframeHelper`의 주요 멤버:
 
@@ -276,28 +277,71 @@ host                                    iframe
 - `_` prefix → 사용자 local-only (dispatch 제외)
 - `$` prefix → 라이브러리 namespace (dispatch 제외, 인식되는 hook은 `$onCommandRun`)
 
-`onStatusChange`처럼 prefix가 없으면서 host에서 호출하면 안 되는 메서드는 반드시 `_` prefix를 붙여야 한다. 그렇지 않으면 host가 `controller.call("onStatusChange", [...])`로 직접 호출할 수 있다.
+`onStatusChange`처럼 prefix가 없으면서 host에서 호출하면 안 되는 메서드는 반드시 `_` prefix를 붙여야 한다. 그렇지 않으면 host가 `controller.invoke("onStatusChange", [...])`로 직접 호출할 수 있다.
 
-> 알림은 iframe → host 단방향이다. host → iframe 알림은 라이브러리 외부에서 `postMessage`로 직접 처리하거나, host에서 커맨드를 호출해 처리한다.
+> 도메인 알림은 iframe → host 단방향이다(라이브러리 내부 lifecycle 메시지 `host:ready-query`는 예외). host → iframe 도메인 알림은 라이브러리 외부에서 `postMessage`로 직접 처리하거나, host에서 커맨드를 호출해 처리한다.
 
 ### 공통 타입
 
-`CommandMap`, `IframeCallController`, `IframeCallRunnerHandle`, `IframeCallTransport`, `ReadyPolicy`, `SerializedIframeCallError` 등 핵심 타입은 `host`/`iframe` 양쪽에서 모두 export된다.
+`CommandMap`, `IframeCallTransport`, `ReadyPolicy`, `SerializedIframeCallError` 등 공통 타입은 `host`/`iframe` 양쪽에서 export된다. 역할 전용 타입은 한쪽에서만 export된다: `IframeCallController`는 `host`, `IframeCallRunnerHandle`은 `iframe`.
 
 ## 보안: origin 검증
 
-`targetOrigin`과 `allowedOrigins`는 반드시 명시적으로 지정한다. 와일드카드(`*`)는 사용하지 않는다.
+`targetOrigin`은 명시적인 origin으로 지정한다. 와일드카드(`*`)는 사용하지 않는다. `allowedOrigins`를 생략하면 `[targetOrigin]`을 쓴다. opaque origin 모드에서는 둘 다 지정하지 않는다.
 
-| 옵션 | 의미 |
-|------|------|
-| `targetOrigin` | `postMessage` 전송 시 사용할 대상 origin |
+| 옵션             | 의미                                      |
+| ---------------- | ----------------------------------------- |
+| `targetOrigin`   | `postMessage` 전송 시 사용할 대상 origin  |
 | `allowedOrigins` | 수신 시 허용할 origin 화이트리스트 (배열) |
 
-수신 메시지의 `event.origin`이 화이트리스트에 없으면 무시된다.
+수신 메시지의 `event.origin`이 화이트리스트에 없으면 무시된다. host의 기본 transport는 `event.source`가 대상 iframe의 `contentWindow`인지도 함께 검사한다. 단, 일반 모드에서 controller 생성 시점에 iframe이 문서에 붙지 않아 `contentWindow`가 없으면 source 검사를 생략한다. controller는 iframe을 문서에 붙인 뒤 만든다(훅은 ref 연결 후 생성하므로 해당 없음).
+
+`targetOrigin`에 `""`, `"*"`, `"null"`을 넘기면 `invalid_origin` 에러를 던진다. origin이 `"null"`인 iframe은 아래 opaque origin 모드를 사용한다.
+
+### opaque origin iframe (`sandbox`)
+
+`sandbox="allow-scripts"`처럼 `allow-same-origin` 없이 띄운 iframe은 origin이 `"null"`이라 명시적인 `targetOrigin`으로 메시지를 보낼 수 없다. host에서 `opaqueOrigin: true`로 opt-in한다.
+
+```tsx
+const { iframeRef, controller, status } = useIframeCallController<AppCommands>({
+  opaqueOrigin: true,
+});
+
+return <iframe ref={iframeRef} sandbox="allow-scripts" srcDoc={runnerHtml} />;
+```
+
+> **iframe 안에서 신뢰하지 않는 코드가 실행되면 채널 전체를 신뢰하지 않는 상대로 취급한다.** 아래 "보안 근거"를 먼저 읽는다.
+
+이 모드의 동작:
+
+- 송신: 내부적으로 `targetOrigin="*"`로 보낸다. 대상은 해당 iframe의 `contentWindow`뿐이다.
+- 수신: `event.origin === "null"` **그리고** `event.source === contentWindow`일 때만 받는다.
+- 생성 시 거부(`invalid_origin`):
+  - `targetOrigin` 또는 `allowedOrigins`를 함께 지정한 경우. 타입에서도 거부한다.
+  - iframe이 문서에 붙지 않아 `contentWindow`가 없는 경우, 또는 커스텀 `transport`에 `expectedSource`가 없는 경우.
+
+보안 근거:
+
+- **source 비교가 필수인 이유**: origin `"null"`은 다른 사이트의 모든 sandboxed frame이 공유하는 값이다. origin만으로는 대상 iframe과 다른 opaque frame을 구별할 수 없다. 그래서 이 모드는 source를 비교할 수 없는 설정을 생성 시점에 거부한다.
+- **source 검사는 iframe 요소를 인증할 뿐 문서를 인증하지 않는다**: `sandbox="allow-scripts"`는 iframe 문서가 자기 자신을 navigation하는 것(`location.href = ...`)을 막지 않는다. 이동한 문서도 sandbox flag를 이어받아 origin이 `"null"`이고, 같은 요소라 `contentWindow`도 같다. 따라서 그 문서는 host의 origin·source 검사를 모두 통과하고, `"*"`로 보낸 command와 인자를 받으며, 응답과 notify를 보낼 수 있다. (headless Chromium에서 확인)
+- **수용 조건**: 위 위험은 iframe 안에서 신뢰하지 않는 코드가 돌지 않을 때만 수용할 수 있다. 이 경우 `src`/`srcdoc`는 host가 통제하므로 iframe이 모르는 문서로 이동하지 않는다.
+- **신뢰하지 않는 코드를 실행하는 iframe**(사용자 코드 실행 샌드박스 등)에서는 채널 전체를 신뢰하지 않는 상대로 취급한다. command 인자에 비밀이나 권한 토큰을 넣지 않고, 응답과 notify는 host에서 검증한다. 이 경우 iframe 안의 코드는 navigation 없이도 채널을 이미 제어할 수 있다. navigation은 그 제어를 iframe 밖의 문서로 넘기는 경로를 하나 더 만든다.
+
+iframe 쪽 runner는 바꿀 필요가 없다. parent(host)는 일반 origin이므로 runner는 지금처럼 `targetOrigin: HOST_ORIGIN`을 명시한다.
+
+### iframe 요소 교체
+
+controller는 iframe 요소 하나에 묶인다. 같은 요소의 `src` 변경은 `contentWindow` identity를 유지하지만, 요소 자체를 새로 만들면 `contentWindow`가 달라진다. 훅은 요소 교체를 감지하지 않으므로, 요소를 교체할 때는 훅을 소유한 컴포넌트를 `key`로 리마운트한다.
+
+```tsx
+<SandboxFrame key={runId} />
+```
+
+리마운트하면 이전 controller가 dispose되어 대기 중인 요청이 `terminated`로 reject되고, 새 controller는 이전 window에서 늦게 도착한 메시지를 source 검사로 버린다.
 
 ## 디버깅
 
-훅 옵션에 `debugLog: true`를 주면 송수신 이벤트가 콘솔에 출력된다. 또는 `consoleDebugLogger`를 직접 전달할 수도 있다.
+훅 옵션에 `debugLog: true`(또는 `{ prefix }`)를 주면 송수신 이벤트가 콘솔에 출력된다. 훅 없이 쓸 때는 `controller.debug.subscribe(consoleDebugLogger())`로 같은 출력을 붙인다.
 
 ```ts
 useIframeCallController({
@@ -321,6 +365,14 @@ pnpm dev:r19
 pnpm dev:r18
 ```
 
+opaque origin 모드 데모는 `http://localhost:3300/opaque`다. iframe-r19 앱을 `sandbox="allow-scripts"`로 띄운다. Next.js dev server는 origin `"null"` 문서의 `/_next` 리소스 요청을 cross-origin으로 차단하므로 iframe 앱은 production 모드로 실행한다.
+
+```sh
+pnpm build
+pnpm --filter iframe-r19 exec next start --port 3301
+pnpm --filter host-r19 dev
+```
+
 ## 라이선스
 
 MIT

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

@@ -31,6 +31,7 @@ function isSerializedIframeCallError(value) {
 }
 
 // src/core/messages.ts
+var READY_QUERY_EVENT = "host:ready-query";
 function createIframeCallRequest(id, cmd, args) {
   return {
     protocol: "iframecall",
@@ -111,10 +112,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
@@ -161,15 +164,33 @@ function createParentWindowTransport() {
   };
 }
 
+// src/core/inboundValidation.ts
+function validateInbound(event, policy) {
+  if (!policy.allowedOrigins.has(event.origin)) {
+    return { accepted: false, reason: "origin" };
+  }
+  if (policy.expectedSource === void 0) {
+    if (policy.requireSource === true) {
+      return { accepted: false, reason: "source" };
+    }
+  } else if (event.source !== policy.expectedSource) {
+    return { accepted: false, reason: "source" };
+  }
+  const message = parseIframeCallMessage(event.data);
+  return message === null ? { accepted: false, reason: "message" } : { accepted: true, message };
+}
+
 export {
   createIframeCallError,
   serializeIframeCallError,
   isSerializedIframeCallError,
+  READY_QUERY_EVENT,
   createIframeCallRequest,
   createIframeCallSuccessResponse,
   createIframeCallErrorResponse,
   createIframeCallNotify,
   parseIframeCallMessage,
   createIframeWindowTransport,
-  createParentWindowTransport
+  createParentWindowTransport,
+  validateInbound
 };

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-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';
+import { H as HostDebugEvent, C as CommandMap, I as IframeCallControllerOptions, a as IframeCallController, b as IframeCallControllerOriginOptions, c as IframeCallControllerBaseOptions, S as SerializedIframeCallError } from './messages-Bk4RCDOd.js';
+export { d as CommandArgs, e as CommandHandler, f as CommandResult, g as CommandRunner, h as IframeCallCallOptions, i as IframeCallLogger, j as IframeCallNotify, k as IframeCallRequest, l as IframeCallResponse, m as IframeCallTransferable, n as IframeCallTransport, o as IframeCallTransportEvent, N as NotifyHandler, P as ParsedIframeCallMessage, R as ReadyPolicy, p as ReservedNotificationName, q as createIframeCallError, r as createIframeCallErrorResponse, s as createIframeCallNotify, t as createIframeCallRequest, u as createIframeCallSuccessResponse, v as createIframeWindowTransport, w as isSerializedIframeCallError, x as parseIframeCallMessage, y as serializeIframeCallError } from './messages-Bk4RCDOd.js';
 
 /** consoleDebugLogger 옵션. prefix를 명시하지 않으면 [iframecall:host]가 기본값이다. */
 type ConsoleDebugLoggerOptions = {
@@ -29,10 +29,9 @@ type UseIframeCallControllerDebugLog = boolean | {
  * useIframeCallController에 전달하는 옵션.
  * iframe element는 callback ref로 받으므로 controller 생성 옵션에서 제외한다.
  */
-type UseIframeCallControllerOptions<TCommands extends CommandMap<TCommands>> = {
-    readonly targetOrigin: string;
+type UseIframeCallControllerOptions<TCommands extends CommandMap<TCommands>> = IframeCallControllerOriginOptions & {
     readonly debugLog?: UseIframeCallControllerDebugLog;
-} & Pick<IframeCallControllerOptions<TCommands>, "allowedOrigins" | "defaultTimeoutMs" | "generateId" | "logger" | "readyPolicy" | "readyQueueLimit" | "readyTimeoutMs" | "transport">;
+} & Pick<IframeCallControllerBaseOptions<TCommands>, "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;
@@ -49,4 +48,4 @@ type UseIframeCallControllerResult<TCommands extends CommandMap<TCommands>, TNot
  */
 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 };
+export { CommandMap, HostDebugEvent, IframeCallController, IframeCallControllerOptions, IframeCallControllerOriginOptions, type IframeCallControllerStatus, SerializedIframeCallError, type UseIframeCallControllerDebugLog, type UseIframeCallControllerOptions, type UseIframeCallControllerResult, consoleDebugLogger, createIframeCallController, useIframeCallController };

package/dist/host.js

@@ -1,4 +1,5 @@
 import {
+  READY_QUERY_EVENT,
   createIframeCallError,
   createIframeCallErrorResponse,
   createIframeCallNotify,
@@ -7,12 +8,14 @@ import {
   createIframeWindowTransport,
   isSerializedIframeCallError,
   parseIframeCallMessage,
-  serializeIframeCallError
-} from "./chunk-UYZXYOI6.js";
+  serializeIframeCallError,
+  validateInbound
+} from "./chunk-UNM5VKFB.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 +98,7 @@ function createControllerLifecycle(options) {
       return;
     }
     cleanupDone = true;
-    onCleanup?.();
+    onCleanup == null ? void 0 : onCleanup();
   }
   return {
     ready,
@@ -117,7 +120,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 () => {
@@ -142,144 +146,173 @@ function createNotifyHandlerRegistry() {
   };
 }
 
-// src/host/pendingCallRegistry.ts
-function createPendingCallRegistry(transport, targetOrigin) {
+// src/host/invocationLedger.ts
+function createInvocationLedger(options) {
+  const queued = /* @__PURE__ */ new Map();
   const pending = /* @__PURE__ */ new Map();
-  function clearCallTimeout(call) {
-    if (call.timeoutId !== null) {
-      clearTimeout(call.timeoutId);
+  let ready = false;
+  function clearDeadline(invocation) {
+    if (invocation.timeoutId !== null) {
+      clearTimeout(invocation.timeoutId);
     }
   }
-  return {
-    add(id, call) {
-      pending.set(id, call);
-    },
-    delete(id) {
-      pending.delete(id);
-    },
-    settle(id, response) {
-      const call = pending.get(id);
-      if (call === void 0) {
-        return;
-      }
+  function rejectInvocation(invocation, error) {
+    clearDeadline(invocation);
+    invocation.reject(error);
+  }
+  function expire(id, command, timeoutMs) {
+    var _a;
+    const invocation = (_a = queued.get(id)) != null ? _a : pending.get(id);
+    if (invocation === void 0) return;
+    queued.delete(id);
+    pending.delete(id);
+    rejectInvocation(
+      invocation,
+      createIframeCallError("timeout", "Command timed out.", {
+        command,
+        details: { timeoutMs }
+      })
+    );
+  }
+  function post(id, invocation) {
+    options.onCommandSent(invocation.command, invocation.args);
+    pending.set(id, invocation);
+    try {
+      options.transport.post(
+        createIframeCallRequest(id, invocation.command, invocation.args),
+        options.targetOrigin,
+        invocation.transfer
+      );
+    } catch (error) {
       pending.delete(id);
-      clearCallTimeout(call);
-      if (response.ok) {
-        call.resolve(response.value);
-        return;
-      }
-      call.reject(response.error);
-    },
-    post(id, cmd, args, transfer) {
-      try {
-        transport.post(
-          createIframeCallRequest(id, cmd, args),
-          targetOrigin,
-          transfer
-        );
-      } catch (error) {
-        const call = pending.get(id);
-        pending.delete(id);
-        if (call !== void 0) {
-          clearCallTimeout(call);
-          call.reject(
-            createIframeCallError(
-              "invalid_args",
-              "Failed to post command request.",
-              {
-                command: cmd,
-                details: error
-              }
-            )
-          );
-        }
-      }
-    },
-    rejectAll(buildError) {
-      for (const [, call] of pending) {
-        clearCallTimeout(call);
-        call.reject(buildError(call.command));
-      }
-      pending.clear();
-    },
-    getCommand(id) {
-      return pending.get(id)?.command;
-    }
-  };
-}
-
-// src/host/readyQueue.ts
-function createReadyQueue() {
-  const queued = /* @__PURE__ */ new Map();
-  function clearCallTimeout(call) {
-    if (call.timeoutId !== null) {
-      clearTimeout(call.timeoutId);
+      rejectInvocation(
+        invocation,
+        createIframeCallError("invalid_args", "Failed to post command request.", {
+          command: invocation.command,
+          details: error
+        })
+      );
     }
   }
   return {
-    size() {
-      return queued.size;
-    },
-    add(id, call) {
-      queued.set(id, call);
-    },
-    delete(id) {
-      queued.delete(id);
+    invoke(generateId, command, args, callOptions) {
+      if (!ready && options.readyPolicy === "reject") {
+        return Promise.reject(
+          createIframeCallError("not_ready", "Iframe is not ready.", {
+            command
+          })
+        );
+      }
+      return new Promise((resolve, reject) => {
+        const id = generateId();
+        const timeoutMs = callOptions.timeoutMs;
+        const timeoutId = timeoutMs === 0 || timeoutMs === Number.POSITIVE_INFINITY ? null : setTimeout(() => expire(id, command, timeoutMs), timeoutMs);
+        const invocation = {
+          command,
+          args,
+          transfer: callOptions.transfer,
+          timeoutId,
+          resolve,
+          reject
+        };
+        if (!ready) {
+          if (queued.size >= options.readyQueueLimit) {
+            clearDeadline(invocation);
+            reject(
+              createIframeCallError("queue_overflow", "Ready queue overflow.", {
+                command,
+                details: { readyQueueLimit: options.readyQueueLimit }
+              })
+            );
+            return;
+          }
+          queued.set(id, invocation);
+          return;
+        }
+        post(id, invocation);
+      });
     },
-    flush(forward) {
-      for (const [id, call] of queued) {
+    acceptReady() {
+      if (ready) return;
+      ready = true;
+      for (const [id, invocation] of queued) {
         queued.delete(id);
-        forward(id, call);
+        post(id, invocation);
       }
     },
-    rejectAll(buildError) {
-      for (const [, call] of queued) {
-        clearCallTimeout(call);
-        call.reject(buildError(call.command));
+    settle(response) {
+      const invocation = pending.get(response.id);
+      if (invocation === void 0) return void 0;
+      pending.delete(response.id);
+      clearDeadline(invocation);
+      if (response.ok) {
+        invocation.resolve(response.value);
+      } else {
+        invocation.reject(response.error);
+      }
+      return invocation.command;
+    },
+    terminate(buildError) {
+      for (const [, invocation] of queued) {
+        rejectInvocation(invocation, buildError(invocation.command));
       }
       queued.clear();
+      for (const [, invocation] of pending) {
+        rejectInvocation(invocation, buildError(invocation.command));
+      }
+      pending.clear();
     }
   };
 }
 
 // src/host/controller.ts
 function createIframeCallController(options) {
-  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 pending = createPendingCallRegistry(transport, targetOrigin);
-  const queue = createReadyQueue();
+  var _a, _b, _c, _d, _e, _f, _g;
+  const transport = (_a = options.transport) != null ? _a : createIframeWindowTransport(options.iframe);
+  const { targetOrigin, allowedOrigins, requireSource } = resolveOriginPolicy(
+    options,
+    transport
+  );
+  const generateId = (_b = options.generateId) != null ? _b : createDefaultRequestId;
+  const defaultTimeoutMs = (_c = options.defaultTimeoutMs) != null ? _c : 3e4;
+  const readyTimeoutMs = (_d = options.readyTimeoutMs) != null ? _d : defaultTimeoutMs;
+  const readyPolicy = (_e = options.readyPolicy) != null ? _e : "queue";
+  const readyQueueLimit = (_f = options.readyQueueLimit) != null ? _f : Number.POSITIVE_INFINITY;
   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);
       }
     }
   }
+  const ledger = createInvocationLedger({
+    transport,
+    targetOrigin,
+    readyPolicy,
+    readyQueueLimit,
+    onCommandSent(command, args) {
+      emitDebug({ type: "commandSentToIframe", command, args });
+    }
+  });
   const lifecycle = createControllerLifecycle({
     readyTimeoutMs,
     onTerminate(error) {
       const buildLifecycleError = (command) => createCallLifecycleError(error, command);
-      pending.rejectAll(buildLifecycleError);
-      queue.rejectAll(buildLifecycleError);
+      ledger.terminate(buildLifecycleError);
     }
   });
   const unsubscribeTransport = transport.subscribe(
     createTransportRouter({
       lifecycle,
       allowedOrigins,
+      requireSource,
       transport,
-      pending,
-      queue,
+      ledger,
       notifyRegistry,
       logger: options.logger,
       emitDebug
@@ -289,68 +322,32 @@ function createIframeCallController(options) {
     unsubscribeTransport();
     notifyRegistry.clear();
   });
+  try {
+    transport.post(
+      createIframeCallNotify(READY_QUERY_EVENT, null),
+      targetOrigin
+    );
+  } catch (error) {
+    (_g = options.logger) == null ? void 0 : _g.warn("iframecall postMessage failed.", error);
+  }
+  const invoke = (cmd, args, callOptions) => {
+    var _a2;
+    const terminatedError = lifecycle.getTerminatedError();
+    if (terminatedError !== null) {
+      return Promise.reject(terminatedError);
+    }
+    const timeoutMs = (_a2 = callOptions == null ? void 0 : callOptions.timeoutMs) != null ? _a2 : defaultTimeoutMs;
+    return ledger.invoke(generateId, cmd, args, {
+      timeoutMs,
+      transfer: callOptions == null ? void 0 : callOptions.transfer
+    });
+  };
   const controller = {
     ready: lifecycle.ready,
     terminated: lifecycle.terminated,
+    invoke,
     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 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);
-          reject(
-            createIframeCallError("timeout", "Command timed out.", {
-              command: cmd,
-              details: { timeoutMs }
-            })
-          );
-        }, 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);
-      });
+      return invoke(cmd, args, callOptions);
     },
     onNotificationFromIframe(event, handler) {
       return notifyRegistry.register(
@@ -367,6 +364,7 @@ function createIframeCallController(options) {
       }
     },
     async dispose(reason = "host_requested") {
+      var _a2;
       if (lifecycle.isTerminated()) {
         lifecycle.cleanup();
         return;
@@ -384,7 +382,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,28 +391,37 @@ 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,
     allowedOrigins,
+    requireSource,
     transport,
-    pending,
-    queue,
+    ledger,
     notifyRegistry,
     logger,
     emitDebug
   } = deps;
   return (event) => {
     if (lifecycle.isTerminated()) return;
-    if (!allowedOrigins.has(event.origin)) return;
-    if (transport.expectedSource !== void 0 && event.source !== transport.expectedSource) {
-      return;
-    }
-    const parsed = parseIframeCallMessage(event.data);
-    if (parsed?.type === "response") {
+    const inbound = validateInbound(event, {
+      allowedOrigins,
+      expectedSource: transport.expectedSource,
+      requireSource
+    });
+    if (!inbound.accepted) return;
+    const parsed = inbound.message;
+    if ((parsed == null ? void 0 : parsed.type) === "response") {
       const responseMessage = parsed.message;
-      const command = pending.getCommand(responseMessage.id);
-      pending.settle(responseMessage.id, responseMessage);
+      const command = ledger.settle(responseMessage);
       if (command !== void 0) {
         if (responseMessage.ok) {
           emitDebug({
@@ -432,10 +439,10 @@ 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);
+      handleReadyNotify(payload, lifecycle, ledger, logger, emitDebug);
       return;
     }
     if (notifyEvent === "terminated") {
@@ -445,7 +452,7 @@ function createTransportRouter(deps) {
       emitDebug({
         type: "terminatedReceived",
         reason,
-        error: cause ?? null
+        error: cause != null ? cause : null
       });
       lifecycle.terminate(
         createIframeCallError("terminated", "Iframe terminated.", {
@@ -463,9 +470,11 @@ function createTransportRouter(deps) {
     });
   };
 }
-function handleReadyNotify(payload, lifecycle, queue, pending, logger, emitDebug) {
+function handleReadyNotify(payload, lifecycle, ledger, logger, emitDebug) {
   if (lifecycle.isReady()) {
-    logger?.warn("iframecall duplicate ready ignored.", payload);
+    if (!(isRecord(payload) && payload.requested === true)) {
+      logger == null ? void 0 : logger.warn("iframecall duplicate ready ignored.", payload);
+    }
     return;
   }
   if (!isSupportedReadyPayload(payload)) {
@@ -480,15 +489,7 @@ function handleReadyNotify(payload, lifecycle, queue, pending, logger, emitDebug
   }
   emitDebug({ type: "readyReceived", payload });
   lifecycle.markReady();
-  queue.flush((id, call) => {
-    emitDebug({
-      type: "commandSentToIframe",
-      command: call.command,
-      args: call.args
-    });
-    pending.add(id, call);
-    pending.post(id, call.command, call.args, call.transfer);
-  });
+  ledger.acceptReady();
 }
 function createCallLifecycleError(error, command) {
   if (error.code !== "timeout" || error.command !== void 0) {
@@ -508,6 +509,34 @@ function getTerminatedCause(payload) {
 function isSupportedReadyPayload(payload) {
   return isRecord(payload) && payload.protocolVersion === 1;
 }
+function resolveOriginPolicy(options, transport) {
+  var _a;
+  if (options.opaqueOrigin !== true) {
+    const targetOrigin = requireTargetOrigin(options.targetOrigin);
+    return {
+      targetOrigin,
+      allowedOrigins: new Set((_a = options.allowedOrigins) != null ? _a : [targetOrigin]),
+      requireSource: false
+    };
+  }
+  if (options.targetOrigin !== void 0 || options.allowedOrigins !== void 0) {
+    throw createIframeCallError(
+      "invalid_origin",
+      "opaqueOrigin cannot be combined with targetOrigin or allowedOrigins."
+    );
+  }
+  if (transport.expectedSource === void 0) {
+    throw createIframeCallError(
+      "invalid_origin",
+      "opaqueOrigin requires transport.expectedSource."
+    );
+  }
+  return {
+    targetOrigin: "*",
+    allowedOrigins: /* @__PURE__ */ new Set(["null"]),
+    requireSource: true
+  };
+}
 function requireTargetOrigin(targetOrigin) {
   if (targetOrigin.length === 0 || targetOrigin === "*" || targetOrigin === "null") {
     throw createIframeCallError(
@@ -532,19 +561,20 @@ function useIframeCallController(options) {
   const [status, setStatus] = useState("pending");
   const [terminationError, setTerminationError] = useState(null);
   const [readyError, setReadyError] = useState(null);
+  const controllerRef = useRef(null);
   const iframeRef = useCallback((node) => {
     iframeElRef.current = node;
     setIframeAttached(node !== null);
   }, []);
   useEffect(() => {
     if (!iframeAttached) return;
+    if (controllerRef.current !== null) return;
     const iframeEl = iframeElRef.current;
     if (iframeEl === null) return;
     const opts = optionsRef.current;
     const next = createIframeCallController({
       iframe: iframeEl,
-      targetOrigin: opts.targetOrigin,
-      allowedOrigins: opts.allowedOrigins,
+      ...pickOriginOptions(opts),
       defaultTimeoutMs: opts.defaultTimeoutMs,
       generateId: opts.generateId,
       logger: opts.logger,
@@ -553,13 +583,15 @@ function useIframeCallController(options) {
       readyTimeoutMs: opts.readyTimeoutMs,
       transport: opts.transport
     });
+    const controller2 = next;
+    controllerRef.current = controller2;
     let cancelled = false;
-    setController(
-      next
-    );
-    setStatus("pending");
-    setTerminationError(null);
-    setReadyError(null);
+    if (controllerRef.current === controller2) {
+      setController(controller2);
+      setStatus("pending");
+      setTerminationError(null);
+      setReadyError(null);
+    }
     next.ready.then(
       () => {
         if (cancelled) return;
@@ -591,6 +623,7 @@ function useIframeCallController(options) {
         unsubscribeDebug();
       }
       void next.dispose("host-unmount");
+      if (controllerRef.current === controller2) controllerRef.current = null;
       setController(null);
     };
   }, [iframeAttached]);
@@ -602,6 +635,13 @@ function useIframeCallController(options) {
     readyError
   };
 }
+function pickOriginOptions(opts) {
+  return {
+    opaqueOrigin: opts.opaqueOrigin,
+    targetOrigin: opts.targetOrigin,
+    allowedOrigins: opts.allowedOrigins
+  };
+}
 export {
   consoleDebugLogger,
   createIframeCallController,

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-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';
+import { z as IframeDebugEvent, C as CommandMap, A as IframeCallRunnerOptions, B as IframeCallRunnerHandle, D as CommandsConstructor, E as IframeCallRunnerClassOptions, F as IframeHelper } from './messages-Bk4RCDOd.js';
+export { d as CommandArgs, e as CommandHandler, f as CommandResult, g as CommandRunner, G as DomainNotificationKey, h as IframeCallCallOptions, i as IframeCallLogger, j as IframeCallNotify, k as IframeCallRequest, l as IframeCallResponse, m as IframeCallTransferable, n as IframeCallTransport, o as IframeCallTransportEvent, N as NotifyHandler, P as ParsedIframeCallMessage, R as ReadyPolicy, p as ReservedNotificationName, S as SerializedIframeCallError, q as createIframeCallError, r as createIframeCallErrorResponse, s as createIframeCallNotify, t as createIframeCallRequest, u as createIframeCallSuccessResponse, J as createParentWindowTransport, w as isSerializedIframeCallError, x as parseIframeCallMessage, y as serializeIframeCallError } from './messages-Bk4RCDOd.js';
 
 /** consoleDebugLogger 옵션. prefix를 명시하지 않으면 [iframecall:iframe]가 기본값이다. */
 type ConsoleDebugLoggerOptions = {

package/dist/iframe.js

@@ -1,4 +1,5 @@
 import {
+  READY_QUERY_EVENT,
   createIframeCallError,
   createIframeCallErrorResponse,
   createIframeCallNotify,
@@ -7,12 +8,14 @@ import {
   createParentWindowTransport,
   isSerializedIframeCallError,
   parseIframeCallMessage,
-  serializeIframeCallError
-} from "./chunk-UYZXYOI6.js";
+  serializeIframeCallError,
+  validateInbound
+} from "./chunk-UNM5VKFB.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 +41,21 @@ 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;
+  let lifecycleReadySent = 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);
       }
     }
   }
@@ -61,6 +67,7 @@ function createIframeCallRunner(options) {
     },
     sendLifecycleReady() {
       if (disposing || disposed) return;
+      lifecycleReadySent = true;
       safePost(createIframeCallNotify("ready", { protocolVersion: 1 }));
     },
     debug: {
@@ -76,14 +83,24 @@ function createIframeCallRunner(options) {
   const { commands, dispatch, commandRunHook } = resolveCommandSource(options, iframeHelper);
   const unsubscribeTransport = transport.subscribe((event) => {
     if (disposing || disposed) return;
-    if (!allowedOrigins.has(event.origin)) {
-      return;
-    }
-    if (transport.expectedSource !== void 0 && event.source !== transport.expectedSource) {
-      return;
-    }
-    const parsed = parseIframeCallMessage(event.data);
-    if (parsed?.type === "notify") {
+    const inbound = validateInbound(event, {
+      allowedOrigins,
+      expectedSource: transport.expectedSource
+    });
+    if (!inbound.accepted) return;
+    const parsed = inbound.message;
+    if ((parsed == null ? void 0 : parsed.type) === "notify") {
+      if (parsed.message.event === READY_QUERY_EVENT) {
+        if (lifecycleReadySent) {
+          safePost(
+            createIframeCallNotify("ready", {
+              protocolVersion: 1,
+              requested: true
+            })
+          );
+        }
+        return;
+      }
       emitDebug({
         type: "notificationReceivedFromHost",
         event: parsed.message.event,
@@ -91,7 +108,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 +122,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;
@@ -260,11 +279,13 @@ 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);
   const [isActive, setIsActive] = useState(false);
   useEffect(() => {
+    if (runnerRef.current !== null) return;
     const opts = optionsRef.current;
     const runner2 = createIframeCallRunner({
       targetOrigin: opts.targetOrigin,
@@ -275,7 +296,7 @@ function useIframeCallRunner(options) {
       transport: opts.transport
     });
     runnerRef.current = runner2;
-    setIsActive(true);
+    if (runnerRef.current === runner2) setIsActive(true);
     let unsubscribeDebug = null;
     const debugLog = opts.debugLog;
     if (debugLog) {
@@ -288,13 +309,13 @@ function useIframeCallRunner(options) {
     return () => {
       if (unsubscribeDebug !== null) unsubscribeDebug();
       runner2.dispose("react_unmount");
-      runnerRef.current = null;
+      if (runnerRef.current === runner2) runnerRef.current = null;
     };
   }, []);
   const runner = runnerRef.current;
   return {
-    commands: runner?.commands ?? null,
-    iframeHelper: runner?.iframeHelper ?? null,
+    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-BuRipoIx.d.ts → messages-Bk4RCDOd.d.ts}

@@ -18,8 +18,9 @@ type IframeCallTransport = {
 };
 /**
  * host 측에서 사용하는 transport. 자식 iframe의 contentWindow로 postMessage를 보낸다.
- * `expectedSource`는 contentWindow가 swap되기 전 시점에 캐시되므로,
- * iframe src 변경처럼 contentWindow가 교체되는 경우 transport도 다시 만들어야 한다.
+ * `expectedSource`는 생성 시점의 contentWindow(WindowProxy)를 캐시한다.
+ * 같은 iframe 요소의 src 변경(navigation)은 WindowProxy identity를 유지하지만,
+ * iframe 요소 자체를 교체하면 contentWindow가 달라지므로 transport도 다시 만들어야 한다.
  */
 declare function createIframeWindowTransport(iframe: HTMLIFrameElement): IframeCallTransport;
 /**
@@ -96,18 +97,38 @@ type IframeCallLogger = {
     readonly info?: (message: string, detail?: unknown) => void;
 };
 /** host controller 생성 옵션. */
-type IframeCallControllerOptions<TCommands extends CommandMap<TCommands>> = {
-    /** 통신 대상 iframe element. transport 미지정 시 contentWindow 기준 기본 transport를 만든다. */
-    readonly iframe: HTMLIFrameElement;
+type IframeCallControllerOptions<TCommands extends CommandMap<TCommands>> = IframeCallControllerOriginOptions & IframeCallControllerBaseOptions<TCommands>;
+/**
+ * controller의 origin 정책 옵션.
+ * 일반 origin iframe은 targetOrigin을 명시하고, sandbox로 격리된 opaque origin("null") iframe은 opaqueOrigin으로 opt-in한다.
+ */
+type IframeCallControllerOriginOptions = {
+    /** opaque origin 모드를 끈다. 생략과 같다. */
+    readonly opaqueOrigin?: false;
     /** postMessage targetOrigin. wildcard("*"/"null"/빈 문자열)는 거부한다. */
     readonly targetOrigin: string;
     /** 수신 시 허용할 origin 목록. 미지정이면 targetOrigin 단일 값을 사용한다. */
     readonly allowedOrigins?: readonly string[];
+} | {
+    /**
+     * opaque origin("null") iframe과 통신한다. 송신은 "*"로, 수신은 origin "null"이면서
+     * source가 transport.expectedSource와 같은 메시지만 받는다. expectedSource가 없으면 생성 시 거부한다.
+     */
+    readonly opaqueOrigin: true;
+    /** opaque origin 모드에서는 지정할 수 없다. */
+    readonly targetOrigin?: never;
+    /** opaque origin 모드에서는 지정할 수 없다. */
+    readonly allowedOrigins?: never;
+};
+/** origin 정책을 제외한 controller 옵션. */
+type IframeCallControllerBaseOptions<TCommands extends CommandMap<TCommands>> = {
+    /** 통신 대상 iframe element. transport 미지정 시 contentWindow 기준 기본 transport를 만든다. */
+    readonly iframe: HTMLIFrameElement;
     /** ready 이전 호출 처리 정책. "queue"는 대기열에 쌓고, "reject"는 즉시 거부한다. */
     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;
@@ -230,10 +251,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로 구독한다.
@@ -328,4 +351,4 @@ declare function createIframeCallNotify(event: string, payload: unknown): Iframe
  */
 declare function parseIframeCallMessage(value: unknown): ParsedIframeCallMessage | null;
 
-export { type CommandsConstructor as A, type IframeCallRunnerClassOptions as B, type CommandMap as C, type IframeHelper as D, type DomainNotificationKey as E, createParentWindowTransport as F, type HostDebugEvent as H, type IframeCallControllerOptions as I, type NotifyHandler as N, type ParsedIframeCallMessage as P, type ReadyPolicy as R, type SerializedIframeCallError as S, type IframeCallController as a, type CommandArgs as b, type CommandHandler as c, type CommandResult as d, type CommandRunner as e, type IframeCallCallOptions as f, type IframeCallLogger as g, type IframeCallNotify as h, type IframeCallRequest as i, type IframeCallResponse as j, type IframeCallTransferable as k, type IframeCallTransport as l, type IframeCallTransportEvent as m, type ReservedNotificationName as n, createIframeCallError as o, createIframeCallErrorResponse as p, createIframeCallNotify as q, createIframeCallRequest as r, createIframeCallSuccessResponse as s, createIframeWindowTransport as t, isSerializedIframeCallError as u, parseIframeCallMessage as v, serializeIframeCallError as w, type IframeDebugEvent as x, type IframeCallRunnerOptions as y, type IframeCallRunnerHandle as z };
+export { type IframeCallRunnerOptions as A, type IframeCallRunnerHandle as B, type CommandMap as C, type CommandsConstructor as D, type IframeCallRunnerClassOptions as E, type IframeHelper as F, type DomainNotificationKey as G, type HostDebugEvent as H, type IframeCallControllerOptions as I, createParentWindowTransport as J, type NotifyHandler as N, type ParsedIframeCallMessage as P, type ReadyPolicy as R, type SerializedIframeCallError as S, type IframeCallController as a, type IframeCallControllerOriginOptions as b, type IframeCallControllerBaseOptions as c, type CommandArgs as d, type CommandHandler as e, type CommandResult as f, type CommandRunner as g, type IframeCallCallOptions as h, type IframeCallLogger as i, type IframeCallNotify as j, type IframeCallRequest as k, type IframeCallResponse as l, type IframeCallTransferable as m, type IframeCallTransport as n, type IframeCallTransportEvent as o, type ReservedNotificationName as p, createIframeCallError as q, createIframeCallErrorResponse as r, createIframeCallNotify as s, createIframeCallRequest as t, createIframeCallSuccessResponse as u, createIframeWindowTransport as v, isSerializedIframeCallError as w, parseIframeCallMessage as x, serializeIframeCallError as y, type IframeDebugEvent as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cp949/iframecall",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "타입 안전한 host ↔ iframe postMessage 호출 라이브러리 (React 18/19 지원)",
   "keywords": [
     "iframe",
@@ -24,6 +24,10 @@
   },
   "type": "module",
   "sideEffects": false,
+  "browserslist": [
+    "chrome 75",
+    "firefox 67"
+  ],
   "files": [
     "dist",
     "README.md",
@@ -44,23 +48,26 @@
     "access": "public"
   },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "@types/react": "^18.0.0 || ^19.0.0"
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "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",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "19.3.0",
+    "eslint": "^9.39.5",
+    "jsdom": "^29.1.1",
+    "react": "^19.3.0",
+    "tsup": "^8.5.1",
     "typescript": "6.0.3",
-    "tsup": "^8.0.0",
-    "vitest": "^4.1.5",
-    "@repo/typescript-config": "0.0.0"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "lint": "eslint . --max-warnings 0",
     "check-types": "tsc --noEmit",
     "test": "vitest run tests/unit --passWithNoTests"
   }