@bstage-sdk/bridge 0.9.1 → 0.10.0

package/README.md

@@ -79,6 +79,62 @@ host.dispose()
 모두 맞는 메시지만 처리한다. 토큰은 프레임으로 가지 않는다 — 인증은 `fetchImpl`이 호스트 쪽에서 붙이고,
 프레임에는 상태·statusText·content-type·본문 문자열만 돌아간다.
 
+### 세션 수명과 프레임 자기 내비게이션
+
+템플릿은 자기 프레임을 다른 URL로 옮길 수 있다(`location = 'https://attacker/#' + session`). sandbox 플래그는
+내비게이션 뒤에도 남으므로 새 문서도 origin `"null"`이고 `contentWindow`도 같다 — `ev.source`·origin 검사만으로는
+옛 문서와 새 문서를 가를 수 없고, 세션은 srcdoc 본문에 있어 템플릿이 읽어 URL로 넘길 수 있다. 호스트가 iframe의
+두 번째 `load`에서 `dispose()`해도 새 문서의 스크립트는 `load`보다 먼저 돈다. SDK는 이 틈을 다음으로 닫는다
+(호스트 코드 변경 없음).
+
+- **세션당 문서 하나(프레임 토큰)**: 프레임 런타임이 부트스트랩 때 문서마다 128비트 토큰을 만들어 모든 봉투 최상위
+  `frame`에 싣는다. 호스트는 세션이 맞는 첫 메시지의 토큰에 세션을 묶고, 이후 **토큰이 없거나 다른** 메시지가 오면
+  그 메시지를 처리하지 않고 즉시 `dispose()`한다. 같은 토큰의 `ready` 재전송에는 계속 답하지만, 다른 문서의 두 번째
+  핸드셰이크는 성립하지 않는다. 세션을 URL로 받은 새 문서는 토큰을 모르므로 첫 메시지에서 세션이 끊긴다.
+- **토큰은 CSPRNG로만 만든다**: `crypto.getRandomValues`가 없으면 `Math.random`으로 대신하지 않고 브리지를 열지 않는다(`frame-unload` 외에는 아무것도 보내지 않는다).
+- **핸드셰이크 전에는 이벤트를 보내지 않는다**: `host.send`는 토큰이 묶이기 전에는 프레임에 보내지 않고 init에만 반영한다. init에 접히지 않는 `visibility`는 마지막 값을 묶인 직후(init 뒤) 한 번 보낸다. 공개되는 봉투 id 접두사와 따로 뽑는다.
+- **토큰은 템플릿 코드에 노출하지 않는다**: 런타임 클로저에만 있고, 봉투는 객체 리터럴로 만들며(Object.prototype
+  setter를 부르지 않는다) 부트스트랩 때 `bind`해 둔 `parent.postMessage`로만 보낸다. 호스트 → 프레임 메시지
+  (init·응답·이벤트)에는 실리지 않는다. 그래서 템플릿이 `Object.assign`·`Function.prototype.*`·`Object.prototype`
+  setter를 가로채도 보이는 것은 세션뿐이다(테스트로 고정). 세션은 템플릿이 읽을 수 있다 — 같은 문서이고 srcdoc 본문에
+  있기 때문이다. 세션은 "이 iframe의 메시지"라는 표식일 뿐 비밀로 취급하지 않는다.
+- **`frame-unload`**: 부트스트랩이 `pagehide`(capture, 템플릿보다 먼저 등록)에서 `evt:frame-unload`를 동기로 보낸다.
+  **전송을 가장 먼저** 하고, 전송 경로는 객체 리터럴과 부트스트랩 때 잡아 둔 참조(`bind`한 `postMessage`,
+  `PageTransitionEvent.prototype.persisted` 원본 접근자를 `Function.prototype.call.bind`로 묶은 것)만 쓴다.
+  `clearInterval`·`clearTimeout`도 부트스트랩 때 잡고, 타이머·대기 요청 정리는 전송 뒤 각각 try로 감싼다. 그래서
+  템플릿이 **리스너가 살아 있는 동안** 전역·프로토타입(`clearInterval`·`clearTimeout`·`Map.prototype.forEach`·`Error`·
+  `Function.prototype.call`·`persisted` 접근자)을 바꾸거나 던지게 해도 전송은 막히지 않는다(테스트로 고정).
+  `persisted` 읽기가 실패하면 bfcache 진입이 아닌 것으로 보고 보낸다(실패는 끊는 쪽으로).
+  보장하지 **않는** 것: 템플릿이 `document.open()`으로 창의 이벤트 리스너를 모두 지운 뒤 내비게이션하면 `pagehide`
+  처리기 자체가 돌지 않는다 — 이때는 프레임 토큰과 호스트의 두 번째 `load` dispose에 기댄다.
+  호스트는 받는 즉시 `dispose()`한다 — 이후 메시지는 무시되고, dispose 뒤 끝난 요청의 응답도 프레임에 보내지 않는다.
+  프레임 쪽 대기 요청은 `UNSUPPORTED`로 바로 거절된다. bfcache 진입(`persisted: true`)에는 보내지 않는다(복원되면 같은 문서가 계속 쓴다).
+- **`onDispose(reason)`**(선택): 호스트가 dispose될 때 한 번 불린다. `'frame-unload'`·`'frame-mismatch'`는 호스트가
+  스스로 끊은 경우, `'manual'`은 `dispose()` 호출이다. 임베더는 이 콜백에서 iframe을 바로 걷어 낼 수 있다(콜백 예외는 삼킨다).
+  `beforeunload`·`unload`는 쓰지 않는다 — `beforeunload`는 호스트 페이지 자체의 이동에도 프레임에 오므로 이동이
+  취소되거나 bfcache에서 복원되면 멀쩡한 템플릿이 끊기고, 하위 프레임의 `unload` 리스너는 호스트 페이지의 bfcache를
+  막고 폐기 중인 API다.
+
+**남는 위험(정직하게)**
+
+- 막는 것은 "새 문서가 유효한 교환을 하는 것"이다. 새 문서가 **메시지를 보내지 않고 기다리면**, 호스트가 알아채기
+  전까지(`frame-unload` 처리 또는 두 번째 `load`) `host.send`로 보내는 이벤트(`locale`·`theme`·`member`의
+  `signedIn`·`nickname`·`slot.context`·`visibility`)를 받을 수 있다. Chromium은 다른 프로세스로 가는 하위 프레임
+  내비게이션에서 옛 문서의 `pagehide`를 새 문서 커밋과 병렬로 돌리므로 이 틈은 0이 아니다. 이벤트·init에 민감 정보를
+  싣지 않는다는 원칙이 여기서도 경계다.
+- 토큰 비공개는 JS 수준 보장이다. 엔진 버그나 이 SDK가 놓친 관찰 경로로 원래 문서의 템플릿이 토큰을 얻어 URL로 넘기면,
+  새 문서는 `frame-unload`가 처리되기 전까지 유효한 요청을 보낼 수 있다. 이 경우의 마지막 방어선은 `frame-unload`와
+  호스트의 두 번째 `load` dispose다.
+- **진행 중인 요청의 응답**: 원래 문서가 보낸 요청의 응답이 내비게이션 뒤·dispose 전에 끝나면, 호스트는 그 응답을
+  `iframe.contentWindow`(= 새 문서)로 보낸다. 새 문서는 응답 봉투를 읽을 수 있다. dispose 뒤에 끝난 응답은 버리지만
+  호스트 쪽 fetch 자체를 중단하지는 않는다(dispose 시 진행 중 fetch abort는 후속 과제).
+- 세션을 아는 쪽(= 그 프레임의 템플릿)은 잘못된 토큰을 보내 자기 세션을 끊을 수 있다. 자기 자신에 대한 서비스 거부일 뿐이다.
+- 호스트는 srcdoc마다 새 세션(`createSession()`)을 만들고 세션 하나에 `createBridgeHost`를 하나만 둔다. 같은 세션으로
+  호스트를 다시 만들면 묶임이 새로 시작된다.
+- **같은 srcdoc의 재로드·재삽입에는 새 호스트가 필요하다**: iframe을 DOM에서 옮기거나 다시 넣거나 `srcdoc`를 다시 설정하면
+  새 문서(새 프레임 토큰)가 뜨므로, 옛 호스트는 `frame-unload`나 `frame-mismatch`로 끊기고 그 문서는 브리지를 쓰지 못한다.
+  이때는 새 세션으로 `createSrcdoc`·`createBridgeHost`를 다시 만든다(`onDispose`로 감지할 수 있다).
+
 ### fetch 정책
 
 `new URL(url, hostOrigin)`으로 정규화한 뒤 목적지를 네 갈래로 나눈다.
@@ -159,6 +215,7 @@ external에 인증을 붙이는 fetch를 주입하지 않는다. 외부 갈래
 
 오류 코드: `FORBIDDEN_DESTINATION`·`FORBIDDEN_METHOD`·`BODY_TOO_LARGE`·`RATE_LIMITED`·`BAD_REQUEST`·`TIMEOUT`·`NETWORK_ERROR`·`UNSUPPORTED`.
 프레임 요청은 15초 안에 응답이 없으면 `TIMEOUT`. 핸드셰이크(`ready`)는 init을 받을 때까지 재전송한다(처음 10초는 250ms, 이후 2초 간격).
+프레임 → 호스트 봉투에는 최상위 `frame`(프레임 토큰)이 붙고, 문서가 내려갈 때 `evt:frame-unload`(`FRAME_UNLOAD_EVENT`)가 간다(위 "세션 수명").
 
 ## 프레임 문서
 

package/dist/{chunk-6LV7HEN4.js → chunk-JH3A3Z2A.js}

@@ -1,7 +1,7 @@
 import {
   bridgeRuntime,
   createBridgeFetch
-} from "./chunk-KQMJY4ZH.js";
+} from "./chunk-N3JID7KQ.js";
 
 // src/protocol/envelope.ts
 var BRIDGE_VERSION = 1;
@@ -65,6 +65,7 @@ var REQUEST_TYPES = [
 var HOST_EVENT_TYPES = ["slot.context", "locale", "member", "theme", "visibility"];
 var READY_EVENT = "ready";
 var INIT_RESPONSE = "init";
+var FRAME_UNLOAD_EVENT = "frame-unload";
 var BRIDGE_SURFACES = ["page", "slot"];
 function isBridgeSurface(value) {
   return BRIDGE_SURFACES.includes(value);
@@ -551,6 +552,7 @@ export {
   HOST_EVENT_TYPES,
   READY_EVENT,
   INIT_RESPONSE,
+  FRAME_UNLOAD_EVENT,
   BRIDGE_SURFACES,
   isBridgeSurface,
   IFRAME_ATTRIBUTES,

package/dist/{chunk-KQMJY4ZH.js → chunk-N3JID7KQ.js}

@@ -103,6 +103,20 @@ function bridgeRuntime(g, makeFetch, config) {
   const session = config.session;
   const hostOrigin = config.hostOrigin;
   const parent = g.parent;
+  const sendToHost = parent ? parent.postMessage.bind(parent) : void 0;
+  const stopInterval = clearInterval;
+  const stopTimeout = clearTimeout;
+  let readPersisted;
+  const ownDescriptor = Object.getOwnPropertyDescriptor;
+  const hasOwn = Function.prototype.call.bind(Object.prototype.hasOwnProperty);
+  try {
+    const pte = g.PageTransitionEvent;
+    const desc = pte ? Object.getOwnPropertyDescriptor(pte.prototype, "persisted") : void 0;
+    if (desc && typeof desc.get === "function")
+      readPersisted = Function.prototype.call.bind(desc.get);
+  } catch {
+    readPersisted = void 0;
+  }
   const pending = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Map();
   let init;
@@ -119,6 +133,17 @@ function bridgeRuntime(g, makeFetch, config) {
     return out;
   }
   const idPrefix = randomPrefix();
+  function secureToken() {
+    if (!g.crypto || typeof g.crypto.getRandomValues !== "function") return "";
+    const bytes = new Uint8Array(16);
+    g.crypto.getRandomValues(bytes);
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 1) out += (bytes[i] + 256).toString(16).slice(1);
+    return out;
+  }
+  const frameToken = secureToken();
+  let closed = frameToken === "";
+  let unloaded = false;
   function nextId() {
     seq += 1;
     return idPrefix + "-" + seq;
@@ -130,9 +155,12 @@ function bridgeRuntime(g, makeFetch, config) {
     return err;
   }
   function post(kind, type, id, payload) {
-    if (!parent) return;
+    if (!sendToHost || closed) return;
     const body = Object.assign({}, payload, { session });
-    parent.postMessage({ v: 1, ns: NS, id, kind, type, payload: body }, hostOrigin);
+    sendToHost(
+      { v: 1, ns: NS, id, kind, type, payload: body, frame: frameToken },
+      hostOrigin
+    );
   }
   function isEnvelope(m) {
     if (typeof m !== "object" || m === null) return false;
@@ -205,6 +233,54 @@ function bridgeRuntime(g, makeFetch, config) {
     }
   }
   g.addEventListener("message", onMessage);
+  function isPersisted(ev) {
+    try {
+      if (readPersisted) return readPersisted(ev) === true;
+      if (typeof ev !== "object" || ev === null) return false;
+      const desc = ownDescriptor(ev, "persisted");
+      return !!desc && hasOwn(desc, "value") && desc.value === true;
+    } catch {
+      return false;
+    }
+  }
+  function onPageHide(ev) {
+    if (unloaded || isPersisted(ev)) return;
+    unloaded = true;
+    closed = true;
+    if (sendToHost) {
+      try {
+        sendToHost(
+          {
+            v: 1,
+            ns: NS,
+            id: idPrefix + "-unload",
+            kind: "evt",
+            type: "frame-unload",
+            payload: { session },
+            frame: frameToken
+          },
+          hostOrigin
+        );
+      } catch {
+      }
+    }
+    try {
+      stopInterval(readyTimer);
+    } catch {
+    }
+    try {
+      pending.forEach(function(entry) {
+        try {
+          stopTimeout(entry.timer);
+          entry.reject(codeError("UNSUPPORTED", "bridge closed"));
+        } catch {
+        }
+      });
+      pending.clear();
+    } catch {
+    }
+  }
+  g.addEventListener("pagehide", onPageHide, true);
   let readyAttempts = 0;
   function sendReady() {
     readyAttempts += 1;
@@ -218,6 +294,10 @@ function bridgeRuntime(g, makeFetch, config) {
   sendReady();
   function request(type, payload) {
     return new Promise(function(resolve, reject) {
+      if (closed) {
+        reject(codeError("UNSUPPORTED", "bridge closed"));
+        return;
+      }
       const id = nextId();
       const timer = setTimeout(function() {
         pending.delete(id);

package/dist/frame.cjs

@@ -130,6 +130,20 @@ function bridgeRuntime(g, makeFetch, config) {
   const session = config.session;
   const hostOrigin = config.hostOrigin;
   const parent = g.parent;
+  const sendToHost = parent ? parent.postMessage.bind(parent) : void 0;
+  const stopInterval = clearInterval;
+  const stopTimeout = clearTimeout;
+  let readPersisted;
+  const ownDescriptor = Object.getOwnPropertyDescriptor;
+  const hasOwn = Function.prototype.call.bind(Object.prototype.hasOwnProperty);
+  try {
+    const pte = g.PageTransitionEvent;
+    const desc = pte ? Object.getOwnPropertyDescriptor(pte.prototype, "persisted") : void 0;
+    if (desc && typeof desc.get === "function")
+      readPersisted = Function.prototype.call.bind(desc.get);
+  } catch {
+    readPersisted = void 0;
+  }
   const pending = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Map();
   let init;
@@ -146,6 +160,17 @@ function bridgeRuntime(g, makeFetch, config) {
     return out;
   }
   const idPrefix = randomPrefix();
+  function secureToken() {
+    if (!g.crypto || typeof g.crypto.getRandomValues !== "function") return "";
+    const bytes = new Uint8Array(16);
+    g.crypto.getRandomValues(bytes);
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 1) out += (bytes[i] + 256).toString(16).slice(1);
+    return out;
+  }
+  const frameToken = secureToken();
+  let closed = frameToken === "";
+  let unloaded = false;
   function nextId() {
     seq += 1;
     return idPrefix + "-" + seq;
@@ -157,9 +182,12 @@ function bridgeRuntime(g, makeFetch, config) {
     return err;
   }
   function post(kind, type, id, payload) {
-    if (!parent) return;
+    if (!sendToHost || closed) return;
     const body = Object.assign({}, payload, { session });
-    parent.postMessage({ v: 1, ns: NS, id, kind, type, payload: body }, hostOrigin);
+    sendToHost(
+      { v: 1, ns: NS, id, kind, type, payload: body, frame: frameToken },
+      hostOrigin
+    );
   }
   function isEnvelope(m) {
     if (typeof m !== "object" || m === null) return false;
@@ -232,6 +260,54 @@ function bridgeRuntime(g, makeFetch, config) {
     }
   }
   g.addEventListener("message", onMessage);
+  function isPersisted(ev) {
+    try {
+      if (readPersisted) return readPersisted(ev) === true;
+      if (typeof ev !== "object" || ev === null) return false;
+      const desc = ownDescriptor(ev, "persisted");
+      return !!desc && hasOwn(desc, "value") && desc.value === true;
+    } catch {
+      return false;
+    }
+  }
+  function onPageHide(ev) {
+    if (unloaded || isPersisted(ev)) return;
+    unloaded = true;
+    closed = true;
+    if (sendToHost) {
+      try {
+        sendToHost(
+          {
+            v: 1,
+            ns: NS,
+            id: idPrefix + "-unload",
+            kind: "evt",
+            type: "frame-unload",
+            payload: { session },
+            frame: frameToken
+          },
+          hostOrigin
+        );
+      } catch {
+      }
+    }
+    try {
+      stopInterval(readyTimer);
+    } catch {
+    }
+    try {
+      pending.forEach(function(entry) {
+        try {
+          stopTimeout(entry.timer);
+          entry.reject(codeError("UNSUPPORTED", "bridge closed"));
+        } catch {
+        }
+      });
+      pending.clear();
+    } catch {
+    }
+  }
+  g.addEventListener("pagehide", onPageHide, true);
   let readyAttempts = 0;
   function sendReady() {
     readyAttempts += 1;
@@ -245,6 +321,10 @@ function bridgeRuntime(g, makeFetch, config) {
   sendReady();
   function request(type, payload) {
     return new Promise(function(resolve, reject) {
+      if (closed) {
+        reject(codeError("UNSUPPORTED", "bridge closed"));
+        return;
+      }
       const id = nextId();
       const timer = setTimeout(function() {
         pending.delete(id);

package/dist/frame.d.cts

@@ -1,4 +1,4 @@
-import { g as BridgeInit, j as BridgeRequestType, i as BridgeRequestMap, e as BridgeEventMap } from './messages-9N0GFq5b.cjs';
+import { g as BridgeInit, j as BridgeRequestType, i as BridgeRequestMap, e as BridgeEventMap } from './messages-CRGnyf-6.cjs';
 
 /** 프레임 런타임 설정 — srcdoc 부트스트랩이 상수로 넘긴다. */
 interface BridgeClientConfig {
@@ -28,14 +28,18 @@ interface RuntimeGlobal {
     parent: {
         postMessage(message: unknown, targetOrigin: string): void;
     } | null;
-    addEventListener(type: 'message', fn: (ev: {
-        source: unknown;
-        origin: string;
-        data: unknown;
-    }) => void): void;
+    /**
+     * `message`(호스트 응답·이벤트)와 `pagehide`(frame-unload 전송, capture)에 쓴다.
+     * 처리기 인자 모양은 type마다 다르다 — message는 `{ source, origin, data }`, pagehide는 `{ persisted }`.
+     */
+    addEventListener(type: 'message' | 'pagehide', fn: (ev: never) => void, capture?: boolean): void;
     crypto?: {
         getRandomValues<T extends ArrayBufferView | null>(array: T): T;
     };
+    /** pagehide 이벤트 생성자 — `persisted` 원본 접근자를 부트스트랩 때 잡는 데 쓴다(없으면 이벤트 속성을 읽는다). */
+    PageTransitionEvent?: {
+        readonly prototype: object;
+    };
     __bstage_bridge__?: BridgeClient;
 }
 /** `createBridgeFetch`가 요구하는 클라이언트 부분. */

package/dist/frame.d.ts

@@ -1,4 +1,4 @@
-import { g as BridgeInit, j as BridgeRequestType, i as BridgeRequestMap, e as BridgeEventMap } from './messages-9N0GFq5b.js';
+import { g as BridgeInit, j as BridgeRequestType, i as BridgeRequestMap, e as BridgeEventMap } from './messages-CRGnyf-6.js';
 
 /** 프레임 런타임 설정 — srcdoc 부트스트랩이 상수로 넘긴다. */
 interface BridgeClientConfig {
@@ -28,14 +28,18 @@ interface RuntimeGlobal {
     parent: {
         postMessage(message: unknown, targetOrigin: string): void;
     } | null;
-    addEventListener(type: 'message', fn: (ev: {
-        source: unknown;
-        origin: string;
-        data: unknown;
-    }) => void): void;
+    /**
+     * `message`(호스트 응답·이벤트)와 `pagehide`(frame-unload 전송, capture)에 쓴다.
+     * 처리기 인자 모양은 type마다 다르다 — message는 `{ source, origin, data }`, pagehide는 `{ persisted }`.
+     */
+    addEventListener(type: 'message' | 'pagehide', fn: (ev: never) => void, capture?: boolean): void;
     crypto?: {
         getRandomValues<T extends ArrayBufferView | null>(array: T): T;
     };
+    /** pagehide 이벤트 생성자 — `persisted` 원본 접근자를 부트스트랩 때 잡는 데 쓴다(없으면 이벤트 속성을 읽는다). */
+    PageTransitionEvent?: {
+        readonly prototype: object;
+    };
     __bstage_bridge__?: BridgeClient;
 }
 /** `createBridgeFetch`가 요구하는 클라이언트 부분. */

package/dist/frame.js

@@ -1,7 +1,7 @@
 import {
   bridgeRuntime,
   createBridgeFetch
-} from "./chunk-KQMJY4ZH.js";
+} from "./chunk-N3JID7KQ.js";
 
 // src/frame/createBridgeClient.ts
 var BRIDGE_CONFIG_GLOBAL = "__bstage_bridge_config__";

package/dist/host.cjs

@@ -107,6 +107,7 @@ var REQUEST_TYPES = [
 var HOST_EVENT_TYPES = ["slot.context", "locale", "member", "theme", "visibility"];
 var READY_EVENT = "ready";
 var INIT_RESPONSE = "init";
+var FRAME_UNLOAD_EVENT = "frame-unload";
 var BRIDGE_SURFACES = ["page", "slot"];
 function isBridgeSurface(value) {
   return BRIDGE_SURFACES.includes(value);
@@ -844,6 +845,9 @@ function assertOptions(options) {
       "[bstage-bridge] externalFetchImpl\uC5D0 partnerFetchImpl(\uD32C \uD1A0\uD070 fetch)\uC744 \uC4F8 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4"
     );
   }
+  if (options.onDispose !== void 0 && typeof options.onDispose !== "function") {
+    throw new TypeError("[bstage-bridge] onDispose\uB294 \uD568\uC218\uC5EC\uC57C \uD569\uB2C8\uB2E4");
+  }
   if (!options.iframe || !options.init) {
     throw new TypeError("[bstage-bridge] iframe\xB7init\uC774 \uD544\uC694\uD569\uB2C8\uB2E4");
   }
@@ -866,6 +870,8 @@ function createBridgeHost(options) {
   let current = buildInit(options.init, hostOrigin, partnerOrigins, policy);
   let inFlightFetches = 0;
   let disposed = false;
+  let boundFrame;
+  let pendingVisibility;
   let resizeHandle;
   let pendingHeight;
   const raf = typeof win.requestAnimationFrame === "function" ? (cb) => win.requestAnimationFrame(cb) : (cb) => setTimeout(cb, 16);
@@ -929,13 +935,44 @@ function createBridgeHost(options) {
     const env = ev.data;
     if (!isBridgeEnvelope(env)) return;
     if (!hasSession(env.payload, session)) return;
+    const token = env.frame;
+    if (!isValidSession(token) || boundFrame !== void 0 && token !== boundFrame) {
+      dispose("frame-mismatch");
+      return;
+    }
+    boundFrame = token;
+    if (env.kind === "evt" && env.type === FRAME_UNLOAD_EVENT) {
+      dispose("frame-unload");
+      return;
+    }
     if (env.kind === "evt" && env.type === READY_EVENT) {
       if (!readyLimiter.take()) return;
       post(frame, createEnvelope("res", INIT_RESPONSE, env.id, { ok: true, data: current }));
+      flushPendingVisibility(frame);
       return;
     }
+    flushPendingVisibility(frame);
     if (env.kind === "req") void handleRequest(frame, env);
   }
+  function flushPendingVisibility(frame) {
+    if (pendingVisibility === void 0) return;
+    const payload = pendingVisibility;
+    pendingVisibility = void 0;
+    post(frame, createEnvelope("evt", "visibility", createSession(), payload));
+  }
+  function dispose(reason) {
+    if (disposed) return;
+    disposed = true;
+    win.removeEventListener("message", onMessage);
+    if (resizeHandle !== void 0) cancelRaf(resizeHandle);
+    resizeHandle = void 0;
+    if (options.onDispose) {
+      try {
+        options.onDispose(reason);
+      } catch {
+      }
+    }
+  }
   win.addEventListener("message", onMessage);
   return {
     send(type, payload) {
@@ -946,15 +983,15 @@ function createBridgeHost(options) {
       }
       const clean = sanitizeEvent(type, payload);
       current = applyEvent(current, type, clean);
+      if (boundFrame === void 0) {
+        if (type === "visibility") pendingVisibility = clean;
+        return;
+      }
       const frame = iframe.contentWindow;
       if (frame) post(frame, createEnvelope("evt", type, createSession(), clean));
     },
     dispose() {
-      if (disposed) return;
-      disposed = true;
-      win.removeEventListener("message", onMessage);
-      if (resizeHandle !== void 0) cancelRaf(resizeHandle);
-      resizeHandle = void 0;
+      dispose("manual");
     }
   };
 }
@@ -972,6 +1009,20 @@ function bridgeRuntime(g, makeFetch, config) {
   const session = config.session;
   const hostOrigin = config.hostOrigin;
   const parent = g.parent;
+  const sendToHost = parent ? parent.postMessage.bind(parent) : void 0;
+  const stopInterval = clearInterval;
+  const stopTimeout = clearTimeout;
+  let readPersisted;
+  const ownDescriptor = Object.getOwnPropertyDescriptor;
+  const hasOwn = Function.prototype.call.bind(Object.prototype.hasOwnProperty);
+  try {
+    const pte = g.PageTransitionEvent;
+    const desc = pte ? Object.getOwnPropertyDescriptor(pte.prototype, "persisted") : void 0;
+    if (desc && typeof desc.get === "function")
+      readPersisted = Function.prototype.call.bind(desc.get);
+  } catch {
+    readPersisted = void 0;
+  }
   const pending = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Map();
   let init;
@@ -988,6 +1039,17 @@ function bridgeRuntime(g, makeFetch, config) {
     return out;
   }
   const idPrefix = randomPrefix();
+  function secureToken() {
+    if (!g.crypto || typeof g.crypto.getRandomValues !== "function") return "";
+    const bytes = new Uint8Array(16);
+    g.crypto.getRandomValues(bytes);
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 1) out += (bytes[i] + 256).toString(16).slice(1);
+    return out;
+  }
+  const frameToken = secureToken();
+  let closed = frameToken === "";
+  let unloaded = false;
   function nextId() {
     seq += 1;
     return idPrefix + "-" + seq;
@@ -999,9 +1061,12 @@ function bridgeRuntime(g, makeFetch, config) {
     return err;
   }
   function post(kind, type, id, payload) {
-    if (!parent) return;
+    if (!sendToHost || closed) return;
     const body = Object.assign({}, payload, { session });
-    parent.postMessage({ v: 1, ns: NS, id, kind, type, payload: body }, hostOrigin);
+    sendToHost(
+      { v: 1, ns: NS, id, kind, type, payload: body, frame: frameToken },
+      hostOrigin
+    );
   }
   function isEnvelope(m) {
     if (typeof m !== "object" || m === null) return false;
@@ -1074,6 +1139,54 @@ function bridgeRuntime(g, makeFetch, config) {
     }
   }
   g.addEventListener("message", onMessage);
+  function isPersisted(ev) {
+    try {
+      if (readPersisted) return readPersisted(ev) === true;
+      if (typeof ev !== "object" || ev === null) return false;
+      const desc = ownDescriptor(ev, "persisted");
+      return !!desc && hasOwn(desc, "value") && desc.value === true;
+    } catch {
+      return false;
+    }
+  }
+  function onPageHide(ev) {
+    if (unloaded || isPersisted(ev)) return;
+    unloaded = true;
+    closed = true;
+    if (sendToHost) {
+      try {
+        sendToHost(
+          {
+            v: 1,
+            ns: NS,
+            id: idPrefix + "-unload",
+            kind: "evt",
+            type: "frame-unload",
+            payload: { session },
+            frame: frameToken
+          },
+          hostOrigin
+        );
+      } catch {
+      }
+    }
+    try {
+      stopInterval(readyTimer);
+    } catch {
+    }
+    try {
+      pending.forEach(function(entry) {
+        try {
+          stopTimeout(entry.timer);
+          entry.reject(codeError("UNSUPPORTED", "bridge closed"));
+        } catch {
+        }
+      });
+      pending.clear();
+    } catch {
+    }
+  }
+  g.addEventListener("pagehide", onPageHide, true);
   let readyAttempts = 0;
   function sendReady() {
     readyAttempts += 1;
@@ -1087,6 +1200,10 @@ function bridgeRuntime(g, makeFetch, config) {
   sendReady();
   function request(type, payload) {
     return new Promise(function(resolve, reject) {
+      if (closed) {
+        reject(codeError("UNSUPPORTED", "bridge closed"));
+        return;
+      }
       const id = nextId();
       const timer = setTimeout(function() {
         pending.delete(id);

package/dist/host.d.cts

@@ -1,5 +1,5 @@
-import { f as BridgeHostEventType, e as BridgeEventMap, s as ToastKind, L as LogLevel, l as BridgeSurface, T as ThemeState, S as SlotState, M as MemberState, m as BridgeTranslations } from './messages-9N0GFq5b.cjs';
-export { a as BRIDGE_SURFACES, I as IFRAME_ATTRIBUTES, v as isBridgeSurface } from './messages-9N0GFq5b.cjs';
+import { f as BridgeHostEventType, e as BridgeEventMap, t as ToastKind, L as LogLevel, l as BridgeSurface, T as ThemeState, S as SlotState, M as MemberState, m as BridgeTranslations } from './messages-CRGnyf-6.cjs';
+export { a as BRIDGE_SURFACES, I as IFRAME_ATTRIBUTES, w as isBridgeSurface } from './messages-CRGnyf-6.cjs';
 export { C as CreateSrcdocOptions, c as createNonce, d as createSession, e as createSrcdoc, f as isValidSession } from './createSrcdoc-bOoxttPz.cjs';
 
 /** 호스트 fetch 정책. */
@@ -213,11 +213,25 @@ interface CreateBridgeHostOptions {
     readonly pinnedHeaders?: Readonly<Record<string, string>>;
     readonly handlers?: BridgeHostHandlers;
     readonly policy?: Partial<BridgePolicy>;
+    /**
+     * 호스트가 dispose될 때 한 번 불린다. `frame-unload`(프레임 문서가 내려감)·`frame-mismatch`(토큰이 없거나 다른
+     * 메시지 = 같은 창의 다른 문서)는 호스트가 스스로 끊은 경우, `manual`은 `dispose()` 호출이다. 임베더가 iframe을
+     * 바로 걷어 내는 데 쓴다. 이 콜백의 예외는 삼킨다.
+     */
+    readonly onDispose?: (reason: BridgeDisposeReason) => void;
 }
+/** `onDispose` 사유. */
+type BridgeDisposeReason = 'frame-unload' | 'frame-mismatch' | 'manual';
 interface BridgeHost {
-    /** 프레임에 이벤트를 보낸다. 이후 ready에 답하는 init에도 반영된다. */
+    /**
+     * 프레임에 이벤트를 보낸다. 이후 ready에 답하는 init에도 반영된다.
+     * 프레임 토큰이 묶이기(첫 유효 메시지) 전에는 보내지 않고 init에만 반영한다.
+     */
     send<E extends BridgeHostEventType>(type: E, payload: BridgeEventMap[E]): void;
-    /** 리스너·대기 중인 resize를 정리한다. 이후 메시지는 무시된다. */
+    /**
+     * 리스너·대기 중인 resize를 정리한다. 이후 메시지는 무시되고, 진행 중이던 요청의 응답도 프레임에 보내지 않는다.
+     * 프레임이 `frame-unload`를 보내거나 다른 프레임 토큰이 오면 호스트가 스스로 부른다.
+     */
     dispose(): void;
 }
 
@@ -226,7 +240,11 @@ interface BridgeHost {
  *
  * - 발신자 확인: `ev.source === iframe.contentWindow`, origin `"null"`(sandbox 프레임), 봉투 형식,
  *   `payload.session === session`이 모두 맞는 메시지만 처리한다.
- * - `evt:ready`에 `res:init`으로 답한다(프레임이 재전송하면 매번 최신 init으로).
+ * - 세션당 프레임 문서는 하나다: 처음 받은 유효 메시지의 프레임 토큰(`env.frame`)에 세션을 묶고, 토큰이 없거나
+ *   다른 메시지(= 같은 contentWindow에 새로 뜬 문서, 예: 템플릿의 자기 내비게이션)가 오면 즉시 dispose한다.
+ *   그래서 두 번째 핸드셰이크는 성립하지 않는다.
+ * - `evt:frame-unload`(부트스트랩이 pagehide에서 보낸다)를 받으면 즉시 dispose한다.
+ * - `evt:ready`에 `res:init`으로 답한다(같은 토큰의 재전송이면 매번 최신 init으로).
  * - 요청은 fetch 정책(policy.ts)·요청별 상한(validators.ts)을 적용해 처리기 또는 주입 `fetchImpl`로 넘긴다.
  *
  * 토큰은 이 함수가 다루지 않는다 — 인증은 `fetchImpl`(플랫폼의 인증 fetch)이 호스트 쪽에서 붙이고,
@@ -259,4 +277,4 @@ interface PathCheck {
  */
 declare function checkPath(pathname: string, options?: PathCheckOptions): PathCheck;
 
-export { ALLOWED_METHODS, ALLOWED_REQUEST_HEADERS, type BridgeHost, type BridgeHostHandlers, type BridgeInitInput, type BridgePolicy, BridgeSurface, type CreateBridgeHostOptions, DEFAULT_GATEWAY_DENY_SEGMENTS, DEFAULT_POLICY, type Destination, type DestinationContext, type DestinationKind, type FrameWindow, HOST_ONLY_HEADERS, type HostFetch, type HostWindow, type IframeLike, MAX_DECODE_PASSES, MAX_PARTNER_ORIGINS, type MessageEventLike, type PathCheck, type PathCheckOptions, type PreparedFetch, checkPath, classifyDestination, createBridgeHost, isAllowedGatewayPath, normalizePartnerOrigins, normalizePinnedHeaders, prepareFetch, resolveDestination, resolvePolicy };
+export { ALLOWED_METHODS, ALLOWED_REQUEST_HEADERS, type BridgeDisposeReason, type BridgeHost, type BridgeHostHandlers, type BridgeInitInput, type BridgePolicy, BridgeSurface, type CreateBridgeHostOptions, DEFAULT_GATEWAY_DENY_SEGMENTS, DEFAULT_POLICY, type Destination, type DestinationContext, type DestinationKind, type FrameWindow, HOST_ONLY_HEADERS, type HostFetch, type HostWindow, type IframeLike, MAX_DECODE_PASSES, MAX_PARTNER_ORIGINS, type MessageEventLike, type PathCheck, type PathCheckOptions, type PreparedFetch, checkPath, classifyDestination, createBridgeHost, isAllowedGatewayPath, normalizePartnerOrigins, normalizePinnedHeaders, prepareFetch, resolveDestination, resolvePolicy };

package/dist/host.d.ts

@@ -1,5 +1,5 @@
-import { f as BridgeHostEventType, e as BridgeEventMap, s as ToastKind, L as LogLevel, l as BridgeSurface, T as ThemeState, S as SlotState, M as MemberState, m as BridgeTranslations } from './messages-9N0GFq5b.js';
-export { a as BRIDGE_SURFACES, I as IFRAME_ATTRIBUTES, v as isBridgeSurface } from './messages-9N0GFq5b.js';
+import { f as BridgeHostEventType, e as BridgeEventMap, t as ToastKind, L as LogLevel, l as BridgeSurface, T as ThemeState, S as SlotState, M as MemberState, m as BridgeTranslations } from './messages-CRGnyf-6.js';
+export { a as BRIDGE_SURFACES, I as IFRAME_ATTRIBUTES, w as isBridgeSurface } from './messages-CRGnyf-6.js';
 export { C as CreateSrcdocOptions, c as createNonce, d as createSession, e as createSrcdoc, f as isValidSession } from './createSrcdoc-bOoxttPz.js';
 
 /** 호스트 fetch 정책. */
@@ -213,11 +213,25 @@ interface CreateBridgeHostOptions {
     readonly pinnedHeaders?: Readonly<Record<string, string>>;
     readonly handlers?: BridgeHostHandlers;
     readonly policy?: Partial<BridgePolicy>;
+    /**
+     * 호스트가 dispose될 때 한 번 불린다. `frame-unload`(프레임 문서가 내려감)·`frame-mismatch`(토큰이 없거나 다른
+     * 메시지 = 같은 창의 다른 문서)는 호스트가 스스로 끊은 경우, `manual`은 `dispose()` 호출이다. 임베더가 iframe을
+     * 바로 걷어 내는 데 쓴다. 이 콜백의 예외는 삼킨다.
+     */
+    readonly onDispose?: (reason: BridgeDisposeReason) => void;
 }
+/** `onDispose` 사유. */
+type BridgeDisposeReason = 'frame-unload' | 'frame-mismatch' | 'manual';
 interface BridgeHost {
-    /** 프레임에 이벤트를 보낸다. 이후 ready에 답하는 init에도 반영된다. */
+    /**
+     * 프레임에 이벤트를 보낸다. 이후 ready에 답하는 init에도 반영된다.
+     * 프레임 토큰이 묶이기(첫 유효 메시지) 전에는 보내지 않고 init에만 반영한다.
+     */
     send<E extends BridgeHostEventType>(type: E, payload: BridgeEventMap[E]): void;
-    /** 리스너·대기 중인 resize를 정리한다. 이후 메시지는 무시된다. */
+    /**
+     * 리스너·대기 중인 resize를 정리한다. 이후 메시지는 무시되고, 진행 중이던 요청의 응답도 프레임에 보내지 않는다.
+     * 프레임이 `frame-unload`를 보내거나 다른 프레임 토큰이 오면 호스트가 스스로 부른다.
+     */
     dispose(): void;
 }
 
@@ -226,7 +240,11 @@ interface BridgeHost {
  *
  * - 발신자 확인: `ev.source === iframe.contentWindow`, origin `"null"`(sandbox 프레임), 봉투 형식,
  *   `payload.session === session`이 모두 맞는 메시지만 처리한다.
- * - `evt:ready`에 `res:init`으로 답한다(프레임이 재전송하면 매번 최신 init으로).
+ * - 세션당 프레임 문서는 하나다: 처음 받은 유효 메시지의 프레임 토큰(`env.frame`)에 세션을 묶고, 토큰이 없거나
+ *   다른 메시지(= 같은 contentWindow에 새로 뜬 문서, 예: 템플릿의 자기 내비게이션)가 오면 즉시 dispose한다.
+ *   그래서 두 번째 핸드셰이크는 성립하지 않는다.
+ * - `evt:frame-unload`(부트스트랩이 pagehide에서 보낸다)를 받으면 즉시 dispose한다.
+ * - `evt:ready`에 `res:init`으로 답한다(같은 토큰의 재전송이면 매번 최신 init으로).
  * - 요청은 fetch 정책(policy.ts)·요청별 상한(validators.ts)을 적용해 처리기 또는 주입 `fetchImpl`로 넘긴다.
  *
  * 토큰은 이 함수가 다루지 않는다 — 인증은 `fetchImpl`(플랫폼의 인증 fetch)이 호스트 쪽에서 붙이고,
@@ -259,4 +277,4 @@ interface PathCheck {
  */
 declare function checkPath(pathname: string, options?: PathCheckOptions): PathCheck;
 
-export { ALLOWED_METHODS, ALLOWED_REQUEST_HEADERS, type BridgeHost, type BridgeHostHandlers, type BridgeInitInput, type BridgePolicy, BridgeSurface, type CreateBridgeHostOptions, DEFAULT_GATEWAY_DENY_SEGMENTS, DEFAULT_POLICY, type Destination, type DestinationContext, type DestinationKind, type FrameWindow, HOST_ONLY_HEADERS, type HostFetch, type HostWindow, type IframeLike, MAX_DECODE_PASSES, MAX_PARTNER_ORIGINS, type MessageEventLike, type PathCheck, type PathCheckOptions, type PreparedFetch, checkPath, classifyDestination, createBridgeHost, isAllowedGatewayPath, normalizePartnerOrigins, normalizePinnedHeaders, prepareFetch, resolveDestination, resolvePolicy };
+export { ALLOWED_METHODS, ALLOWED_REQUEST_HEADERS, type BridgeDisposeReason, type BridgeHost, type BridgeHostHandlers, type BridgeInitInput, type BridgePolicy, BridgeSurface, type CreateBridgeHostOptions, DEFAULT_GATEWAY_DENY_SEGMENTS, DEFAULT_POLICY, type Destination, type DestinationContext, type DestinationKind, type FrameWindow, HOST_ONLY_HEADERS, type HostFetch, type HostWindow, type IframeLike, MAX_DECODE_PASSES, MAX_PARTNER_ORIGINS, type MessageEventLike, type PathCheck, type PathCheckOptions, type PreparedFetch, checkPath, classifyDestination, createBridgeHost, isAllowedGatewayPath, normalizePartnerOrigins, normalizePinnedHeaders, prepareFetch, resolveDestination, resolvePolicy };

package/dist/host.js

@@ -5,6 +5,7 @@ import {
   BridgeError,
   DEFAULT_GATEWAY_DENY_SEGMENTS,
   DEFAULT_POLICY,
+  FRAME_UNLOAD_EVENT,
   HOST_ONLY_HEADERS,
   IFRAME_ATTRIBUTES,
   INIT_RESPONSE,
@@ -31,8 +32,8 @@ import {
   prepareFetch,
   resolveDestination,
   resolvePolicy
-} from "./chunk-6LV7HEN4.js";
-import "./chunk-KQMJY4ZH.js";
+} from "./chunk-JH3A3Z2A.js";
+import "./chunk-N3JID7KQ.js";
 
 // src/host/rateLimiter.ts
 var DEFAULT_WINDOW_MS = 6e4;
@@ -453,6 +454,9 @@ function assertOptions(options) {
       "[bstage-bridge] externalFetchImpl\uC5D0 partnerFetchImpl(\uD32C \uD1A0\uD070 fetch)\uC744 \uC4F8 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4"
     );
   }
+  if (options.onDispose !== void 0 && typeof options.onDispose !== "function") {
+    throw new TypeError("[bstage-bridge] onDispose\uB294 \uD568\uC218\uC5EC\uC57C \uD569\uB2C8\uB2E4");
+  }
   if (!options.iframe || !options.init) {
     throw new TypeError("[bstage-bridge] iframe\xB7init\uC774 \uD544\uC694\uD569\uB2C8\uB2E4");
   }
@@ -475,6 +479,8 @@ function createBridgeHost(options) {
   let current = buildInit(options.init, hostOrigin, partnerOrigins, policy);
   let inFlightFetches = 0;
   let disposed = false;
+  let boundFrame;
+  let pendingVisibility;
   let resizeHandle;
   let pendingHeight;
   const raf = typeof win.requestAnimationFrame === "function" ? (cb) => win.requestAnimationFrame(cb) : (cb) => setTimeout(cb, 16);
@@ -538,13 +544,44 @@ function createBridgeHost(options) {
     const env = ev.data;
     if (!isBridgeEnvelope(env)) return;
     if (!hasSession(env.payload, session)) return;
+    const token = env.frame;
+    if (!isValidSession(token) || boundFrame !== void 0 && token !== boundFrame) {
+      dispose("frame-mismatch");
+      return;
+    }
+    boundFrame = token;
+    if (env.kind === "evt" && env.type === FRAME_UNLOAD_EVENT) {
+      dispose("frame-unload");
+      return;
+    }
     if (env.kind === "evt" && env.type === READY_EVENT) {
       if (!readyLimiter.take()) return;
       post(frame, createEnvelope("res", INIT_RESPONSE, env.id, { ok: true, data: current }));
+      flushPendingVisibility(frame);
       return;
     }
+    flushPendingVisibility(frame);
     if (env.kind === "req") void handleRequest(frame, env);
   }
+  function flushPendingVisibility(frame) {
+    if (pendingVisibility === void 0) return;
+    const payload = pendingVisibility;
+    pendingVisibility = void 0;
+    post(frame, createEnvelope("evt", "visibility", createSession(), payload));
+  }
+  function dispose(reason) {
+    if (disposed) return;
+    disposed = true;
+    win.removeEventListener("message", onMessage);
+    if (resizeHandle !== void 0) cancelRaf(resizeHandle);
+    resizeHandle = void 0;
+    if (options.onDispose) {
+      try {
+        options.onDispose(reason);
+      } catch {
+      }
+    }
+  }
   win.addEventListener("message", onMessage);
   return {
     send(type, payload) {
@@ -555,15 +592,15 @@ function createBridgeHost(options) {
       }
       const clean = sanitizeEvent(type, payload);
       current = applyEvent(current, type, clean);
+      if (boundFrame === void 0) {
+        if (type === "visibility") pendingVisibility = clean;
+        return;
+      }
       const frame = iframe.contentWindow;
       if (frame) post(frame, createEnvelope("evt", type, createSession(), clean));
     },
     dispose() {
-      if (disposed) return;
-      disposed = true;
-      win.removeEventListener("message", onMessage);
-      if (resizeHandle !== void 0) cancelRaf(resizeHandle);
-      resizeHandle = void 0;
+      dispose("manual");
     }
   };
 }

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(src_exports, {
   BRIDGE_SURFACES: () => BRIDGE_SURFACES,
   BRIDGE_VERSION: () => BRIDGE_VERSION,
   BridgeError: () => BridgeError,
+  FRAME_UNLOAD_EVENT: () => FRAME_UNLOAD_EVENT,
   HOST_EVENT_TYPES: () => HOST_EVENT_TYPES,
   IFRAME_ATTRIBUTES: () => IFRAME_ATTRIBUTES,
   INIT_RESPONSE: () => INIT_RESPONSE,
@@ -114,6 +115,7 @@ var REQUEST_TYPES = [
 var HOST_EVENT_TYPES = ["slot.context", "locale", "member", "theme", "visibility"];
 var READY_EVENT = "ready";
 var INIT_RESPONSE = "init";
+var FRAME_UNLOAD_EVENT = "frame-unload";
 var BRIDGE_SURFACES = ["page", "slot"];
 function isBridgeSurface(value) {
   return BRIDGE_SURFACES.includes(value);
@@ -165,6 +167,20 @@ function bridgeRuntime(g, makeFetch, config) {
   const session = config.session;
   const hostOrigin = config.hostOrigin;
   const parent = g.parent;
+  const sendToHost = parent ? parent.postMessage.bind(parent) : void 0;
+  const stopInterval = clearInterval;
+  const stopTimeout = clearTimeout;
+  let readPersisted;
+  const ownDescriptor = Object.getOwnPropertyDescriptor;
+  const hasOwn = Function.prototype.call.bind(Object.prototype.hasOwnProperty);
+  try {
+    const pte = g.PageTransitionEvent;
+    const desc = pte ? Object.getOwnPropertyDescriptor(pte.prototype, "persisted") : void 0;
+    if (desc && typeof desc.get === "function")
+      readPersisted = Function.prototype.call.bind(desc.get);
+  } catch {
+    readPersisted = void 0;
+  }
   const pending = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Map();
   let init;
@@ -181,6 +197,17 @@ function bridgeRuntime(g, makeFetch, config) {
     return out;
   }
   const idPrefix = randomPrefix();
+  function secureToken() {
+    if (!g.crypto || typeof g.crypto.getRandomValues !== "function") return "";
+    const bytes = new Uint8Array(16);
+    g.crypto.getRandomValues(bytes);
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 1) out += (bytes[i] + 256).toString(16).slice(1);
+    return out;
+  }
+  const frameToken = secureToken();
+  let closed = frameToken === "";
+  let unloaded = false;
   function nextId() {
     seq += 1;
     return idPrefix + "-" + seq;
@@ -192,9 +219,12 @@ function bridgeRuntime(g, makeFetch, config) {
     return err;
   }
   function post(kind, type, id, payload) {
-    if (!parent) return;
+    if (!sendToHost || closed) return;
     const body = Object.assign({}, payload, { session });
-    parent.postMessage({ v: 1, ns: NS, id, kind, type, payload: body }, hostOrigin);
+    sendToHost(
+      { v: 1, ns: NS, id, kind, type, payload: body, frame: frameToken },
+      hostOrigin
+    );
   }
   function isEnvelope(m) {
     if (typeof m !== "object" || m === null) return false;
@@ -267,6 +297,54 @@ function bridgeRuntime(g, makeFetch, config) {
     }
   }
   g.addEventListener("message", onMessage);
+  function isPersisted(ev) {
+    try {
+      if (readPersisted) return readPersisted(ev) === true;
+      if (typeof ev !== "object" || ev === null) return false;
+      const desc = ownDescriptor(ev, "persisted");
+      return !!desc && hasOwn(desc, "value") && desc.value === true;
+    } catch {
+      return false;
+    }
+  }
+  function onPageHide(ev) {
+    if (unloaded || isPersisted(ev)) return;
+    unloaded = true;
+    closed = true;
+    if (sendToHost) {
+      try {
+        sendToHost(
+          {
+            v: 1,
+            ns: NS,
+            id: idPrefix + "-unload",
+            kind: "evt",
+            type: "frame-unload",
+            payload: { session },
+            frame: frameToken
+          },
+          hostOrigin
+        );
+      } catch {
+      }
+    }
+    try {
+      stopInterval(readyTimer);
+    } catch {
+    }
+    try {
+      pending.forEach(function(entry) {
+        try {
+          stopTimeout(entry.timer);
+          entry.reject(codeError("UNSUPPORTED", "bridge closed"));
+        } catch {
+        }
+      });
+      pending.clear();
+    } catch {
+    }
+  }
+  g.addEventListener("pagehide", onPageHide, true);
   let readyAttempts = 0;
   function sendReady() {
     readyAttempts += 1;
@@ -280,6 +358,10 @@ function bridgeRuntime(g, makeFetch, config) {
   sendReady();
   function request(type, payload) {
     return new Promise(function(resolve, reject) {
+      if (closed) {
+        reject(codeError("UNSUPPORTED", "bridge closed"));
+        return;
+      }
       const id = nextId();
       const timer = setTimeout(function() {
         pending.delete(id);
@@ -646,6 +728,7 @@ ${script}
   BRIDGE_SURFACES,
   BRIDGE_VERSION,
   BridgeError,
+  FRAME_UNLOAD_EVENT,
   HOST_EVENT_TYPES,
   IFRAME_ATTRIBUTES,
   INIT_RESPONSE,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export { B as BRIDGE_ERROR_CODES, a as BRIDGE_SURFACES, b as BridgeError, c as BridgeErrorCode, d as BridgeErrorLike, e as BridgeEventMap, f as BridgeHostEventType, g as BridgeInit, h as BridgeLimits, i as BridgeRequestMap, j as BridgeRequestType, k as BridgeResult, l as BridgeSurface, m as BridgeTranslations, F as FetchRequest, n as FetchResult, H as HOST_EVENT_TYPES, I as IFRAME_ATTRIBUTES, o as INIT_RESPONSE, L as LogLevel, M as MemberState, R as READY_EVENT, p as REQUEST_TIMEOUT_MS, q as REQUEST_TYPES, S as SlotState, r as StorageOp, T as ThemeState, s as ToastKind, W as WithSession, t as isBridgeErrorCode, u as isBridgeErrorLike, v as isBridgeSurface, w as isHostEventType, x as isRequestType } from './messages-9N0GFq5b.cjs';
+export { B as BRIDGE_ERROR_CODES, a as BRIDGE_SURFACES, b as BridgeError, c as BridgeErrorCode, d as BridgeErrorLike, e as BridgeEventMap, f as BridgeHostEventType, g as BridgeInit, h as BridgeLimits, i as BridgeRequestMap, j as BridgeRequestType, k as BridgeResult, l as BridgeSurface, m as BridgeTranslations, F as FRAME_UNLOAD_EVENT, n as FetchRequest, o as FetchResult, H as HOST_EVENT_TYPES, I as IFRAME_ATTRIBUTES, p as INIT_RESPONSE, L as LogLevel, M as MemberState, R as READY_EVENT, q as REQUEST_TIMEOUT_MS, r as REQUEST_TYPES, S as SlotState, s as StorageOp, T as ThemeState, t as ToastKind, W as WithSession, u as isBridgeErrorCode, v as isBridgeErrorLike, w as isBridgeSurface, x as isHostEventType, y as isRequestType } from './messages-CRGnyf-6.cjs';
 export { C as CreateSrcdocOptions, M as MAX_ELEMENT_NAME_LENGTH, a as MAX_MEDIA_ORIGINS, b as buildFrameCsp, c as createNonce, d as createSession, e as createSrcdoc, i as isValidNonce, f as isValidSession } from './createSrcdoc-bOoxttPz.cjs';
 
 /** 봉투 버전. 형식이 하위 호환되지 않게 바뀔 때만 올린다. */
@@ -19,6 +19,11 @@ interface BridgeEnvelope<P = unknown> {
     readonly kind: EnvelopeKind;
     readonly type: string;
     readonly payload: P;
+    /**
+     * 프레임 → 호스트 봉투에만 붙는 프레임 토큰(소문자 hex 32자). 프레임 런타임이 문서마다 새로 만들고
+     * 호스트는 처음 본 값에 세션을 묶는다. 호스트 → 프레임 봉투에는 없다.
+     */
+    readonly frame?: string;
 }
 /**
  * 값이 브리지 봉투인지 검사한다. 모양만 본다 — 발신자 확인(source·session)은 호출자 몫이다.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { B as BRIDGE_ERROR_CODES, a as BRIDGE_SURFACES, b as BridgeError, c as BridgeErrorCode, d as BridgeErrorLike, e as BridgeEventMap, f as BridgeHostEventType, g as BridgeInit, h as BridgeLimits, i as BridgeRequestMap, j as BridgeRequestType, k as BridgeResult, l as BridgeSurface, m as BridgeTranslations, F as FetchRequest, n as FetchResult, H as HOST_EVENT_TYPES, I as IFRAME_ATTRIBUTES, o as INIT_RESPONSE, L as LogLevel, M as MemberState, R as READY_EVENT, p as REQUEST_TIMEOUT_MS, q as REQUEST_TYPES, S as SlotState, r as StorageOp, T as ThemeState, s as ToastKind, W as WithSession, t as isBridgeErrorCode, u as isBridgeErrorLike, v as isBridgeSurface, w as isHostEventType, x as isRequestType } from './messages-9N0GFq5b.js';
+export { B as BRIDGE_ERROR_CODES, a as BRIDGE_SURFACES, b as BridgeError, c as BridgeErrorCode, d as BridgeErrorLike, e as BridgeEventMap, f as BridgeHostEventType, g as BridgeInit, h as BridgeLimits, i as BridgeRequestMap, j as BridgeRequestType, k as BridgeResult, l as BridgeSurface, m as BridgeTranslations, F as FRAME_UNLOAD_EVENT, n as FetchRequest, o as FetchResult, H as HOST_EVENT_TYPES, I as IFRAME_ATTRIBUTES, p as INIT_RESPONSE, L as LogLevel, M as MemberState, R as READY_EVENT, q as REQUEST_TIMEOUT_MS, r as REQUEST_TYPES, S as SlotState, s as StorageOp, T as ThemeState, t as ToastKind, W as WithSession, u as isBridgeErrorCode, v as isBridgeErrorLike, w as isBridgeSurface, x as isHostEventType, y as isRequestType } from './messages-CRGnyf-6.js';
 export { C as CreateSrcdocOptions, M as MAX_ELEMENT_NAME_LENGTH, a as MAX_MEDIA_ORIGINS, b as buildFrameCsp, c as createNonce, d as createSession, e as createSrcdoc, i as isValidNonce, f as isValidSession } from './createSrcdoc-bOoxttPz.js';
 
 /** 봉투 버전. 형식이 하위 호환되지 않게 바뀔 때만 올린다. */
@@ -19,6 +19,11 @@ interface BridgeEnvelope<P = unknown> {
     readonly kind: EnvelopeKind;
     readonly type: string;
     readonly payload: P;
+    /**
+     * 프레임 → 호스트 봉투에만 붙는 프레임 토큰(소문자 hex 32자). 프레임 런타임이 문서마다 새로 만들고
+     * 호스트는 처음 본 값에 세션을 묶는다. 호스트 → 프레임 봉투에는 없다.
+     */
+    readonly frame?: string;
 }
 /**
  * 값이 브리지 봉투인지 검사한다. 모양만 본다 — 발신자 확인(source·session)은 호출자 몫이다.

package/dist/index.js

@@ -4,6 +4,7 @@ import {
   BRIDGE_SURFACES,
   BRIDGE_VERSION,
   BridgeError,
+  FRAME_UNLOAD_EVENT,
   HOST_EVENT_TYPES,
   IFRAME_ATTRIBUTES,
   INIT_RESPONSE,
@@ -28,14 +29,15 @@ import {
   isRequestType,
   isValidNonce,
   isValidSession
-} from "./chunk-6LV7HEN4.js";
-import "./chunk-KQMJY4ZH.js";
+} from "./chunk-JH3A3Z2A.js";
+import "./chunk-N3JID7KQ.js";
 export {
   BRIDGE_ERROR_CODES,
   BRIDGE_NAMESPACE,
   BRIDGE_SURFACES,
   BRIDGE_VERSION,
   BridgeError,
+  FRAME_UNLOAD_EVENT,
   HOST_EVENT_TYPES,
   IFRAME_ATTRIBUTES,
   INIT_RESPONSE,

package/dist/{messages-9N0GFq5b.d.cts → messages-CRGnyf-6.d.cts}

@@ -28,6 +28,11 @@ type BridgeHostEventType = (typeof HOST_EVENT_TYPES)[number];
 declare const READY_EVENT = "ready";
 /** 호스트 → 프레임 핸드셰이크 응답 type. */
 declare const INIT_RESPONSE = "init";
+/**
+ * 프레임 → 호스트 종료 알림 이벤트. 부트스트랩이 `pagehide`(bfcache 제외)에서 동기로 보낸다.
+ * 호스트는 받는 즉시 세션을 끊는다(이후 메시지 무시).
+ */
+declare const FRAME_UNLOAD_EVENT = "frame-unload";
 /** 프레임이 보내는 모든 payload에 붙는 세션. */
 type WithSession<T> = T & {
     readonly session: string;
@@ -183,4 +188,4 @@ declare const IFRAME_ATTRIBUTES: {
 declare function isRequestType(value: unknown): value is BridgeRequestType;
 declare function isHostEventType(value: unknown): value is BridgeHostEventType;
 
-export { BRIDGE_ERROR_CODES as B, type FetchRequest as F, HOST_EVENT_TYPES as H, IFRAME_ATTRIBUTES as I, type LogLevel as L, type MemberState as M, READY_EVENT as R, type SlotState as S, type ThemeState as T, type WithSession as W, BRIDGE_SURFACES as a, BridgeError as b, type BridgeErrorCode as c, type BridgeErrorLike as d, type BridgeEventMap as e, type BridgeHostEventType as f, type BridgeInit as g, type BridgeLimits as h, type BridgeRequestMap as i, type BridgeRequestType as j, type BridgeResult as k, type BridgeSurface as l, type BridgeTranslations as m, type FetchResult as n, INIT_RESPONSE as o, REQUEST_TIMEOUT_MS as p, REQUEST_TYPES as q, type StorageOp as r, type ToastKind as s, isBridgeErrorCode as t, isBridgeErrorLike as u, isBridgeSurface as v, isHostEventType as w, isRequestType as x };
+export { BRIDGE_ERROR_CODES as B, FRAME_UNLOAD_EVENT as F, HOST_EVENT_TYPES as H, IFRAME_ATTRIBUTES as I, type LogLevel as L, type MemberState as M, READY_EVENT as R, type SlotState as S, type ThemeState as T, type WithSession as W, BRIDGE_SURFACES as a, BridgeError as b, type BridgeErrorCode as c, type BridgeErrorLike as d, type BridgeEventMap as e, type BridgeHostEventType as f, type BridgeInit as g, type BridgeLimits as h, type BridgeRequestMap as i, type BridgeRequestType as j, type BridgeResult as k, type BridgeSurface as l, type BridgeTranslations as m, type FetchRequest as n, type FetchResult as o, INIT_RESPONSE as p, REQUEST_TIMEOUT_MS as q, REQUEST_TYPES as r, type StorageOp as s, type ToastKind as t, isBridgeErrorCode as u, isBridgeErrorLike as v, isBridgeSurface as w, isHostEventType as x, isRequestType as y };

package/dist/{messages-9N0GFq5b.d.ts → messages-CRGnyf-6.d.ts}

@@ -28,6 +28,11 @@ type BridgeHostEventType = (typeof HOST_EVENT_TYPES)[number];
 declare const READY_EVENT = "ready";
 /** 호스트 → 프레임 핸드셰이크 응답 type. */
 declare const INIT_RESPONSE = "init";
+/**
+ * 프레임 → 호스트 종료 알림 이벤트. 부트스트랩이 `pagehide`(bfcache 제외)에서 동기로 보낸다.
+ * 호스트는 받는 즉시 세션을 끊는다(이후 메시지 무시).
+ */
+declare const FRAME_UNLOAD_EVENT = "frame-unload";
 /** 프레임이 보내는 모든 payload에 붙는 세션. */
 type WithSession<T> = T & {
     readonly session: string;
@@ -183,4 +188,4 @@ declare const IFRAME_ATTRIBUTES: {
 declare function isRequestType(value: unknown): value is BridgeRequestType;
 declare function isHostEventType(value: unknown): value is BridgeHostEventType;
 
-export { BRIDGE_ERROR_CODES as B, type FetchRequest as F, HOST_EVENT_TYPES as H, IFRAME_ATTRIBUTES as I, type LogLevel as L, type MemberState as M, READY_EVENT as R, type SlotState as S, type ThemeState as T, type WithSession as W, BRIDGE_SURFACES as a, BridgeError as b, type BridgeErrorCode as c, type BridgeErrorLike as d, type BridgeEventMap as e, type BridgeHostEventType as f, type BridgeInit as g, type BridgeLimits as h, type BridgeRequestMap as i, type BridgeRequestType as j, type BridgeResult as k, type BridgeSurface as l, type BridgeTranslations as m, type FetchResult as n, INIT_RESPONSE as o, REQUEST_TIMEOUT_MS as p, REQUEST_TYPES as q, type StorageOp as r, type ToastKind as s, isBridgeErrorCode as t, isBridgeErrorLike as u, isBridgeSurface as v, isHostEventType as w, isRequestType as x };
+export { BRIDGE_ERROR_CODES as B, FRAME_UNLOAD_EVENT as F, HOST_EVENT_TYPES as H, IFRAME_ATTRIBUTES as I, type LogLevel as L, type MemberState as M, READY_EVENT as R, type SlotState as S, type ThemeState as T, type WithSession as W, BRIDGE_SURFACES as a, BridgeError as b, type BridgeErrorCode as c, type BridgeErrorLike as d, type BridgeEventMap as e, type BridgeHostEventType as f, type BridgeInit as g, type BridgeLimits as h, type BridgeRequestMap as i, type BridgeRequestType as j, type BridgeResult as k, type BridgeSurface as l, type BridgeTranslations as m, type FetchRequest as n, type FetchResult as o, INIT_RESPONSE as p, REQUEST_TIMEOUT_MS as q, REQUEST_TYPES as r, type StorageOp as s, type ToastKind as t, isBridgeErrorCode as u, isBridgeErrorLike as v, isBridgeSurface as w, isHostEventType as x, isRequestType as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bstage-sdk/bridge",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "bstage SDK bridge — isolated template iframe protocol, host policy and frame client",
   "type": "module",
   "publishConfig": {