@aiot-nexus/plugin-sdk 2.1.1 → 3.1.0

package/dev-host/main.js

@@ -2,19 +2,10 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 
 const fs = require("fs");
+const { createRequire } = require("module");
 const path = require("path");
-const { app, BrowserWindow, ipcMain, protocol, utilityProcess } = require("electron");
+const { app, BrowserWindow, ipcMain, protocol } = require("electron");
 const sdk = require(path.join(__dirname, "..", "dist", "src", "index.js"));
-const { PluginElectronFacadeBrokerService } = require(path.join(
-  __dirname,
-  "..",
-  "dist",
-  "internal",
-  "src-electron",
-  "main",
-  "plugins",
-  "plugin-electron-facade-broker.js"
-));
 
 const pluginRendererProtocol = "nexus-plugin";
 const ipcChannels = {
@@ -22,13 +13,9 @@ const ipcChannels = {
   invoke: "nexus-plugin-dev:invoke",
   frameReady: "nexus-plugin-dev:frame-ready"
 };
-const pluginPermissions = ["businessLog", "settings", "filesystem", "udp", "serial", "externalProcess", "dialog", "electronHostControl"];
+const pluginPermissions = ["businessLog", "settings", "filesystem", "udp", "serial", "externalProcess", "dialog"];
 const implementedPermissions = new Set(["businessLog", "settings"]);
-const hostControlPermissions = new Set(["electronHostControl"]);
 const routeGuardPermissions = new Set(["filesystem", "udp", "serial", "dialog"]);
-const workerProtocolVersion = 3;
-const workerOperationTimeoutMs = 15000;
-const electronFacadeBroker = new PluginElectronFacadeBrokerService();
 
 protocol.registerSchemesAsPrivileged([
   {
@@ -57,13 +44,14 @@ app.setName("Nexus Plugin Dev: " + configuration.manifest.pluginId);
 let mainWindow;
 let smokeTimeout;
 let smokeVerificationRunning = false;
-let pluginWorker;
-let workerShutdownStarted = false;
-let workerShutdownComplete = false;
+let pluginModule;
+let pluginActivated = false;
+let pluginDeactivated = false;
+const rendererOperations = new Map();
 
-app.whenReady().then(async function startDevHost() {
+app.whenReady().then(function startDevHost() {
   registerPluginRendererProtocol();
-  await startPluginWorker();
+  activatePluginMainEntry();
   registerIpcHandlers();
   createWindow();
 }).catch(failStartup);
@@ -72,26 +60,18 @@ app.on("window-all-closed", function quitAfterWindowClose() {
   app.quit();
 });
 
-app.on("before-quit", function waitForPluginWorkerShutdown(event) {
-  if (!pluginWorker || workerShutdownComplete) {
-    return;
-  }
-  event.preventDefault();
-  if (workerShutdownStarted) {
-    return;
-  }
-  workerShutdownStarted = true;
-  void pluginWorker.shutdown("quit")
-    .catch(function reportWorkerShutdownFailure(error) {
-      process.stderr.write("[nexus-plugin-dev] plugin worker shutdown failed: " + errorMessage(error) + "\n");
-    })
-    .finally(function finishPluginWorkerShutdown() {
-      electronFacadeBroker.disposePlugin(configuration.manifest.pluginId);
-      workerShutdownComplete = true;
-      app.quit();
-    });
+app.on("before-quit", function deactivateBeforeQuit() {
+  deactivatePluginMainEntry("quit");
 });
 
+process.once("SIGINT", requestSignalQuit);
+process.once("SIGTERM", requestSignalQuit);
+
+function requestSignalQuit() {
+  deactivatePluginMainEntry("quit");
+  app.quit();
+}
+
 function loadConfiguration(args) {
   const packageDirectory = requiredPathArgument(args, "--plugin-package");
   const projectDirectory = requiredPathArgument(args, "--project-directory");
@@ -107,7 +87,6 @@ function loadConfiguration(args) {
   const language = requiredArgument(args, "--language");
   const themeMode = requiredArgument(args, "--theme");
   const hostVersion = requiredArgument(args, "--host-version");
-  const workerInspector = parseWorkerInspector(args);
   if (!isStrictVersion(hostVersion)) {
     throw new Error("--host-version must use X.Y.Z format.");
   }
@@ -127,7 +106,6 @@ function loadConfiguration(args) {
     language,
     themeMode,
     hostVersion,
-    workerInspector,
     openDevTools: !args.includes("--no-devtools"),
     smoke: args.includes("--smoke"),
     devDataDirectory,
@@ -194,451 +172,233 @@ function resolvePluginRendererFile(url) {
   });
 }
 
-async function startPluginWorker() {
+function activatePluginMainEntry() {
   if (!configuration.manifest.mainEntry) {
     return;
   }
-  pluginWorker = new PluginWorkerClient(configuration);
-  electronFacadeBroker.attachPlugin(configuration.manifest.pluginId, {
-    pluginDirectory: configuration.packageDirectory,
-    hostControl: configuration.manifest.permissions.includes("electronHostControl"),
-    invokeCallback: (callbackId, args) => pluginWorker.invokeElectronCallback(callbackId, args),
-    emitEvent: (callbackId, args) => pluginWorker.emitElectronEvent(callbackId, args)
-  });
-  let ready;
+  const mainEntryPath = resolvePluginMainEntry(configuration.manifest.mainEntry);
+  const pluginRequire = createRequire(mainEntryPath);
+  const loaded = pluginRequire(mainEntryPath);
+  if (!loaded || typeof loaded !== "object") {
+    throw new Error("Plugin main entry must export an object.");
+  }
+  pluginModule = loaded;
+  let activationStarted = false;
   try {
-    ready = await pluginWorker.start();
+    const activate = loaded.activate || (loaded.default && loaded.default.activate);
+    if (activate) {
+      if (typeof activate !== "function") {
+        throw new Error("Plugin activate export must be a function.");
+      }
+      if (isAsyncFunction(activate)) {
+        throw new Error("Plugin activate must complete synchronously in Framework API 3.1.0.");
+      }
+      activationStarted = true;
+      const result = activate(createActivationContext());
+      if (isPromiseLike(result)) {
+        observeRejectedLifecyclePromise(result, "activate");
+        throw new Error("Plugin activate must complete synchronously in Framework API 3.1.0.");
+      }
+    }
+    pluginActivated = true;
+    process.stdout.write(
+      "[nexus-plugin-dev] activated " + configuration.manifest.pluginId
+      + " directly in the Electron main process with " + String(rendererOperations.size) + " renderer operation(s).\n"
+    );
   } catch (error) {
-    electronFacadeBroker.disposePlugin(configuration.manifest.pluginId);
+    if (activationStarted) {
+      runActivationCleanup(loaded);
+    }
+    rendererOperations.clear();
+    pluginModule = undefined;
     throw error;
   }
-  process.stdout.write(
-    "[nexus-plugin-dev] activated " + configuration.manifest.pluginId
-    + " with " + String(ready.operations.length) + " renderer operation(s).\n"
-  );
 }
 
-class PluginWorkerClient {
-  constructor(workerConfiguration) {
-    this.configuration = workerConfiguration;
-    this.child = undefined;
-    this.pending = new Map();
-    this.startPromise = undefined;
-    this.startResolve = undefined;
-    this.startReject = undefined;
-    this.startTimer = undefined;
-    this.shutdownPromise = undefined;
-    this.shutdownResolve = undefined;
-    this.shutdownTimer = undefined;
-    this.initializationRequestId = undefined;
-    this.requestSequence = 0;
-    this.intentionalStop = false;
-    this.ready = false;
+function resolvePluginMainEntry(relativePath) {
+  if (path.isAbsolute(relativePath)) {
+    throw new Error("Plugin mainEntry must be relative to the plugin package.");
   }
-
-  start() {
-    if (this.startPromise) {
-      return this.startPromise;
-    }
-    const startPromise = new Promise((resolve, reject) => {
-      this.startResolve = resolve;
-      this.startReject = reject;
-    });
-    this.startPromise = startPromise;
-    this.intentionalStop = false;
-    this.ready = false;
-    try {
-      this.child = utilityProcess.fork(path.join(__dirname, "plugin-host.js"), [], {
-        cwd: this.configuration.packageDirectory,
-        serviceName: "nexus-plugin-dev-" + this.configuration.manifest.pluginId,
-        stdio: this.configuration.workerInspector ? "inherit" : "ignore",
-        execArgv: this.configuration.workerInspector ? [this.configuration.workerInspector.execArg] : []
-      });
-      this.child.on("message", (message) => { void this.handleMessage(readWorkerMessage(message)); });
-      this.child.on("exit", (code) => this.handleExit(code));
-      if (!this.configuration.workerInspector || !this.configuration.workerInspector.breakOnStart) {
-        this.startTimer = setTimeout(() => {
-          this.failStart(new Error("Plugin worker activation timed out."));
-          this.kill();
-        }, 15_000);
-      }
-      const initializationRequestId = this.nextRequestId("initialize");
-      this.initializationRequestId = initializationRequestId;
-      this.post({
-        protocolVersion: workerProtocolVersion,
-        type: "initialize",
-        requestId: initializationRequestId,
-        payload: {
-          pluginId: this.configuration.manifest.pluginId,
-          pluginDirectory: this.configuration.packageDirectory,
-          pluginDataDirectory: this.configuration.pluginDataDirectory,
-          manifest: sanitizeJsonValue(this.configuration.manifest),
-          hostVersion: this.configuration.hostVersion,
-          hostApiVersion: sdk.PLUGIN_FRAMEWORK_VERSION
-        }
-      });
-    } catch (error) {
-      this.failStart(error);
-    }
-    return startPromise;
+  const resolvedPath = path.resolve(configuration.packageDirectory, relativePath);
+  if (!isPathInside(configuration.packageDirectory, resolvedPath)) {
+    throw new Error("Plugin mainEntry resolves outside the plugin package.");
   }
-
-  invoke(payload) {
-    if (!this.child || !this.ready) {
-      return Promise.resolve(fail("PluginWorkerNotReady", "Plugin worker is not ready."));
-    }
-    const requestId = this.nextRequestId("invoke");
-    return new Promise((resolve) => {
-      const pending = {
-        kind: "invoke",
-        resolve,
-        timer: setTimeout(() => {
-          if (this.pending.get(requestId) !== pending) {
-            return;
-          }
-          this.pending.delete(requestId);
-          pending.timer = undefined;
-          this.ready = false;
-          resolve(fail("PluginOperationTimeout", "Plugin worker operation timed out.", {
-            pluginId: this.configuration.manifest.pluginId,
-            operation: payload.operation,
-            timeoutMs: workerOperationTimeoutMs
-          }));
-          this.kill();
-        }, workerOperationTimeoutMs)
-      };
-      this.pending.set(requestId, pending);
-      try {
-        this.post({ protocolVersion: workerProtocolVersion, type: "invoke", requestId, payload });
-      } catch (error) {
-        this.pending.delete(requestId);
-        clearPendingTimer(pending);
-        resolve(fail("PluginWorkerExited", "Plugin worker request could not be sent.", errorMessage(error)));
-      }
-    });
-  }
-
-  invokeElectronCallback(callbackId, args) {
-    if (!this.child) {
-      return Promise.resolve(fail("PluginProcessNotReady", "Plugin worker is not available for Electron callback."));
-    }
-    const requestId = this.nextRequestId("electron-callback");
-    return new Promise((resolve) => {
-      const pending = {
-        kind: "electronCallback",
-        resolve,
-        timer: setTimeout(() => {
-          if (this.pending.get(requestId) !== pending) {
-            return;
-          }
-          this.pending.delete(requestId);
-          pending.timer = undefined;
-          resolve(fail("PluginOperationTimeout", "Electron facade callback timed out.", {
-            pluginId: this.configuration.manifest.pluginId,
-            callbackId,
-            timeoutMs: workerOperationTimeoutMs
-          }));
-        }, workerOperationTimeoutMs)
-      };
-      this.pending.set(requestId, pending);
-      try {
-        this.post({
-          protocolVersion: workerProtocolVersion,
-          type: "electronCallback",
-          requestId,
-          payload: { callbackId, args }
-        });
-      } catch (error) {
-        this.pending.delete(requestId);
-        clearPendingTimer(pending);
-        resolve(fail("PluginProcessExited", "Electron facade callback could not be sent.", errorMessage(error)));
-      }
-    });
-  }
-
-  emitElectronEvent(callbackId, args) {
-    if (!this.child) {
-      return false;
-    }
-    try {
-      this.post({
-        protocolVersion: workerProtocolVersion,
-        type: "electronEvent",
-        payload: { callbackId, args }
-      });
-      return true;
-    } catch {
-      return false;
-    }
+  if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isFile() || fs.lstatSync(resolvedPath).isSymbolicLink()) {
+    throw new Error("Plugin mainEntry was not found or is not a regular file: " + relativePath);
   }
-
-  shutdown(reason) {
-    this.intentionalStop = true;
-    if (!this.child) {
-      return Promise.resolve(ok(true));
-    }
-    if (this.shutdownPromise) {
-      return this.shutdownPromise;
-    }
-    const requestId = this.nextRequestId("shutdown");
-    this.shutdownPromise = new Promise((resolve) => {
-      this.shutdownResolve = resolve;
-      this.pending.set(requestId, { kind: "shutdown", resolve });
-      this.shutdownTimer = setTimeout(() => {
-        this.pending.delete(requestId);
-        this.shutdownResolve = undefined;
-        this.shutdownPromise = undefined;
-        const result = fail("PluginWorkerShutdownTimeout", "Plugin worker shutdown timed out.");
-        resolve(result);
-        this.kill();
-      }, 5000);
-      try {
-        this.post({ protocolVersion: workerProtocolVersion, type: "shutdown", requestId, payload: { reason: reason || "quit" } });
-      } catch (error) {
-        clearTimeout(this.shutdownTimer);
-        this.shutdownTimer = undefined;
-        this.pending.delete(requestId);
-        this.shutdownPromise = undefined;
-        resolve(fail("PluginWorkerExited", "Plugin worker shutdown could not be sent.", errorMessage(error)));
-        this.kill();
-      }
-    });
-    return this.shutdownPromise;
+  const realRoot = fs.realpathSync(configuration.packageDirectory);
+  const realPath = fs.realpathSync(resolvedPath);
+  if (!isPathInside(realRoot, realPath)) {
+    throw new Error("Plugin mainEntry resolves outside the plugin package.");
   }
+  return realPath;
+}
 
-  async handleMessage(message) {
-    if (!isRecord(message) || message.protocolVersion !== workerProtocolVersion) {
-      this.handleProtocolViolation("Plugin worker sent an invalid RPC message.");
-      return;
-    }
-    if (message.type === "ready") {
-      if (!this.startPromise
-        || this.ready
-        || message.requestId !== this.initializationRequestId
-        || !isRecord(message.payload)
-        || !Array.isArray(message.payload.operations)
-        || !message.payload.operations.every(isSafeOperationName)
-        || new Set(message.payload.operations).size !== message.payload.operations.length
-        || typeof message.payload.activatedAtUtc !== "string"
-        || !message.payload.activatedAtUtc) {
-        this.handleProtocolViolation("Plugin worker ready response did not match initialization.");
-        return;
-      }
-      clearTimeout(this.startTimer);
-      this.startTimer = undefined;
-      this.initializationRequestId = undefined;
-      this.ready = true;
-      this.startResolve?.(message.payload);
-      this.startResolve = undefined;
-      this.startReject = undefined;
-      this.startPromise = undefined;
-      return;
-    }
-    if (message.type === "hostRequest") {
-      if (!isWorkerRequestId(message.requestId)) {
-        this.handleProtocolViolation("Plugin worker Host API request id is invalid.");
-        return;
-      }
-      const result = normalizeRpcResult(await handlePluginHostRequest(this.configuration, message.payload));
-      try {
-        this.post({ protocolVersion: workerProtocolVersion, type: "hostResult", requestId: message.requestId, result });
-      } catch {
-        // The worker may have exited while a Host API request was running.
-      }
-      return;
-    }
-    if (message.type === "result") {
-      if (!isWorkerRequestId(message.requestId) || !isNexusResult(message.result)) {
-        this.handleProtocolViolation("Plugin worker result is invalid.");
-        return;
-      }
-      const pending = this.pending.get(message.requestId);
-      if (!pending) {
-        return;
-      }
-      if (pending.kind === "electronCallback") {
-        this.handleProtocolViolation("Plugin worker used a normal result for an Electron callback.");
-        return;
-      }
-      this.pending.delete(message.requestId);
-      clearPendingTimer(pending);
-      if (pending.kind === "shutdown") {
-        clearTimeout(this.shutdownTimer);
-        this.shutdownTimer = undefined;
-        this.shutdownResolve = undefined;
-        this.shutdownPromise = undefined;
-        pending.resolve(message.result);
-        this.kill();
-        return;
-      }
-      pending.resolve(message.result);
-      return;
-    }
-    if (message.type === "electronCallbackResult") {
-      if (!isWorkerRequestId(message.requestId) || !isNexusResult(message.result)) {
-        this.handleProtocolViolation("Plugin worker Electron callback result is invalid.");
-        return;
-      }
-      const pending = this.pending.get(message.requestId);
-      if (!pending) {
-        return;
-      }
-      if (pending.kind !== "electronCallback") {
-        this.handleProtocolViolation("Plugin worker used an Electron callback result for another request.");
-        return;
-      }
-      this.pending.delete(message.requestId);
-      clearPendingTimer(pending);
-      pending.resolve(message.result);
+function runActivationCleanup(loaded) {
+  try {
+    const deactivate = loaded.deactivate || (loaded.default && loaded.default.deactivate);
+    if (!deactivate) {
       return;
     }
-    if (message.type === "fatal") {
-      const error = new Error(isRecord(message.payload) && typeof message.payload.message === "string" ? message.payload.message : "Plugin worker failed.");
-      if (this.startPromise) {
-        this.failStart(error);
-      } else {
-        process.stderr.write("[nexus-plugin-dev] plugin worker failed: " + error.message + "\n");
-      }
-      this.kill();
+    if (typeof deactivate !== "function" || isAsyncFunction(deactivate)) {
+      process.stderr.write("[nexus-plugin-dev] activation cleanup must complete synchronously.\n");
       return;
     }
-    this.handleProtocolViolation("Plugin worker sent a message in the wrong direction.");
-  }
-
-  handleExit(code) {
-    electronFacadeBroker.disposePlugin(this.configuration.manifest.pluginId);
-    this.child = undefined;
-    this.ready = false;
-    this.initializationRequestId = undefined;
-    clearTimeout(this.startTimer);
-    this.startTimer = undefined;
-    clearTimeout(this.shutdownTimer);
-    this.shutdownTimer = undefined;
-    this.shutdownPromise = undefined;
-    this.shutdownResolve = undefined;
-    const result = fail("PluginWorkerExited", "Plugin worker process exited.", { code });
-    if (this.startPromise) {
-      this.failStart(new Error(result.error.message));
-    }
-    for (const pending of this.pending.values()) {
-      clearPendingTimer(pending);
-      pending.resolve(result);
-    }
-    this.pending.clear();
-    if (!this.intentionalStop) {
-      process.stderr.write("[nexus-plugin-dev] plugin worker exited with code " + String(code) + ".\n");
+    const result = deactivate("reload");
+    if (isPromiseLike(result)) {
+      observeRejectedLifecyclePromise(result, "activation cleanup");
+      process.stderr.write("[nexus-plugin-dev] activation cleanup must complete synchronously.\n");
     }
+  } catch (error) {
+    process.stderr.write("[nexus-plugin-dev] activation cleanup failed: " + errorMessage(error) + "\n");
   }
+}
 
-  failStart(error) {
-    clearTimeout(this.startTimer);
-    this.startTimer = undefined;
-    this.initializationRequestId = undefined;
-    this.startReject?.(error instanceof Error ? error : new Error(String(error)));
-    this.startResolve = undefined;
-    this.startReject = undefined;
-    this.startPromise = undefined;
+function deactivatePluginMainEntry(reason) {
+  if (!pluginModule || pluginDeactivated) {
+    return;
   }
-
-  handleProtocolViolation(message) {
-    const error = new Error(message);
-    if (this.startPromise) {
-      this.failStart(error);
-    } else {
-      process.stderr.write("[nexus-plugin-dev] " + message + "\n");
+  pluginDeactivated = true;
+  try {
+    const deactivate = pluginModule.deactivate || (pluginModule.default && pluginModule.default.deactivate);
+    if (!deactivate) {
+      return;
     }
-    this.kill();
-  }
-
-  post(message) {
-    if (!this.child) {
-      throw new Error("Plugin worker process has exited.");
+    if (typeof deactivate !== "function" || isAsyncFunction(deactivate)) {
+      process.stderr.write("[nexus-plugin-dev] plugin deactivate must complete synchronously in Framework API 3.1.0.\n");
+      return;
     }
-    this.child.postMessage(message);
-  }
-
-  kill() {
-    if (this.child) {
-      this.child.kill();
+    const result = deactivate(reason);
+    if (isPromiseLike(result)) {
+      observeRejectedLifecyclePromise(result, "deactivate");
+      process.stderr.write("[nexus-plugin-dev] plugin deactivate must complete synchronously in Framework API 3.1.0.\n");
     }
-  }
-
-  nextRequestId(kind) {
-    this.requestSequence += 1;
-    return this.configuration.manifest.pluginId + "-" + kind + "-" + String(this.requestSequence);
-  }
-}
-
-function clearPendingTimer(pending) {
-  if (pending && pending.timer) {
-    clearTimeout(pending.timer);
-    pending.timer = undefined;
+  } catch (error) {
+    process.stderr.write("[nexus-plugin-dev] plugin deactivation failed: " + errorMessage(error) + "\n");
+  } finally {
+    pluginActivated = false;
+    rendererOperations.clear();
   }
 }
 
-function readWorkerMessage(message) {
-  return isRecord(message) && Object.prototype.hasOwnProperty.call(message, "data") ? message.data : message;
+function observeRejectedLifecyclePromise(value, lifecycle) {
+  void Promise.resolve(value).catch(function reportLifecycleRejection(error) {
+    process.stderr.write("[nexus-plugin-dev] plugin " + lifecycle + " returned a rejected Promise: " + errorMessage(error) + "\n");
+  });
 }
 
-async function handlePluginHostRequest(workerConfiguration, request) {
-  if (!isRecord(request) || typeof request.method !== "string") {
-    return fail("InvalidRequest", "Plugin Host API request is invalid.");
-  }
-  const manifest = workerConfiguration.manifest;
-  const params = isRecord(request.params) ? request.params : undefined;
-  if (request.method === "electronFacade") {
-    return electronFacadeBroker.invoke(manifest.pluginId, params);
-  }
-  if (request.method === "getCapabilityStatus") {
-    return isPluginPermission(params && params.permission)
-      ? ok(createPermissionSummary(params.permission))
-      : fail("InvalidRequest", "Plugin capability name is invalid.");
-  }
-  if (request.method === "unsupportedCapability") {
-    return unsupportedCapability(manifest, params && params.permission, params && params.operation);
-  }
-  if (request.method === "log") {
-    if (!manifest.permissions.includes("businessLog")) {
-      return fail("PluginPermissionDenied", "Plugin does not declare businessLog permission.");
-    }
-    if (!params || (params.level !== "info" && params.level !== "warn" && params.level !== "error") || typeof params.message !== "string" || !params.message.trim()) {
-      return fail("InvalidRequest", "Plugin log request is invalid.");
-    }
-    return ok(appendLog(params.level, "plugin:" + manifest.pluginId, params.message.trim(), typeof params.exception === "string" ? params.exception : undefined));
-  }
-  if (request.method === "getSettings") {
-    return manifest.permissions.includes("settings")
-      ? ok(loadSettings())
-      : fail("PluginPermissionDenied", "Plugin does not declare settings permission.");
-  }
-  if (request.method === "updateSettings") {
-    if (!manifest.permissions.includes("settings")) {
-      return fail("PluginPermissionDenied", "Plugin does not declare settings permission.");
-    }
-    if (!params || !isRecord(params.values)) {
-      return fail("InvalidRequest", "Plugin settings values must be an object.");
+function createActivationContext() {
+  const manifest = configuration.manifest;
+  const unsupported = function createUnsupportedApi(permission) {
+    const summary = createPermissionSummary(permission);
+    const target = {
+      permission,
+      supportState: summary.supportState,
+      describe: function describe() {
+        return ok(summary);
+      },
+      unsupported: function unsupported(operation) {
+        return unsupportedCapability(manifest, permission, operation);
+      }
+    };
+    return new Proxy(target, {
+      get: function getUnsupported(apiTarget, property) {
+        if (property in apiTarget) {
+          return Reflect.get(apiTarget, property);
+        }
+        if (typeof property === "symbol" || property === "then") {
+          return undefined;
+        }
+        return function reportUnsupported() {
+          return apiTarget.unsupported(property);
+        };
+      }
+    });
+  };
+  return {
+    pluginId: manifest.pluginId,
+    pluginDirectory: configuration.packageDirectory,
+    manifest,
+    host: {
+      hostVersion: configuration.hostVersion,
+      hostApiVersion: sdk.PLUGIN_FRAMEWORK_VERSION,
+      pluginId: manifest.pluginId,
+      pluginDataDirectory: configuration.pluginDataDirectory,
+      hasPermission: function hasPermission(permission) {
+        return manifest.permissions.includes(permission);
+      },
+      registerRendererMethod: function registerRendererMethod(name, handler) {
+        if (!isSafeOperationName(name) || typeof handler !== "function") {
+          return fail("InvalidRequest", "Plugin renderer operation registration is invalid.");
+        }
+        if (rendererOperations.has(name)) {
+          return fail("InvalidRequest", "Plugin renderer operation is already registered.", {
+            pluginId: manifest.pluginId,
+            operation: name
+          });
+        }
+        rendererOperations.set(name, handler);
+        return ok(true);
+      },
+      getCapabilityStatus: function getCapabilityStatus(permission) {
+        return isPluginPermission(permission)
+          ? ok(createPermissionSummary(permission))
+          : fail("InvalidRequest", "Plugin capability name is invalid.", { pluginId: manifest.pluginId, permission });
+      },
+      unsupportedCapability: function reportUnsupported(permission, operation) {
+        return unsupportedCapability(manifest, permission, operation);
+      },
+      log: function log(level, message, exception) {
+        if (!manifest.permissions.includes("businessLog")) {
+          return fail("PluginPermissionDenied", "Plugin does not declare businessLog permission.", { pluginId: manifest.pluginId });
+        }
+        if ((level !== "info" && level !== "warn" && level !== "error") || typeof message !== "string" || !message.trim()) {
+          return fail("InvalidRequest", "Plugin log request is invalid.", { pluginId: manifest.pluginId });
+        }
+        return ok(appendLog(level, "plugin:" + manifest.pluginId, message.trim(), typeof exception === "string" ? exception : undefined));
+      },
+      getSettings: function getSettings() {
+        return manifest.permissions.includes("settings")
+          ? ok(loadSettings())
+          : fail("PluginPermissionDenied", "Plugin does not declare settings permission.", { pluginId: manifest.pluginId });
+      },
+      updateSettings: function updateSettings(values) {
+        if (!manifest.permissions.includes("settings")) {
+          return fail("PluginPermissionDenied", "Plugin does not declare settings permission.", { pluginId: manifest.pluginId });
+        }
+        if (!isRecord(values)) {
+          return fail("InvalidRequest", "Plugin settings values must be an object.");
+        }
+        return ok(saveSettings(values));
+      },
+      filesystem: unsupported("filesystem"),
+      udp: unsupported("udp"),
+      serial: unsupported("serial"),
+      dialog: unsupported("dialog"),
+      externalProcess: unsupported("externalProcess")
     }
-    return ok(saveSettings(params.values));
-  }
-  return fail("InvalidRequest", "Plugin Host API method is invalid.", { method: request.method });
+  };
 }
 
 function unsupportedCapability(manifest, permission, operation) {
   if (!isPluginPermission(permission)) {
-    return fail("InvalidRequest", "Plugin capability name is invalid.", { permission });
+    return fail("InvalidRequest", "Plugin capability name is invalid.", { pluginId: manifest.pluginId, permission });
   }
   if (!manifest.permissions.includes(permission)) {
-    return fail("PluginPermissionDenied", "Plugin does not declare " + permission + " permission.", { permission });
+    return fail("PluginPermissionDenied", "Plugin does not declare " + permission + " permission.", {
+      pluginId: manifest.pluginId,
+      permission
+    });
   }
   const summary = createPermissionSummary(permission);
   return fail(
     "PluginCapabilityUnsupported",
-    "Plugin Host API capability is not available to trusted mainEntry.",
+    "This Host API capability is not available; use the native Electron or Node API from mainEntry.",
     {
+      pluginId: manifest.pluginId,
       permission,
       operation: typeof operation === "string" ? operation : undefined,
-      supportState: summary.supportState,
-      statusMessage: summary.statusMessage
+      supportState: summary.supportState
     }
   );
 }
@@ -680,8 +440,11 @@ async function verifyRendererContextSmoke() {
   if (!frame) {
     throw new Error("Plugin renderer frame was not found.");
   }
-  if (configuration.manifest.hostApiVersion !== sdk.PLUGIN_FRAMEWORK_VERSION
-    || (configuration.manifest.mainEntry && !pluginWorker)
+  if (!sdk.isPluginFrameworkVersionCompatible(
+    configuration.manifest.hostApiVersion,
+    sdk.PLUGIN_FRAMEWORK_VERSION
+  )
+    || (configuration.manifest.mainEntry && !pluginActivated)
     || configuration.manifest.minHostVersion === undefined) {
     throw new Error("Development Host API version contract is inconsistent.");
   }
@@ -817,15 +580,32 @@ async function invokeMain(params) {
   if (!isSafeOperationName(params.operation)) {
     return fail("InvalidRequest", "Plugin renderer operation name is invalid.", { operation: params.operation });
   }
-  if (!pluginWorker) {
+  if (!pluginActivated) {
     return fail("PluginCapabilityUnsupported", "Plugin mainEntry is not available in this debug target.", { operation: params.operation });
   }
-  return pluginWorker.invoke({
-    surface: configuration.surface,
-    contributionId: configuration.contributionId,
-    operation: params.operation,
-    input: isRecord(params.input) ? sanitizeJsonValue(params.input) : undefined
-  });
+  const handler = rendererOperations.get(params.operation);
+  if (!handler) {
+    return fail("NotFound", "Plugin renderer operation was not registered.", {
+      pluginId: configuration.manifest.pluginId,
+      operation: params.operation
+    });
+  }
+  try {
+    const value = await handler({
+      pluginId: configuration.manifest.pluginId,
+      surface: configuration.surface,
+      contributionId: configuration.contributionId,
+      operation: params.operation,
+      input: isRecord(params.input) ? decodeOperationValue(params.input) : undefined
+    });
+    return normalizeOperationResult(value);
+  } catch (error) {
+    return fail("PluginMainOperationFailed", "Plugin renderer operation failed.", {
+      pluginId: configuration.manifest.pluginId,
+      operation: params.operation,
+      error: errorMessage(error)
+    });
+  }
 }
 
 function createWindow() {
@@ -905,12 +685,10 @@ function saveSettings(values) {
   const document = {
     schemaVersion: sdk.PLUGIN_MANIFEST_SCHEMA_VERSION,
     pluginId: configuration.manifest.pluginId,
-    values: Object.assign({}, existing.values, sanitizeJsonObject(values))
+    values: { ...existing.values, ...sanitizeJsonObject(values) }
   };
   const filePath = settingsFilePath();
-  const temporaryPath = filePath + ".tmp";
-  fs.writeFileSync(temporaryPath, JSON.stringify(document, null, 2) + "\n", "utf8");
-  fs.renameSync(temporaryPath, filePath);
+  fs.writeFileSync(filePath, JSON.stringify(document, null, 2) + "\n", "utf8");
   return document;
 }
 
@@ -973,37 +751,131 @@ function isSafeOperationName(value) {
     });
 }
 
-function isNexusResult(value) {
-  if (!isRecord(value) || typeof value.ok !== "boolean") {
-    return false;
+function normalizeOperationResult(value) {
+  if (isNexusResult(value)) {
+    return value.ok
+      ? ok(encodeOperationValue(value.value))
+      : fail(value.error.code, value.error.message, encodeOperationValue(value.error.details));
   }
-  return value.ok
-    ? Object.prototype.hasOwnProperty.call(value, "value")
-    : isRecord(value.error) && typeof value.error.code === "string" && typeof value.error.message === "string";
+  return ok(encodeOperationValue(value));
 }
 
-function normalizeRpcResult(result) {
-  if (!isNexusResult(result)) {
-    return fail("UnexpectedFailure", "Plugin Host API returned an invalid result.");
+function isNexusResult(value) {
+  return isRecord(value)
+    && typeof value.ok === "boolean"
+    && (value.ok
+      ? Object.prototype.hasOwnProperty.call(value, "value")
+      : isRecord(value.error) && typeof value.error.code === "string" && typeof value.error.message === "string");
+}
+
+function encodeOperationValue(value, seen) {
+  const visited = seen || new WeakSet();
+  if (value === undefined) {
+    return { __nexusWire: "undefined" };
   }
-  if (result.ok) {
-    return { ok: true, value: sanitizeJsonValue(result.value) };
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
   }
-  return {
-    ok: false,
-    error: {
-      code: result.error.code,
-      message: result.error.message,
-      ...(result.error.details === undefined ? {} : { details: sanitizeJsonValue(result.error.details) })
+  if (typeof value === "bigint") {
+    return { __nexusWire: "bigint", value: value.toString(10) };
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value !== "object" || visited.has(value)) {
+    return null;
+  }
+  if (value instanceof Date) {
+    return { __nexusWire: "date", value: value.toISOString() };
+  }
+  if (value instanceof Error) {
+    return {
+      __nexusWire: "error",
+      name: value.name,
+      message: value.message,
+      ...(value.stack ? { stack: value.stack } : {})
+    };
+  }
+  if (Buffer.isBuffer(value)) {
+    return { __nexusWire: "buffer", value: value.toString("hex") };
+  }
+  if (!Array.isArray(value) && !isPlainObject(value)) {
+    return null;
+  }
+  visited.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map(function encodeItem(item) {
+        return encodeOperationValue(item, visited);
+      });
     }
-  };
+    const encoded = Object.fromEntries(Object.entries(value).map(function encodeEntry(entry) {
+      return [entry[0], encodeOperationValue(entry[1], visited)];
+    }));
+    return Object.prototype.hasOwnProperty.call(value, "__nexusWire")
+      ? { __nexusWire: "object", value: encoded }
+      : encoded;
+  } finally {
+    visited.delete(value);
+  }
 }
 
-function isWorkerRequestId(value) {
-  return typeof value === "string"
-    && value.length > 0
-    && value.length <= 128
-    && /^[A-Za-z0-9._:-]+$/.test(value);
+function decodeOperationValue(value, seen) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  const visited = seen || new WeakSet();
+  if (visited.has(value)) {
+    return null;
+  }
+  if (value.__nexusWire === "undefined") {
+    return undefined;
+  }
+  if (value.__nexusWire === "bigint" && typeof value.value === "string") {
+    try {
+      return BigInt(value.value);
+    } catch {
+      return null;
+    }
+  }
+  if (value.__nexusWire === "date" && typeof value.value === "string") {
+    const date = new Date(value.value);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  if (value.__nexusWire === "buffer" && typeof value.value === "string") {
+    return value.value.length % 2 === 0 && /^[0-9a-f]*$/i.test(value.value)
+      ? Buffer.from(value.value, "hex")
+      : null;
+  }
+  if (value.__nexusWire === "error" && typeof value.message === "string") {
+    const error = new Error(value.message);
+    if (typeof value.name === "string") {
+      error.name = value.name;
+    }
+    if (typeof value.stack === "string") {
+      error.stack = value.stack;
+    }
+    return error;
+  }
+  if (value.__nexusWire === "object" && isRecord(value.value)) {
+    return decodeOperationValue(value.value, visited);
+  }
+  visited.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map(function decodeItem(item) {
+        return decodeOperationValue(item, visited);
+      });
+    }
+    if (!isPlainObject(value)) {
+      return null;
+    }
+    return Object.fromEntries(Object.entries(value).map(function decodeEntry(entry) {
+      return [entry[0], decodeOperationValue(entry[1], visited)];
+    }));
+  } finally {
+    visited.delete(value);
+  }
 }
 
 function isPluginPermission(value) {
@@ -1011,9 +883,6 @@ function isPluginPermission(value) {
 }
 
 function permissionSupportState(permission) {
-  if (hostControlPermissions.has(permission)) {
-    return "hostControl";
-  }
   if (implementedPermissions.has(permission)) {
     return "implemented";
   }
@@ -1027,8 +896,6 @@ function createPermissionSummary(permission) {
   const supportState = permissionSupportState(permission);
   const statusMessage = supportState === "implemented"
     ? "Available to trusted mainEntry Host API."
-    : supportState === "hostControl"
-      ? "Grants direct control of Nexus Electron host objects; global changes can affect the application and may not be reversible."
     : supportState === "routeGuard"
       ? "Declared for renderer route guards; not exposed to trusted mainEntry Host API."
       : "Reserved for a future Host API; trusted mainEntry calls return PluginCapabilityUnsupported.";
@@ -1061,6 +928,22 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isPlainObject(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isPromiseLike(value) {
+  return isRecord(value) && typeof value.then === "function";
+}
+
+function isAsyncFunction(value) {
+  return typeof value === "function" && value.constructor && value.constructor.name === "AsyncFunction";
+}
+
 function isLogLevel(value) {
   return value === "debug" || value === "info" || value === "warn" || value === "error";
 }
@@ -1109,28 +992,6 @@ function isStrictVersion(value) {
   }));
 }
 
-function parseWorkerInspector(args) {
-  const prefix = "--worker-inspector=";
-  const matches = args.filter(function isWorkerInspectorArgument(value) {
-    return value.startsWith(prefix);
-  });
-  if (matches.length > 1) {
-    throw new Error("--worker-inspector must not be repeated.");
-  }
-  if (matches.length === 0) {
-    return undefined;
-  }
-  const match = /^(inspect|inspect-brk):([0-9]+)$/.exec(matches[0].slice(prefix.length));
-  const port = match ? Number(match[2]) : 0;
-  if (!match || !Number.isInteger(port) || port < 1 || port > 65535) {
-    throw new Error("--worker-inspector must use inspect:<port> or inspect-brk:<port>.");
-  }
-  return {
-    execArg: "--" + match[1] + "=" + String(port),
-    breakOnStart: match[1] === "inspect-brk"
-  };
-}
-
 function requiredArgument(args, name) {
   const prefix = name + "=";
   const argument = args.find(function findArgument(value) {