@bstage-sdk/host 0.1.0

package/LICENSE

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

package/dist/index.cjs

@@ -0,0 +1,239 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SLOT_CATALOG: () => import_core2.SLOT_CATALOG,
+  TemplateHandle: () => TemplateHandle,
+  getSlotsByTarget: () => import_core2.getSlotsByTarget,
+  loadTemplate: () => loadTemplate,
+  loadTemplatesBySlots: () => loadTemplatesBySlots
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/loadTemplate.ts
+var import_core = require("@bstage-sdk/core");
+
+// src/scriptLoader.ts
+var cache = /* @__PURE__ */ new Map();
+function loadScript(url, timeoutMs = 1e4) {
+  const existing = cache.get(url);
+  if (existing) return existing;
+  const promise = new Promise((resolve, reject) => {
+    const script = document.createElement("script");
+    script.src = url;
+    script.async = true;
+    const timer = setTimeout(() => {
+      cleanup();
+      cache.delete(url);
+      reject(new Error(`Script load timed out after ${timeoutMs}ms: ${url}`));
+    }, timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timer);
+      script.removeEventListener("load", onLoad);
+      script.removeEventListener("error", onError);
+    };
+    const onLoad = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = () => {
+      cleanup();
+      cache.delete(url);
+      reject(new Error(`Failed to load script: ${url}`));
+    };
+    script.addEventListener("load", onLoad);
+    script.addEventListener("error", onError);
+    document.head.appendChild(script);
+  });
+  cache.set(url, promise);
+  return promise;
+}
+
+// src/TemplateHandle.ts
+var READY_EVENT = "bstage:__ready__";
+var TemplateHandle = class _TemplateHandle {
+  constructor(info) {
+    this.element = null;
+    this.container = null;
+    this.bufferedListeners = [];
+    this.activeListeners = [];
+    this._templateReady = false;
+    this._dispatchBuffer = [];
+    this.info = info;
+  }
+  /**
+   * 컨테이너 엘리먼트에 템플릿을 마운트합니다.
+   * 커스텀 엘리먼트를 생성하고, 버퍼링된 리스너를 연결한 뒤, DOM에 추가합니다.
+   */
+  mount(container) {
+    if (this.element) {
+      throw new Error(`Template "${this.info.elementName}" is already mounted`);
+    }
+    this.container = container;
+    this.element = document.createElement(this.info.elementName);
+    this.element.addEventListener(
+      READY_EVENT,
+      () => {
+        this._templateReady = true;
+        for (const { type, detail } of this._dispatchBuffer) {
+          this.element.dispatchEvent(
+            new CustomEvent(type, { bubbles: false, composed: false, detail })
+          );
+        }
+        this._dispatchBuffer = [];
+      },
+      { once: true }
+    );
+    for (const { type, handler } of this.bufferedListeners) {
+      this.element.addEventListener(type, handler);
+      this.activeListeners.push({ type, handler });
+    }
+    this.bufferedListeners = [];
+    container.appendChild(this.element);
+  }
+  /**
+   * 동일한 매니페스트로 독립적인 새 핸들을 생성합니다.
+   * 같은 슬롯을 페이지 내 여러 위치에 마운트해야 할 때 사용합니다.
+   * 번들 스크립트는 이미 로드된 상태이므로 추가 네트워크 요청이 없습니다.
+   */
+  fork() {
+    return new _TemplateHandle(this.info);
+  }
+  /**
+   * 템플릿을 언마운트합니다 — 리스너와 엘리먼트를 DOM에서 제거합니다.
+   * 멱등성: 여러 번 호출해도 안전합니다.
+   */
+  unmount() {
+    if (!this.element) return;
+    for (const { type, handler } of this.activeListeners) {
+      this.element.removeEventListener(type, handler);
+    }
+    this.activeListeners = [];
+    this.element.remove();
+    this.element = null;
+    this.container = null;
+    this._templateReady = false;
+    this._dispatchBuffer = [];
+  }
+  /**
+   * 템플릿 이벤트를 수신합니다 (템플릿 → 플랫폼).
+   * mount() 전에 호출할 수 있습니다 — 리스너가 버퍼링되어 마운트 시 연결됩니다.
+   * 구독 해제 함수를 반환합니다.
+   */
+  on(type, handler) {
+    const eventType = `bstage:${type}`;
+    const listener = (e) => {
+      handler(e.detail);
+    };
+    if (this.element) {
+      this.element.addEventListener(eventType, listener);
+      this.activeListeners.push({ type: eventType, handler: listener });
+    } else {
+      this.bufferedListeners.push({ type: eventType, handler: listener });
+    }
+    return () => {
+      if (this.element) {
+        this.element.removeEventListener(eventType, listener);
+        this.activeListeners = this.activeListeners.filter((l) => l.handler !== listener);
+      } else {
+        this.bufferedListeners = this.bufferedListeners.filter((l) => l.handler !== listener);
+      }
+    };
+  }
+  /**
+   * 템플릿으로 플랫폼 이벤트를 디스패치합니다 (플랫폼 → 템플릿).
+   * 템플릿이 아직 ready가 아니면 버퍼링 후 ready 시 리플레이합니다.
+   */
+  dispatch(type, payload) {
+    if (!this.element) {
+      throw new Error(`Template "${this.info.elementName}" is not mounted`);
+    }
+    const eventType = `bstage:${type}`;
+    if (!this._templateReady) {
+      this._dispatchBuffer.push({ type: eventType, detail: payload });
+      return;
+    }
+    this.element.dispatchEvent(
+      new CustomEvent(eventType, {
+        bubbles: false,
+        composed: false,
+        detail: payload
+      })
+    );
+  }
+};
+
+// src/loadTemplate.ts
+async function loadTemplate(templateUrl, options) {
+  const timeout = options?.timeout ?? 1e4;
+  await loadScript(templateUrl, timeout);
+  const elementName = (0, import_core.lookupElementName)(templateUrl) ?? recoverLegacyElementName(templateUrl);
+  if (!elementName) {
+    throw new Error(
+      `Template bundle registered no custom element: ${templateUrl}. Rebuild the template with a current @bstage-sdk/cli.`
+    );
+  }
+  return new TemplateHandle({ elementName });
+}
+function recoverLegacyElementName(templateUrl) {
+  const path = templateUrl.split("?")[0].split("#")[0];
+  const segments = path.split("/").filter(Boolean);
+  const candidate = segments[segments.length - 2];
+  if (!candidate) return void 0;
+  return customElements.get(candidate) ? candidate : void 0;
+}
+
+// src/loadTemplatesBySlots.ts
+async function loadTemplatesBySlots(customSlots, options) {
+  const result = /* @__PURE__ */ new Map();
+  const tasks = [];
+  for (const [slot, entries] of Object.entries(customSlots)) {
+    for (const entry of entries) {
+      tasks.push({ slot, templateUrl: entry.templateUrl });
+    }
+  }
+  const settled = await Promise.allSettled(
+    tasks.map(({ templateUrl }) => loadTemplate(templateUrl, options))
+  );
+  for (let i = 0; i < tasks.length; i++) {
+    const { slot } = tasks[i];
+    const outcome = settled[i];
+    if (outcome.status === "rejected") {
+      console.warn(`[bstage-host] Failed to load template for slot "${slot}":`, outcome.reason);
+      continue;
+    }
+    const handles = result.get(slot) ?? [];
+    handles.push(outcome.value);
+    result.set(slot, handles);
+  }
+  return result;
+}
+
+// src/index.ts
+var import_core2 = require("@bstage-sdk/core");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SLOT_CATALOG,
+  TemplateHandle,
+  getSlotsByTarget,
+  loadTemplate,
+  loadTemplatesBySlots
+});

package/dist/index.d.cts

@@ -0,0 +1,93 @@
+import { TemplateEventType, TemplateEventMap, PlatformEventType, PlatformEventMap, CustomSlots, CustomSlotsV2 } from '@bstage-sdk/core';
+export { CustomSlots, SLOT_CATALOG, TemplateSlot, getSlotsByTarget } from '@bstage-sdk/core';
+
+/**
+ * 로드한 템플릿에 대해 호스트가 아는 것.
+ *
+ * `bstage build`가 manifest.json을 만들던 시절에는 sdkVersion·framework·entry도 함께 실렸지만,
+ * 호스트가 실제로 쓰는 값은 태그명 하나뿐이었다. 지금은 번들이 로드되면서 스스로 알린다.
+ */
+interface TemplateInfo {
+    /**
+     * Custom Element 태그명. 템플릿이 `createTemplate({ name })`에 넣은 값 그대로.
+     * `customElements.define`과 `document.createElement`가 사용하는 load-bearing 식별자.
+     */
+    elementName: string;
+}
+interface LoadTemplateOptions {
+    /** 스크립트 로드 타임아웃 (밀리초 단위, 기본값: 10,000) */
+    timeout?: number;
+}
+
+declare class TemplateHandle {
+    readonly info: TemplateInfo;
+    private element;
+    private container;
+    private bufferedListeners;
+    private activeListeners;
+    private _templateReady;
+    private _dispatchBuffer;
+    constructor(info: TemplateInfo);
+    /**
+     * 컨테이너 엘리먼트에 템플릿을 마운트합니다.
+     * 커스텀 엘리먼트를 생성하고, 버퍼링된 리스너를 연결한 뒤, DOM에 추가합니다.
+     */
+    mount(container: HTMLElement): void;
+    /**
+     * 동일한 매니페스트로 독립적인 새 핸들을 생성합니다.
+     * 같은 슬롯을 페이지 내 여러 위치에 마운트해야 할 때 사용합니다.
+     * 번들 스크립트는 이미 로드된 상태이므로 추가 네트워크 요청이 없습니다.
+     */
+    fork(): TemplateHandle;
+    /**
+     * 템플릿을 언마운트합니다 — 리스너와 엘리먼트를 DOM에서 제거합니다.
+     * 멱등성: 여러 번 호출해도 안전합니다.
+     */
+    unmount(): void;
+    /**
+     * 템플릿 이벤트를 수신합니다 (템플릿 → 플랫폼).
+     * mount() 전에 호출할 수 있습니다 — 리스너가 버퍼링되어 마운트 시 연결됩니다.
+     * 구독 해제 함수를 반환합니다.
+     */
+    on<T extends TemplateEventType>(type: T, handler: (payload: TemplateEventMap[T]) => void): () => void;
+    /**
+     * 템플릿으로 플랫폼 이벤트를 디스패치합니다 (플랫폼 → 템플릿).
+     * 템플릿이 아직 ready가 아니면 버퍼링 후 ready 시 리플레이합니다.
+     */
+    dispatch<T extends PlatformEventType>(type: T, payload: PlatformEventMap[T]): void;
+}
+
+/**
+ * 템플릿 번들 URL로부터 템플릿을 로드합니다.
+ *
+ * 1. `<script>`로 IIFE 번들을 로드합니다 (멱등성)
+ * 2. 번들이 등록한 Custom Element 태그명을 확인합니다
+ * 3. 생명주기 관리를 위한 TemplateHandle을 반환합니다
+ *
+ * 예전에는 manifest.json을 먼저 받아 태그명과 번들 경로를 읽었습니다. manifest가 실어 나르던
+ * 정보는 태그명 하나뿐이었고 entry는 늘 `template.js`로 고정이라, 번들이 로드되면서 스스로
+ * 태그명을 알리는 방식으로 바꿨습니다. 관리도구도 `templateUrl` 하나만 내려줍니다.
+ *
+ * @example
+ * const tpl = await loadTemplate('/cdn/bmf/landing/template.js')
+ * tpl.on('navigate', ({ path }) => router.push(path))
+ * tpl.mount(container)
+ */
+declare function loadTemplate(templateUrl: string, options?: LoadTemplateOptions): Promise<TemplateHandle>;
+
+/**
+ * 관리도구가 CDN에 업로드한 `config-latest.json`(또는 동일 형태의 객체)을 받아
+ * 슬롯별 TemplateHandle 배열을 반환한다.
+ *
+ * - 런타임에서는 목록에 없는 슬롯 키도 허용(관리도구가 신버전을 선반영한 경우)
+ * - 개별 템플릿 로드 실패 시 해당 항목만 건너뛰고 나머지를 반환
+ * - 옛 모양(`CustomSlots`, 4-part 키)·새 모양(`CustomSlotsV2`, 3-part 키) 둘 다 받음.
+ *   한 객체에 둘이 섞여 있어도 동작한다(키 형식만 다른 같은 모양).
+ *
+ * @example
+ * const slotMap = await loadTemplatesBySlots(await fetchCustomSlots(spaceId))
+ * const beforeHandles = slotMap.get('contents.home.contents.before') ?? []
+ */
+declare function loadTemplatesBySlots(customSlots: CustomSlots | CustomSlotsV2, options?: LoadTemplateOptions): Promise<Map<string, TemplateHandle[]>>;
+
+export { type LoadTemplateOptions, TemplateHandle, type TemplateInfo, loadTemplate, loadTemplatesBySlots };

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import { TemplateEventType, TemplateEventMap, PlatformEventType, PlatformEventMap, CustomSlots, CustomSlotsV2 } from '@bstage-sdk/core';
+export { CustomSlots, SLOT_CATALOG, TemplateSlot, getSlotsByTarget } from '@bstage-sdk/core';
+
+/**
+ * 로드한 템플릿에 대해 호스트가 아는 것.
+ *
+ * `bstage build`가 manifest.json을 만들던 시절에는 sdkVersion·framework·entry도 함께 실렸지만,
+ * 호스트가 실제로 쓰는 값은 태그명 하나뿐이었다. 지금은 번들이 로드되면서 스스로 알린다.
+ */
+interface TemplateInfo {
+    /**
+     * Custom Element 태그명. 템플릿이 `createTemplate({ name })`에 넣은 값 그대로.
+     * `customElements.define`과 `document.createElement`가 사용하는 load-bearing 식별자.
+     */
+    elementName: string;
+}
+interface LoadTemplateOptions {
+    /** 스크립트 로드 타임아웃 (밀리초 단위, 기본값: 10,000) */
+    timeout?: number;
+}
+
+declare class TemplateHandle {
+    readonly info: TemplateInfo;
+    private element;
+    private container;
+    private bufferedListeners;
+    private activeListeners;
+    private _templateReady;
+    private _dispatchBuffer;
+    constructor(info: TemplateInfo);
+    /**
+     * 컨테이너 엘리먼트에 템플릿을 마운트합니다.
+     * 커스텀 엘리먼트를 생성하고, 버퍼링된 리스너를 연결한 뒤, DOM에 추가합니다.
+     */
+    mount(container: HTMLElement): void;
+    /**
+     * 동일한 매니페스트로 독립적인 새 핸들을 생성합니다.
+     * 같은 슬롯을 페이지 내 여러 위치에 마운트해야 할 때 사용합니다.
+     * 번들 스크립트는 이미 로드된 상태이므로 추가 네트워크 요청이 없습니다.
+     */
+    fork(): TemplateHandle;
+    /**
+     * 템플릿을 언마운트합니다 — 리스너와 엘리먼트를 DOM에서 제거합니다.
+     * 멱등성: 여러 번 호출해도 안전합니다.
+     */
+    unmount(): void;
+    /**
+     * 템플릿 이벤트를 수신합니다 (템플릿 → 플랫폼).
+     * mount() 전에 호출할 수 있습니다 — 리스너가 버퍼링되어 마운트 시 연결됩니다.
+     * 구독 해제 함수를 반환합니다.
+     */
+    on<T extends TemplateEventType>(type: T, handler: (payload: TemplateEventMap[T]) => void): () => void;
+    /**
+     * 템플릿으로 플랫폼 이벤트를 디스패치합니다 (플랫폼 → 템플릿).
+     * 템플릿이 아직 ready가 아니면 버퍼링 후 ready 시 리플레이합니다.
+     */
+    dispatch<T extends PlatformEventType>(type: T, payload: PlatformEventMap[T]): void;
+}
+
+/**
+ * 템플릿 번들 URL로부터 템플릿을 로드합니다.
+ *
+ * 1. `<script>`로 IIFE 번들을 로드합니다 (멱등성)
+ * 2. 번들이 등록한 Custom Element 태그명을 확인합니다
+ * 3. 생명주기 관리를 위한 TemplateHandle을 반환합니다
+ *
+ * 예전에는 manifest.json을 먼저 받아 태그명과 번들 경로를 읽었습니다. manifest가 실어 나르던
+ * 정보는 태그명 하나뿐이었고 entry는 늘 `template.js`로 고정이라, 번들이 로드되면서 스스로
+ * 태그명을 알리는 방식으로 바꿨습니다. 관리도구도 `templateUrl` 하나만 내려줍니다.
+ *
+ * @example
+ * const tpl = await loadTemplate('/cdn/bmf/landing/template.js')
+ * tpl.on('navigate', ({ path }) => router.push(path))
+ * tpl.mount(container)
+ */
+declare function loadTemplate(templateUrl: string, options?: LoadTemplateOptions): Promise<TemplateHandle>;
+
+/**
+ * 관리도구가 CDN에 업로드한 `config-latest.json`(또는 동일 형태의 객체)을 받아
+ * 슬롯별 TemplateHandle 배열을 반환한다.
+ *
+ * - 런타임에서는 목록에 없는 슬롯 키도 허용(관리도구가 신버전을 선반영한 경우)
+ * - 개별 템플릿 로드 실패 시 해당 항목만 건너뛰고 나머지를 반환
+ * - 옛 모양(`CustomSlots`, 4-part 키)·새 모양(`CustomSlotsV2`, 3-part 키) 둘 다 받음.
+ *   한 객체에 둘이 섞여 있어도 동작한다(키 형식만 다른 같은 모양).
+ *
+ * @example
+ * const slotMap = await loadTemplatesBySlots(await fetchCustomSlots(spaceId))
+ * const beforeHandles = slotMap.get('contents.home.contents.before') ?? []
+ */
+declare function loadTemplatesBySlots(customSlots: CustomSlots | CustomSlotsV2, options?: LoadTemplateOptions): Promise<Map<string, TemplateHandle[]>>;
+
+export { type LoadTemplateOptions, TemplateHandle, type TemplateInfo, loadTemplate, loadTemplatesBySlots };

package/dist/index.js

@@ -0,0 +1,211 @@
+// src/loadTemplate.ts
+import { lookupElementName } from "@bstage-sdk/core";
+
+// src/scriptLoader.ts
+var cache = /* @__PURE__ */ new Map();
+function loadScript(url, timeoutMs = 1e4) {
+  const existing = cache.get(url);
+  if (existing) return existing;
+  const promise = new Promise((resolve, reject) => {
+    const script = document.createElement("script");
+    script.src = url;
+    script.async = true;
+    const timer = setTimeout(() => {
+      cleanup();
+      cache.delete(url);
+      reject(new Error(`Script load timed out after ${timeoutMs}ms: ${url}`));
+    }, timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timer);
+      script.removeEventListener("load", onLoad);
+      script.removeEventListener("error", onError);
+    };
+    const onLoad = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = () => {
+      cleanup();
+      cache.delete(url);
+      reject(new Error(`Failed to load script: ${url}`));
+    };
+    script.addEventListener("load", onLoad);
+    script.addEventListener("error", onError);
+    document.head.appendChild(script);
+  });
+  cache.set(url, promise);
+  return promise;
+}
+
+// src/TemplateHandle.ts
+var READY_EVENT = "bstage:__ready__";
+var TemplateHandle = class _TemplateHandle {
+  constructor(info) {
+    this.element = null;
+    this.container = null;
+    this.bufferedListeners = [];
+    this.activeListeners = [];
+    this._templateReady = false;
+    this._dispatchBuffer = [];
+    this.info = info;
+  }
+  /**
+   * 컨테이너 엘리먼트에 템플릿을 마운트합니다.
+   * 커스텀 엘리먼트를 생성하고, 버퍼링된 리스너를 연결한 뒤, DOM에 추가합니다.
+   */
+  mount(container) {
+    if (this.element) {
+      throw new Error(`Template "${this.info.elementName}" is already mounted`);
+    }
+    this.container = container;
+    this.element = document.createElement(this.info.elementName);
+    this.element.addEventListener(
+      READY_EVENT,
+      () => {
+        this._templateReady = true;
+        for (const { type, detail } of this._dispatchBuffer) {
+          this.element.dispatchEvent(
+            new CustomEvent(type, { bubbles: false, composed: false, detail })
+          );
+        }
+        this._dispatchBuffer = [];
+      },
+      { once: true }
+    );
+    for (const { type, handler } of this.bufferedListeners) {
+      this.element.addEventListener(type, handler);
+      this.activeListeners.push({ type, handler });
+    }
+    this.bufferedListeners = [];
+    container.appendChild(this.element);
+  }
+  /**
+   * 동일한 매니페스트로 독립적인 새 핸들을 생성합니다.
+   * 같은 슬롯을 페이지 내 여러 위치에 마운트해야 할 때 사용합니다.
+   * 번들 스크립트는 이미 로드된 상태이므로 추가 네트워크 요청이 없습니다.
+   */
+  fork() {
+    return new _TemplateHandle(this.info);
+  }
+  /**
+   * 템플릿을 언마운트합니다 — 리스너와 엘리먼트를 DOM에서 제거합니다.
+   * 멱등성: 여러 번 호출해도 안전합니다.
+   */
+  unmount() {
+    if (!this.element) return;
+    for (const { type, handler } of this.activeListeners) {
+      this.element.removeEventListener(type, handler);
+    }
+    this.activeListeners = [];
+    this.element.remove();
+    this.element = null;
+    this.container = null;
+    this._templateReady = false;
+    this._dispatchBuffer = [];
+  }
+  /**
+   * 템플릿 이벤트를 수신합니다 (템플릿 → 플랫폼).
+   * mount() 전에 호출할 수 있습니다 — 리스너가 버퍼링되어 마운트 시 연결됩니다.
+   * 구독 해제 함수를 반환합니다.
+   */
+  on(type, handler) {
+    const eventType = `bstage:${type}`;
+    const listener = (e) => {
+      handler(e.detail);
+    };
+    if (this.element) {
+      this.element.addEventListener(eventType, listener);
+      this.activeListeners.push({ type: eventType, handler: listener });
+    } else {
+      this.bufferedListeners.push({ type: eventType, handler: listener });
+    }
+    return () => {
+      if (this.element) {
+        this.element.removeEventListener(eventType, listener);
+        this.activeListeners = this.activeListeners.filter((l) => l.handler !== listener);
+      } else {
+        this.bufferedListeners = this.bufferedListeners.filter((l) => l.handler !== listener);
+      }
+    };
+  }
+  /**
+   * 템플릿으로 플랫폼 이벤트를 디스패치합니다 (플랫폼 → 템플릿).
+   * 템플릿이 아직 ready가 아니면 버퍼링 후 ready 시 리플레이합니다.
+   */
+  dispatch(type, payload) {
+    if (!this.element) {
+      throw new Error(`Template "${this.info.elementName}" is not mounted`);
+    }
+    const eventType = `bstage:${type}`;
+    if (!this._templateReady) {
+      this._dispatchBuffer.push({ type: eventType, detail: payload });
+      return;
+    }
+    this.element.dispatchEvent(
+      new CustomEvent(eventType, {
+        bubbles: false,
+        composed: false,
+        detail: payload
+      })
+    );
+  }
+};
+
+// src/loadTemplate.ts
+async function loadTemplate(templateUrl, options) {
+  const timeout = options?.timeout ?? 1e4;
+  await loadScript(templateUrl, timeout);
+  const elementName = lookupElementName(templateUrl) ?? recoverLegacyElementName(templateUrl);
+  if (!elementName) {
+    throw new Error(
+      `Template bundle registered no custom element: ${templateUrl}. Rebuild the template with a current @bstage-sdk/cli.`
+    );
+  }
+  return new TemplateHandle({ elementName });
+}
+function recoverLegacyElementName(templateUrl) {
+  const path = templateUrl.split("?")[0].split("#")[0];
+  const segments = path.split("/").filter(Boolean);
+  const candidate = segments[segments.length - 2];
+  if (!candidate) return void 0;
+  return customElements.get(candidate) ? candidate : void 0;
+}
+
+// src/loadTemplatesBySlots.ts
+async function loadTemplatesBySlots(customSlots, options) {
+  const result = /* @__PURE__ */ new Map();
+  const tasks = [];
+  for (const [slot, entries] of Object.entries(customSlots)) {
+    for (const entry of entries) {
+      tasks.push({ slot, templateUrl: entry.templateUrl });
+    }
+  }
+  const settled = await Promise.allSettled(
+    tasks.map(({ templateUrl }) => loadTemplate(templateUrl, options))
+  );
+  for (let i = 0; i < tasks.length; i++) {
+    const { slot } = tasks[i];
+    const outcome = settled[i];
+    if (outcome.status === "rejected") {
+      console.warn(`[bstage-host] Failed to load template for slot "${slot}":`, outcome.reason);
+      continue;
+    }
+    const handles = result.get(slot) ?? [];
+    handles.push(outcome.value);
+    result.set(slot, handles);
+  }
+  return result;
+}
+
+// src/index.ts
+import {
+  SLOT_CATALOG,
+  getSlotsByTarget
+} from "@bstage-sdk/core";
+export {
+  SLOT_CATALOG,
+  TemplateHandle,
+  getSlotsByTarget,
+  loadTemplate,
+  loadTemplatesBySlots
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@bstage-sdk/host",
+  "version": "0.1.0",
+  "description": "bstage SDK host — load and manage template bundles on the platform side",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bstage-sdk/web-sdk.git",
+    "directory": "packages/host"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@bstage-sdk/core": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}