@bstage-sdk/bridge 0.9.1 → 0.11.0

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);
@@ -505,6 +506,7 @@ function buildInit(init, hostOrigin, partnerOrigins, policy) {
     spaceId: String(init.spaceId),
     hostOrigin,
     gatewayBase: `${hostOrigin}/gw`,
+    gatewayPrefixes: policy.gatewayPrefixes,
     locale: String(init.locale),
     theme: sanitizeTheme(init.theme),
     ...slot ? { slot } : {},
@@ -844,6 +846,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 +871,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 +936,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 +984,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 +1010,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 +1040,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 +1062,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 +1140,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 +1201,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);
@@ -1221,6 +1339,126 @@ function createBridgeFetch(client) {
   return bridgeFetch;
 }
 
+// src/frame/directFetch.ts
+function installDirectFetch(g, client, config) {
+  const hostOrigin = config.hostOrigin;
+  const callFn = Function.prototype.call;
+  const NativeURL = g.URL;
+  const rawFetch = g.fetch;
+  const nativeFetch = typeof rawFetch === "function" ? callFn.bind(rawFetch) : void 0;
+  const bridgeFetch = client.fetch;
+  const strSlice = callFn.bind(String.prototype.slice);
+  const promiseThen = callFn.bind(Promise.prototype.then);
+  const promiseReject = Promise.reject.bind(Promise);
+  const assign = Object.assign;
+  const TypeErr = TypeError;
+  function getter(ctor, name) {
+    if (typeof ctor !== "function") return void 0;
+    let proto = ctor.prototype;
+    while (proto) {
+      const desc = Object.getOwnPropertyDescriptor(proto, name);
+      if (desc && typeof desc.get === "function") {
+        return callFn.bind(desc.get);
+      }
+      proto = Object.getPrototypeOf(proto);
+    }
+    return void 0;
+  }
+  const getHref = getter(NativeURL, "href");
+  const getOrigin = getter(NativeURL, "origin");
+  const getProtocol = getter(NativeURL, "protocol");
+  const getPathname = getter(NativeURL, "pathname");
+  const getRequestUrl = getter(g.Request, "url");
+  let gatewayPrefixes = null;
+  let partnerOrigins = [];
+  let routesReady = false;
+  function copyStrings(value) {
+    if (!Array.isArray(value)) return null;
+    const out = [];
+    for (let i = 0; i < value.length; i += 1) {
+      if (typeof value[i] === "string") out[out.length] = value[i];
+    }
+    return out;
+  }
+  function takeSnapshot(init) {
+    if (routesReady) return;
+    const raw = init;
+    gatewayPrefixes = copyStrings(raw.gatewayPrefixes);
+    partnerOrigins = copyStrings(raw.partnerOrigins) || [];
+    routesReady = true;
+  }
+  promiseThen(client.ready, takeSnapshot);
+  function matchesPrefix2(pathname, prefix) {
+    const bare = strSlice(prefix, prefix.length - 1) === "/" ? strSlice(prefix, 0, -1) : prefix;
+    return pathname === bare || strSlice(pathname, 0, bare.length + 1) === bare + "/";
+  }
+  function routeOf(origin, protocol, pathname) {
+    if (origin === hostOrigin) {
+      if (gatewayPrefixes === null) return "bridge";
+      for (let i = 0; i < gatewayPrefixes.length; i += 1) {
+        if (matchesPrefix2(pathname, gatewayPrefixes[i])) return "bridge";
+      }
+      return "reject";
+    }
+    for (let i = 0; i < partnerOrigins.length; i += 1) {
+      if (origin === partnerOrigins[i]) return "bridge";
+    }
+    return protocol === "https:" ? "direct" : "reject";
+  }
+  function requestUrlOf(input) {
+    if (!getRequestUrl || typeof input !== "object" || input === null) return void 0;
+    try {
+      return getRequestUrl(input);
+    } catch {
+      return void 0;
+    }
+  }
+  function dispatch2(input, init) {
+    if (typeof NativeURL !== "function" || !getHref || !getOrigin || !getProtocol || !getPathname) {
+      return promiseReject(new TypeErr("bstage fetch: URL is unavailable"));
+    }
+    const requestUrl = requestUrlOf(input);
+    const request = requestUrl !== void 0;
+    let parsed;
+    try {
+      parsed = new NativeURL(request ? requestUrl : String(input), hostOrigin);
+    } catch {
+      return promiseReject(new TypeErr("bstage fetch: invalid url"));
+    }
+    const href = getHref(parsed);
+    const route = routeOf(getOrigin(parsed), getProtocol(parsed), getPathname(parsed));
+    const target = request ? input : href;
+    if (route === "bridge") return bridgeFetch(target, init);
+    if (route === "reject") {
+      return promiseReject(new TypeErr("bstage fetch: destination not allowed"));
+    }
+    if (!nativeFetch) return promiseReject(new TypeErr("bstage fetch: fetch is unavailable"));
+    return nativeFetch(
+      g,
+      target,
+      assign({}, init, { credentials: "omit", referrerPolicy: "no-referrer" })
+    );
+  }
+  function bstageFetch(input, init) {
+    try {
+      if (routesReady) return dispatch2(input, init);
+      return promiseThen(client.ready, function(value) {
+        takeSnapshot(value);
+        return dispatch2(input, init);
+      });
+    } catch {
+      return promiseReject(new TypeErr("bstage fetch: request failed"));
+    }
+  }
+  Object.defineProperty(g, "__bstage_fetch__", {
+    value: bstageFetch,
+    writable: false,
+    configurable: false,
+    enumerable: false
+  });
+  return bstageFetch;
+}
+
 // src/srcdoc/escape.ts
 var HTML_ESCAPES = {
   "&": "&amp;",
@@ -1286,7 +1524,7 @@ function buildFrameCsp(nonce, assetOrigin, mediaOrigins = []) {
     `img-src ${media} data: blob:`,
     `font-src ${assetOrigin} data:`,
     `media-src ${media} blob:`,
-    "connect-src 'none'",
+    "connect-src https: wss:",
     "frame-src 'none'",
     "form-action 'none'",
     "base-uri 'none'"
@@ -1303,6 +1541,9 @@ function bootstrapScript(o) {
     `var bridgeRuntime = ${bridgeRuntime.toString()};`,
     `var createBridgeFetch = ${createBridgeFetch.toString()};`,
     "var client = bridgeRuntime(globalThis, createBridgeFetch, { session: SESSION, hostOrigin: HOST_ORIGIN });",
+    // 라우터는 항상 심는다. ready.then이 엔트리 로드(아래 client.ready.then)보다 먼저 등록돼야 템플릿보다 먼저 스냅샷을 잡는다.
+    `var installDirectFetch = ${installDirectFetch.toString()};`,
+    "installDirectFetch(globalThis, client, { hostOrigin: HOST_ORIGIN });",
     "var lastHeight = -1;",
     "var scheduled = false;",
     "function reportHeight() {",

package/dist/host.d.cts

@@ -1,6 +1,6 @@
-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';
-export { C as CreateSrcdocOptions, c as createNonce, d as createSession, e as createSrcdoc, f as isValidSession } from './createSrcdoc-bOoxttPz.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-BjpZyiLy.cjs';
+export { a as BRIDGE_SURFACES, I as IFRAME_ATTRIBUTES, w as isBridgeSurface } from './messages-BjpZyiLy.cjs';
+export { C as CreateSrcdocOptions, c as createNonce, d as createSession, e as createSrcdoc, f as isValidSession } from './createSrcdoc-DgQyvIjG.cjs';
 
 /** 호스트 fetch 정책. */
 interface BridgePolicy {
@@ -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,6 +1,6 @@
-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';
-export { C as CreateSrcdocOptions, c as createNonce, d as createSession, e as createSrcdoc, f as isValidSession } from './createSrcdoc-bOoxttPz.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-BjpZyiLy.js';
+export { a as BRIDGE_SURFACES, I as IFRAME_ATTRIBUTES, w as isBridgeSurface } from './messages-BjpZyiLy.js';
+export { C as CreateSrcdocOptions, c as createNonce, d as createSession, e as createSrcdoc, f as isValidSession } from './createSrcdoc-DgQyvIjG.js';
 
 /** 호스트 fetch 정책. */
 interface BridgePolicy {
@@ -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-ND2HFYBP.js";
+import "./chunk-CSAW3L7P.js";
 
 // src/host/rateLimiter.ts
 var DEFAULT_WINDOW_MS = 6e4;
@@ -114,6 +115,7 @@ function buildInit(init, hostOrigin, partnerOrigins, policy) {
     spaceId: String(init.spaceId),
     hostOrigin,
     gatewayBase: `${hostOrigin}/gw`,
+    gatewayPrefixes: policy.gatewayPrefixes,
     locale: String(init.locale),
     theme: sanitizeTheme(init.theme),
     ...slot ? { slot } : {},
@@ -453,6 +455,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 +480,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 +545,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 +593,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");
     }
   };
 }