@vustcc/suite-sdk 0.1.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，并遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
+
+## [0.1.0-alpha.1] - 2026-09-10
+
+### Added
+
+- 首次发布 `@vustcc/suite-sdk` 套件集成 SDK。
+- 提供套件端桥接、主控端桥接、主题同步、语言同步和消息订阅能力。
+- 支持套件导航请求、统一通知和独立运行时降级。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gwj
+
+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/README.md

@@ -0,0 +1,183 @@
+# @vustcc/suite-sdk
+
+VUST 套件集成 SDK，为运行在 iframe 中的套件 Web 前端提供统一的主控通信协议。
+
+## 能力
+
+- 套件向主控报告就绪状态。
+- 主控向套件同步主题。
+- 主控向套件同步国际化语言。
+- 套件请求主控展示统一通知。
+- 套件请求主控执行导航动作，例如打开主控应用、跳转外链或切换主控页面。
+- 套件请求主控聚焦承载窗口。
+- 套件独立运行时自动使用系统主题和浏览器语言。
+- 提供无框架 TypeScript API，Vue、React 或原生前端都可以使用。
+
+设计约定由 `vust-docs` 统一维护，见 [VUST 套件 SDK 设计规范](https://github.com/vustcc/vust-docs/blob/main/suites/VUST%E5%A5%97%E4%BB%B6SDK%E8%AE%BE%E8%AE%A1%E8%A7%84%E8%8C%83.md)。
+
+## 安装
+
+```bash
+pnpm add @vustcc/suite-sdk
+```
+
+## 套件端使用
+
+```ts
+import { createSuiteBridge } from "@vustcc/suite-sdk";
+
+const bridge = createSuiteBridge();
+bridge.ready();
+```
+
+SDK 会把最终主题写入：
+
+```ts
+document.documentElement.dataset.theme;
+document.documentElement.style.colorScheme;
+```
+
+如果需要监听主题变化：
+
+```ts
+const unsubscribe = bridge.subscribeTheme((theme) => {
+  console.log(theme.resolvedTheme);
+});
+
+unsubscribe();
+```
+
+如果套件已经接入国际化，可以声明并监听语言变化：
+
+```ts
+const bridge = createSuiteBridge({
+  capabilities: ["theme", "locale"],
+  supportedLocales: ["zh-CN", "en-US"],
+  defaultLocale: "zh-CN",
+});
+
+bridge.subscribeLocale((locale) => {
+  console.log(locale.locale);
+});
+```
+
+如果套件需要统一通知，声明 `notification` 能力后调用 `notify()`。主控可用时由主控弹窗；独立运行或主控不可用时返回 `false`，套件应使用自己的本地 toast 降级。
+
+```ts
+const bridge = createSuiteBridge({
+  capabilities: ["theme", "locale", "notification"],
+});
+
+const delivered = bridge.notify({
+  type: "success",
+  title: "上传成功",
+  message: "PCAP 文件已进入解析队列",
+});
+
+if (!delivered) {
+  showLocalToast("success", "上传成功", "PCAP 文件已进入解析队列");
+}
+```
+
+如果套件需要通过主控打开应用或跳转页面，声明 `navigation` 能力后调用 `navigate()`。主控可用并且套件处于 iframe 承载环境时返回 `true`；独立运行或主控不可用时返回 `false`，套件应按业务需要降级处理。
+
+```ts
+const bridge = createSuiteBridge({
+  capabilities: ["theme", "locale", "navigation"],
+});
+
+const delivered = bridge.navigate({
+  target: "suite-center",
+});
+
+if (!delivered) {
+  showLocalNavigationHint();
+}
+```
+
+当前 `navigate()` payload 使用统一结构：
+
+```ts
+interface SuiteNavigationPayload {
+  target: "app" | "url" | "suite-center" | "desktop";
+  value?: string;
+  payload?: Record<string, unknown>;
+  external?: boolean;
+}
+```
+
+SDK 只负责发送通用导航请求，具体 `target` 的执行策略由主控承载层决定。
+
+## 主控端使用
+
+```ts
+import { createSuiteHostBridge } from "@vustcc/suite-sdk";
+
+const bridge = createSuiteHostBridge({
+  iframe: () => iframeElement,
+  theme: () => "light",
+  locale: () => "zh-CN",
+});
+
+bridge.sendTheme();
+bridge.sendLocale();
+```
+
+主控收到 `suite:lifecycle:ready` 后会自动补发主题。套件声明 `locale` 能力时，主控也会补发语言。
+
+## 协议
+
+所有消息都使用统一 envelope：
+
+```ts
+interface SuiteMessage<TPayload = unknown> {
+  protocolVersion: 1;
+  source: "vust-suite" | "vust-host";
+  type: string;
+  id?: string;
+  requestId?: string;
+  payload?: TPayload;
+  error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+}
+```
+
+当前内置消息：
+
+- `suite:lifecycle:ready`
+- `host:theme:update`
+- `host:locale:update`
+- `suite:notification:show`
+- `suite:navigation:open`
+- `suite:window:focus`
+
+已占位但暂未实现运行逻辑的蓝图消息：
+
+- `host:context:update`
+- `host:permission:grant`
+- `host:permission:deny`
+- `suite:dialog:confirm`
+- `suite:window:title:update`
+- `suite:window:dirty:update`
+- `suite:file:open`
+- `suite:file:save`
+- `suite:log:event`
+- `suite:error:report`
+- `suite:lifecycle:heartbeat`
+- `suite:lifecycle:status`
+
+## API
+
+```ts
+createSuiteBridge(options?: CreateSuiteBridgeOptions): SuiteBridge
+createSuiteHostBridge(options: CreateSuiteHostBridgeOptions): SuiteHostBridge
+```
+
+声明 `window` capability 后，套件 SDK 会在套件内 `pointerdown` 和 `focusin` 时自动发送 `suite:window:focus`，主控可据此聚焦承载窗口。特殊场景也可以调用 `bridge.requestWindowFocus()` 手动请求聚焦。
+
+声明 `notification` capability 后，套件可以调用 `bridge.notify(payload)` 请求主控展示统一通知。该方法返回布尔值，便于套件在独立运行时切回本地通知。
+
+声明 `navigation` capability 后，套件可以调用 `bridge.navigate(payload)` 请求主控执行导航动作。该方法返回布尔值，便于套件在独立运行时使用本地窗口、链接或提示降级。

package/dist/environment.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file environment.ts
+ * @description 浏览器运行环境辅助函数。
+ */
+export declare function isBrowser(): boolean;
+export declare function resolveIframe(iframe: HTMLIFrameElement | (() => HTMLIFrameElement | null)): HTMLIFrameElement | null;

package/dist/host-bridge.d.ts

@@ -0,0 +1,5 @@
+import { CreateSuiteHostBridgeOptions, SuiteHostBridge } from './types';
+/**
+ * @description 创建主控端 Bridge，负责向套件 iframe 推送主控主题与语言。
+ */
+export declare function createSuiteHostBridge(options: CreateSuiteHostBridgeOptions): SuiteHostBridge;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file index.ts
+ * @description VUST 套件 SDK 公开入口。
+ */
+export { createSuiteHostBridge } from './host-bridge';
+export { createSuiteBridge } from './suite-bridge';
+export { SECLAB_SUITE_PROTOCOL_VERSION, SUITE_MESSAGE_TYPES } from './protocol';
+export type * from './types';

package/dist/index.js

@@ -0,0 +1,206 @@
+//#region src/environment.ts
+function e() {
+	return typeof window < "u" && typeof document < "u";
+}
+function t(e) {
+	return typeof e == "function" ? e() : e;
+}
+//#endregion
+//#region src/protocol.ts
+var n = 1, r = {
+	lifecycleReady: "suite:lifecycle:ready",
+	hostThemeUpdate: "host:theme:update",
+	hostLocaleUpdate: "host:locale:update",
+	hostContextUpdate: "host:context:update",
+	hostPermissionGrant: "host:permission:grant",
+	hostPermissionDeny: "host:permission:deny",
+	suiteNotificationShow: "suite:notification:show",
+	suiteDialogConfirm: "suite:dialog:confirm",
+	suiteNavigationOpen: "suite:navigation:open",
+	suiteWindowFocus: "suite:window:focus",
+	suiteWindowTitleUpdate: "suite:window:title:update",
+	suiteWindowDirtyUpdate: "suite:window:dirty:update",
+	suiteFileOpen: "suite:file:open",
+	suiteFileSave: "suite:file:save",
+	suiteLogEvent: "suite:log:event",
+	suiteErrorReport: "suite:error:report",
+	suiteLifecycleHeartbeat: "suite:lifecycle:heartbeat",
+	suiteLifecycleStatus: "suite:lifecycle:status"
+};
+function i(e) {
+	if (!e || typeof e != "object") return !1;
+	let t = e;
+	return t.protocolVersion === 1 && (t.source === "vust-suite" || t.source === "vust-host") && typeof t.type == "string";
+}
+function a(e, t, n) {
+	return {
+		protocolVersion: 1,
+		source: e,
+		type: t,
+		payload: n
+	};
+}
+//#endregion
+//#region src/theme.ts
+function o() {
+	return !e() || typeof window.matchMedia != "function" ? "light" : window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function s(e) {
+	return e === "light" || e === "dark" || e === "auto";
+}
+function c(e) {
+	return typeof e == "string" ? {
+		theme: s(e) ? e : "auto",
+		resolvedTheme: e === "auto" ? o() : e
+	} : !e || typeof e != "object" ? {
+		theme: "auto",
+		resolvedTheme: o()
+	} : {
+		theme: s(e.theme) ? e.theme : "auto",
+		resolvedTheme: e.resolvedTheme === "dark" || e.resolvedTheme === "light" ? e.resolvedTheme : e.theme === "dark" ? "dark" : "light"
+	};
+}
+function l(e, t) {
+	return {
+		...c(e),
+		source: t
+	};
+}
+function u(e, t) {
+	let n = "documentElement" in e ? e.documentElement : e;
+	n.dataset.theme = t.resolvedTheme, n.style.colorScheme = t.resolvedTheme;
+}
+//#endregion
+//#region src/host-bridge.ts
+function d(n) {
+	let o = n.targetOrigin ?? "*", s = !1, l = () => c(typeof n.theme == "function" ? n.theme() : n.theme), u = () => {
+		if (n.locale === void 0) return null;
+		let e = typeof n.locale == "function" ? n.locale() : n.locale;
+		return typeof e == "string" ? { locale: e } : e;
+	}, d = (e, r) => {
+		s || t(n.iframe)?.contentWindow?.postMessage(a("vust-host", e, r), o);
+	}, f = () => {
+		d(r.hostThemeUpdate, l());
+	}, p = () => {
+		let e = u();
+		e && d(r.hostLocaleUpdate, e);
+	}, m = (e) => {
+		let a = t(n.iframe);
+		if (!a || e.source !== a.contentWindow || !i(e.data)) return;
+		let o = e.data;
+		if (o.source === "vust-suite") {
+			if (o.type === r.lifecycleReady) {
+				let t = o.payload;
+				n.onReady?.(t, e), f(), t.capabilities.includes("locale") && p();
+			}
+			n.onMessage?.(o, e);
+		}
+	};
+	return e() && window.addEventListener("message", m), {
+		sendTheme: f,
+		sendLocale: p,
+		postMessage: d,
+		destroy() {
+			s = !0, e() && window.removeEventListener("message", m);
+		}
+	};
+}
+//#endregion
+//#region src/locale.ts
+function f(e) {
+	return e.trim() || void 0;
+}
+function p(e, t) {
+	let n = f(e);
+	if (!n) return;
+	if (t.length === 0 || t.includes(n)) return n;
+	let r = n.split("-")[0];
+	return t.find((e) => e.split("-")[0] === r);
+}
+function m(t, n) {
+	if (!e()) return {
+		locale: n,
+		source: "default"
+	};
+	let r = [...navigator.languages, navigator.language].filter(Boolean);
+	for (let e of r) {
+		let n = p(e, t);
+		if (n) return {
+			locale: n,
+			source: "browser"
+		};
+	}
+	return {
+		locale: n,
+		source: "default"
+	};
+}
+function h(e, t, n) {
+	let r = typeof e == "string" ? e : e?.locale;
+	return { locale: (typeof r == "string" ? p(r, t) : void 0) ?? n };
+}
+//#endregion
+//#region src/suite-bridge.ts
+function g(t = {}) {
+	let n = t.capabilities ?? ["theme"], o = t.target ?? (e() ? document : void 0), s = t.parentWindow ?? (e() ? window.parent : void 0), c = t.targetOrigin ?? "*", d = t.applyTheme ?? !0, f = t.supportedLocales ?? [], p = t.defaultLocale ?? "zh-CN", g = /* @__PURE__ */ new Map(), _ = /* @__PURE__ */ new Set(), v = /* @__PURE__ */ new Set(), y = !1, b = l("auto", "system"), x = m(f, p), S = 0, C = () => {
+		for (let e of _) e(b);
+	}, w = () => {
+		for (let e of v) e(x);
+	}, T = (e) => {
+		b = e, d && o && u(o, b), C();
+	}, E = (e) => {
+		x = e, w();
+	}, D = (e, t) => {
+		y || !s || s.postMessage(a("vust-suite", e, t), c);
+	}, O = () => !y && !!s && (!e() || s !== window), k = (e) => !n.includes("notification") || !O() ? !1 : (D(r.suiteNotificationShow, e), !0), A = (e) => !n.includes("navigation") || !O() ? !1 : (D(r.suiteNavigationOpen, e), !0), j = (e = "manual") => {
+		let t = Date.now();
+		t - S < 300 || (S = t, D(r.suiteWindowFocus, { reason: e }));
+	}, M = (e) => {
+		if (y || !i(e.data) || e.data.source !== "vust-host") return;
+		let t = e.data;
+		t.type === r.hostThemeUpdate && T(l(t.payload, "host")), t.type === r.hostLocaleUpdate && E({
+			locale: h(t.payload, f, p).locale,
+			source: "host"
+		});
+		let n = g.get(t.type);
+		if (n) for (let r of n) r(t, e);
+	}, N = e() && typeof window.matchMedia == "function" ? window.matchMedia("(prefers-color-scheme: dark)") : null, P = () => {
+		b.source !== "host" && T(l("auto", "system"));
+	}, F = () => j("pointer"), I = () => j("focus");
+	return e() && (window.addEventListener("message", M), N?.addEventListener("change", P), n.includes("window") && (document.addEventListener("pointerdown", F, !0), document.addEventListener("focusin", I, !0))), T(b), t.onThemeChange && _.add(t.onThemeChange), t.onLocaleChange && v.add(t.onLocaleChange), {
+		ready() {
+			D(r.lifecycleReady, { capabilities: n });
+		},
+		notify: k,
+		navigate: A,
+		requestWindowFocus: j,
+		postMessage: D,
+		onMessage(e, t) {
+			let n = g.get(e) ?? /* @__PURE__ */ new Set();
+			return n.add(t), g.set(e, n), () => {
+				n.delete(t), n.size === 0 && g.delete(e);
+			};
+		},
+		subscribeTheme(e) {
+			return _.add(e), e(b), () => {
+				_.delete(e);
+			};
+		},
+		subscribeLocale(e) {
+			return v.add(e), e(x), () => {
+				v.delete(e);
+			};
+		},
+		getThemeSnapshot() {
+			return b;
+		},
+		getLocaleSnapshot() {
+			return x;
+		},
+		destroy() {
+			y = !0, g.clear(), _.clear(), v.clear(), e() && (window.removeEventListener("message", M), N?.removeEventListener("change", P), document.removeEventListener("pointerdown", F, !0), document.removeEventListener("focusin", I, !0));
+		}
+	};
+}
+//#endregion
+export { n as SECLAB_SUITE_PROTOCOL_VERSION, r as SUITE_MESSAGE_TYPES, g as createSuiteBridge, d as createSuiteHostBridge };

package/dist/locale.d.ts

@@ -0,0 +1,3 @@
+import { SuiteLocalePayload, SuiteLocaleState } from './types';
+export declare function resolveBrowserLocale(supportedLocales: string[], defaultLocale: string): SuiteLocaleState;
+export declare function normalizeLocale(input: string | SuiteLocalePayload, supportedLocales: string[], defaultLocale: string): SuiteLocalePayload;

package/dist/protocol.d.ts

@@ -0,0 +1,24 @@
+import { SuiteMessage, SuiteMessageSource } from './types';
+export declare const SECLAB_SUITE_PROTOCOL_VERSION: 1;
+export declare const SUITE_MESSAGE_TYPES: {
+    readonly lifecycleReady: "suite:lifecycle:ready";
+    readonly hostThemeUpdate: "host:theme:update";
+    readonly hostLocaleUpdate: "host:locale:update";
+    readonly hostContextUpdate: "host:context:update";
+    readonly hostPermissionGrant: "host:permission:grant";
+    readonly hostPermissionDeny: "host:permission:deny";
+    readonly suiteNotificationShow: "suite:notification:show";
+    readonly suiteDialogConfirm: "suite:dialog:confirm";
+    readonly suiteNavigationOpen: "suite:navigation:open";
+    readonly suiteWindowFocus: "suite:window:focus";
+    readonly suiteWindowTitleUpdate: "suite:window:title:update";
+    readonly suiteWindowDirtyUpdate: "suite:window:dirty:update";
+    readonly suiteFileOpen: "suite:file:open";
+    readonly suiteFileSave: "suite:file:save";
+    readonly suiteLogEvent: "suite:log:event";
+    readonly suiteErrorReport: "suite:error:report";
+    readonly suiteLifecycleHeartbeat: "suite:lifecycle:heartbeat";
+    readonly suiteLifecycleStatus: "suite:lifecycle:status";
+};
+export declare function isSuiteMessage(value: unknown): value is SuiteMessage;
+export declare function createMessage<TPayload>(source: SuiteMessageSource, type: string, payload?: TPayload): SuiteMessage<TPayload>;

package/dist/suite-bridge.d.ts

@@ -0,0 +1,5 @@
+import { CreateSuiteBridgeOptions, SuiteBridge } from './types';
+/**
+ * @description 创建套件端 Bridge，负责向主控报告就绪状态并接收主控主题与语言。
+ */
+export declare function createSuiteBridge(options?: CreateSuiteBridgeOptions): SuiteBridge;

package/dist/theme.d.ts

@@ -0,0 +1,5 @@
+import { SuiteResolvedTheme, SuiteThemeMode, SuiteThemePayload, SuiteThemeSource, SuiteThemeState } from './types';
+export declare function resolveSystemTheme(): SuiteResolvedTheme;
+export declare function normalizeTheme(input: SuiteThemeMode | SuiteThemePayload): SuiteThemePayload;
+export declare function resolveThemeState(input: SuiteThemeMode | SuiteThemePayload, source: SuiteThemeSource): SuiteThemeState;
+export declare function applyThemeToTarget(target: Document | HTMLElement, theme: SuiteThemeState): void;

package/dist/types.d.ts

@@ -0,0 +1,150 @@
+import { SECLAB_SUITE_PROTOCOL_VERSION, SUITE_MESSAGE_TYPES } from './protocol';
+export type SuiteProtocolVersion = typeof SECLAB_SUITE_PROTOCOL_VERSION;
+export type SuiteMessageSource = "vust-suite" | "vust-host";
+export type SuiteResolvedTheme = "light" | "dark";
+export type SuiteThemeMode = SuiteResolvedTheme | "auto";
+export type SuiteThemeSource = "host" | "system";
+export type SuiteLocaleSource = "host" | "browser" | "default";
+export type SuiteRunMode = "hosted" | "standalone";
+export type SuiteNotificationType = "info" | "success" | "warning" | "error";
+export type SuiteCapability = "theme" | "locale" | "context" | "notification" | "dialog" | "navigation" | "window" | "file" | "diagnostics" | "heartbeat";
+export type SuiteMessageType = (typeof SUITE_MESSAGE_TYPES)[keyof typeof SUITE_MESSAGE_TYPES];
+export type SuiteMessageHandler<TPayload = unknown> = (message: SuiteMessage<TPayload>, event: MessageEvent) => void;
+export type SuiteThemeSubscriber = (theme: SuiteThemeState) => void;
+export type SuiteLocaleSubscriber = (locale: SuiteLocaleState) => void;
+export type SuiteUnsubscribe = () => void;
+export interface SuiteMessage<TPayload = unknown> {
+    protocolVersion: SuiteProtocolVersion;
+    source: SuiteMessageSource;
+    type: string;
+    id?: string;
+    requestId?: string;
+    payload?: TPayload;
+    error?: SuiteMessageError;
+}
+export interface SuiteMessageError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export interface SuiteThemeState {
+    theme: SuiteThemeMode;
+    resolvedTheme: SuiteResolvedTheme;
+    source: SuiteThemeSource;
+}
+export interface SuiteThemePayload {
+    theme: SuiteThemeMode;
+    resolvedTheme: SuiteResolvedTheme;
+}
+export interface SuiteLocaleState {
+    locale: string;
+    source: SuiteLocaleSource;
+}
+export interface SuiteLocalePayload {
+    locale: string;
+}
+export interface SuiteContextPayload {
+    suiteId: string;
+    instanceId?: string;
+    appId?: string;
+    runMode: SuiteRunMode;
+    basePath?: string;
+    user?: {
+        id: string;
+        name?: string;
+    };
+    node?: {
+        id: string;
+        name?: string;
+    };
+}
+export interface SuiteNotificationPayload {
+    type?: SuiteNotificationType;
+    title: string;
+    message?: string;
+    duration?: number;
+}
+export interface SuiteConfirmDialogPayload {
+    title: string;
+    message?: string;
+    confirmText?: string;
+    cancelText?: string;
+    danger?: boolean;
+}
+export interface SuiteNavigationPayload {
+    target: "app" | "url" | "suite-center" | "desktop";
+    value?: string;
+    payload?: Record<string, unknown>;
+    external?: boolean;
+}
+export interface SuiteWindowTitlePayload {
+    title: string;
+}
+/**
+ * 套件请求主控聚焦承载窗口的原因，用于后续诊断或策略分流。
+ */
+export interface SuiteWindowFocusPayload {
+    reason: "pointer" | "focus" | "manual";
+}
+export interface SuiteWindowDirtyPayload {
+    dirty: boolean;
+}
+export interface SuiteLogEventPayload {
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+    details?: unknown;
+}
+export interface SuiteLifecycleStatusPayload {
+    status: "ready" | "busy" | "idle" | "error";
+    message?: string;
+}
+export interface SuiteReadyPayload {
+    capabilities: SuiteCapability[];
+}
+export interface CreateSuiteBridgeOptions {
+    capabilities?: SuiteCapability[];
+    target?: Document | HTMLElement;
+    parentWindow?: Window;
+    targetOrigin?: string;
+    applyTheme?: boolean;
+    supportedLocales?: string[];
+    defaultLocale?: string;
+    onThemeChange?: SuiteThemeSubscriber;
+    onLocaleChange?: SuiteLocaleSubscriber;
+}
+export interface SuiteBridge {
+    ready: () => void;
+    /**
+     * 请求主控展示统一通知；独立运行或主控不可用时返回 false，套件应使用本地通知降级。
+     */
+    notify: (payload: SuiteNotificationPayload) => boolean;
+    /**
+     * 请求主控执行导航动作，例如打开主控内置应用或跳转外链。
+     */
+    navigate: (payload: SuiteNavigationPayload) => boolean;
+    /**
+     * 手动请求主控聚焦承载窗口；常规点击和焦点变化由 SDK 自动上报。
+     */
+    requestWindowFocus: () => void;
+    postMessage: <TPayload = unknown>(type: string, payload?: TPayload) => void;
+    onMessage: <TPayload = unknown>(type: string, handler: SuiteMessageHandler<TPayload>) => SuiteUnsubscribe;
+    subscribeTheme: (subscriber: SuiteThemeSubscriber) => SuiteUnsubscribe;
+    subscribeLocale: (subscriber: SuiteLocaleSubscriber) => SuiteUnsubscribe;
+    getThemeSnapshot: () => SuiteThemeState;
+    getLocaleSnapshot: () => SuiteLocaleState;
+    destroy: () => void;
+}
+export interface CreateSuiteHostBridgeOptions {
+    iframe: HTMLIFrameElement | (() => HTMLIFrameElement | null);
+    theme: SuiteThemeMode | SuiteThemePayload | (() => SuiteThemeMode | SuiteThemePayload);
+    locale?: string | SuiteLocalePayload | (() => string | SuiteLocalePayload);
+    targetOrigin?: string;
+    onReady?: (payload: SuiteReadyPayload, event: MessageEvent) => void;
+    onMessage?: SuiteMessageHandler;
+}
+export interface SuiteHostBridge {
+    sendTheme: () => void;
+    sendLocale: () => void;
+    postMessage: <TPayload = unknown>(type: string, payload?: TPayload) => void;
+    destroy: () => void;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@vustcc/suite-sdk",
+  "version": "0.1.0-alpha.1",
+  "description": "VUST Suite Integration SDK",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vustcc/vust-ui.git",
+    "directory": "packages/suite-sdk"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build",
+    "type-check": "tsc --noEmit -p tsconfig.json"
+  }
+}