@cp949/iframecall 0.1.0

package/dist/iframe.js

@@ -0,0 +1,299 @@
+import {
+  createIframeCallError,
+  createIframeCallErrorResponse,
+  createIframeCallNotify,
+  createIframeCallRequest,
+  createIframeCallSuccessResponse,
+  createParentWindowTransport,
+  isSerializedIframeCallError,
+  parseIframeCallMessage,
+  serializeIframeCallError
+} from "./chunk-UYZXYOI6.js";
+
+// src/iframe/consoleDebugLogger.ts
+function consoleDebugLogger(options = {}) {
+  const prefix = options.prefix ?? "[iframecall:iframe]";
+  const head = prefix.length > 0 ? `${prefix} ` : "";
+  return (event) => {
+    switch (event.type) {
+      case "commandReceivedFromHost":
+        console.debug(`${head}${event.type} ${event.command}`, event.args);
+        return;
+      case "commandResultSentToHost":
+        console.debug(`${head}${event.type} ${event.command}`, event.value);
+        return;
+      case "commandErrorSentToHost":
+        console.debug(`${head}${event.type} ${event.command}`, event.error);
+        return;
+      case "notificationSentToHost":
+        console.debug(`${head}${event.type} ${event.event}`, event.payload);
+        return;
+      case "notificationReceivedFromHost":
+        console.debug(`${head}${event.type} ${event.event}`, event.payload);
+        return;
+    }
+  };
+}
+
+// src/iframe/runner.ts
+var RESERVED_COMMAND_NAMES = /* @__PURE__ */ new Set(["constructor", "host:dispose"]);
+function createIframeCallRunner(options) {
+  const targetOrigin = requireTargetOrigin(options.targetOrigin);
+  const allowedOrigins = new Set(options.allowedOrigins ?? [targetOrigin]);
+  const transport = options.transport ?? createParentWindowTransport();
+  let disposing = false;
+  let disposed = false;
+  const debugSubscribers = /* @__PURE__ */ new Set();
+  function emitDebug(event) {
+    for (const handler of debugSubscribers) {
+      try {
+        handler(event);
+      } catch (error) {
+        options.logger?.warn("iframecall debug subscriber threw.", error);
+      }
+    }
+  }
+  const helperInternal = {
+    sendNotificationToHost(event, payload) {
+      if (disposing || disposed) return;
+      safePost(createIframeCallNotify(event, payload));
+      emitDebug({ type: "notificationSentToHost", event, payload });
+    },
+    sendReadyToHost() {
+      if (disposing || disposed) return;
+      safePost(createIframeCallNotify("ready", { protocolVersion: 1 }));
+    },
+    debug: {
+      subscribe(handler) {
+        debugSubscribers.add(handler);
+        return () => {
+          debugSubscribers.delete(handler);
+        };
+      }
+    }
+  };
+  const iframeHelper = helperInternal;
+  const { commands, dispatch } = 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") {
+      emitDebug({
+        type: "notificationReceivedFromHost",
+        event: parsed.message.event,
+        payload: parsed.message.payload
+      });
+      return;
+    }
+    if (parsed?.type !== "request") {
+      return;
+    }
+    if (parsed.message.cmd === "host:dispose") {
+      void handleHostDispose(getDisposeReason(parsed.message.args[0]));
+      return;
+    }
+    void handleRequest(
+      parsed.message.id,
+      parsed.message.cmd,
+      parsed.message.args
+    );
+  });
+  function safePost(message, transfer) {
+    try {
+      transport.post(message, targetOrigin, transfer);
+    } catch (error) {
+      options.logger?.warn("iframecall postMessage failed.", error);
+    }
+  }
+  async function handleHostDispose(reason) {
+    if (disposing || disposed) return;
+    disposing = true;
+    try {
+      await options.onHostDispose?.(reason);
+    } catch (error) {
+      options.logger?.warn("iframecall host dispose handler failed.", error);
+    } finally {
+      safePost(createIframeCallNotify("terminated", { reason }));
+      disposed = true;
+      unsubscribeTransport();
+    }
+  }
+  async function handleRequest(id, cmd, args) {
+    if (disposing || disposed) return;
+    emitDebug({ type: "commandReceivedFromHost", command: cmd, args });
+    const handler = dispatch(cmd);
+    if (handler === void 0) {
+      const error = createIframeCallError(
+        "command_not_found",
+        `Command not found: ${cmd}`,
+        { command: cmd }
+      );
+      safePost(createIframeCallErrorResponse(id, error));
+      emitDebug({ type: "commandErrorSentToHost", command: cmd, error });
+      return;
+    }
+    try {
+      const value = await handler(...args);
+      if (disposing || disposed) return;
+      safePost(createIframeCallSuccessResponse(id, value));
+      emitDebug({ type: "commandResultSentToHost", command: cmd, value });
+    } catch (rawError) {
+      if (disposing || disposed) return;
+      const serialized = serializeIframeCallError(rawError, cmd);
+      safePost(createIframeCallErrorResponse(id, serialized));
+      emitDebug({
+        type: "commandErrorSentToHost",
+        command: cmd,
+        error: serialized
+      });
+    }
+  }
+  const sendNotificationToHostUntyped = (event, payload) => helperInternal.sendNotificationToHost(event, payload);
+  const handle = {
+    commands,
+    iframeHelper,
+    sendNotificationToHost: sendNotificationToHostUntyped,
+    sendReadyToHost() {
+      iframeHelper.sendReadyToHost();
+    },
+    terminated(reason, error) {
+      if (disposing || disposed) return;
+      disposing = true;
+      safePost(createIframeCallNotify("terminated", { reason, error }));
+      disposed = true;
+      unsubscribeTransport();
+    },
+    dispose(_reason) {
+      if (disposing || disposed) return;
+      disposing = true;
+      disposed = true;
+      unsubscribeTransport();
+    }
+  };
+  return handle;
+}
+function resolveCommandSource(options, iframeHelper) {
+  const rawOptions = options;
+  const hasCommandsObject = "commands" in rawOptions && rawOptions.commands !== void 0;
+  const hasCommandsClass = "Commands" in rawOptions && rawOptions.Commands !== void 0;
+  if (hasCommandsObject) {
+    throw createIframeCallError(
+      "invalid_args",
+      "createIframeCallRunner no longer accepts { commands }. Use { Commands } class."
+    );
+  }
+  if (!hasCommandsClass) {
+    throw createIframeCallError(
+      "invalid_args",
+      "createIframeCallRunner requires { Commands } class."
+    );
+  }
+  const Ctor = rawOptions.Commands;
+  const instance = new Ctor(iframeHelper);
+  const handlerCache = buildPrototypeCommandHandlers(instance);
+  return {
+    commands: instance,
+    dispatch(cmd) {
+      return handlerCache.get(cmd);
+    }
+  };
+}
+function buildPrototypeCommandHandlers(instance) {
+  const handlers = /* @__PURE__ */ new Map();
+  let proto = Object.getPrototypeOf(instance);
+  while (proto !== null && proto !== Object.prototype) {
+    for (const key of Reflect.ownKeys(proto)) {
+      if (typeof key !== "string") continue;
+      if (RESERVED_COMMAND_NAMES.has(key)) continue;
+      if (key.startsWith("_")) continue;
+      if (handlers.has(key)) continue;
+      const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+      if (descriptor === void 0) continue;
+      if (descriptor.get !== void 0 || descriptor.set !== void 0)
+        continue;
+      if (typeof descriptor.value !== "function") continue;
+      const method = descriptor.value;
+      handlers.set(key, method.bind(instance));
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+  return handlers;
+}
+function requireTargetOrigin(targetOrigin) {
+  if (targetOrigin.length === 0 || targetOrigin === "*" || targetOrigin === "null") {
+    throw createIframeCallError(
+      "invalid_origin",
+      "targetOrigin must be explicit."
+    );
+  }
+  return targetOrigin;
+}
+function getDisposeReason(payload) {
+  if (typeof payload === "object" && payload !== null && "reason" in payload && typeof payload.reason === "string") {
+    return payload.reason;
+  }
+  return "host_requested";
+}
+
+// src/iframe/useIframeCallRunner.tsx
+import { useEffect, useRef, useState } from "react";
+function useIframeCallRunner(options) {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const runnerRef = useRef(null);
+  const [isActive, setIsActive] = useState(false);
+  useEffect(() => {
+    const opts = optionsRef.current;
+    const runner2 = createIframeCallRunner({
+      targetOrigin: opts.targetOrigin,
+      allowedOrigins: opts.allowedOrigins,
+      Commands: opts.Commands,
+      logger: opts.logger,
+      onHostDispose: opts.onHostDispose,
+      transport: opts.transport
+    });
+    runnerRef.current = runner2;
+    setIsActive(true);
+    let unsubscribeDebug = null;
+    const debugLog = opts.debugLog;
+    if (debugLog) {
+      const prefix = typeof debugLog === "object" && debugLog !== null ? debugLog.prefix : void 0;
+      const handler = consoleDebugLogger(
+        prefix !== void 0 ? { prefix } : void 0
+      );
+      unsubscribeDebug = runner2.iframeHelper.debug.subscribe(handler);
+    }
+    return () => {
+      if (unsubscribeDebug !== null) unsubscribeDebug();
+      runner2.dispose("react_unmount");
+      runnerRef.current = null;
+    };
+  }, []);
+  const runner = runnerRef.current;
+  return {
+    commands: runner?.commands,
+    iframeHelper: runner?.iframeHelper,
+    runner: runner ?? void 0,
+    isActive
+  };
+}
+export {
+  consoleDebugLogger,
+  createIframeCallError,
+  createIframeCallErrorResponse,
+  createIframeCallNotify,
+  createIframeCallRequest,
+  createIframeCallRunner,
+  createIframeCallSuccessResponse,
+  createParentWindowTransport,
+  isSerializedIframeCallError,
+  parseIframeCallMessage,
+  serializeIframeCallError,
+  useIframeCallRunner
+};

package/dist/messages-Cg4n93bf.d.ts

@@ -0,0 +1,331 @@
+/** transport가 controller/runner로 전달하는 정규화된 수신 이벤트. */
+type IframeCallTransportEvent = {
+    /** postMessage로 도착한 raw payload. 파싱 전 단계의 값이다. */
+    readonly data: unknown;
+    /** 메시지 송신자의 origin. allowedOrigins 검증에 사용한다. */
+    readonly origin: string;
+    /** 송신자 Window 참조. expectedSource와 비교해 cross-frame 위장을 차단한다. */
+    readonly source: unknown;
+};
+/** controller/runner가 사용하는 transport 추상화. Window 외 다른 매체로도 교체할 수 있다. */
+type IframeCallTransport = {
+    /** 송신자 Window의 기대값. 정의되어 있으면 수신 시 source 일치를 강제한다. */
+    expectedSource?: unknown;
+    /** 메시지를 targetOrigin으로 전송한다. transferable이 있으면 ownership을 함께 넘긴다. */
+    post(message: unknown, targetOrigin: string, transfer?: readonly IframeCallTransferable[]): void;
+    /** 수신 이벤트를 구독한다. 반환된 함수를 호출하면 listener를 해제한다. */
+    subscribe(handler: (event: IframeCallTransportEvent) => void): () => void;
+};
+/**
+ * host 측에서 사용하는 transport. 자식 iframe의 contentWindow로 postMessage를 보낸다.
+ * `expectedSource`는 contentWindow가 swap되기 전 시점에 캐시되므로,
+ * iframe src 변경처럼 contentWindow가 교체되는 경우 transport도 다시 만들어야 한다.
+ */
+declare function createIframeWindowTransport(iframe: HTMLIFrameElement): IframeCallTransport;
+/**
+ * iframe 측에서 사용하는 transport. 부모 Window를 송신 대상으로 삼고,
+ * 수신 이벤트의 source가 부모 Window 참조와 일치하는지 검증한다.
+ */
+declare function createParentWindowTransport(): IframeCallTransport;
+
+/** Wire envelope: host -> iframe 방향 request. */
+type IframeCallRequest = {
+    readonly protocol: "iframecall";
+    readonly version: 1;
+    readonly id: string;
+    readonly cmd: string;
+    readonly args: readonly unknown[];
+};
+/** Wire envelope: iframe -> host 방향 response. 성공/실패 모두 포함한다. */
+type IframeCallResponse = {
+    readonly protocol: "iframecall";
+    readonly version: 1;
+    readonly id: string;
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly protocol: "iframecall";
+    readonly version: 1;
+    readonly id: string;
+    readonly ok: false;
+    readonly error: SerializedIframeCallError;
+};
+/** Wire envelope: iframe -> host 방향 notify. id 없이 event 이름과 payload만 가진다. */
+type IframeCallNotify = {
+    readonly protocol: "iframecall";
+    readonly version: 1;
+    readonly event: string;
+    readonly payload: unknown;
+};
+/** Error response body. 재귀적으로 cause를 가질 수 있다. */
+type SerializedIframeCallError = {
+    readonly code: string;
+    readonly message: string;
+    readonly command?: string;
+    readonly details?: unknown;
+    readonly cause?: SerializedIframeCallError;
+};
+/** Host controller가 ready 이전 호출을 어떻게 다룰지 선택한다. */
+type ReadyPolicy = "queue" | "reject";
+/** command handler 시그니처. args와 return 모두 structured clone 가능해야 한다. */
+type CommandHandler<TArgs extends readonly unknown[] = readonly unknown[], TResult = unknown> = (...args: TArgs) => TResult | PromiseLike<TResult>;
+/** command map의 각 property가 command handler인지 검증한다. */
+type CommandMap<TCommands> = {
+    readonly [K in keyof TCommands]: TCommands[K] extends (...args: infer TArgs) => infer TResult ? TArgs extends readonly unknown[] ? CommandHandler<TArgs, Awaited<TResult>> : never : never;
+};
+/** command handler의 args tuple을 꺼낸다. */
+type CommandArgs<TCommand> = TCommand extends (...args: infer TArgs) => unknown ? TArgs : never;
+/** command handler의 awaited return type을 꺼낸다. */
+type CommandResult<TCommand> = TCommand extends (...args: infer TArgs) => infer TResult ? TArgs extends readonly unknown[] ? Awaited<TResult> : never : never;
+/** 도메인별 command 목록을 타입 파라미터로 받는 command map. */
+type CommandRunner<TCommands extends CommandMap<TCommands>> = {
+    readonly commands: TCommands;
+};
+/** host가 subscribe하는 notify handler. */
+type NotifyHandler<TPayload = unknown> = (payload: TPayload) => void;
+/** postMessage가 ownership을 넘길 transferable 값. */
+type IframeCallTransferable = Transferable;
+/** command 호출별 timeout과 transfer 대상을 지정한다. */
+type IframeCallCallOptions = {
+    readonly timeoutMs?: number;
+    readonly transfer?: readonly IframeCallTransferable[];
+};
+/** 디버그용 최소 logger. */
+type IframeCallLogger = {
+    readonly warn: (message: string, detail?: unknown) => void;
+    readonly info?: (message: string, detail?: unknown) => void;
+};
+/** host controller 생성 옵션. */
+type IframeCallControllerOptions<TCommands extends CommandMap<TCommands>> = {
+    /** 통신 대상 iframe element. transport 미지정 시 contentWindow 기준 기본 transport를 만든다. */
+    readonly iframe: HTMLIFrameElement;
+    /** postMessage targetOrigin. wildcard("*"/"null"/빈 문자열)는 거부한다. */
+    readonly targetOrigin: string;
+    /** 수신 시 허용할 origin 목록. 미지정이면 targetOrigin 단일 값을 사용한다. */
+    readonly allowedOrigins?: readonly string[];
+    /** ready 이전 호출 처리 정책. "queue"는 대기열에 쌓고, "reject"는 즉시 거부한다. */
+    readonly readyPolicy?: ReadyPolicy;
+    /** queue 정책일 때 대기열 최대 크기. 초과 호출은 queue_overflow 에러로 거부한다. */
+    readonly readyQueueLimit?: number;
+    /** call() 호출별 timeout 기본값(ms). 0 또는 Infinity면 timeout을 적용하지 않는다. */
+    readonly defaultTimeoutMs?: number;
+    /** ready 신호 대기 timeout(ms). 미지정이면 defaultTimeoutMs를 따른다. */
+    readonly readyTimeoutMs?: number;
+    /** request id 생성기. 테스트 환경에서 결정적인 id를 주입할 때 사용한다. */
+    readonly generateId?: () => string;
+    /** 디버그 로그 출력 hook. ready 중복 수신, postMessage 실패 등 비치명적 이벤트만 흘려준다. */
+    readonly logger?: IframeCallLogger;
+    /** Window 외 매체로 통신할 때 주입하는 transport. 미지정이면 iframe 기반 transport를 사용한다. */
+    readonly transport?: IframeCallTransport;
+    /** TCommands를 추론에 강제하기 위한 phantom 필드. 런타임에서는 사용하지 않는다. */
+    readonly __commandsPhantom?: TCommands;
+};
+/**
+ * `ready`는 transport lifecycle event라 domain notification map에 섞이지 않는다.
+ * 사용자가 `TNotificationsToHost`에 `ready` 키를 넣으려 해도 type-level에서 거부한다.
+ */
+type ReservedNotificationName = "ready" | "terminated";
+/**
+ * 도메인 notification map에서 lifecycle 예약 이름을 제거한다.
+ * `sendNotificationToHost`의 generic K 추론에 사용한다.
+ */
+type DomainNotificationKey<TNotificationsToHost> = Exclude<keyof TNotificationsToHost & string, ReservedNotificationName>;
+/**
+ * iframe runner가 host로 보낼 수 있는 notification helper.
+ * Commands class constructor에 주입되어 도메인 코드가 host로 신호를 흘려보낼 때 사용한다.
+ *
+ * 명시된 notification map에서는 lifecycle 예약 이름을 generic K에서 자동으로 제거하고,
+ * default wildcard map에서는 string event를 받는다.
+ */
+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;
+    /** 개발/디버그 패널이 iframecall 통신 흐름을 관찰할 수 있도록 raw event를 흘려준다. */
+    readonly debug: {
+        subscribe(handler: (event: IframeDebugEvent) => void): () => void;
+    };
+};
+/**
+ * 디버그 패널이 관찰하는 iframecall 통신 이벤트.
+ * raw payload를 그대로 전달하므로 production logging에는 사용하지 않는다.
+ */
+type IframeDebugEvent = {
+    readonly type: "commandReceivedFromHost";
+    readonly command: string;
+    readonly args: readonly unknown[];
+} | {
+    readonly type: "commandResultSentToHost";
+    readonly command: string;
+    readonly value: unknown;
+} | {
+    readonly type: "commandErrorSentToHost";
+    readonly command: string;
+    readonly error: SerializedIframeCallError;
+} | {
+    readonly type: "notificationSentToHost";
+    readonly event: string;
+    readonly payload: unknown;
+} | {
+    readonly type: "notificationReceivedFromHost";
+    readonly event: string;
+    readonly payload: unknown;
+};
+/**
+ * host controller가 관찰하는 iframecall 통신 이벤트.
+ * raw payload를 그대로 전달하므로 production logging에는 사용하지 않는다.
+ * iframe 측 IframeDebugEvent와 같은 dev-only 정책을 따른다.
+ */
+type HostDebugEvent = {
+    readonly type: "commandSentToIframe";
+    readonly command: string;
+    readonly args: readonly unknown[];
+} | {
+    readonly type: "commandResultReceivedFromIframe";
+    readonly command: string;
+    readonly value: unknown;
+} | {
+    readonly type: "commandErrorReceivedFromIframe";
+    readonly command: string;
+    readonly error: SerializedIframeCallError;
+} | {
+    readonly type: "notificationReceivedFromIframe";
+    readonly event: string;
+    readonly payload: unknown;
+} | {
+    readonly type: "readyReceived";
+    readonly payload: unknown;
+} | {
+    readonly type: "terminatedReceived";
+    readonly reason: string;
+    readonly error: SerializedIframeCallError | null;
+};
+/**
+ * iframe 업체가 구현하는 `Commands` class의 constructor 시그니처.
+ * runner가 `new Commands(iframeHelper)`로 정확히 한 번 호출한다.
+ */
+type CommandsConstructor<TCommands, TNotificationsToHost = Record<string, unknown>> = new (iframeHelper: IframeHelper<TNotificationsToHost>) => TCommands;
+/**
+ * class 기반 runner 옵션.
+ * 업체 개발자는 `Commands` class만 작성하면 되고, runner가 `iframeHelper`를 주입한다.
+ */
+type IframeCallRunnerClassOptions<TCommands, TNotificationsToHost = Record<string, unknown>> = {
+    readonly targetOrigin: string;
+    readonly allowedOrigins?: readonly string[];
+    readonly Commands: CommandsConstructor<TCommands, TNotificationsToHost>;
+    readonly logger?: IframeCallLogger;
+    readonly onHostDispose?: (reason: string) => void | PromiseLike<void>;
+    readonly transport?: IframeCallTransport;
+};
+/** iframe runner 생성 옵션. */
+type IframeCallRunnerOptions<TCommands, TNotificationsToHost = Record<string, unknown>> = IframeCallRunnerClassOptions<TCommands, TNotificationsToHost>;
+/**
+ * host controller public surface.
+ * 두 번째 generic은 default를 두어 단일 generic 호출처가 typecheck를 유지한다.
+ */
+type IframeCallController<TCommands extends CommandMap<TCommands>, TNotificationsFromIframe = Record<string, unknown>> = {
+    /** iframe이 ready 신호를 보낼 때까지 대기하는 promise. terminate 시 reject된다. */
+    readonly ready: Promise<void>;
+    /** 종료 사유를 노출하는 promise. 정상 dispose면 null, 비정상 종료면 직렬화된 에러로 resolve된다. */
+    readonly terminated: Promise<SerializedIframeCallError | null>;
+    /**
+     * iframe에 등록된 command를 호출한다.
+     * ready 이전 호출은 readyPolicy에 따라 queue되거나 즉시 거부된다.
+     * timeout/transfer는 호출별 options로 지정한다.
+     */
+    call<K extends keyof TCommands & string>(cmd: K, args: CommandArgs<TCommands[K]>, options?: IframeCallCallOptions): Promise<CommandResult<TCommands[K]>>;
+    /**
+     * iframe이 host로 보낸 notification을 event 이름과 payload로 구독한다.
+     * payload 타입은 `TNotificationsFromIframe`로 추론된다.
+     */
+    onNotificationFromIframe<K extends keyof TNotificationsFromIframe & string>(event: K, handler: NotifyHandler<TNotificationsFromIframe[K]>): () => void;
+    /**
+     * controller를 종료하고 transport listener를 정리한다.
+     * iframe에 dispose request를 한 번 시도하지만 실패해도 내부 상태는 항상 정리된다.
+     */
+    dispose(reason?: string): Promise<void>;
+    /**
+     * 개발/디버그 패널이 host 측 통신 흐름을 관찰할 수 있도록 raw event를 흘려준다.
+     * raw payload를 그대로 전달하므로 production logging에는 사용하지 않는다.
+     */
+    readonly debug: {
+        subscribe(handler: (event: HostDebugEvent) => void): () => void;
+    };
+};
+/**
+ * notification map 명시 여부를 판별하는 conditional helper.
+ * 명시된 키 union이면 false, default `Record<string, unknown>`이나 `unknown` 같은 wildcard면 true가 된다.
+ *
+ * `unknown`인 경우 `keyof = never`라 별도로 wildcard로 취급한다.
+ */
+type IsWildcardNotificationMap<TNotificationsToHost> = unknown extends TNotificationsToHost ? true : string extends keyof TNotificationsToHost & string ? true : false;
+/**
+ * iframe runner public surface.
+ * 두 generic 모두 default를 두어 단일 generic 호출처가 typecheck를 유지한다.
+ */
+type IframeCallRunnerHandle<TCommands = Record<string, CommandHandler>, TNotificationsToHost = Record<string, unknown>> = {
+    /** runner가 생성한 Commands 인스턴스. class API 사용 시 host와 같은 reference를 노출한다. */
+    readonly commands: TCommands;
+    /** Commands constructor에 주입된 helper와 같은 reference. debug 구독에도 사용한다. */
+    readonly iframeHelper: IframeHelper<TNotificationsToHost>;
+    /** 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;
+    terminated(reason: string, error?: SerializedIframeCallError): void;
+    /** local transport subscription을 즉시 정리하고 이후 inbound/outbound를 모두 no-op으로 만든다. */
+    dispose(reason?: string): void;
+};
+
+type ErrorOptions = {
+    readonly command?: string;
+    readonly details?: unknown;
+    readonly cause?: SerializedIframeCallError;
+};
+/**
+ * 직렬화된 iframecall 에러 객체를 생성한다.
+ * `command`/`details`/`cause`가 명시적으로 전달되지 않으면 결과 객체에서도 키를 누락시켜
+ * postMessage 직렬화 결과가 호출자 의도와 어긋나지 않게 한다.
+ */
+declare function createIframeCallError(code: string, message: string, options?: ErrorOptions): SerializedIframeCallError;
+/**
+ * 임의의 throw 값을 직렬화된 iframecall 에러로 정규화한다.
+ * - 이미 직렬화된 형태면 `command` 정보가 비어 있을 때만 보강한다.
+ * - 실제 Error 인스턴스는 message만 살리고 name은 details에 보존한다.
+ * - 그 외 값은 문자열화한 결과를 message로, 원본을 details로 남긴다.
+ */
+declare function serializeIframeCallError(value: unknown, command?: string): SerializedIframeCallError;
+/**
+ * 임의의 값이 이미 직렬화된 iframecall 에러 형태인지 검사한다.
+ * `code`와 `message`가 모두 string이어야 한다.
+ */
+declare function isSerializedIframeCallError(value: unknown): value is SerializedIframeCallError;
+
+/** 파싱 결과를 type tag로 구분한 discriminated union. 알 수 없는 형태는 null로 반환한다. */
+type ParsedIframeCallMessage = {
+    readonly type: "request";
+    readonly message: IframeCallRequest;
+} | {
+    readonly type: "response";
+    readonly message: IframeCallResponse;
+} | {
+    readonly type: "notify";
+    readonly message: IframeCallNotify;
+};
+/** host -> iframe 방향 command 요청 envelope을 만든다. */
+declare function createIframeCallRequest(id: string, cmd: string, args: readonly unknown[]): IframeCallRequest;
+/** iframe -> host 방향 command 성공 응답 envelope을 만든다. */
+declare function createIframeCallSuccessResponse(id: string, value: unknown): IframeCallResponse;
+/** iframe -> host 방향 command 실패 응답 envelope을 만든다. */
+declare function createIframeCallErrorResponse(id: string, error: SerializedIframeCallError): IframeCallResponse;
+/** iframe -> host 방향 notify envelope을 만든다. id 없이 event 이름과 payload만 가진다. */
+declare function createIframeCallNotify(event: string, payload: unknown): IframeCallNotify;
+/**
+ * postMessage로 받은 임의의 값을 iframecall envelope으로 파싱한다.
+ * `protocol`/`version`이 어긋나거나 envelope 형태가 어떤 분기와도 일치하지 않으면 null을 돌려준다.
+ * 호출 측은 origin/source 검증 후 이 함수의 결과를 신뢰해 dispatch한다.
+ */
+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 };