@aiot-nexus/plugin-sdk 2.0.2 → 2.1.1

package/dist/src/types.d.ts

@@ -1,3 +1,5 @@
+/// <reference types="node" />
+/// <reference types="node" />
 export interface NexusError {
     code: string;
     message: string;
@@ -12,8 +14,8 @@ export type NexusResult<T> = {
 };
 export type ThemeMode = "light" | "dark" | "system";
 export type LaunchPageParams = Record<string, string>;
-export type PluginPermission = "businessLog" | "settings" | "filesystem" | "udp" | "serial" | "externalProcess" | "dialog";
-export type PluginPermissionSupportState = "implemented" | "routeGuard" | "reserved";
+export type PluginPermission = "businessLog" | "settings" | "filesystem" | "udp" | "serial" | "externalProcess" | "dialog" | "electronHostControl";
+export type PluginPermissionSupportState = "implemented" | "hostControl" | "routeGuard" | "reserved";
 export interface PluginPermissionSummary {
     permission: PluginPermission;
     supportState: PluginPermissionSupportState;
@@ -111,6 +113,86 @@ export interface PluginUnsupportedCapabilityApi {
     unsupported(operation?: unknown): Promise<NexusResult<never>>;
     [operation: string]: unknown;
 }
+type ElectronExports = typeof import("electron");
+type PluginElectronFacadeScalar = string | number | boolean | bigint | null | undefined | Date | Buffer | Error;
+type PluginElectronFacadeRemoteObject = import("electron").BrowserView | import("electron").BrowserWindow | import("electron").ClientRequest | import("electron").CommandLine | import("electron").Cookies | import("electron").Debugger | import("electron").DownloadItem | import("electron").Dock | import("electron").Event | import("electron").IncomingMessage | import("electron").IpcMainEvent | import("electron").IpcMainInvokeEvent | import("electron").Menu | import("electron").MenuItem | import("electron").MessageChannelMain | import("electron").MessagePortMain | import("electron").NativeImage | import("electron").Notification | import("electron").Session | import("electron").ServiceWorkers | import("electron").ShareMenu | import("electron").TouchBar | import("electron").TouchBarButton | import("electron").TouchBarColorPicker | import("electron").TouchBarGroup | import("electron").TouchBarLabel | import("electron").TouchBarOtherItemsProxy | import("electron").TouchBarPopover | import("electron").TouchBarScrubber | import("electron").TouchBarSegmentedControl | import("electron").TouchBarSlider | import("electron").TouchBarSpacer | import("electron").Tray | import("electron").UtilityProcess | import("electron").WebContents | import("electron").WebFrameMain | import("electron").WebRequest;
+type PluginElectronFacadeArguments<T extends readonly unknown[]> = {
+    [K in keyof T]: PluginElectronFacadeArgument<T[K]>;
+};
+type PluginElectronFacadeArgument<T> = T extends PluginElectronFacadeScalar ? T : T extends PluginElectronFacadeRemoteObject ? PluginElectronFacadeModule<T> : T extends (...args: infer TArgs) => infer TResult ? (...args: PluginElectronFacadeArguments<TArgs>) => PluginElectronFacadeValue<TResult> | Promise<PluginElectronFacadeValue<TResult>> : T extends readonly unknown[] ? PluginElectronFacadeArguments<T> : T extends object ? {
+    [K in keyof T]: PluginElectronFacadeArgument<T[K]>;
+} : T;
+type PluginElectronFacadeValue<T> = T extends PromiseLike<infer TValue> ? PluginElectronFacadeValue<TValue> : T extends PluginElectronFacadeScalar ? T : T extends PluginElectronFacadeRemoteObject ? PluginElectronFacadeModule<T> : T extends readonly unknown[] ? {
+    [K in keyof T]: PluginElectronFacadeValue<T[K]>;
+} : T extends object ? {
+    readonly [K in keyof T]: PluginElectronFacadeValue<T[K]>;
+} : T;
+type PluginElectronFacadeAsyncMembers<T> = {
+    readonly [K in keyof T as T[K] extends (...args: never[]) => unknown ? K : never]: T[K] extends (...args: infer TArgs) => infer TResult ? (...args: PluginElectronFacadeArguments<TArgs>) => Promise<PluginElectronFacadeValue<TResult>> : never;
+};
+type PluginElectronFacadeConstructed<T> = T extends abstract new (...args: never[]) => infer TInstance ? TInstance : Record<string, unknown>;
+type PluginElectronFacadeConstructorArguments<T> = T extends abstract new (...args: infer TArgs) => unknown ? PluginElectronFacadeArguments<TArgs> : unknown[];
+export type PluginElectronFacadeMethod<TArgs extends readonly unknown[] = unknown[], TResult = unknown> = (...args: PluginElectronFacadeArguments<TArgs>) => Promise<PluginElectronFacadeValue<TResult>>;
+export interface PluginElectronFacadeSubscription {
+    readonly $typeName?: "ElectronEventSubscription" | string;
+    $release(): Promise<void>;
+}
+export interface PluginElectronFacadeEventSnapshot {
+    readonly defaultPrevented: boolean;
+    readonly preventDefaultSupported: false;
+    readonly senderId?: number | string;
+}
+export type PluginElectronFacadeModule<TModule = Record<string, unknown>> = PluginElectronFacadeAsyncMembers<TModule> & {
+    readonly $typeName?: string;
+    $construct(...args: PluginElectronFacadeConstructorArguments<TModule>): Promise<PluginElectronFacadeModule<PluginElectronFacadeConstructed<TModule>>>;
+    $get<TKey extends keyof TModule>(member: TKey): Promise<PluginElectronFacadeValue<TModule[TKey]>>;
+    $get(member: string): Promise<unknown>;
+    $set<TKey extends keyof TModule>(member: TKey, value: PluginElectronFacadeArgument<TModule[TKey]>): Promise<void>;
+    $set(member: string, value: unknown): Promise<void>;
+    $on(event: string, listener: (...args: unknown[]) => unknown): Promise<PluginElectronFacadeSubscription>;
+    $once(event: string, listener: (...args: unknown[]) => unknown): Promise<PluginElectronFacadeSubscription>;
+    $release(): Promise<void>;
+};
+export interface PluginElectronFacade {
+    readonly app: PluginElectronFacadeModule<ElectronExports["app"]>;
+    readonly autoUpdater: PluginElectronFacadeModule<ElectronExports["autoUpdater"]>;
+    readonly BrowserView: PluginElectronFacadeModule<ElectronExports["BrowserView"]>;
+    readonly BrowserWindow: PluginElectronFacadeModule<ElectronExports["BrowserWindow"]>;
+    readonly clipboard: PluginElectronFacadeModule<ElectronExports["clipboard"]>;
+    readonly contentTracing: PluginElectronFacadeModule<ElectronExports["contentTracing"]>;
+    readonly contextBridge: PluginElectronFacadeModule<ElectronExports["contextBridge"]>;
+    readonly crashReporter: PluginElectronFacadeModule<ElectronExports["crashReporter"]>;
+    readonly desktopCapturer: PluginElectronFacadeModule<ElectronExports["desktopCapturer"]>;
+    readonly dialog: PluginElectronFacadeModule<ElectronExports["dialog"]>;
+    readonly globalShortcut: PluginElectronFacadeModule<ElectronExports["globalShortcut"]>;
+    readonly inAppPurchase: PluginElectronFacadeModule<ElectronExports["inAppPurchase"]>;
+    readonly ipcMain: PluginElectronFacadeModule<ElectronExports["ipcMain"]>;
+    readonly ipcRenderer: PluginElectronFacadeModule<ElectronExports["ipcRenderer"]>;
+    readonly Menu: PluginElectronFacadeModule<ElectronExports["Menu"]>;
+    readonly MenuItem: PluginElectronFacadeModule<ElectronExports["MenuItem"]>;
+    readonly MessageChannelMain: PluginElectronFacadeModule<ElectronExports["MessageChannelMain"]>;
+    readonly nativeImage: PluginElectronFacadeModule<ElectronExports["nativeImage"]>;
+    readonly nativeTheme: PluginElectronFacadeModule<ElectronExports["nativeTheme"]>;
+    readonly net: PluginElectronFacadeModule<ElectronExports["net"]>;
+    readonly netLog: PluginElectronFacadeModule<ElectronExports["netLog"]>;
+    readonly Notification: PluginElectronFacadeModule<ElectronExports["Notification"]>;
+    readonly powerMonitor: PluginElectronFacadeModule<ElectronExports["powerMonitor"]>;
+    readonly powerSaveBlocker: PluginElectronFacadeModule<ElectronExports["powerSaveBlocker"]>;
+    readonly protocol: PluginElectronFacadeModule<ElectronExports["protocol"]>;
+    readonly pushNotifications: PluginElectronFacadeModule<ElectronExports["pushNotifications"]>;
+    readonly safeStorage: PluginElectronFacadeModule<ElectronExports["safeStorage"]>;
+    readonly screen: PluginElectronFacadeModule<ElectronExports["screen"]>;
+    readonly session: PluginElectronFacadeModule<ElectronExports["session"]>;
+    readonly ShareMenu: PluginElectronFacadeModule<ElectronExports["ShareMenu"]>;
+    readonly shell: PluginElectronFacadeModule<ElectronExports["shell"]>;
+    readonly systemPreferences: PluginElectronFacadeModule<ElectronExports["systemPreferences"]>;
+    readonly TouchBar: PluginElectronFacadeModule<ElectronExports["TouchBar"]>;
+    readonly Tray: PluginElectronFacadeModule<ElectronExports["Tray"]>;
+    readonly utilityProcess: PluginElectronFacadeModule<ElectronExports["utilityProcess"]>;
+    readonly webContents: PluginElectronFacadeModule<ElectronExports["webContents"]>;
+    readonly webFrame: PluginElectronFacadeModule<ElectronExports["webFrame"]>;
+    readonly webFrameMain: PluginElectronFacadeModule<ElectronExports["webFrameMain"]>;
+}
 export interface PluginHostApi {
     readonly hostVersion: string;
     readonly hostApiVersion: string;
@@ -123,6 +205,7 @@ export interface PluginHostApi {
     log(level: PluginHostLogLevel, message: string, exception?: string): Promise<NexusResult<BusinessLogEntry>>;
     getSettings(): Promise<NexusResult<PluginSettingsDocument>>;
     updateSettings(values: Record<string, unknown>): Promise<NexusResult<PluginSettingsDocument>>;
+    readonly electron: PluginElectronFacade;
     filesystem: PluginUnsupportedCapabilityApi;
     udp: PluginUnsupportedCapabilityApi;
     serial: PluginUnsupportedCapabilityApi;
@@ -143,3 +226,4 @@ export interface PluginMainModule {
         deactivate?: (reason: string) => unknown;
     };
 }
+export {};

package/dist/src/web-dev.js

@@ -34,8 +34,8 @@ 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'";
+const pluginContentSecurityPolicy = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; worker-src 'self' blob:; 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'; worker-src 'self' blob:; 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiot-nexus/plugin-sdk",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "Types, PluginFrame client, and CLI for AIoT Nexus independent plugins.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -37,7 +37,8 @@
     "build": "node scripts/build.js",
     "postinstall": "node scripts/sdk-update-check.js --install",
     "verify:package": "node scripts/verify-package.js",
-    "test": "npm run build && node tests/package.test.js && node tests/sdk-update-check.test.js && node tests/cli.test.js && node tests/cli-entry.test.js && node tests/update-notice.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",
+    "test:types": "tsc -p tsconfig.types-test.json",
+    "test": "npm run build && npm run test:types && node tests/package.test.js && node tests/sdk-update-check.test.js && node tests/cli.test.js && node tests/cli-entry.test.js && node tests/update-notice.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"
@@ -45,8 +46,12 @@
   "dependencies": {
     "ajv": "8.17.1"
   },
+  "peerDependencies": {
+    "electron": "22.3.27"
+  },
   "devDependencies": {
     "@types/node": "16.18.126",
+    "electron": "22.3.27",
     "typescript": "4.9.4"
   },
   "engines": {

package/templates/minimal/README.md.tmpl

@@ -17,13 +17,94 @@ The check follows the npm-configured registry, falls back to the official npm re
 
 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 host coordinates worker shutdown, atomic replacement, and worker reactivation without changing the Nexus PID.
 
-The renderer calls the plugin-worker `demo.echo` operation through `@aiot-nexus/plugin-sdk`. Run `npm run validate` after changing the manifest or output layout.
+## Electron Facade file dialogs
 
-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.
+`mainEntry` receives an asynchronous Electron 22 Facade through `context.host.electron`. A regular plugin can open native file, folder, and save dialogs without declaring `electronHostControl` or the legacy `dialog` permission:
+
+```ts
+import * as fs from "fs/promises";
+import type { NexusResult, PluginMainActivationContext } from "@aiot-nexus/plugin-sdk";
+
+const maximumTextFileBytes = 1024 * 1024;
+
+export async function chooseAndReadText(
+  context: PluginMainActivationContext
+): Promise<NexusResult<string | undefined>> {
+  const result = await context.host.electron.dialog.showOpenDialog({
+    properties: ["openFile"],
+    filters: [{ name: "Text", extensions: ["txt", "md", "json"] }]
+  });
+  if (result.canceled || !result.filePaths[0]) {
+    return { ok: true, value: undefined };
+  }
+  return readTextFileBounded(result.filePaths[0]);
+}
+
+async function readTextFileBounded(filePath: string): Promise<NexusResult<string>> {
+  try {
+    const file = await fs.open(filePath, "r");
+    try {
+      const stat = await file.stat();
+      if (!stat.isFile()) {
+        return failure("FileNotReadable", "The selected path is not a regular file.");
+      }
+      if (stat.size > maximumTextFileBytes) {
+        return failure("FileTooLarge", "The selected text file exceeds the 1 MiB limit.");
+      }
+
+      // The extra byte detects a file that grows after stat without an unbounded allocation.
+      const buffer = Buffer.alloc(maximumTextFileBytes + 1);
+      let totalBytes = 0;
+      while (totalBytes < buffer.length) {
+        const { bytesRead } = await file.read(
+          buffer,
+          totalBytes,
+          buffer.length - totalBytes,
+          totalBytes
+        );
+        if (bytesRead === 0) {
+          break;
+        }
+        totalBytes += bytesRead;
+      }
+      if (totalBytes > maximumTextFileBytes) {
+        return failure("FileTooLarge", "The selected text file exceeds the 1 MiB limit.");
+      }
+      return { ok: true, value: buffer.subarray(0, totalBytes).toString("utf8") };
+    } finally {
+      await file.close();
+    }
+  } catch {
+    return failure("FileReadFailed", "The selected text file could not be read.");
+  }
+}
+
+function failure(code: string, message: string): NexusResult<never> {
+  return { ok: false, error: { code, message } };
+}
+
+export async function chooseFolder(context: PluginMainActivationContext): Promise<string | undefined> {
+  const result = await context.host.electron.dialog.showOpenDialog({
+    properties: ["openDirectory", "createDirectory"]
+  });
+  return result.canceled ? undefined : result.filePaths[0];
+}
+
+export async function chooseSavePath(context: PluginMainActivationContext): Promise<string | undefined> {
+  const result = await context.host.electron.dialog.showSaveDialog({ defaultPath: "document.txt" });
+  return result.canceled ? undefined : result.filePath;
+}
+```
+
+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 the Facade 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 Facade; use `npm run dev` or a formal Nexus host to test these dialogs.
+
+The renderer calls the plugin-worker `demo.echo` operation through `@aiot-nexus/plugin-sdk`. The worker also calls `context.host.electron.app.getName()` during activation, so `npm run dev` verifies the real asynchronous Electron Facade 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 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.
 
-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: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`, create a worker, provide Electron Facade, 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.
 
 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 worker-sensitive manifest changes rebuild the full package, stop the old plugin worker, replace the package, and start a new worker while keeping the Nexus PID. Failed builds keep the previous deployment; a failed worker reload rolls the package back and restores the previous worker. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
 

package/templates/minimal/src/main.ts.tmpl

@@ -1,6 +1,7 @@
 import type { PluginMainActivationContext } from "@aiot-nexus/plugin-sdk";
 
 export async function activate(context: PluginMainActivationContext): Promise<void> {
+  const applicationName = await context.host.electron.app.getName();
   const registration = await context.host.registerRendererMethod("demo.echo", (request) => {
     const value = request.input && typeof request.input.value === "string"
       ? request.input.value.trim()
@@ -19,7 +20,7 @@ export async function activate(context: PluginMainActivationContext): Promise<vo
   if (!registration.ok) {
     throw new Error(registration.error.message);
   }
-  const logResult = await context.host.log("info", "__PLUGIN_ID__ activated.");
+  const logResult = await context.host.log("info", "__PLUGIN_ID__ activated in " + applicationName + ".");
   if (!logResult.ok) {
     throw new Error(logResult.error.message);
   }

package/templates/sqlite/README.md.tmpl

@@ -19,11 +19,39 @@ Every `npm run build` rebuilds `better-sqlite3@8.7.0` for Electron 22.3.27 with
 
 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 host coordinates worker shutdown, atomic replacement, and worker reactivation without changing the Nexus PID. Runtime data is stored in the host-provided plugin data directory and is not written into the plugin package.
 
-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.
+The template is a schema-aware SQLite database browser. It opens `plugin.db` in the plugin data directory by default and initializes the `plugin_records` sample table there. **Open Database** calls `context.host.electron.dialog.showOpenDialog()` from `mainEntry`; it accepts a single existing SQLite file, including files without an extension. A regular plugin can use this dialog Facade without `electronHostControl`. The renderer only displays the selected path and invokes parameterized operations. It never receives an Electron object and does not expose a path input, arbitrary SQL, DDL, `ATTACH`, or a SQL console.
+
+## Electron Facade database dialog
+
+The template's `sqlite.chooseDatabase` operation uses the same asynchronous Electron Facade available to other v2 plugins. The essential call in `src/main.ts` is:
+
+```ts
+const result = await context.host.electron.dialog.showOpenDialog({
+  title: "Open SQLite database",
+  properties: ["openFile"],
+  filters: [
+    { name: "SQLite databases", extensions: ["db", "db3", "sqlite", "sqlite3"] },
+    { name: "All files", extensions: ["*"] }
+  ]
+});
+
+if (!result.canceled && result.filePaths[0]) {
+  const selectedDatabasePath = result.filePaths[0];
+  // Validate the candidate before replacing the active connection.
+}
+```
+
+For related workflows, use `properties: ["openDirectory", "createDirectory"]` to choose a folder or `context.host.electron.dialog.showSaveDialog()` to choose a save path. These calls belong in `mainEntry`; the renderer should invoke a registered business operation such as `sqlite.chooseDatabase` through `client.invokeMain()` and receive only the result it needs. No `electronHostControl` or legacy `dialog` permission is required. Native dialogs are unavailable in `npm run dev:web`; use `npm run dev` or a formal Nexus host.
+
+External files are opened read/write only after a separate candidate connection can query `sqlite_schema`. Canceling the dialog or selecting a corrupt, locked, or inaccessible file keeps the current connection. The latest external path is atomically stored as `sqlite-browser-state.json` in the plugin data directory. Startup restores it when valid; otherwise the template clears the saved selection, falls back to `plugin.db`, and returns a visible notice. External databases do not receive the sample schema or journal pragma.
+
+The table selector lists ordinary user tables from the `main` schema. Dynamic headers show declared type, SQLite affinity, primary-key order, NULL, default, and generated-column metadata. The editor supports default/NULL/value modes for inserts and unchanged/NULL/value modes for updates. INTEGER input uses exact decimal integers, REAL must be finite, NUMERIC accepts integer, real, or text values, and BLOB input uses even-length hexadecimal text. The 1 MiB field and 4 MiB row limits count decoded BLOB bytes rather than hexadecimal characters. Ordinary rowid tables prefer an unshadowed built-in rowid; `WITHOUT ROWID` tables, or tables that shadow every rowid alias, fall back only to primary-key columns that are all non-NULL. A table without a unique locator remains browsable and insertable, but update and delete are unavailable. Primary-key locators larger than 16 KiB are also treated as browse-only so a page cannot copy unbounded keys into the plugin worker and iframe. Update and delete run in a transaction and must affect exactly one row. TEXT previews are capped at 16 KiB of UTF-8 data; BLOB previews show the byte length and first 32 bytes.
+
+The renderer follows `context.language` and `context.themeMode` from Nexus and preserves unfinished editor values during in-place context updates. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host. Below that toolbar, the iframe has no host padding, border, minimum size, or content-driven height and fills the remaining host viewport. This SDK template deliberately has no Quasar dependency, so its data grid uses a native `<table>` as a dependency-minimized template exception. It still provides pagination, contained horizontal scrolling, light/dark themes, `en-US` / `zh-CN`, and busy/empty/error states. 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.
 
-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: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`, create a worker, provide Electron Facade, 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. The page explicitly reports `PluginCapabilityUnsupported`; file selection, table loading, and CRUD require `npm run dev` or a formal Nexus host. 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 worker-sensitive manifest changes run the complete build (including the Electron 22.3.27 native rebuild), stop the old plugin worker, replace the package, and start a new worker in the same Nexus process. The database remains under the host-provided plugin data directory across worker replacements. Failed builds keep the previous deployment, and a failed worker reload rolls the package back and restores the previous worker. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
 

package/templates/sqlite/src/better-sqlite3.d.ts

@@ -1,12 +1,21 @@
 declare module "better-sqlite3" {
   class Database {
-    constructor(filename: string);
+    constructor(filename: string, options?: Database.Options);
+    readonly readonly: boolean;
     close(): void;
+    defaultSafeIntegers(toggle?: boolean): this;
     pragma(source: string): unknown;
     prepare(source: string): Database.Statement;
+    transaction<TResult>(action: () => TResult): () => TResult;
   }
 
   namespace Database {
+    interface Options {
+      readonly?: boolean;
+      fileMustExist?: boolean;
+      timeout?: number;
+    }
+
     interface RunResult {
       changes: number;
       lastInsertRowid: number | bigint;
@@ -16,6 +25,8 @@ declare module "better-sqlite3" {
       run(...params: unknown[]): RunResult;
       get(...params: unknown[]): unknown;
       all(...params: unknown[]): unknown[];
+      raw(toggle?: boolean): this;
+      safeIntegers(toggle?: boolean): this;
     }
   }