@aiot-nexus/plugin-sdk 3.1.1 → 3.3.0

package/dist/src/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/src/browser/frame-client.js

@@ -8,6 +8,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();
 class PluginFrameClientError extends Error {
     constructor(code, message) {
         super(message);
@@ -25,6 +59,7 @@ 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.");
     }
@@ -39,6 +74,16 @@ 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;
@@ -56,6 +101,14 @@ 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;
@@ -128,6 +181,7 @@ function createPluginFrameClient(options = {}) {
             const hadContext = contextValue !== undefined;
             hostOrigin = event.origin;
             contextValue = event.data.context;
+            applyCurrentHostTheme();
             if (!contextSettled) {
                 contextSettled = true;
                 if (contextTimeoutId !== undefined) {
@@ -170,6 +224,99 @@ 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;
@@ -204,6 +351,19 @@ 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);
@@ -241,8 +401,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/src/cli/run.js

@@ -102,7 +102,7 @@ function usage() {
         "  nexus-plugin dev:web [plugin-project-directory] [--no-build] [--no-open] [--port <port>]",
         "    [--language <culture>] [--theme system|light|dark] [--surface business|tool|settings]",
         "    [--contribution-id <id>]",
-        "  nexus-plugin dev:nexus [plugin-project-directory] --host <nexus.exe-or-directory>",
+        "  nexus-plugin dev:nexus [plugin-project-directory] --host <host-exe-or-directory>",
         "    [--inspect[=<port>] | --inspect-brk[=<port>]] [--no-devtools]",
         "    [--language <culture>] [--theme system|light|dark] [--surface business|tool|settings]",
         "    [--contribution-id <id>]"
@@ -247,7 +247,7 @@ function runNexusDev(args, io) {
         }
     }
     if (!options.hostPath) {
-        return usageError(io, "dev:nexus requires --host <nexus.exe-or-directory>.");
+        return usageError(io, "dev:nexus requires --host <host-exe-or-directory>.");
     }
     return (0, nexus_dev_1.runPluginNexusDev)(options, io).catch((error) => {
         if (error instanceof dev_1.PluginDevError) {

package/dist/src/index.d.ts

@@ -1,6 +1,7 @@
 import pluginManifestSchema from "../.generated/plugin-manifest.schema.json";
 export { pluginManifestSchema };
 export * from "../.generated/plugin-framework-version";
+export { NEXUS_PLUGIN_RENDERER_THEME } from "../.generated/theme-contract";
 export * from "./sdk-info";
 export * from "./types";
 export * from "./electron-namespaces";

package/dist/src/index.js

@@ -17,10 +17,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pluginManifestSchema = void 0;
+exports.NEXUS_PLUGIN_RENDERER_THEME = exports.pluginManifestSchema = void 0;
 const plugin_manifest_schema_json_1 = __importDefault(require("../.generated/plugin-manifest.schema.json"));
 exports.pluginManifestSchema = plugin_manifest_schema_json_1.default;
 __exportStar(require("../.generated/plugin-framework-version"), exports);
+var theme_contract_1 = require("../.generated/theme-contract");
+Object.defineProperty(exports, "NEXUS_PLUGIN_RENDERER_THEME", { enumerable: true, get: function () { return theme_contract_1.NEXUS_PLUGIN_RENDERER_THEME; } });
 __exportStar(require("./sdk-info"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./electron-namespaces"), exports);

package/dist/src/nexus-dev-deployment.js

@@ -34,9 +34,9 @@ function resolveNexusExecutable(hostPath) {
         throw new dev_1.PluginDevError("Nexus host path does not exist: " + resolved);
     }
     const stat = fs.statSync(resolved);
-    const executable = stat.isDirectory() ? path.join(resolved, "nexus.exe") : resolved;
+    const executable = stat.isDirectory() ? path.join(resolved, "AIoT Toolkits.exe") : resolved;
     if (!fs.existsSync(executable) || !fs.statSync(executable).isFile()) {
-        throw new dev_1.PluginDevError("Nexus executable is missing: " + executable);
+        throw new dev_1.PluginDevError("AIoT Toolkits executable is missing: " + executable);
     }
     if (process.platform === "win32" && path.extname(executable).toLowerCase() !== ".exe") {
         throw new dev_1.PluginDevError("Nexus host must be a Windows executable: " + executable);

package/dist/src/scaffold.js

@@ -218,7 +218,7 @@ function createPackageJson(options, sdkSource) {
         name: options.pluginId,
         version: "0.1.0",
         private: true,
-        description: options.displayName + " independent plugin for AIoT Nexus.",
+        description: options.displayName + " independent plugin for AIoT Toolkits.",
         scripts
     };
     if (options.template === "sqlite") {

package/dist/src/sdk-info.d.ts

@@ -1,4 +1,4 @@
-export declare const PLUGIN_SDK_VERSION = "3.1.1";
+export declare const PLUGIN_SDK_VERSION = "3.3.0";
 export declare const PLUGIN_SDK_NODE_ENGINE = ">=16.20.0 <17";
 export declare const PLUGIN_SDK_NPM_ENGINE = ">=6.13.4";
 export declare const PLUGIN_SDK_ELECTRON_VERSION = "22.3.27";

package/dist/src/sdk-info.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPluginSdkInfo = exports.PLUGIN_SDK_TYPES_NODE_VERSION = exports.PLUGIN_SDK_TYPESCRIPT_VERSION = exports.PLUGIN_SDK_ELECTRON_VERSION = exports.PLUGIN_SDK_NPM_ENGINE = exports.PLUGIN_SDK_NODE_ENGINE = exports.PLUGIN_SDK_VERSION = void 0;
 const plugin_framework_version_1 = require("../.generated/plugin-framework-version");
-exports.PLUGIN_SDK_VERSION = "3.1.1";
+exports.PLUGIN_SDK_VERSION = "3.3.0";
 exports.PLUGIN_SDK_NODE_ENGINE = ">=16.20.0 <17";
 exports.PLUGIN_SDK_NPM_ENGINE = ">=6.13.4";
 exports.PLUGIN_SDK_ELECTRON_VERSION = "22.3.27";

package/dist/src/types.d.ts

@@ -12,6 +12,42 @@ export type NexusResult<T> = {
 };
 export type ThemeMode = "light" | "dark" | "system";
 export type LaunchPageParams = Record<string, string>;
+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;
+}
 export type PluginPermission = "businessLog" | "settings" | "filesystem" | "udp" | "serial" | "externalProcess" | "dialog";
 export type PluginPermissionSupportState = "implemented" | "routeGuard" | "reserved";
 export interface PluginPermissionSummary {
@@ -76,6 +112,7 @@ export interface PluginRendererContext {
     launchParams?: LaunchPageParams;
     language: string;
     themeMode: ThemeMode;
+    theme?: PluginRendererTheme;
     hostApiVersion: string;
 }
 export interface PluginSettingsDocument {

package/dist/src/web-dev.js

@@ -30,6 +30,7 @@ const http = __importStar(require("http"));
 const path = __importStar(require("path"));
 const dev_1 = require("./dev");
 const plugin_framework_version_1 = require("../.generated/plugin-framework-version");
+const theme_contract_1 = require("../.generated/theme-contract");
 const loopbackHost = "127.0.0.1";
 const defaultBodyLimit = 1024 * 1024;
 const browserApiPrefix = "/__nexus_plugin_dev";
@@ -165,6 +166,7 @@ function pluginContext(target) {
         contributionId: target.contributionId,
         language: target.language,
         themeMode: target.themeMode,
+        theme: theme_contract_1.NEXUS_PLUGIN_RENDERER_THEME,
         hostApiVersion: plugin_framework_version_1.PLUGIN_FRAMEWORK_VERSION
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiot-nexus/plugin-sdk",
-  "version": "3.1.1",
+  "version": "3.3.0",
   "description": "Types, PluginFrame client, and CLI for AIoT Nexus independent plugins.",
   "license": "UNLICENSED",
   "publishConfig": {

package/templates/minimal/README.md.tmpl

@@ -1,6 +1,6 @@
 # __DISPLAY_NAME_MARKDOWN__
 
-AIoT Nexus independent PluginFrame plugin generated from the `minimal` template.
+AIoT Toolkits independent PluginFrame plugin generated from the `minimal` template.
 
 ```bash
 npm install
@@ -8,14 +8,14 @@ npm run typecheck
 npm run build
 npm run dev:web
 npm run dev
-npm run dev:nexus -- --host C:\path\to\nexus.exe
+npm run dev:nexus -- --host "C:\path\to\AIoT Toolkits.exe"
 ```
 
 SDK checks for a newer `@aiot-nexus/plugin-sdk` in two steps. The package `postinstall` refreshes a user cache; npm 7+ hides dependency lifecycle output by default, so use `npm install --foreground-scripts` to see it. The `nexus-plugin` CLI reads that cache and prints npm-style notices when it is fresh; missing or older-than-24-hours cache data is checked in the background without blocking the command. `npm install --ignore-scripts` skips only the install check, while CLI checks remain available.
 
 The check follows the npm-configured registry, falls back to the official npm registry when needed, and silently ignores offline, timeout, malformed-response, or corrupt-cache failures. Use `NEXUS_PLUGIN_SDK_UPDATE_CHECK=0` or `NO_UPDATE_NOTIFIER=1` to disable both checks. Notices never modify the project. When one appears, substitute the exact version printed by the notice for `X.Y.Z`: `npx --package=@aiot-nexus/plugin-sdk@X.Y.Z nexus-plugin upgrade . --check`, then repeat without `--check`. The transaction synchronizes package.json, package-lock.json, and node_modules, runs project checks, and rolls back on failure. A major update additionally requires `--allow-major` and the migration guide linked by the CLI; source and manifest files are never rewritten.
 
-The deployable plugin package is `dist/__PLUGIN_ID__/`. For a manual installation, stop Nexus before replacing `Plugins/__PLUGIN_ID__/`, then start it again. During development, use `npm run dev:nexus` so the CLI coordinates Nexus shutdown, atomic replacement, and restart for trusted `mainEntry` changes.
+The deployable plugin package is `dist/__PLUGIN_ID__/`. For a manual installation, stop AIoT Toolkits before replacing `Plugins/__PLUGIN_ID__/`, then start it again. During development, use `npm run dev:nexus` so the CLI coordinates AIoT Toolkits shutdown, atomic replacement, and restart for trusted `mainEntry` changes.
 
 ## Native Electron file dialogs
 
@@ -97,17 +97,21 @@ export async function chooseSavePath(): Promise<string | undefined> {
 }
 ```
 
-Call these helpers from an operation registered with `context.host.registerRendererMethod`, then let the renderer invoke that narrow operation through `client.invokeMain()`. Return the `NexusResult` from `chooseAndReadText` directly so the renderer receives the stable `FileNotReadable`, `FileTooLarge`, or `FileReadFailed` code. Do not expose Electron objects or unrestricted file paths to the iframe. For larger files, stream or paginate in `mainEntry` and return only bounded chunks or summaries instead of the whole file. `npm run dev:web` is renderer-only and deliberately has no `mainEntry`, Node filesystem, or Electron main-process API; use `npm run dev` or a formal Nexus host to test these dialogs.
+Call these helpers from an operation registered with `context.host.registerRendererMethod`, then let the renderer invoke that narrow operation through `client.invokeMain()`. Return the `NexusResult` from `chooseAndReadText` directly so the renderer receives the stable `FileNotReadable`, `FileTooLarge`, or `FileReadFailed` code. Do not expose Electron objects or unrestricted file paths to the iframe. For larger files, stream or paginate in `mainEntry` and return only bounded chunks or summaries instead of the whole file. `npm run dev:web` is renderer-only and deliberately has no `mainEntry`, Node filesystem, or Electron main-process API; use `npm run dev` or a formal AIoT Toolkits host to test these dialogs.
 
 The renderer calls the trusted-main `demo.echo` operation through `@aiot-nexus/plugin-sdk`. The main entry also calls the directly imported `app.getName()` during activation, so `npm run dev` verifies the real Electron main-process path. Run `npm run validate` after changing the manifest or output layout.
 
-The renderer follows `context.language` and `context.themeMode` from Nexus, subscribes to in-place context updates without reloading the iframe, and includes `en-US` and `zh-CN` message catalogs. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host and simulate Nexus context changes. Below that toolbar, the iframe has no host padding, border, minimum size, or content-driven height and fills the remaining host viewport. Add or edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
+The renderer follows `context.language` and `context.themeMode` from AIoT Toolkits, subscribes to in-place context updates without reloading the iframe, and includes `en-US` and `zh-CN` message catalogs. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host and simulate AIoT Toolkits context changes. Below that toolbar, the iframe has no host padding, border, minimum size, or content-driven height and fills the remaining host viewport. Add or edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
-The current SDK has no generic business-event subscription API. For a long-running operation, register a fast `job.start` operation that returns a `taskId`, then expose `job.getStatus` and optional `job.cancel` for renderer polling. See the Nexus repository's plugin IPC and event notification example for the full contract and code.
+SDK 3.2 automatically maps the active `context.theme` palette to `--nexus-color-*` variables and sets `data-nexus-theme="light|dark"` on the document root. This template consumes those variables with local light/dark fallbacks, so it still renders on an older host. Merely upgrading the SDK does not recolor custom CSS: use the namespaced variables or read the optional palette explicitly, for example `const primary = context.theme?.light.primary`.
 
-Use `npm run dev:web` for renderer-only UI work in the system browser. It runs `build:web`, writes an isolated package under `.nexus-plugin-dev/web-package/`, builds with source maps, serves only on `127.0.0.1:4173`, and opens the browser automatically. It does not execute `mainEntry`, provide Node or Electron main-process APIs, or overwrite the deployable `dist` package. Language and theme controls still simulate Nexus context, while `invokeMain` is intentionally unavailable. Pass `-- --no-open` or `-- --port <port>` when needed; use `npm run dev` for Host API and Electron integration.
+For a plugin-owned theme, create the client with `createPluginFrameClient({ autoApplyHostTheme: false })`. The palette remains available from `await client.waitForContext()`, but the SDK will not write CSS variables or `data-nexus-theme`. It never overwrites plugin-owned `--bg`, `--accent`, `data-theme`, or `color-scheme` values.
 
-Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` for live development against a compiled, packaged Nexus. The CLI atomically deploys this plugin to `<exeDir>/Plugins/__PLUGIN_ID__/`. Renderer changes rebuild and reload the iframe without changing the Nexus PID; safe manifest changes rescan contributions in the same process; `mainEntry`, dependency, native-module, or restart-sensitive manifest changes stop Nexus, replace the complete package, and start a new Nexus process because trusted modules cannot be unloaded safely from Node's module cache. Failed builds keep the previous deployment; launch or readiness failures restore the previous package and host. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
+The current SDK has no generic business-event subscription API. For a long-running operation, register a fast `job.start` operation that returns a `taskId`, then expose `job.getStatus` and optional `job.cancel` for renderer polling. See the AIoT Toolkits repository's plugin IPC and event notification example for the full contract and code.
+
+Use `npm run dev:web` for renderer-only UI work in the system browser. It runs `build:web`, writes an isolated package under `.nexus-plugin-dev/web-package/`, builds with source maps, serves only on `127.0.0.1:4173`, and opens the browser automatically. It does not execute `mainEntry`, provide Node or Electron main-process APIs, or overwrite the deployable `dist` package. Language and theme controls still simulate AIoT Toolkits context, while `invokeMain` is intentionally unavailable. Pass `-- --no-open` or `-- --port <port>` when needed; use `npm run dev` for Host API and Electron integration.
+
+Use `npm run dev:nexus -- --host "C:\path\to\AIoT Toolkits.exe"` for live development against a compiled, packaged AIoT Toolkits. The CLI atomically deploys this plugin to `<exeDir>/Plugins/__PLUGIN_ID__/`. Renderer changes rebuild and reload the iframe without changing the AIoT Toolkits PID; safe manifest changes rescan contributions in the same process; `mainEntry`, dependency, native-module, or restart-sensitive manifest changes stop AIoT Toolkits, replace the complete package, and start a new AIoT Toolkits process because trusted modules cannot be unloaded safely from Node's module cache. Failed builds keep the previous deployment; launch or readiness failures restore the previous package and host. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
 
 When this project was created from a local SDK archive, `vendor/aiot-nexus-plugin-sdk.tgz` is part of the source project and must be kept when the project is moved or committed. An explicit local upgrade copies the target archive to `vendor/aiot-nexus-plugin-sdk-<version>.tgz` and updates the exact file dependency.
 
@@ -115,4 +119,4 @@ For a local SDK archive, the tgz version remains the plugin's current SDK versio
 
 For trusted-main breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. To attach manually, start `npm run dev:debug` and select `Attach Nexus plugin main process (9229)`. Renderer DevTools opens automatically, with `src/renderer/app.ts` available through the development source map. `npm run dev` rebuilds before launch; use `npm run dev -- --no-build` only when intentionally reusing the current `dist` output.
 
-The independent host stores data under `.nexus-plugin-dev/` and mirrors the PluginFrame protocol and current Host API surface. Its simulated Nexus application version defaults to the version recorded by the SDK build; pass `npm run dev -- --host-version <X.Y.Z>` to exercise another compatibility branch. Run the deployable `dist/__PLUGIN_ID__/` in Nexus before delivery because the standalone host does not reproduce the full application shell or routing state.
+The independent host stores data under `.nexus-plugin-dev/` and mirrors the PluginFrame protocol and current Host API surface. Its simulated AIoT Toolkits application version defaults to the version recorded by the SDK build; pass `npm run dev -- --host-version <X.Y.Z>` to exercise another compatibility branch. Run the deployable `dist/__PLUGIN_ID__/` in AIoT Toolkits before delivery because the standalone host does not reproduce the full application shell or routing state.

package/templates/minimal/src/renderer/app.ts.tmpl

@@ -1,4 +1,5 @@
 import { createPluginFrameClient } from "@aiot-nexus/plugin-sdk/browser";
+import type { PluginThemeTokens } from "@aiot-nexus/plugin-sdk";
 
 interface EchoResponse {
   value: string;
@@ -139,9 +140,11 @@ function applyLanguage(nextLanguage: SupportedLanguage): void {
   client.notifyResize();
 }
 
-function applyContext(context: { language: string; themeMode: ThemeMode }): void {
+function applyContext(context: { language: string; themeMode: ThemeMode; theme?: { light: PluginThemeTokens; dark: PluginThemeTokens } }): void {
   applyLanguage(resolveLanguage(context.language));
   applyTheme(context.themeMode);
+  const resolvedMode = context.themeMode === "dark" || (context.themeMode === "system" && systemDarkMode.matches) ? "dark" : "light";
+  contextOutput.dataset.hostPrimary = context.theme?.[resolvedMode].primary || "";
   revealPluginContent();
 }