@aiot-nexus/plugin-sdk 1.0.1 → 1.1.0

package/templates/sqlite/README.md.tmpl

@@ -6,17 +6,23 @@ AIoT Nexus independent PluginFrame plugin generated from the `sqlite` 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
 ```
 
 Every `npm run build` rebuilds `better-sqlite3@8.7.0` for Electron 22.3.27 with `@electron/rebuild@3.7.2` before packaging. `npm run rebuild:native` remains available as a standalone diagnostic command.
 
 The deployable plugin package is `dist/__PLUGIN_ID__/`. Copy that directory to the Nexus executable's `Plugins/__PLUGIN_ID__/` directory, then restart Nexus. Runtime data is stored in the host-provided plugin data directory and is not written into the plugin package.
 
-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. Static labels, CRUD status messages, action buttons, validation text, and date formatting switch together. 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. Static labels, CRUD status messages, action buttons, validation text, and date formatting switch together. 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 layout, styling, localization, and responsive checks in the system browser. It runs `build:web`, writes an isolated package under `.nexus-plugin-dev/web-package/`, and does not rebuild or load `better-sqlite3`, execute `mainEntry`, copy native runtime files, or overwrite the deployable `dist` package. It builds with source maps, serves only on `127.0.0.1:4173`, and opens the browser automatically. Database operations report unsupported; use `npm run dev` for SQLite and Host API integration. Pass `-- --no-open` or `-- --port <port>` when needed.
+
+Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` to run the plugin inside a compiled, packaged Nexus. The initial deployment and every full package replacement are atomic. Renderer-only and safe manifest updates keep the Nexus PID; `mainEntry`, dependency, native-module, or restart-sensitive manifest changes run the complete build (including the Electron 22.3.27 native rebuild) before restarting Nexus. The database remains under the host-provided plugin data directory across restarts. 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. The default debug build also runs the Electron 22.3.27 native rebuild before launch. Use `npm run dev -- --no-build` only when intentionally reusing a compatible current `dist` output.
 
-The independent host stores the SQLite database and settings under `.nexus-plugin-dev/data/` 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 the SQLite database and settings under `.nexus-plugin-dev/data/` 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/sqlite/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 nodeModulesDirectory = path.join(pluginRoot, "node_modules");
 const sdkModuleSpecifier = "@aiot-nexus/plugin-sdk/browser";
 const runtimePackages = ["better-sqlite3", "bindings", "file-uri-to-path"];
@@ -17,15 +20,21 @@ const runtimePackages = ["better-sqlite3", "bindings", "file-uri-to-path"];
 run();
 
 function run() {
-  verifyNativeDependency();
+  if (!rendererOnly) {
+    verifyNativeDependency();
+  }
   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(
@@ -33,11 +42,23 @@ function run() {
     path.join(outputDirectory, "renderer", "assets", "app.js")
   );
   copyBrowserSdk();
-  for (const packageName of runtimePackages) {
-    copyRuntimePackage(packageName);
+  if (!rendererOnly) {
+    for (const packageName of runtimePackages) {
+      copyRuntimePackage(packageName);
+    }
   }
   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 verifyNativeDependency() {

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

@@ -16,6 +16,7 @@ interface SqliteRecord {
 }
 
 type SupportedLanguage = "en-US" | "zh-CN";
+type ThemeMode = "light" | "dark" | "system";
 type MessageParams = Record<string, string | number>;
 
 const englishMessages = {
@@ -133,8 +134,10 @@ const elements = {
   recordsBody: requireElement<HTMLTableSectionElement>("recordsBody"),
   statusLog: requireElement<HTMLElement>("statusLog")
 };
+const systemDarkMode = window.matchMedia("(prefers-color-scheme: dark)");
 
 let language: SupportedLanguage = "en-US";
+let themeMode: ThemeMode = "system";
 let records: SqliteRecord[] = [];
 let editingRecord: SqliteRecord | undefined;
 let pendingDeleteId: number | undefined;
@@ -154,19 +157,22 @@ elements.titleInput.addEventListener("keydown", (event) => {
   }
 });
 const stopContextUpdates = client.onContextChanged((context) => {
-  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) => {
-  applyLanguage(resolveLanguage(context.language));
+  applyContext(context);
   return refreshAll();
 }).catch((error: unknown) => {
+  applyLanguage(language);
+  applyTheme(themeMode);
+  revealPluginContent();
   writeStatusMessage("error.initializationFailed", { message: errorMessage(error) });
 });
 
@@ -389,6 +395,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 renderState(state: LocalizedState): string {
   return state.kind === "message" ? text(state.key, state.params) : state.value;
 }

package/templates/sqlite/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 SQLite</title>
     <link rel="stylesheet" href="assets/plugin.css">
   </head>
-  <body>
+  <body hidden>
     <main class="plugin-shell">
       <header class="plugin-header">
         <div>

package/templates/sqlite/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;
@@ -24,6 +28,7 @@ body {
 .plugin-header,
 .summary,
 .panel {
+  min-width: 0;
   border: 1px solid #d4d9df;
   border-radius: 8px;
   background: #ffffff;
@@ -37,6 +42,10 @@ body {
   padding: 14px 16px;
 }
 
+.plugin-header > div {
+  min-width: 0;
+}
+
 h1,
 h2,
 p {
@@ -180,6 +189,8 @@ button.button-danger {
 }
 
 .table-wrap {
+  min-width: 0;
+  max-width: 100%;
   overflow: auto;
   border: 1px solid #d4d9df;
   border-radius: 6px;
@@ -229,47 +240,50 @@ td {
   }
 }
 
-@media (prefers-color-scheme: dark) {
-  :root,
-  body {
-    background: #16191d;
-    color: #edf0f2;
-  }
+:root[data-theme="dark"] {
+  color-scheme: dark;
+  background: #16191d;
+  color: #edf0f2;
+}
 
-  .plugin-header,
-  .summary,
-  .panel {
-    border-color: #454b52;
-    background: #24282d;
-  }
+:root[data-theme="dark"] body {
+  background: #16191d;
+  color: #edf0f2;
+}
 
-  .plugin-header p,
-  .summary span,
-  #statusLog,
-  .empty-state {
-    color: #aeb7c2;
-  }
+:root[data-theme="dark"] .plugin-header,
+:root[data-theme="dark"] .summary,
+:root[data-theme="dark"] .panel {
+  border-color: #454b52;
+  background: #24282d;
+}
 
-  input,
-  textarea,
-  button.button-secondary {
-    border-color: #59616a;
-    background: #191c20;
-    color: #edf0f2;
-  }
+:root[data-theme="dark"] .plugin-header p,
+:root[data-theme="dark"] .summary span,
+:root[data-theme="dark"] #statusLog,
+:root[data-theme="dark"] .empty-state {
+  color: #aeb7c2;
+}
 
-  .table-wrap,
-  .empty-state {
-    border-color: #454b52;
-  }
+:root[data-theme="dark"] input,
+:root[data-theme="dark"] textarea,
+:root[data-theme="dark"] button.button-secondary {
+  border-color: #59616a;
+  background: #191c20;
+  color: #edf0f2;
+}
 
-  th {
-    background: #2d3238;
-    color: #d2d8de;
-  }
+:root[data-theme="dark"] .table-wrap,
+:root[data-theme="dark"] .empty-state {
+  border-color: #454b52;
+}
 
-  th,
-  td {
-    border-bottom-color: #454b52;
-  }
+:root[data-theme="dark"] th {
+  background: #2d3238;
+  color: #d2d8de;
+}
+
+:root[data-theme="dark"] th,
+:root[data-theme="dark"] td {
+  border-bottom-color: #454b52;
 }