@aiot-nexus/plugin-sdk 1.0.1 → 1.1.0

package/dist/src/web-dev.js

@@ -0,0 +1,379 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginWebDevServerUrl = exports.createPluginWebDevServer = exports.runPluginWebDev = void 0;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+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 loopbackHost = "127.0.0.1";
+const defaultBodyLimit = 1024 * 1024;
+const browserApiPrefix = "/__nexus_plugin_dev";
+const pluginAssetPrefix = "/plugin/";
+const pluginContentSecurityPolicy = "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'";
+const hostContentSecurityPolicy = "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'none'";
+function runPluginWebDev(options, io) {
+    const projectDirectory = path.resolve(options.projectDirectory);
+    let packageKind = "auto";
+    if (options.build) {
+        io.stdout("Building plugin UI with development source maps: " + projectDirectory);
+        packageKind = (0, dev_1.buildPluginRendererForDevelopment)(projectDirectory);
+        if (packageKind === "package") {
+            io.stdout("Plugin project has no build:web script; using its full build output for compatibility.");
+        }
+    }
+    const target = (0, dev_1.preparePluginBrowserDebugTarget)({ ...options, projectDirectory }, packageKind);
+    const server = createPluginWebDevServer(target, io);
+    server.once("error", (error) => {
+        io.stderr("Plugin browser dev host failed: " + error.message);
+        process.exitCode = 1;
+    });
+    server.listen(options.port, loopbackHost, () => {
+        const url = pluginWebDevServerUrl(server);
+        io.stdout("Plugin browser UI host: " + url
+            + "\nPlugin package: " + target.packageDirectory
+            + "\nContribution: " + target.surface + ":" + target.contributionId
+            + "\nMain entry: disabled in browser UI mode");
+        if (options.openBrowser) {
+            openDefaultBrowser(url, io);
+        }
+    });
+    return 0;
+}
+exports.runPluginWebDev = runPluginWebDev;
+function createPluginWebDevServer(target, io) {
+    const hostHtmlPath = path.join(resolvePackageRoot(), "dev-host", "host.html");
+    if (!fs.existsSync(hostHtmlPath) || !fs.statSync(hostHtmlPath).isFile()) {
+        throw new dev_1.PluginDevError("Plugin SDK browser host is missing: " + hostHtmlPath);
+    }
+    const runtime = { settingsValues: {} };
+    const server = http.createServer((request, response) => {
+        void handleBrowserRequest(server, target, runtime, hostHtmlPath, request, response, io).catch((error) => {
+            const statusCode = isBrowserRequestError(error) ? error.statusCode : 500;
+            if (!response.headersSent) {
+                sendJson(response, statusCode, {
+                    error: statusCode === 500 ? "Browser host request failed." : errorMessage(error)
+                });
+            }
+            else {
+                response.destroy();
+            }
+            if (statusCode === 500) {
+                io.stderr("Plugin browser host request failed: " + errorMessage(error));
+            }
+        });
+    });
+    server.on("clientError", (_error, socket) => {
+        socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
+    });
+    return server;
+}
+exports.createPluginWebDevServer = createPluginWebDevServer;
+function pluginWebDevServerUrl(server) {
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        throw new dev_1.PluginDevError("Plugin browser dev host is not listening on TCP.");
+    }
+    return "http://" + loopbackHost + ":" + String(address.port);
+}
+exports.pluginWebDevServerUrl = pluginWebDevServerUrl;
+async function handleBrowserRequest(server, target, runtime, hostHtmlPath, request, response, io) {
+    if (!requestMatchesServer(request, server)) {
+        sendJson(response, 403, { error: "Unexpected Host header." });
+        return;
+    }
+    const method = request.method || "GET";
+    const requestUrl = new URL(request.url || "/", pluginWebDevServerUrl(server));
+    const pathname = requestUrl.pathname;
+    if ((pathname === "/" || pathname === "/index.html") && (method === "GET" || method === "HEAD")) {
+        sendFile(response, hostHtmlPath, method === "HEAD", hostContentSecurityPolicy);
+        return;
+    }
+    if (pathname === "/favicon.ico" && (method === "GET" || method === "HEAD")) {
+        response.writeHead(204, commonHeaders());
+        response.end();
+        return;
+    }
+    if (pathname === browserApiPrefix + "/config" && method === "GET") {
+        sendJson(response, 200, createBrowserConfiguration(target, pluginWebDevServerUrl(server)));
+        return;
+    }
+    if (pathname === browserApiPrefix + "/invoke" && method === "POST") {
+        if (!requestOriginAllowed(request, pluginWebDevServerUrl(server))) {
+            sendJson(response, 403, { error: "Unexpected request origin." });
+            return;
+        }
+        const requestBody = await readJsonBody(request);
+        sendJson(response, 200, invokeBrowserHost(target, runtime, requestBody, io));
+        return;
+    }
+    if (pathname.startsWith(pluginAssetPrefix) && (method === "GET" || method === "HEAD")) {
+        const rendererFile = resolveRendererFile(target, pathname.slice(pluginAssetPrefix.length));
+        if (!rendererFile) {
+            sendJson(response, 404, { error: "Plugin renderer asset was not found." });
+            return;
+        }
+        sendFile(response, rendererFile, method === "HEAD", pluginContentSecurityPolicy);
+        return;
+    }
+    sendJson(response, 404, { error: "Not found." });
+}
+function createBrowserConfiguration(target, origin) {
+    const encodedEntry = target.manifest.rendererEntry.split("/").map(encodeURIComponent).join("/");
+    const query = new URLSearchParams({
+        surface: target.surface,
+        contributionId: target.contributionId
+    });
+    return {
+        pluginId: target.pluginId,
+        frameOrigin: origin,
+        frameUrl: origin + pluginAssetPrefix + encodedEntry + "?" + query.toString(),
+        supportedCultures: target.manifest.supportedCultures,
+        smoke: false,
+        context: pluginContext(target)
+    };
+}
+function pluginContext(target) {
+    return {
+        schemaVersion: plugin_framework_version_1.PLUGIN_MANIFEST_SCHEMA_VERSION,
+        pluginId: target.pluginId,
+        surface: target.surface,
+        contributionId: target.contributionId,
+        language: target.language,
+        themeMode: target.themeMode,
+        hostApiVersion: plugin_framework_version_1.PLUGIN_FRAMEWORK_VERSION
+    };
+}
+function invokeBrowserHost(target, runtime, request, io) {
+    if (!isRecord(request) || typeof request.method !== "string") {
+        return fail("InvalidRequest", "Plugin renderer request is invalid.");
+    }
+    const params = isRecord(request.params) ? request.params : undefined;
+    if (request.method === "getContext") {
+        return ok(pluginContext(target));
+    }
+    if (request.method === "getSettings") {
+        if (!hasPermission(target, "settings")) {
+            return fail("PluginPermissionDenied", "Plugin does not declare settings permission.");
+        }
+        return ok(settingsDocument(target, runtime));
+    }
+    if (request.method === "updateSettings") {
+        if (!hasPermission(target, "settings")) {
+            return fail("PluginPermissionDenied", "Plugin does not declare settings permission.");
+        }
+        if (!params || !isRecord(params.values)) {
+            return fail("InvalidRequest", "Plugin renderer settings update requires values.");
+        }
+        runtime.settingsValues = { ...runtime.settingsValues, ...sanitizeJsonObject(params.values) };
+        return ok(settingsDocument(target, runtime));
+    }
+    if (request.method === "appendLog") {
+        if (!hasPermission(target, "businessLog")) {
+            return fail("PluginPermissionDenied", "Plugin does not declare businessLog permission.");
+        }
+        if (!params || !isLogLevel(params.level) || typeof params.message !== "string" || !params.message.trim()) {
+            return fail("InvalidRequest", "Plugin renderer log request is invalid.");
+        }
+        const category = "plugin:" + target.pluginId
+            + (typeof params.category === "string" && params.category.trim() ? ":" + params.category.trim() : "");
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: params.level,
+            category,
+            message: params.message.trim(),
+            exception: typeof params.exception === "string" && params.exception.trim() ? params.exception.trim() : undefined
+        };
+        const output = "[nexus-plugin-web][" + entry.level + "][" + category + "] " + entry.message
+            + (entry.exception ? "\n" + entry.exception : "");
+        if (entry.level === "warn" || entry.level === "error") {
+            io.stderr(output);
+        }
+        else {
+            io.stdout(output);
+        }
+        return ok(entry);
+    }
+    if (request.method === "invokeMain") {
+        return fail("PluginCapabilityUnsupported", "Plugin mainEntry is not executed by the browser UI debug host. Use nexus-plugin dev for Host API integration.", { operation: params && typeof params.operation === "string" ? params.operation : undefined });
+    }
+    return fail("InvalidRequest", "Plugin renderer request method is invalid.", { method: request.method });
+}
+function settingsDocument(target, runtime) {
+    return {
+        schemaVersion: plugin_framework_version_1.PLUGIN_MANIFEST_SCHEMA_VERSION,
+        pluginId: target.pluginId,
+        values: runtime.settingsValues
+    };
+}
+function resolveRendererFile(target, encodedRelativePath) {
+    let relativePath;
+    try {
+        relativePath = decodeURIComponent(encodedRelativePath);
+    }
+    catch {
+        return undefined;
+    }
+    if (!relativePath || relativePath.includes("\0")) {
+        return undefined;
+    }
+    const entryPath = path.resolve(target.packageDirectory, target.manifest.rendererEntry);
+    const rendererRoot = path.dirname(entryPath);
+    const requestedPath = path.resolve(target.packageDirectory, relativePath);
+    if (!isPathInside(rendererRoot, requestedPath)
+        || !fs.existsSync(requestedPath)
+        || !fs.statSync(requestedPath).isFile()
+        || fs.lstatSync(requestedPath).isSymbolicLink()) {
+        return undefined;
+    }
+    const realRoot = fs.realpathSync(rendererRoot);
+    const realPath = fs.realpathSync(requestedPath);
+    return isPathInside(realRoot, realPath) ? realPath : undefined;
+}
+async function readJsonBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > defaultBodyLimit) {
+            throw browserRequestError(413, "Request body is too large.");
+        }
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0) {
+        throw browserRequestError(400, "Request body is required.");
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw browserRequestError(400, "Request body is not valid JSON.");
+    }
+}
+function sendFile(response, filePath, headOnly, contentSecurityPolicy) {
+    response.writeHead(200, {
+        ...commonHeaders(),
+        "Content-Type": mimeType(filePath),
+        "Content-Security-Policy": contentSecurityPolicy
+    });
+    if (headOnly) {
+        response.end();
+        return;
+    }
+    const stream = fs.createReadStream(filePath);
+    stream.on("error", () => response.destroy());
+    stream.pipe(response);
+}
+function sendJson(response, statusCode, value) {
+    const body = JSON.stringify(value);
+    response.writeHead(statusCode, {
+        ...commonHeaders(),
+        "Content-Type": "application/json; charset=utf-8",
+        "Content-Length": Buffer.byteLength(body)
+    });
+    response.end(body);
+}
+function commonHeaders() {
+    return {
+        "Cache-Control": "no-store",
+        "Cross-Origin-Resource-Policy": "same-origin",
+        "X-Content-Type-Options": "nosniff"
+    };
+}
+function requestMatchesServer(request, server) {
+    const expected = new URL(pluginWebDevServerUrl(server));
+    return request.headers.host === expected.host || request.headers.host === "localhost:" + expected.port;
+}
+function requestOriginAllowed(request, origin) {
+    return request.headers.origin === undefined || request.headers.origin === origin;
+}
+function hasPermission(target, permission) {
+    return target.manifest.permissions.includes(permission);
+}
+function sanitizeJsonObject(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function fail(code, message, details) {
+    return { ok: false, error: { code, message, details } };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isLogLevel(value) {
+    return value === "debug" || value === "info" || value === "warn" || value === "error";
+}
+function isPathInside(rootDirectory, childPath) {
+    const relative = path.relative(path.resolve(rootDirectory), path.resolve(childPath));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function mimeType(filePath) {
+    const types = {
+        ".html": "text/html; charset=utf-8",
+        ".js": "text/javascript; charset=utf-8",
+        ".mjs": "text/javascript; charset=utf-8",
+        ".css": "text/css; charset=utf-8",
+        ".json": "application/json; charset=utf-8",
+        ".svg": "image/svg+xml",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".ico": "image/x-icon",
+        ".woff": "font/woff",
+        ".woff2": "font/woff2",
+        ".ttf": "font/ttf"
+    };
+    return types[path.extname(filePath).toLowerCase()] || "application/octet-stream";
+}
+function openDefaultBrowser(url, io) {
+    const command = process.platform === "win32" ? "rundll32.exe" : process.platform === "darwin" ? "open" : "xdg-open";
+    const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+    const child = (0, child_process_1.spawn)(command, args, { detached: true, stdio: "ignore" });
+    child.once("error", (error) => {
+        io.stderr("Default browser could not be opened: " + error.message + "\nOpen " + url + " manually.");
+    });
+    child.unref();
+}
+function browserRequestError(statusCode, message) {
+    const error = new Error(message);
+    error.statusCode = statusCode;
+    return error;
+}
+function isBrowserRequestError(value) {
+    return value instanceof Error && typeof value.statusCode === "number";
+}
+function resolvePackageRoot() {
+    return path.resolve(__dirname, "..", "..");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiot-nexus/plugin-sdk",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Types, PluginFrame client, and CLI for AIoT Nexus independent plugins.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -34,8 +34,11 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "npm run build && node tests/package.test.js && node tests/cli.test.js && node tests/frame-client.test.js",
-    "pack:sdk": "npm run build && node scripts/pack.js"
+    "verify:package": "node scripts/verify-package.js",
+    "test": "npm run build && node tests/package.test.js && node tests/cli.test.js && node tests/dev.test.js && node tests/nexus-dev.test.js && node tests/frame-client.test.js && node tests/web-dev.test.js && npm run verify:package",
+    "prepack": "node scripts/prepack.js",
+    "pack:sdk": "npm run build && npm run verify:package && node scripts/pack.js",
+    "publish:sdk": "npm publish"
   },
   "dependencies": {
     "ajv": "8.17.1"

package/templates/minimal/README.md.tmpl

@@ -6,17 +6,23 @@ AIoT Nexus independent PluginFrame plugin generated from the `minimal` template.
 npm install
 npm run typecheck
 npm run build
+npm run dev:web
 npm run dev
+npm run dev:nexus -- --host C:\path\to\nexus.exe
 ```
 
 The deployable plugin package is `dist/__PLUGIN_ID__/`. Copy that directory to the Nexus executable's `Plugins/__PLUGIN_ID__/` directory, then restart Nexus.
 
 The renderer calls the main-process `demo.echo` operation through `@aiot-nexus/plugin-sdk`. Run `npm run validate` after changing the manifest or output layout.
 
-The renderer follows `context.language` from Nexus, subscribes to in-place context updates without reloading the iframe, and includes `en-US` and `zh-CN` message catalogs. 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 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. Add or edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
+
+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` 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 integration.
+
+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 rebuild the full package and restart Nexus. Failed builds keep the previous deployment, and a failed restarted host rolls back the package. 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.
 
 For main-process breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. If child-process auto attach is disabled, start `npm run dev:debug` and select `Attach Nexus plugin main (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. 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 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.

package/templates/minimal/scripts/build.js.tmpl

@@ -9,7 +9,10 @@ const ts = require("typescript");
 const pluginId = "__PLUGIN_ID__";
 const pluginRoot = path.resolve(__dirname, "..");
 const buildDirectory = path.join(pluginRoot, ".build");
-const outputDirectory = path.join(pluginRoot, "dist", pluginId);
+const rendererOnly = readRendererOnlyOption(process.argv.slice(2));
+const outputDirectory = rendererOnly
+  ? path.join(pluginRoot, ".nexus-plugin-dev", "web-package", pluginId)
+  : path.join(pluginRoot, "dist", pluginId);
 const sdkModuleSpecifier = "@aiot-nexus/plugin-sdk/browser";
 
 run();
@@ -17,12 +20,16 @@ run();
 function run() {
   fs.rmSync(buildDirectory, { recursive: true, force: true });
   fs.rmSync(outputDirectory, { recursive: true, force: true });
-  runTypeScript("tsconfig.main.json");
+  if (!rendererOnly) {
+    runTypeScript("tsconfig.main.json");
+  }
   runTypeScript("tsconfig.renderer.json");
 
   fs.mkdirSync(path.join(outputDirectory, "renderer", "assets"), { recursive: true });
   fs.copyFileSync(path.join(pluginRoot, "src", "manifest.json"), path.join(outputDirectory, "manifest.json"));
-  fs.copyFileSync(path.join(buildDirectory, "main", "main.js"), path.join(outputDirectory, "main.cjs"));
+  if (!rendererOnly) {
+    fs.copyFileSync(path.join(buildDirectory, "main", "main.js"), path.join(outputDirectory, "main.cjs"));
+  }
   fs.copyFileSync(path.join(pluginRoot, "src", "renderer", "index.html"), path.join(outputDirectory, "renderer", "index.html"));
   fs.copyFileSync(path.join(pluginRoot, "src", "renderer", "plugin.css"), path.join(outputDirectory, "renderer", "assets", "plugin.css"));
   rewriteRendererSdkImport(
@@ -31,7 +38,17 @@ function run() {
   );
   copyBrowserSdk();
   fs.rmSync(buildDirectory, { recursive: true, force: true });
-  console.log("[" + pluginId + "] built " + outputDirectory);
+  console.log("[" + pluginId + "] built " + (rendererOnly ? "browser UI package " : "") + outputDirectory);
+}
+
+function readRendererOnlyOption(args) {
+  if (args.length === 0) {
+    return false;
+  }
+  if (args.length === 1 && args[0] === "--renderer-only") {
+    return true;
+  }
+  throw new Error("Unknown build option: " + args.join(" "));
 }
 
 function runTypeScript(configName) {

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

@@ -6,6 +6,7 @@ interface EchoResponse {
 }
 
 type SupportedLanguage = "en-US" | "zh-CN";
+type ThemeMode = "light" | "dark" | "system";
 
 const englishMessages = {
   "document.title": "Plugin Echo",
@@ -58,8 +59,10 @@ const button = requireElement<HTMLButtonElement>("echoButton");
 const resultOutput = requireElement<HTMLOutputElement>("echoResult");
 const contextOutput = requireElement<HTMLElement>("pluginContext");
 const connectionState = requireElement<HTMLElement>("connectionState");
+const systemDarkMode = window.matchMedia("(prefers-color-scheme: dark)");
 
 let language: SupportedLanguage = "en-US";
+let themeMode: ThemeMode = "system";
 let pluginId = "";
 let surface = "";
 let connectionStateKey: MessageKey = "status.waiting";
@@ -77,23 +80,26 @@ input.addEventListener("keydown", (event) => {
 const stopContextUpdates = client.onContextChanged((context) => {
   pluginId = context.pluginId;
   surface = context.surface;
-  applyLanguage(resolveLanguage(context.language));
+  applyContext(context);
 });
+systemDarkMode.addEventListener("change", handleSystemThemeChange);
 window.addEventListener("beforeunload", () => {
   stopContextUpdates();
+  systemDarkMode.removeEventListener("change", handleSystemThemeChange);
   client.dispose();
 });
 
-applyLanguage(language);
-
 void client.waitForContext().then((context) => {
   pluginId = context.pluginId;
   surface = context.surface;
   connectionStateKey = "status.ready";
-  applyLanguage(resolveLanguage(context.language));
+  applyContext(context);
 }).catch((error: unknown) => {
   connectionStateKey = "status.error";
   outputState = { kind: "literal", value: errorMessage(error) };
+  applyLanguage(language);
+  applyTheme(themeMode);
+  revealPluginContent();
   renderLocalizedState();
 });
 
@@ -133,6 +139,33 @@ function applyLanguage(nextLanguage: SupportedLanguage): void {
   client.notifyResize();
 }
 
+function applyContext(context: { language: string; themeMode: ThemeMode }): void {
+  applyLanguage(resolveLanguage(context.language));
+  applyTheme(context.themeMode);
+  revealPluginContent();
+}
+
+function revealPluginContent(): void {
+  document.documentElement.dataset.contextReady = "true";
+  document.body.hidden = false;
+  client.notifyResize();
+}
+
+function applyTheme(nextThemeMode: ThemeMode): void {
+  themeMode = nextThemeMode;
+  const resolvedTheme = themeMode === "system"
+    ? (systemDarkMode.matches ? "dark" : "light")
+    : themeMode;
+  document.documentElement.dataset.theme = resolvedTheme;
+  document.documentElement.style.colorScheme = resolvedTheme;
+}
+
+function handleSystemThemeChange(): void {
+  if (themeMode === "system") {
+    applyTheme(themeMode);
+  }
+}
+
 function renderLocalizedState(): void {
   contextOutput.textContent = pluginId
     ? pluginId + " / " + localizedSurface(surface)

package/templates/minimal/src/renderer/index.html

@@ -1,12 +1,12 @@
 <!doctype html>
-<html lang="en-US">
+<html lang="en-US" data-context-ready="false">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title data-i18n="document.title">Plugin Echo</title>
     <link rel="stylesheet" href="assets/plugin.css">
   </head>
-  <body>
+  <body hidden>
     <main class="plugin-shell">
       <header class="plugin-header">
         <div>

package/templates/minimal/src/renderer/plugin.css

@@ -1,5 +1,5 @@
 :root {
-  color-scheme: light dark;
+  color-scheme: light;
   font-family: "Segoe UI", Arial, sans-serif;
   background: #f3f5f7;
   color: #20252b;
@@ -9,6 +9,10 @@
   box-sizing: border-box;
 }
 
+:root:not([data-context-ready="true"]) .plugin-shell {
+  visibility: hidden;
+}
+
 body {
   margin: 0;
   min-height: 0;
@@ -130,35 +134,38 @@ output {
   }
 }
 
-@media (prefers-color-scheme: dark) {
-  :root,
-  body {
-    background: #16191d;
-    color: #edf0f2;
-  }
+:root[data-theme="dark"] {
+  color-scheme: dark;
+  background: #16191d;
+  color: #edf0f2;
+}
 
-  .plugin-header,
-  .echo-panel {
-    border-color: #454b52;
-    background: #24282d;
-  }
+:root[data-theme="dark"] body {
+  background: #16191d;
+  color: #edf0f2;
+}
 
-  p,
-  .result-row > span {
-    color: #aeb7c2;
-  }
+:root[data-theme="dark"] .plugin-header,
+:root[data-theme="dark"] .echo-panel {
+  border-color: #454b52;
+  background: #24282d;
+}
 
-  input {
-    border-color: #59616a;
-    background: #191c20;
-    color: #edf0f2;
-  }
+:root[data-theme="dark"] p,
+:root[data-theme="dark"] .result-row > span {
+  color: #aeb7c2;
+}
 
-  .result-row {
-    border-top-color: #454b52;
-  }
+:root[data-theme="dark"] input {
+  border-color: #59616a;
+  background: #191c20;
+  color: #edf0f2;
+}
 
-  .status {
-    color: #75d6a5;
-  }
+:root[data-theme="dark"] .result-row {
+  border-top-color: #454b52;
+}
+
+:root[data-theme="dark"] .status {
+  color: #75d6a5;
 }