@aiot-nexus/plugin-sdk 3.1.1 → 3.3.0

package/README.md

@@ -1,15 +1,20 @@
 # @aiot-nexus/plugin-sdk
 
-> 当前 SDK 包版本为 `3.1.1`，Framework API 为 `3.1.0`，manifest schema 保持 `1`。Framework 3 将可信插件的 `mainEntry` 直接加载到 Nexus Electron 主进程；它不是安全沙箱。PluginFrame iframe 仍保持 sandbox、无 Node/Electron 访问。宿主运行模型见 [Framework v3 架构](../docs/plugin-framework-v3-architecture.md)。
+> 当前 SDK 包版本为 `3.3.0`，Framework API 为 `3.2.0`，manifest schema 保持 `1`。Framework 3 将可信插件的 `mainEntry` 直接加载到 AIoT Toolkits Electron 主进程；它不是安全沙箱。PluginFrame iframe 仍保持 sandbox、无 Node/Electron 访问。宿主运行模型见 [Framework v3 架构](../docs/plugin-framework-v3-architecture.md)。
 
 本包提供公开 TypeScript 契约、PluginFrame 浏览器客户端和 `nexus-plugin` CLI。v2 项目升级前请先阅读 [v2 到 v3 迁移说明](../docs/plugin-framework-v2-v3-migration.md)。完整开发流程见 [独立插件开发指南](../docs/standalone-plugin-development-guide.md)。
 
+宿主产品名为 AIoT Toolkits，SDK 包名和 `dev:nexus` 命令保持不变。
+本仓库 SDK 的 `--host` 目录参数只查找 `AIoT Toolkits.exe`，文件不存在时直接报错。
+尚未更新的已发布 SDK 应传完整路径，例如 `--host "C:\Tools\AIoT Toolkits.exe"`；
+目录自动识别的新行为需使用包含本次修改的 SDK 构建。
+
 ## 兼容基线
 
 | 项目 | 固定值 |
 | --- | --- |
-| SDK | `3.1.1` |
-| Framework API | `3.1.0` |
+| SDK | `3.3.0` |
+| Framework API | `3.2.0` |
 | Manifest schema | `1` |
 | Node 安装和构建 | `>=16.20.0 <17` |
 | Electron | `22.3.27` |
@@ -27,7 +32,7 @@ nexus-plugin create <plugin-id> --template minimal|sqlite --output <parent-direc
 nexus-plugin upgrade [plugin-project-directory] [--check] [--sdk-source <version-or-local-tgz>]
 nexus-plugin dev [plugin-project-directory]
 nexus-plugin dev:web [plugin-project-directory]
-nexus-plugin dev:nexus [plugin-project-directory] --host <nexus.exe-or-directory>
+nexus-plugin dev:nexus [plugin-project-directory] --host <host-exe-or-directory>
 ```
 
 仓库内 SDK 命令：
@@ -48,15 +53,15 @@ npm run publish:sdk
 registry 升级与只读预检：
 
 ```bash
-npx --package=@aiot-nexus/plugin-sdk@3.1.1 nexus-plugin upgrade . --check
-npx --package=@aiot-nexus/plugin-sdk@3.1.1 nexus-plugin upgrade .
+npx --package=@aiot-nexus/plugin-sdk@3.3.0 nexus-plugin upgrade . --check
+npx --package=@aiot-nexus/plugin-sdk@3.3.0 nexus-plugin upgrade .
 ```
 
 发布前或本地 tgz：
 
 ```bash
-npx --package=./aiot-nexus-plugin-sdk-3.1.1.tgz nexus-plugin upgrade . \
-  --sdk-source ./aiot-nexus-plugin-sdk-3.1.1.tgz
+npx --package=./aiot-nexus-plugin-sdk-3.3.0.tgz nexus-plugin upgrade . \
+  --sdk-source ./aiot-nexus-plugin-sdk-3.3.0.tgz
 ```
 
 CI 可以追加 `--json` 获得 `up-to-date`、`upgrade-available`、`upgraded`、`rolled-back` 或 `blocked`。`--allow-major` 只解除 major 保护，不会改写业务源码；跨 major 必须先阅读迁移指南。`--skip-project-checks` 只跳过项目 typecheck/build，安装后的 SDK、package 和 lockfile 一致性仍会验证。
@@ -67,7 +72,7 @@ CI 可以追加 `--json` 获得 `up-to-date`、`upgrade-available`、`upgraded`
 
 安装或项目验证失败时恢复备份，并在原 lockfile 存在时运行 `npm ci`。没有原 lockfile 时会运行 `npm install` 并恢复原 SDK，但无法证明完整传递依赖树与升级前一致，因此返回 `blocked` 并保留恢复数据。标准脚手架 build 的 `dist/<pluginId>` 在回滚范围内；自定义 typecheck/build 若修改其他路径，这些副作用不属于升级事务，项目必须自行管理。
 
-SDK `3.0.2` 或 `3.1.0` 升级到 `3.1.1` 后，原有 `hostApiVersion: 3.0.0` 可以保持不变。只有实际使用 `showHostStatusBar` 等 3.1 专属字段时，才把 manifest 声明提升到 `3.1.0`。SDK 3.1.1 修复了 registry 升级时把裸版本号误传给 `npm install` 的问题；全局安装 3.1.0 的用户应先把全局 CLI 更新到 3.1.1。
+SDK `3.0.x` / `3.1.x` 插件可以由 3.2.x 宿主继续加载。升级到 SDK `3.2.0` 只提供主题能力和新的契约；插件必须引用 `--nexus-color-*` 或读取 `context.theme` 才会使用宿主主题色。没有引用新变量的插件保持原有颜色；需要自定义主题时传入 `autoApplyHostTheme: false`。原有 `hostApiVersion: 3.0.0` 可以保持不变，只有实际使用 `showHostStatusBar` 时才需要声明 `hostApiVersion: 3.1.0` 或更高。SDK 3.1.1 修复 registry 升级命令丢失 npm 包名的问题，SDK 3.3.0 将 `dev:nexus --host` 目录查找目标改为 `AIoT Toolkits.exe`，均作为历史兼容说明保留。
 
 ## 创建插件
 
@@ -90,14 +95,14 @@ nexus-plugin create my-frame-plugin \
 
 ```bash
 npm run pack:sdk
-nexus-plugin create my-frame-plugin --sdk-source ./package/aiot-nexus-plugin-sdk-3.1.1.tgz --install
+nexus-plugin create my-frame-plugin --sdk-source ./package/aiot-nexus-plugin-sdk-3.3.0.tgz --install
 ```
 
-生成插件后，可以在 `src/manifest.json` 的业务入口中静态控制 Nexus 宿主状态栏。相关 manifest 片段如下，其余必填字段沿用脚手架生成值：
+生成插件后，可以在 `src/manifest.json` 的业务入口中静态控制 AIoT Toolkits 宿主状态栏。相关 manifest 片段如下，其余必填字段沿用脚手架生成值：
 
 ```json
 {
-  "hostApiVersion": "3.1.0",
+  "hostApiVersion": "3.2.0",
   "businessEntries": [
     {
       "businessId": "my-frame-plugin",
@@ -115,7 +120,7 @@ nexus-plugin create my-frame-plugin --sdk-source ./package/aiot-nexus-plugin-sdk
 
 仅显式设置为 `false` 时隐藏。字段省略或设置为 `true` 时显示；离开该业务入口后，宿主状态栏自动恢复。该字段要求 `hostApiVersion >= 3.1.0`。
 
-## Framework 3.1 mainEntry
+## Framework 3.2 mainEntry
 
 `mainEntry` 是可信 Electron 主进程代码，可直接导入 Electron、Node 内置模块和插件本地依赖：
 
@@ -183,9 +188,9 @@ function failure(code: string, message: string) {
 - `context.host.*` 直接返回 `NexusResult<T>`，不需要 `await`。
 - 注册的 operation handler 可以返回 Promise，可等待异步文件对话框、网络或其他用户交互。
 - operation 默认没有业务超时。浏览器客户端 `requestTimeoutMs` 默认是 `0`；20 秒仅用于 iframe 初始化握手。
-- 同步 Electron API 也能调用，但 `showOpenDialogSync()`、同步文件 I/O、长 CPU 任务会阻塞 Nexus 主进程、所有窗口和插件，应优先使用异步版本。
+- 同步 Electron API 也能调用，但 `showOpenDialogSync()`、同步文件 I/O、长 CPU 任务会阻塞 AIoT Toolkits 主进程、所有窗口和插件，应优先使用异步版本。
 - Framework 不跟踪插件直接创建的 Electron/Node 资源。插件必须在 `deactivate` 中自行清理。
-- Node 模块图和原生模块不能安全热卸载。已加载 `mainEntry`、依赖、原生模块或相关 manifest 变化必须重启 Nexus。
+- Node 模块图和原生模块不能安全热卸载。已加载 `mainEntry`、依赖、原生模块或相关 manifest 变化必须重启 AIoT Toolkits。
 
 Framework 3 不再提供 `context.host.electron` Facade，也没有 `electronHostControl` 权限。manifest 权限只描述 Host API 能力，不限制可信 `mainEntry` 直接调用 Electron/Node。SDK 保留 `createPluginElectronIpcChannel()` 和 `createPluginElectronProtocolScheme()` 作为命名约定帮助函数；宿主不会自动隔离或清理对应注册。
 
@@ -205,6 +210,12 @@ script-src 'self'; style-src 'self' 'unsafe-inline'; worker-src 'self' blob:
 
 `createPluginFrameClient()` 的首次初始化默认等待 20 秒。业务请求默认不设超时；只有插件显式传入正数 `requestTimeoutMs` 时客户端才会主动超时。进度、取消和恢复仍建议使用 `taskId + getStatus + cancel`，但这是任务 UX 和资源管理策略，不是 worker 存活要求。通信契约见 [插件 IPC 与事件通知示例](../docs/plugin-ipc-event-notification-example.md)。
 
+### 宿主主题色
+
+Framework 3.2 在 `PluginRendererContext.theme` 中提供 `light` 和 `dark` 两套语义 palette。SDK frame client 默认把当前 palette 的固定白名单字段写入 `--nexus-color-*`，并设置 `data-nexus-theme="light|dark"`；`themeMode: "system"` 会跟随系统主题变化。SDK 不会修改插件已有的 `--bg`、`--accent`、`data-theme` 或 `color-scheme`。
+
+SDK 升级本身只提供能力。插件需要在 CSS 中引用 `var(--nexus-color-primary, #8fc31f)` 等变量，或从 `context.theme?.dark.primary` 读取值，才会使用宿主主题色。旧宿主或缺少 `theme` 的上下文仍可正常初始化。自定义主题插件可以显式使用 `createPluginFrameClient({ autoApplyHostTheme: false })`，此时不注入变量、不设置宿主主题标记，但仍可手动读取 `context.theme`。
+
 ## SQLite 模板
 
 `sqlite` 模板默认打开 `pluginDataDirectory/plugin.db` 并初始化 `plugin_records`。工具栏“打开数据库”由 `mainEntry` 直接调用 `dialog.showOpenDialog()`；iframe 只接收数据库信息和参数化 operation。
@@ -228,7 +239,7 @@ script-src 'self'; style-src 'self' 'unsafe-inline'; worker-src 'self' blob:
 | `npm run dev:web` | 不执行 | 不可用 | 只调试 Renderer；`invokeMain` 返回 `PluginCapabilityUnsupported`。 |
 | `npm run dev` | Electron 调试宿主主进程直接加载 | 可用 | 调试真实生命周期、对话框、SQLite 和插件窗口。 |
 | `npm run dev:debug` | 同 `dev` | 可用 | Electron 主进程以 `--inspect-brk=9229` 启动。 |
-| `npm run dev:nexus -- --host ...` | 正式 Nexus 主进程直接加载 | 可用 | 最终集成和监听更新。 |
+| `npm run dev:nexus -- --host ...` | 正式 AIoT Toolkits 主进程直接加载 | 可用 | 最终集成和监听更新。 |
 
 Electron 调试壳仅保留 context 工具栏；插件 iframe 无边距、无边框，填满剩余窗口，不设置最小宽高，也不根据内容上报限制尺寸。Renderer DevTools 默认打开。
 
@@ -238,16 +249,16 @@ VS Code 模板提供 `Debug Nexus plugin` 和 `Attach Nexus plugin main process
 
 | 修改范围 | 处理方式 |
 | --- | --- |
-| `src/renderer/**` | 只构建 Renderer 并重载 iframe，Nexus PID 不变。 |
+| `src/renderer/**` | 只构建 Renderer 并重载 iframe，AIoT Toolkits PID 不变。 |
 | 无 `mainEntry` 插件的安全 manifest 展示/贡献字段 | 原子替换 manifest 并重扫，PID 不变。 |
-| 有 `mainEntry` 插件的 manifest 变化 | 完整构建并重启 Nexus。 |
-| `src/main.*`、依赖、原生模块、构建脚本 | 完整构建并重启 Nexus。 |
+| 有 `mainEntry` 插件的 manifest 变化 | 完整构建并重启 AIoT Toolkits。 |
+| `src/main.*`、依赖、原生模块、构建脚本 | 完整构建并重启 AIoT Toolkits。 |
 
-构建失败保留旧部署；新宿主启动或就绪失败会恢复旧包和旧宿主。`--inspect` / `--inspect-brk` 调试的是 Nexus Electron 主进程，因此会同时暂停或暴露宿主代码。按 `Ctrl+C` 时 CLI 关闭自己启动的宿主。
+构建失败保留旧部署；新宿主启动或就绪失败会恢复旧包和旧宿主。`--inspect` / `--inspect-brk` 调试的是 AIoT Toolkits Electron 主进程，因此会同时暂停或暴露宿主代码。按 `Ctrl+C` 时 CLI 关闭自己启动的宿主。
 
 ## 发布前检查
 
-1. `hostApiVersion` 为 `3.1.0`，manifest schema 仍为 `1`。
+1. `hostApiVersion` 使用当前 `3.2.0`（或按实际能力保持旧版本），manifest schema 仍为 `1`。
 2. 业务入口的 `showHostStatusBar` 可静态声明是否保留宿主状态栏；省略时默认保留，显式使用时要求 `hostApiVersion >= 3.1.0`。
 3. `activate/deactivate` 同步，operation handler 才使用异步。
 4. Renderer 只使用窄口径 operation，所有输入在 mainEntry 再校验。
@@ -255,4 +266,5 @@ VS Code 模板提供 `Debug Nexus plugin` 和 `Attach Nexus plugin main process
 6. IPC、protocol、快捷键、菜单和文件路径使用插件命名空间并检测冲突。
 7. `deactivate` 关闭窗口、Session 监听、IPC、protocol、快捷键、定时器、数据库和子进程。
 8. 没有同步长任务、无限载荷、任意命令/SQL/路径透传或日志敏感信息。
-9. 运行 `npm test`、插件构建、正式 Nexus 集成和 Windows 7 真机验收。
+9. 主题集成明确引用 `--nexus-color-*` / `context.theme`，或显式关闭 `autoApplyHostTheme`。
+10. 运行 `npm test`、插件构建、正式 AIoT Toolkits 集成和 Windows 7 真机验收。

package/dev-host/main.js

@@ -191,13 +191,13 @@ function activatePluginMainEntry() {
         throw new Error("Plugin activate export must be a function.");
       }
       if (isAsyncFunction(activate)) {
-        throw new Error("Plugin activate must complete synchronously in Framework API 3.1.0.");
+        throw new Error("Plugin activate must complete synchronously in Framework API 3.2.0.");
       }
       activationStarted = true;
       const result = activate(createActivationContext());
       if (isPromiseLike(result)) {
         observeRejectedLifecyclePromise(result, "activate");
-        throw new Error("Plugin activate must complete synchronously in Framework API 3.1.0.");
+        throw new Error("Plugin activate must complete synchronously in Framework API 3.2.0.");
       }
     }
     pluginActivated = true;
@@ -265,13 +265,13 @@ function deactivatePluginMainEntry(reason) {
       return;
     }
     if (typeof deactivate !== "function" || isAsyncFunction(deactivate)) {
-      process.stderr.write("[nexus-plugin-dev] plugin deactivate must complete synchronously in Framework API 3.1.0.\n");
+      process.stderr.write("[nexus-plugin-dev] plugin deactivate must complete synchronously in Framework API 3.2.0.\n");
       return;
     }
     const result = deactivate(reason);
     if (isPromiseLike(result)) {
       observeRejectedLifecyclePromise(result, "deactivate");
-      process.stderr.write("[nexus-plugin-dev] plugin deactivate must complete synchronously in Framework API 3.1.0.\n");
+      process.stderr.write("[nexus-plugin-dev] plugin deactivate must complete synchronously in Framework API 3.2.0.\n");
     }
   } catch (error) {
     process.stderr.write("[nexus-plugin-dev] plugin deactivation failed: " + errorMessage(error) + "\n");
@@ -448,6 +448,11 @@ async function verifyRendererContextSmoke() {
     || configuration.manifest.minHostVersion === undefined) {
     throw new Error("Development Host API version contract is inconsistent.");
   }
+  const frameSmokeToken = "nexus-plugin-frame-" + String(Date.now()) + "-" + String(Math.random());
+  await frame.executeJavaScript(
+    "window.__nexusPluginDevHostFrameToken = " + JSON.stringify(frameSmokeToken) + ";",
+    true
+  );
   const initialState = await readRendererContextState(frame);
   const targetLanguage = configuration.manifest.supportedCultures.find(function findAlternative(culture) {
     return culture !== configuration.language;
@@ -468,7 +473,11 @@ async function verifyRendererContextSmoke() {
     lastState = await readRendererContextState(frame);
     const languageChanged = lastState.language === targetLanguage
       && (targetLanguage === configuration.language || lastState.localizedText !== initialState.localizedText);
-    if (languageChanged && lastState.theme === targetTheme) {
+    if (languageChanged
+      && lastState.theme === targetTheme
+      && lastState.nexusTheme === targetTheme
+      && lastState.primary === sdk.NEXUS_PLUGIN_RENDERER_THEME[targetTheme].primary
+      && lastState.frameToken === frameSmokeToken) {
       return;
     }
     await new Promise(function wait(resolve) {
@@ -477,6 +486,8 @@ async function verifyRendererContextSmoke() {
   }
   throw new Error(
     "Expected language=" + targetLanguage + " and theme=" + targetTheme
+    + " and primary=" + sdk.NEXUS_PLUGIN_RENDERER_THEME[targetTheme].primary
+    + " and unchanged frame token"
     + ", received " + JSON.stringify(lastState) + "."
   );
 }
@@ -498,6 +509,9 @@ async function readRendererContextState(frame) {
   return frame.executeJavaScript(`({
     language: document.documentElement.lang,
     theme: document.documentElement.dataset.theme || "",
+    nexusTheme: document.documentElement.dataset.nexusTheme || "",
+    primary: document.documentElement.style.getPropertyValue("--nexus-color-primary").trim(),
+    frameToken: window.__nexusPluginDevHostFrameToken || "",
     localizedText: document.querySelector("[data-i18n]")
       ? document.querySelector("[data-i18n]").textContent
       : ""
@@ -525,6 +539,7 @@ function createRendererConfiguration() {
       contributionId: configuration.contributionId,
       language: configuration.language,
       themeMode: configuration.themeMode,
+      theme: sdk.NEXUS_PLUGIN_RENDERER_THEME,
       hostApiVersion: sdk.PLUGIN_FRAMEWORK_VERSION
     }
   };

package/dist/.generated/plugin-framework-version.d.ts

@@ -1,6 +1,7 @@
-export declare const PLUGIN_FRAMEWORK_VERSION = "3.1.0";
+export declare const PLUGIN_FRAMEWORK_VERSION = "3.2.0";
 export declare const PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
 export declare const PLUGIN_COMPATIBLE_VERSION_PATTERN = "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$";
+export declare const PLUGIN_VERSION_PATTERN = "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$";
 export interface ParsedPluginVersion {
     major: number;
     minor: number;

package/dist/.generated/plugin-framework-version.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isPluginFrameworkVersionCompatible = exports.comparePluginVersions = exports.parsePluginCompatibleVersion = exports.PLUGIN_COMPATIBLE_VERSION_PATTERN = exports.PLUGIN_MANIFEST_SCHEMA_VERSION = exports.PLUGIN_FRAMEWORK_VERSION = void 0;
-exports.PLUGIN_FRAMEWORK_VERSION = "3.1.0";
+exports.isPluginFrameworkVersionCompatible = exports.comparePluginVersions = exports.parsePluginCompatibleVersion = exports.PLUGIN_VERSION_PATTERN = exports.PLUGIN_COMPATIBLE_VERSION_PATTERN = exports.PLUGIN_MANIFEST_SCHEMA_VERSION = exports.PLUGIN_FRAMEWORK_VERSION = void 0;
+exports.PLUGIN_FRAMEWORK_VERSION = "3.2.0";
 exports.PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
 exports.PLUGIN_COMPATIBLE_VERSION_PATTERN = "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$";
+exports.PLUGIN_VERSION_PATTERN = "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$";
 function parsePluginCompatibleVersion(value) {
     const match = /^(0|[1-9][0-9]*)(?:\.(0|[1-9][0-9]*))?(?:\.(0|[1-9][0-9]*))?$/.exec(value.trim());
     if (!match) {

package/dist/.generated/plugin-manifest.schema.json

@@ -20,7 +20,7 @@
         "pluginId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$" },
         "displayNameKey": { "type": "string", "minLength": 1 },
         "descriptionKey": { "type": "string" },
-        "pluginVersion": { "type": "string", "minLength": 1 },
+        "pluginVersion": { "type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$" },
         "hostApiVersion": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$" },
         "minHostVersion": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$" },
         "supportedCultures": {

package/dist/.generated/theme-contract.d.ts

@@ -0,0 +1,43 @@
+export declare const NEXUS_THEME_BACKGROUND_COLORS: {
+    readonly light: "#eef1f4";
+    readonly dark: "#101418";
+};
+export declare const NEXUS_BRAND_ACCENT_KEY = "green";
+export interface PluginThemeTokens {
+    background: string;
+    surface: string;
+    surfaceAlt: string;
+    surfaceRaised: string;
+    surfaceHover: string;
+    surfaceInset: string;
+    border: string;
+    borderSoft: string;
+    borderStrong: string;
+    text: string;
+    textMuted: string;
+    textSoft: string;
+    textFaint: string;
+    primary: string;
+    accent: string;
+    onPrimary: string;
+    primarySoft: string;
+    info: string;
+    infoSoft: string;
+    positive: string;
+    positiveSoft: string;
+    warning: string;
+    warningSoft: string;
+    negative: string;
+    negativeSoft: string;
+    mutedSoft: string;
+    onInfo: string;
+    onPositive: string;
+    onWarning: string;
+    onNegative: string;
+}
+export interface PluginRendererTheme {
+    light: PluginThemeTokens;
+    dark: PluginThemeTokens;
+}
+/** Public semantic colors exposed to isolated PluginFrame renderers. */
+export declare const NEXUS_PLUGIN_RENDERER_THEME: PluginRendererTheme;

package/dist/.generated/theme-contract.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEXUS_PLUGIN_RENDERER_THEME = exports.NEXUS_BRAND_ACCENT_KEY = exports.NEXUS_THEME_BACKGROUND_COLORS = void 0;
+exports.NEXUS_THEME_BACKGROUND_COLORS = {
+    light: "#eef1f4",
+    dark: "#101418"
+};
+exports.NEXUS_BRAND_ACCENT_KEY = "green";
+/** Public semantic colors exposed to isolated PluginFrame renderers. */
+exports.NEXUS_PLUGIN_RENDERER_THEME = {
+    light: {
+        background: "#eef1f4",
+        surface: "#ffffff",
+        surfaceAlt: "#f7f9fa",
+        surfaceRaised: "#f7f9fa",
+        surfaceHover: "#eef3f6",
+        surfaceInset: "#e4e9ed",
+        border: "#d7dde3",
+        borderSoft: "#e2e7eb",
+        borderStrong: "#c2cbd3",
+        text: "#212a32",
+        textMuted: "#5a6772",
+        textSoft: "#8b97a1",
+        textFaint: "#8b97a1",
+        primary: "#8fc31f",
+        accent: "#6f9a15",
+        onPrimary: "#ffffff",
+        primarySoft: "rgba(143, 195, 31, 0.12)",
+        info: "#2277c4",
+        infoSoft: "rgba(34, 119, 196, 0.12)",
+        positive: "#1f9a4e",
+        positiveSoft: "rgba(31, 154, 78, 0.12)",
+        warning: "#e0a53a",
+        warningSoft: "rgba(224, 165, 58, 0.14)",
+        negative: "#c2402f",
+        negativeSoft: "rgba(194, 64, 47, 0.1)",
+        mutedSoft: "rgba(90, 103, 114, 0.1)",
+        onInfo: "#ffffff",
+        onPositive: "#ffffff",
+        onWarning: "#ffffff",
+        onNegative: "#ffffff"
+    },
+    dark: {
+        background: "#101418",
+        surface: "#1b222a",
+        surfaceAlt: "#171c22",
+        surfaceRaised: "#171c22",
+        surfaceHover: "#222a34",
+        surfaceInset: "#0c0f13",
+        border: "#2a333e",
+        borderSoft: "#303a45",
+        borderStrong: "#38434f",
+        text: "#e2e8ee",
+        textMuted: "#97a3af",
+        textSoft: "#64707c",
+        textFaint: "#64707c",
+        primary: "#8fc31f",
+        accent: "#a5d43e",
+        onPrimary: "#ffffff",
+        primarySoft: "rgba(143, 195, 31, 0.14)",
+        info: "#4da3e8",
+        infoSoft: "rgba(77, 163, 232, 0.14)",
+        positive: "#46b96e",
+        positiveSoft: "rgba(70, 185, 110, 0.14)",
+        warning: "#e0a53a",
+        warningSoft: "rgba(224, 165, 58, 0.14)",
+        negative: "#e2604f",
+        negativeSoft: "rgba(226, 96, 79, 0.14)",
+        mutedSoft: "rgba(151, 163, 175, 0.12)",
+        onInfo: "#101418",
+        onPositive: "#101418",
+        onWarning: "#101418",
+        onNegative: "#101418"
+    }
+};

package/dist/browser/frame-client.d.ts

@@ -10,6 +10,7 @@ export interface PluginFrameClientOptions {
     initializationTimeoutMs?: number;
     requestTimeoutMs?: number;
     autoResize?: boolean;
+    autoApplyHostTheme?: boolean;
     resizeRoot?: HTMLElement;
 }
 export type PluginFrameContextListener = (context: PluginRendererContext) => void;

package/dist/browser/frame-client.mjs

@@ -5,6 +5,40 @@ const requestMessageType = "nexus-plugin:request";
 const responseMessageType = "nexus-plugin:response";
 const resizeMessageType = "nexus-plugin:resize";
 const defaultInitializationTimeoutMs = 20000;
+const systemThemeMediaQuery = "(prefers-color-scheme: dark)";
+const themeTokenCssVariables = [
+    ["background", "--nexus-color-background"],
+    ["surface", "--nexus-color-surface"],
+    ["surfaceAlt", "--nexus-color-surface-alt"],
+    ["surfaceRaised", "--nexus-color-surface-raised"],
+    ["surfaceHover", "--nexus-color-surface-hover"],
+    ["surfaceInset", "--nexus-color-surface-inset"],
+    ["border", "--nexus-color-border"],
+    ["borderSoft", "--nexus-color-border-soft"],
+    ["borderStrong", "--nexus-color-border-strong"],
+    ["text", "--nexus-color-text"],
+    ["textMuted", "--nexus-color-text-muted"],
+    ["textSoft", "--nexus-color-text-soft"],
+    ["textFaint", "--nexus-color-text-faint"],
+    ["primary", "--nexus-color-primary"],
+    ["accent", "--nexus-color-accent"],
+    ["onPrimary", "--nexus-color-on-primary"],
+    ["primarySoft", "--nexus-color-primary-soft"],
+    ["info", "--nexus-color-info"],
+    ["infoSoft", "--nexus-color-info-soft"],
+    ["positive", "--nexus-color-positive"],
+    ["positiveSoft", "--nexus-color-positive-soft"],
+    ["warning", "--nexus-color-warning"],
+    ["warningSoft", "--nexus-color-warning-soft"],
+    ["negative", "--nexus-color-negative"],
+    ["negativeSoft", "--nexus-color-negative-soft"],
+    ["mutedSoft", "--nexus-color-muted-soft"],
+    ["onInfo", "--nexus-color-on-info"],
+    ["onPositive", "--nexus-color-on-positive"],
+    ["onWarning", "--nexus-color-on-warning"],
+    ["onNegative", "--nexus-color-on-negative"]
+];
+const hostThemeOwners = new WeakMap();
 export class PluginFrameClientError extends Error {
     constructor(code, message) {
         super(message);
@@ -21,6 +55,7 @@ export function createPluginFrameClient(options = {}) {
     const targetWindow = options.targetWindow || frameWindow.parent;
     const initializationTimeoutMs = options.initializationTimeoutMs === undefined ? defaultInitializationTimeoutMs : options.initializationTimeoutMs;
     const requestTimeoutMs = options.requestTimeoutMs === undefined ? 0 : options.requestTimeoutMs;
+    const autoApplyHostTheme = options.autoApplyHostTheme !== false;
     if (!Number.isFinite(initializationTimeoutMs) || initializationTimeoutMs <= 0) {
         throw new PluginFrameClientError("ProtocolError", "initializationTimeoutMs must be a positive finite number.");
     }
@@ -35,6 +70,16 @@ export function createPluginFrameClient(options = {}) {
     let contextTimeoutId;
     let resizeTimer;
     let resizeObserver;
+    const hostThemeOwner = Symbol("nexus-plugin-host-theme");
+    let hostThemeRoot;
+    let hostThemeMarker;
+    let hostThemePreviousMarker;
+    let hostThemeHadPreviousMarker = false;
+    const hostThemeAppliedValues = new Map();
+    const hostThemePreviousValues = new Map();
+    const systemThemeMedia = autoApplyHostTheme && typeof frameWindow.matchMedia === "function"
+        ? frameWindow.matchMedia(systemThemeMediaQuery)
+        : undefined;
     const pendingRequests = new Map();
     const contextListeners = new Set();
     let resolveContext;
@@ -52,6 +97,14 @@ export function createPluginFrameClient(options = {}) {
         }
     }, initializationTimeoutMs);
     frameWindow.addEventListener("message", handleMessage);
+    if (systemThemeMedia) {
+        if (typeof systemThemeMedia.addEventListener === "function") {
+            systemThemeMedia.addEventListener("change", handleSystemThemeChange);
+        }
+        else {
+            systemThemeMedia.addListener(handleSystemThemeChange);
+        }
+    }
     if (options.autoResize !== false) {
         frameWindow.addEventListener("resize", scheduleResize);
         const ResizeObserverConstructor = frameWindow.ResizeObserver;
@@ -124,6 +177,7 @@ export function createPluginFrameClient(options = {}) {
             const hadContext = contextValue !== undefined;
             hostOrigin = event.origin;
             contextValue = event.data.context;
+            applyCurrentHostTheme();
             if (!contextSettled) {
                 contextSettled = true;
                 if (contextTimeoutId !== undefined) {
@@ -166,6 +220,99 @@ export function createPluginFrameClient(options = {}) {
             }
         }
     }
+    function handleSystemThemeChange() {
+        if (contextValue?.themeMode === "system") {
+            applyCurrentHostTheme();
+        }
+    }
+    function applyCurrentHostTheme() {
+        if (!autoApplyHostTheme || !contextValue) {
+            return;
+        }
+        const root = frameWindow.document.documentElement;
+        if (!root?.dataset || !root.style) {
+            return;
+        }
+        initializeHostThemeOwnership(root);
+        const resolvedMode = contextValue.themeMode === "system"
+            ? (systemThemeMedia?.matches ? "dark" : "light")
+            : contextValue.themeMode;
+        root.dataset.nexusTheme = resolvedMode;
+        hostThemeMarker = resolvedMode;
+        const tokens = contextValue.theme?.[resolvedMode];
+        for (const [tokenName, cssVariable] of themeTokenCssVariables) {
+            if (tokens) {
+                const value = tokens[tokenName];
+                root.style.setProperty(cssVariable, value);
+                hostThemeAppliedValues.set(cssVariable, value);
+            }
+            else {
+                restoreHostThemeVariable(root, cssVariable);
+            }
+        }
+    }
+    function initializeHostThemeOwnership(root) {
+        if (hostThemeRoot === root) {
+            hostThemeOwners.set(root, hostThemeOwner);
+            return;
+        }
+        if (hostThemeRoot) {
+            cleanupHostTheme();
+        }
+        hostThemeRoot = root;
+        hostThemeOwners.set(root, hostThemeOwner);
+        hostThemePreviousMarker = root.dataset.nexusTheme;
+        hostThemeHadPreviousMarker = Object.prototype.hasOwnProperty.call(root.dataset, "nexusTheme");
+        hostThemePreviousValues.clear();
+        for (const [, cssVariable] of themeTokenCssVariables) {
+            hostThemePreviousValues.set(cssVariable, root.style.getPropertyValue(cssVariable));
+        }
+    }
+    function restoreHostThemeVariable(root, cssVariable) {
+        const appliedValue = hostThemeAppliedValues.get(cssVariable);
+        if (appliedValue === undefined || root.style.getPropertyValue(cssVariable) !== appliedValue) {
+            hostThemeAppliedValues.delete(cssVariable);
+            return;
+        }
+        const previousValue = hostThemePreviousValues.get(cssVariable) || "";
+        if (previousValue) {
+            root.style.setProperty(cssVariable, previousValue);
+        }
+        else {
+            root.style.removeProperty(cssVariable);
+        }
+        hostThemeAppliedValues.delete(cssVariable);
+    }
+    function cleanupHostTheme() {
+        const root = hostThemeRoot;
+        if (!root) {
+            return;
+        }
+        if (hostThemeOwners.get(root) !== hostThemeOwner) {
+            hostThemeRoot = undefined;
+            hostThemeAppliedValues.clear();
+            hostThemePreviousValues.clear();
+            return;
+        }
+        for (const [, cssVariable] of themeTokenCssVariables) {
+            restoreHostThemeVariable(root, cssVariable);
+        }
+        if (hostThemeMarker !== undefined && root.dataset.nexusTheme === hostThemeMarker) {
+            if (hostThemeHadPreviousMarker) {
+                root.dataset.nexusTheme = hostThemePreviousMarker || "";
+            }
+            else {
+                delete root.dataset.nexusTheme;
+            }
+        }
+        hostThemeOwners.delete(root);
+        hostThemeRoot = undefined;
+        hostThemeMarker = undefined;
+        hostThemePreviousMarker = undefined;
+        hostThemeHadPreviousMarker = false;
+        hostThemeAppliedValues.clear();
+        hostThemePreviousValues.clear();
+    }
     function scheduleResize() {
         if (disposed || !contextValue || options.autoResize === false) {
             return;
@@ -200,6 +347,19 @@ export function createPluginFrameClient(options = {}) {
         disposed = true;
         frameWindow.removeEventListener("message", handleMessage);
         frameWindow.removeEventListener("resize", scheduleResize);
+        if (systemThemeMedia) {
+            if (typeof systemThemeMedia.removeEventListener === "function") {
+                systemThemeMedia.removeEventListener("change", handleSystemThemeChange);
+            }
+            else {
+                systemThemeMedia.removeListener(handleSystemThemeChange);
+            }
+        }
+        cleanupHostTheme();
+        if (contextTimeoutId !== undefined) {
+            frameWindow.clearTimeout(contextTimeoutId);
+            contextTimeoutId = undefined;
+        }
         resizeObserver?.disconnect();
         if (resizeTimer !== undefined) {
             frameWindow.clearTimeout(resizeTimer);
@@ -236,8 +396,45 @@ function isPluginRendererContext(value) {
         && typeof value.contributionId === "string"
         && typeof value.language === "string"
         && (value.themeMode === "light" || value.themeMode === "dark" || value.themeMode === "system")
+        && (value.theme === undefined || isPluginRendererTheme(value.theme))
         && typeof value.hostApiVersion === "string";
 }
+function isPluginRendererTheme(value) {
+    if (!hasExactKeys(value, ["light", "dark"])) {
+        return false;
+    }
+    return isPluginThemeTokens(value.light) && isPluginThemeTokens(value.dark);
+}
+function isPluginThemeTokens(value) {
+    const tokenNames = themeTokenCssVariables.map(([tokenName]) => tokenName);
+    return hasExactKeys(value, tokenNames)
+        && tokenNames.every((tokenName) => isSafeCssColorValue(value[tokenName]));
+}
+function hasExactKeys(value, expectedKeys) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    return keys.length === expectedKeys.length && keys.every((key) => expectedKeys.includes(key));
+}
+function isSafeCssColorValue(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 64 || /[;{}]/.test(value)) {
+        return false;
+    }
+    if (/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/i.test(value)) {
+        return true;
+    }
+    const match = /^(rgb|rgba)\(([^)]+)\)$/.exec(value);
+    if (!match) {
+        return false;
+    }
+    const parts = match[2].split(",").map((part) => part.trim());
+    const expectedLength = match[1] === "rgba" ? 4 : 3;
+    if (parts.length !== expectedLength || !parts.slice(0, 3).every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255)) {
+        return false;
+    }
+    return expectedLength === 3 || /^(?:0|1|0?\.\d+)$/.test(parts[3]) && Number(parts[3]) <= 1;
+}
 function isNexusResult(value) {
     if (!isRecord(value) || typeof value.ok !== "boolean") {
         return false;

package/dist/dev-host-metadata.json

@@ -1,3 +1,3 @@
 {
-  "nexusApplicationVersion": "0.0.1"
+  "nexusApplicationVersion": "0.0.3"
 }