@elementspanel/epanel-plugin-instance 1.0.6 → 1.0.7

package/daemon/backend/index.cjs

@@ -9668,6 +9668,39 @@ async function loadPluginModule(entry, directory, revision) {
 
 "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 () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -9686,6 +9719,8 @@ const path_1 = __importDefault(__webpack_require__("path"));
 const module_1 = __webpack_require__("module");
 const plugin_manifest_1 = __webpack_require__("../common/src/plugin_manifest.ts");
 const plugin_contract_1 = __webpack_require__("../common/src/plugin_contract.ts");
+// @ts-ignore Shared by the source runtime and the published npm launcher.
+const npmPlugins = __importStar(__webpack_require__("../../scripts/runtime/npm-plugins.cjs"));
 const PLUGIN_ID = /^[a-z][a-z0-9_-]{1,63}$/;
 const PACKAGE_NAME = /^(?:@[a-z0-9_.-]+\/)?epanel-plugin-[a-z0-9_.-]+$/;
 const VERSION = /^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,63}$/;
@@ -9728,9 +9763,18 @@ function currentProjectRoot(packageRoot = currentPackageRoot()) {
 }
 function npmPluginRoots(options = {}) {
     const packageRoot = path_1.default.resolve(options.packageRoot ?? currentPackageRoot());
+    const projectRoot = path_1.default.resolve(options.projectRoot ?? currentProjectRoot(packageRoot));
+    const host = readJson(path_1.default.join(packageRoot, "package.json"));
+    const side = options.side ||
+        stringValue(objectValue(host?.elementspanel)?.side) ||
+        path_1.default.basename(packageRoot);
     return {
         packageRoot,
-        projectRoot: path_1.default.resolve(options.projectRoot ?? currentProjectRoot(packageRoot))
+        projectRoot,
+        dependencyRoot: path_1.default.dirname(npmPlugins.projectManifestFile(packageRoot, side, {
+            projectRoot,
+            runtimeDirectory: process.env.EPANEL_RUNTIME_ROOT
+        }))
     };
 }
 function projectManifestFile(projectRoot) {
@@ -9758,15 +9802,10 @@ function pluginRecord(pluginId, name, source, packageRoot, directory, folder, ve
 function readPackageEntry(packageRoot, name) {
     // Read package boundaries directly: Node caches require.resolve() paths even
     // after npm moves an installation between nested and hoisted node_modules.
-    let manifestPath;
-    for (const root of [packageRoot, currentProjectRoot(packageRoot)]) {
-        const localRequire = (0, module_1.createRequire)(path_1.default.join(root, "package.json"));
-        manifestPath = (localRequire.resolve.paths(name) || [])
-            .map((directory) => path_1.default.join(directory, name, "package.json"))
-            .find((filename) => fs_extra_1.default.existsSync(filename));
-        if (manifestPath)
-            break;
-    }
+    const localRequire = (0, module_1.createRequire)(path_1.default.join(packageRoot, "package.json"));
+    let manifestPath = (localRequire.resolve.paths(name) || [])
+        .map((directory) => path_1.default.join(directory, name, "package.json"))
+        .find((filename) => fs_extra_1.default.existsSync(filename));
     if (!manifestPath)
         throw new Error(`Missing npm plugin package: ${name}.`);
     manifestPath = fs_extra_1.default.realpathSync(manifestPath);
@@ -9813,83 +9852,26 @@ function recordFromPackage(pluginId, name, source, packageRoot, metadata, side)
 /**
  * Every npm plugin the runtime can load for a side, built-in and project-installed.
  *
- * Built-in package names win over a project mapping for the same id. An explicit
- * project dependency on that same package selects the user's installed version.
- * A project package that does not describe the requested side is skipped instead of failing, which
- * is what lets a two-sided project share one dependency list between sides.
+ * Built-in package names reserve their plugin ids. The side manifest selects
+ * the installed versions; a package without that side is skipped.
  */
 function listNpmPlugins(side, options = {}) {
-    const { packageRoot, projectRoot } = npmPluginRoots(options);
-    const host = readJson(path_1.default.join(packageRoot, "package.json"));
-    if (!host)
-        throw new Error(`Missing runtime package metadata: ${packageRoot}`);
-    const project = path_1.default.resolve(projectRoot) === path_1.default.resolve(packageRoot)
-        ? null
-        : readProjectManifest(projectRoot);
-    const hostMappings = mappingsOf(host);
-    const projectMappings = { ...mappingsOf(project) };
-    for (const name of Object.keys(dependenciesOf(project))) {
-        if (!PACKAGE_NAME.test(name) || Object.values(projectMappings).includes(name))
-            continue;
-        try {
-            const entry = readPackageEntry(projectRoot, name);
-            const id = stringValue(objectValue(entry.metadata.elementspanel)?.id);
-            if (PLUGIN_ID.test(id) && projectMappings[id] === undefined)
-                projectMappings[id] = name;
-        }
-        catch {
-            /* npm may still be writing the package. */
-        }
-    }
-    const mappings = new Map();
-    for (const [pluginId, name] of Object.entries(projectMappings)) {
-        if (!PLUGIN_ID.test(pluginId) || typeof name !== "string" || !PACKAGE_NAME.test(name))
-            continue;
-        mappings.set(pluginId, { name, source: "project" });
-    }
-    for (const [pluginId, name] of Object.entries(hostMappings)) {
-        if (!PLUGIN_ID.test(pluginId) || typeof name !== "string" || !PACKAGE_NAME.test(name))
-            continue;
-        if (dependenciesOf(host)[name] === undefined)
-            continue;
-        mappings.set(pluginId, {
-            name,
-            source: dependenciesOf(project)[name] === undefined ? "bundled" : "project"
-        });
-    }
-    const hostDependencies = dependenciesOf(host);
-    const projectDependencies = dependenciesOf(project);
-    const folders = new Set();
+    const { packageRoot, projectRoot, dependencyRoot } = npmPluginRoots({ ...options, side });
     const records = [];
-    for (const [pluginId, mapping] of mappings) {
-        const declared = hostDependencies[mapping.name] ?? projectDependencies[mapping.name];
-        if (declared === undefined) {
-            if (options.skipInvalid)
-                continue;
-            throw new Error(`Missing npm plugin dependency: ${mapping.name}. Run npm install in the project directory.`);
-        }
-        let entry;
-        try {
-            entry = readPackageEntry(mapping.source === "project" ? projectRoot : packageRoot, mapping.name);
-        }
-        catch (error) {
-            if (options.skipInvalid)
-                continue;
-            throw error;
-        }
-        const record = recordFromPackage(pluginId, mapping.name, mapping.source, entry.root, entry.metadata, side);
+    for (const item of npmPlugins.resolveNpmPlugins(packageRoot, side, {
+        projectRoot,
+        runtimeDirectory: dependencyRoot,
+        skipInvalid: options.skipInvalid
+    })) {
+        const metadata = readJson(path_1.default.join(item.packageRoot, "package.json"));
+        if (!metadata)
+            continue;
+        const record = recordFromPackage(item.id, item.name, item.source, item.packageRoot, metadata, side);
         if (!record) {
-            if (options.skipInvalid || mapping.source === "project")
-                continue;
-            throw new Error(`Invalid ${side ?? "plugin"} entry in npm plugin ${mapping.name}.`);
-        }
-        const folder = record.folder;
-        if (folders.has(folder)) {
             if (options.skipInvalid)
                 continue;
-            throw new Error(`Duplicate npm plugin asset directory: ${folder}.`);
+            throw new Error(`Invalid ${side ?? "plugin"} entry in npm plugin ${item.name}.`);
         }
-        folders.add(folder);
         records.push(record);
     }
     return records;
@@ -9986,10 +9968,9 @@ async function acquireProjectLock(projectRoot) {
         }
     }
 }
-function npmPluginOperationPending() {
-    const { packageRoot, projectRoot } = npmPluginRoots();
-    return (operations.size > 0 ||
-        [packageRoot, projectRoot].some((root) => fs_extra_1.default.existsSync(path_1.default.join(root, LOCK_NAME))));
+function npmPluginOperationPending(side) {
+    const { dependencyRoot } = npmPluginRoots({ side });
+    return operations.size > 0 || fs_extra_1.default.existsSync(path_1.default.join(dependencyRoot, LOCK_NAME));
 }
 function withProjectLock(projectRoot, operation) {
     const key = process.platform === "win32" ? projectRoot.toLowerCase() : projectRoot;
@@ -10024,18 +10005,15 @@ async function installNpmPlugin(options) {
         throw new Error(`Invalid plugin id: ${options.pluginId}`);
     if (!VERSION.test(version))
         throw new Error(`Invalid plugin version: ${version}`);
-    const { packageRoot, projectRoot } = npmPluginRoots(options);
-    return withProjectLock(projectRoot, async () => {
+    const { packageRoot, projectRoot, dependencyRoot } = npmPluginRoots(options);
+    return withProjectLock(dependencyRoot, async () => {
         const host = readJson(path_1.default.join(packageRoot, "package.json"));
         if (!host)
             throw new Error(`Missing runtime package metadata: ${packageRoot}`);
-        const hostId = Object.entries(mappingsOf(host)).find(([, value]) => value === name && dependenciesOf(host)[name] !== undefined)?.[0];
-        const targetRoot = hostId && dependenciesOf(readProjectManifest(projectRoot))[name] === undefined
-            ? packageRoot
-            : projectRoot;
+        const hostId = Object.entries(mappingsOf(host)).find(([, value]) => value === name)?.[0];
+        const targetRoot = dependencyRoot;
         if (options.pluginId &&
             mappingsOf(host)[options.pluginId] &&
-            dependenciesOf(host)[String(mappingsOf(host)[options.pluginId])] !== undefined &&
             mappingsOf(host)[options.pluginId] !== name)
             throw new Error(`BUNDLED:${options.pluginId}`);
         const original = readProjectManifest(targetRoot);
@@ -10064,24 +10042,33 @@ async function installNpmPlugin(options) {
                 "--save-exact",
                 "--no-fund",
                 "--no-audit",
-                "--ignore-scripts"
+                "--ignore-scripts",
+                "--workspaces=false"
             ], targetRoot);
             const entry = readPackageEntry(targetRoot, name);
             const pluginId = options.pluginId || stringValue(objectValue(entry.metadata.elementspanel)?.id);
             if (!PLUGIN_ID.test(pluginId))
                 throw new Error(`Invalid plugin id in ${name}.`);
-            if (mappingsOf(host)[pluginId] &&
-                dependenciesOf(host)[String(mappingsOf(host)[pluginId])] !== undefined &&
-                mappingsOf(host)[pluginId] !== name)
+            if (mappingsOf(host)[pluginId] && mappingsOf(host)[pluginId] !== name)
                 throw new Error(`Plugin id ${pluginId} belongs to a bundled dependency.`);
             if (hostId && pluginId !== hostId)
                 throw new Error(`The package ${name} changed its plugin id from ${hostId} to ${pluginId}.`);
             const mapped = mappingsOf(readProjectManifest(targetRoot))[pluginId];
             if (mapped !== undefined && mapped !== name)
                 throw new Error(`Plugin id ${pluginId} is already installed as ${String(mapped)}.`);
-            const record = recordFromPackage(pluginId, name, targetRoot === packageRoot ? "bundled" : "project", entry.root, entry.metadata, side);
+            const record = recordFromPackage(pluginId, name, hostId ? "bundled" : "project", entry.root, entry.metadata, side);
             if (!record)
                 throw new Error(`The package ${name} does not provide a ${side} plugin named ${pluginId}.`);
+            if (side === "panel") {
+                const expected = objectValue(objectValue(entry.metadata.elementspanel)?.panel)
+                    ?.frontendAssets;
+                const available = objectValue(host.elementspanel)?.frontendAssets;
+                if ((hostId || expected !== undefined) &&
+                    (!Array.isArray(expected) ||
+                        !Array.isArray(available) ||
+                        expected.some((file) => typeof file !== "string" || !available.includes(file))))
+                    throw new Error(`Frontend assets in ${name} do not match this panel. Update the panel or install a matching plugin version.`);
+            }
             if (/^[0-9]/.test(version) && record.version !== version)
                 throw new Error(`The installed package ${name} is ${record.version}, expected ${version}.`);
             if (!process.env.EPANEL_PACKAGE_ROOT &&
@@ -10125,7 +10112,8 @@ async function installNpmPlugin(options) {
                         "--save",
                         "--no-fund",
                         "--no-audit",
-                        "--ignore-scripts"
+                        "--ignore-scripts",
+                        "--workspaces=false"
                     ]
                     : [
                         "--prefix",
@@ -10134,7 +10122,8 @@ async function installNpmPlugin(options) {
                         name,
                         "--no-fund",
                         "--no-audit",
-                        "--ignore-scripts"
+                        "--ignore-scripts",
+                        "--workspaces=false"
                     ], targetRoot);
             }
             catch (rollback) {
@@ -10158,22 +10147,29 @@ async function uninstallNpmPlugin(pluginId, options = {}) {
         throw new Error(`Invalid plugin id: ${pluginId}`);
     if (isEssentialNpmPlugin(pluginId))
         throw new Error(`The essential plugin "${pluginId}" cannot be uninstalled.`);
-    const { packageRoot, projectRoot } = npmPluginRoots(options);
-    return withProjectLock(projectRoot, async () => {
-        const host = readJson(path_1.default.join(packageRoot, "package.json"));
-        const bundledName = mappingsOf(host)[pluginId];
-        const targetRoot = typeof bundledName === "string" &&
-            dependenciesOf(host)[bundledName] !== undefined &&
-            dependenciesOf(readProjectManifest(projectRoot))[bundledName] === undefined
-            ? packageRoot
-            : projectRoot;
+    const { packageRoot, projectRoot, dependencyRoot } = npmPluginRoots(options);
+    return withProjectLock(dependencyRoot, async () => {
+        const targetRoot = dependencyRoot;
         const manifest = readProjectManifest(targetRoot);
         const name = mappingsOf(manifest)[pluginId] ??
-            listNpmPlugins(undefined, { packageRoot, projectRoot, skipInvalid: true }).find((item) => item.pluginId === pluginId)?.name;
+            listNpmPlugins(options.side, { packageRoot, projectRoot, skipInvalid: true }).find((item) => item.pluginId === pluginId)?.name;
         if (typeof name !== "string" || !PACKAGE_NAME.test(name))
             return null;
-        const record = listNpmPlugins(undefined, { packageRoot, projectRoot, skipInvalid: true }).find((item) => item.pluginId === pluginId);
-        await runNpm(["--prefix", targetRoot, "uninstall", name, "--no-fund", "--no-audit", "--ignore-scripts"], targetRoot);
+        const record = listNpmPlugins(options.side, {
+            packageRoot,
+            projectRoot,
+            skipInvalid: true
+        }).find((item) => item.pluginId === pluginId);
+        await runNpm([
+            "--prefix",
+            targetRoot,
+            "uninstall",
+            name,
+            "--no-fund",
+            "--no-audit",
+            "--ignore-scripts",
+            "--workspaces=false"
+        ], targetRoot);
         const updated = readProjectManifest(targetRoot);
         const plugins = { ...mappingsOf(updated) };
         delete plugins[pluginId];
@@ -10347,11 +10343,11 @@ const plugin_npm_1 = __webpack_require__("../common/src/plugin_npm.ts");
 /** Poll package boundaries, allowing npm to finish replacing files before reconciliation. */
 function watchNpmPlugins(ctx, side, reload, changed) {
     const stamp = () => {
-        const { packageRoot, projectRoot } = (0, plugin_npm_1.npmPluginRoots)();
+        const { packageRoot, dependencyRoot } = (0, plugin_npm_1.npmPluginRoots)({ side });
         if (!node_fs_1.default.existsSync(node_path_1.default.join(packageRoot, "package.json")))
             return "";
         const files = [];
-        for (const root of [packageRoot, projectRoot])
+        for (const root of [packageRoot, dependencyRoot])
             for (const name of [
                 "package.json",
                 "package-lock.json",
@@ -10375,7 +10371,7 @@ function watchNpmPlugins(ctx, side, reload, changed) {
     let candidate = applied;
     let busy = false;
     ctx.setInterval(() => {
-        if (busy || (0, plugin_npm_1.npmPluginOperationPending)())
+        if (busy || (0, plugin_npm_1.npmPluginOperationPending)(side))
             return;
         try {
             const next = stamp();
@@ -11460,6 +11456,226 @@ module.exports = require("stream/promises");
 "use strict";
 module.exports = require("util");
 
+/***/ },
+
+/***/ "../../scripts/runtime/npm-plugins.cjs"
+(module, __unused_webpack_exports, __webpack_require__) {
+
+const fs = __webpack_require__("node:fs");
+const path = __webpack_require__("node:path");
+const { createRequire } = __webpack_require__("node:module");
+
+const readJson = (filename) => JSON.parse(fs.readFileSync(filename, "utf8"));
+const readOptional = (filename) => {
+  try {
+    return readJson(filename);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+};
+const validId = /^[a-z][a-z0-9_-]{1,63}$/;
+const validName = /^(?:@[a-z0-9_.-]+\/)?epanel-plugin-[a-z0-9_.-]+$/;
+
+function packageManifest(root, name) {
+  const localRequire = createRequire(path.join(root, "package.json"));
+  const filename = (localRequire.resolve.paths(name) || [])
+    .map((directory) => path.join(directory, name, "package.json"))
+    .find((candidate) => fs.existsSync(candidate));
+  if (!filename) throw new Error(`Missing npm package: ${name}`);
+  return fs.realpathSync(filename);
+}
+
+function within(root, filename) {
+  const relative = path.relative(root, filename);
+  return (
+    relative === "" ||
+    (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+  );
+}
+
+function projectRoot(packageRoot) {
+  if (process.env.EPANEL_PROJECT_ROOT) return path.resolve(process.env.EPANEL_PROJECT_ROOT);
+  const parent = path.resolve(packageRoot, "..");
+  if (path.basename(parent) === "core") return path.dirname(parent);
+  // An installed runtime sits at <project>/node_modules/@scope/<side>; the
+  // project itself is three levels above the package. A development checkout
+  // sits below core/ and is handled above.
+  const scope = parent;
+  const nodeModules = path.dirname(scope);
+  if (path.basename(nodeModules) === "node_modules" && path.basename(scope).startsWith("@")) {
+    return path.dirname(nodeModules);
+  }
+  return parent;
+}
+
+function projectManifestFile(packageRoot, side, options = {}) {
+  const selectedSide =
+    side ||
+    readJson(path.join(packageRoot, "package.json")).elementspanel?.side ||
+    path.basename(packageRoot);
+  if (!["panel", "daemon"].includes(selectedSide)) throw new Error("Missing runtime side.");
+  const directory =
+    options.runtimeDirectory ||
+    (!options.projectRoot && process.env.EPANEL_RUNTIME_ROOT) ||
+    path.join(options.projectRoot || projectRoot(packageRoot), selectedSide);
+  return path.join(path.resolve(directory), "package.json");
+}
+
+function mappingOf(manifest) {
+  const plugins = manifest?.elementspanel?.plugins;
+  return plugins && typeof plugins === "object" && !Array.isArray(plugins) ? plugins : {};
+}
+
+function dependenciesOf(manifest) {
+  const dependencies = manifest?.dependencies;
+  return dependencies && typeof dependencies === "object" ? dependencies : {};
+}
+
+/**
+ * Resolve plugins declared in the side's package.json, including hoisted npm
+ * installations. The host catalogue reserves built-in ids without owning their
+ * versions. Other explicitly mapped plugins remain dormant until enabled.
+ * Runtime startup passes skipInvalid so an optional package being removed does
+ * not stop the host; the caller separately validates the small set of core
+ * plugins.
+ */
+function resolveNpmPlugins(packageRoot, side, options = {}) {
+  const skipInvalid = options.skipInvalid === true;
+  const host = readJson(path.join(packageRoot, "package.json"));
+  const selectedSide = side || host.elementspanel?.side || path.basename(packageRoot);
+  const projectFile = projectManifestFile(packageRoot, selectedSide, options);
+  const project = readOptional(projectFile);
+  const dependencyRoot = path.dirname(projectFile);
+
+  // The side manifest owns every dependency; the host only reserves identities.
+  const configured = new Map();
+  for (const [id, name] of Object.entries(mappingOf(project)))
+    configured.set(id, { name, source: "project" });
+  for (const name of Object.keys(dependenciesOf(project))) {
+    if (!validName.test(name) || [...configured.values()].some((item) => item.name === name))
+      continue;
+    try {
+      const metadata = readJson(packageManifest(dependencyRoot, name));
+      const id = metadata.elementspanel?.id;
+      if (validId.test(id) && !configured.has(id))
+        configured.set(id, { name, source: "project", automatic: true });
+    } catch {
+      /* Ignore incomplete npm installations until the next scan. */
+    }
+  }
+  for (const [id, name] of Object.entries(mappingOf(host))) {
+    if (dependenciesOf(project)[name] !== undefined)
+      configured.set(id, {
+        name,
+        source: "bundled",
+        automatic: true
+      });
+    else if (configured.has(id)) {
+      if (!skipInvalid) throw new Error(`Plugin id ${id} belongs to built-in package ${name}.`);
+      configured.delete(id);
+    }
+  }
+
+  const projectDependencies = dependenciesOf(project);
+  const folders = new Set();
+  const records = [];
+
+  for (const [id, mapping] of configured) {
+    const name = mapping.name;
+    if (
+      !validId.test(id) ||
+      typeof name !== "string" ||
+      !validName.test(name) ||
+      projectDependencies[name] === undefined
+    ) {
+      if (skipInvalid) continue;
+      throw new Error(`Invalid npm plugin dependency: ${id}.`);
+    }
+
+    let manifestPath;
+    let failure;
+    try {
+      manifestPath = packageManifest(dependencyRoot, name);
+    } catch (error) {
+      failure = error;
+    }
+    if (!manifestPath) {
+      if (skipInvalid) continue;
+      throw new Error(`Missing npm plugin ${name}. Run npm install in ${dependencyRoot}.`, {
+        cause: failure
+      });
+    }
+    let metadata;
+    try {
+      metadata = readJson(manifestPath);
+    } catch (error) {
+      if (skipInvalid) continue;
+      throw error;
+    }
+    const definition = metadata.elementspanel?.[selectedSide];
+    // A project dependency may only ship one side; the other side simply does
+    // not see it. A built-in plugin declared by the runtime must carry this side.
+    if (!definition) {
+      if (mapping.source === "project" || skipInvalid) continue;
+      throw new Error(`Invalid ${selectedSide} entry in npm plugin ${name}.`);
+    }
+    const pluginRoot = path.dirname(manifestPath);
+    if (
+      typeof definition.directory !== "string" ||
+      typeof definition.folder !== "string" ||
+      !validId.test(definition.folder) ||
+      path.isAbsolute(definition.directory)
+    ) {
+      if (skipInvalid) continue;
+      throw new Error(`Npm plugin entry escapes its package: ${name}.`);
+    }
+    const directory = path.resolve(pluginRoot, definition.directory);
+    if (directory === pluginRoot || !within(pluginRoot, directory)) {
+      if (skipInvalid) continue;
+      throw new Error(`Npm plugin entry escapes its package: ${name}.`);
+    }
+    let entries;
+    try {
+      entries = readJson(path.join(directory, "plugin.json"));
+    } catch (error) {
+      if (skipInvalid) continue;
+      throw error;
+    }
+    if (
+      metadata.elementspanel?.id !== id ||
+      typeof metadata.version !== "string" ||
+      !metadata.version.trim() ||
+      !entries ||
+      typeof entries !== "object" ||
+      Array.isArray(entries)
+    ) {
+      if (skipInvalid) continue;
+      throw new Error(`Invalid npm plugin identity or version in package.json: ${name}.`);
+    }
+    if (folders.has(definition.folder)) {
+      if (skipInvalid) continue;
+      throw new Error(`Duplicate npm plugin asset directory: ${definition.folder}.`);
+    }
+    folders.add(definition.folder);
+    records.push({
+      id,
+      name,
+      version: metadata.version,
+      source: mapping.source,
+      defaultEnabled: mapping.automatic === true || mapping.source !== "project",
+      packageRoot: pluginRoot,
+      directory,
+      folder: definition.folder,
+      dependencies: Object.keys(metadata.dependencies || {})
+    });
+  }
+  return records;
+}
+
+module.exports = { resolveNpmPlugins, projectManifestFile };
+
+
 /***/ },
 
 /***/ "../../scripts/workspace-layout.cjs"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elementspanel/epanel-plugin-instance",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Application instance and Java runtime management.",
   "license": "Apache-2.0",
   "author": "Csituka_D <694428809@qq.com> (https://github.com/JessDaodao)",
@@ -39,7 +39,45 @@
         "frontend/assets/style-0-style-10-_panel-plugin-build-entry_instance-242e9b23.css"
       ],
       "directory": "panel",
-      "folder": "instance"
+      "folder": "instance",
+      "frontendAssets": [
+        "assets/AppDialog.vue_vue_type_style_index_0_lang-f1610327.js",
+        "assets/CardPanel-6fb07d57.js",
+        "assets/DesktopDialog-653072f1.js",
+        "assets/Loading.vue_vue_type_script_setup_true_lang-e02f05df.js",
+        "assets/PageToolbar-6c8b1cf6.js",
+        "assets/_elements-sdk_cordis-e3bebc89.js",
+        "assets/_elements-sdk_cosmokit-e4842f5c.js",
+        "assets/_plugin-vue_export-helper-c27b6911.js",
+        "assets/const-5d04f817.js",
+        "assets/const-9c0a1a51.js",
+        "assets/context-f49cfcce.js",
+        "assets/copy-9f2e18f6.js",
+        "assets/dayjs.min-25183c0a.js",
+        "assets/desktopNotice-d83e9e67.js",
+        "assets/htmlparser2-bcb8f9db.js",
+        "assets/i18n-66e8c48a.js",
+        "assets/index-c684efbd.js",
+        "assets/instance-5ec65e42.js",
+        "assets/instance_contract-0115efe5.js",
+        "assets/lodash-001e4f93.js",
+        "assets/msl-logo-699c8076.png",
+        "assets/node-e836f0a9.js",
+        "assets/nodes-5b8baedc.js",
+        "assets/protocol-97f7bab7.js",
+        "assets/router-ffe15376.js",
+        "assets/useAppRouters-32a87787.js",
+        "assets/useAppStateStore-e16e4edd.js",
+        "assets/useDefineApi-5b6599dc.js",
+        "assets/useInstanceActionAvailability-514826f4.js",
+        "assets/useKeyboardEvents-b70c8bcd.js",
+        "assets/useMountComponent-26d35a1e.js",
+        "assets/useOverviewInfo-f30aafac.js",
+        "assets/usePolling-73859228.js",
+        "assets/useScreen-7eb281ed.js",
+        "assets/vue-828bfe55.js",
+        "assets/vuetifyModal-47e2f27c.js"
+      ]
     },
     "daemon": {
       "priority": 40,
@@ -50,8 +88,8 @@
     }
   },
   "peerDependencies": {
-    "@elementspanel/panel": "^1.0.3",
-    "@elementspanel/daemon": "^1.0.3"
+    "@elementspanel/panel": "^1.0.0",
+    "@elementspanel/daemon": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "@elementspanel/panel": {

package/panel/backend/index.cjs

@@ -10386,6 +10386,39 @@ async function loadPluginModule(entry, directory, revision) {
 
 "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 () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -10405,6 +10438,8 @@ const path_1 = __importDefault(__webpack_require__("path"));
 const module_1 = __webpack_require__("module");
 const plugin_manifest_1 = __webpack_require__("../common/src/plugin_manifest.ts");
 const plugin_contract_1 = __webpack_require__("../common/src/plugin_contract.ts");
+// @ts-ignore Shared by the source runtime and the published npm launcher.
+const npmPlugins = __importStar(__webpack_require__("../../scripts/runtime/npm-plugins.cjs"));
 const PLUGIN_ID = /^[a-z][a-z0-9_-]{1,63}$/;
 const PACKAGE_NAME = /^(?:@[a-z0-9_.-]+\/)?epanel-plugin-[a-z0-9_.-]+$/;
 const VERSION = /^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,63}$/;
@@ -10446,11 +10481,20 @@ function currentProjectRoot(packageRoot = currentPackageRoot()) {
     return scope;
 }
 function npmPluginRoots(options = {}) {
-    var _a, _b;
+    var _a, _b, _c;
     const packageRoot = path_1.default.resolve((_a = options.packageRoot) !== null && _a !== void 0 ? _a : currentPackageRoot());
+    const projectRoot = path_1.default.resolve((_b = options.projectRoot) !== null && _b !== void 0 ? _b : currentProjectRoot(packageRoot));
+    const host = readJson(path_1.default.join(packageRoot, "package.json"));
+    const side = options.side ||
+        stringValue((_c = objectValue(host === null || host === void 0 ? void 0 : host.elementspanel)) === null || _c === void 0 ? void 0 : _c.side) ||
+        path_1.default.basename(packageRoot);
     return {
         packageRoot,
-        projectRoot: path_1.default.resolve((_b = options.projectRoot) !== null && _b !== void 0 ? _b : currentProjectRoot(packageRoot))
+        projectRoot,
+        dependencyRoot: path_1.default.dirname(npmPlugins.projectManifestFile(packageRoot, side, {
+            projectRoot,
+            runtimeDirectory: process.env.EPANEL_RUNTIME_ROOT
+        }))
     };
 }
 function projectManifestFile(projectRoot) {
@@ -10481,15 +10525,10 @@ function pluginRecord(pluginId, name, source, packageRoot, directory, folder, ve
 function readPackageEntry(packageRoot, name) {
     // Read package boundaries directly: Node caches require.resolve() paths even
     // after npm moves an installation between nested and hoisted node_modules.
-    let manifestPath;
-    for (const root of [packageRoot, currentProjectRoot(packageRoot)]) {
-        const localRequire = (0, module_1.createRequire)(path_1.default.join(root, "package.json"));
-        manifestPath = (localRequire.resolve.paths(name) || [])
-            .map((directory) => path_1.default.join(directory, name, "package.json"))
-            .find((filename) => fs_extra_1.default.existsSync(filename));
-        if (manifestPath)
-            break;
-    }
+    const localRequire = (0, module_1.createRequire)(path_1.default.join(packageRoot, "package.json"));
+    let manifestPath = (localRequire.resolve.paths(name) || [])
+        .map((directory) => path_1.default.join(directory, name, "package.json"))
+        .find((filename) => fs_extra_1.default.existsSync(filename));
     if (!manifestPath)
         throw new Error(`Missing npm plugin package: ${name}.`);
     manifestPath = fs_extra_1.default.realpathSync(manifestPath);
@@ -10537,84 +10576,26 @@ function recordFromPackage(pluginId, name, source, packageRoot, metadata, side)
 /**
  * Every npm plugin the runtime can load for a side, built-in and project-installed.
  *
- * Built-in package names win over a project mapping for the same id. An explicit
- * project dependency on that same package selects the user's installed version.
- * A project package that does not describe the requested side is skipped instead of failing, which
- * is what lets a two-sided project share one dependency list between sides.
+ * Built-in package names reserve their plugin ids. The side manifest selects
+ * the installed versions; a package without that side is skipped.
  */
 function listNpmPlugins(side, options = {}) {
-    var _a, _b;
-    const { packageRoot, projectRoot } = npmPluginRoots(options);
-    const host = readJson(path_1.default.join(packageRoot, "package.json"));
-    if (!host)
-        throw new Error(`Missing runtime package metadata: ${packageRoot}`);
-    const project = path_1.default.resolve(projectRoot) === path_1.default.resolve(packageRoot)
-        ? null
-        : readProjectManifest(projectRoot);
-    const hostMappings = mappingsOf(host);
-    const projectMappings = { ...mappingsOf(project) };
-    for (const name of Object.keys(dependenciesOf(project))) {
-        if (!PACKAGE_NAME.test(name) || Object.values(projectMappings).includes(name))
-            continue;
-        try {
-            const entry = readPackageEntry(projectRoot, name);
-            const id = stringValue((_a = objectValue(entry.metadata.elementspanel)) === null || _a === void 0 ? void 0 : _a.id);
-            if (PLUGIN_ID.test(id) && projectMappings[id] === undefined)
-                projectMappings[id] = name;
-        }
-        catch (_c) {
-            /* npm may still be writing the package. */
-        }
-    }
-    const mappings = new Map();
-    for (const [pluginId, name] of Object.entries(projectMappings)) {
-        if (!PLUGIN_ID.test(pluginId) || typeof name !== "string" || !PACKAGE_NAME.test(name))
-            continue;
-        mappings.set(pluginId, { name, source: "project" });
-    }
-    for (const [pluginId, name] of Object.entries(hostMappings)) {
-        if (!PLUGIN_ID.test(pluginId) || typeof name !== "string" || !PACKAGE_NAME.test(name))
-            continue;
-        if (dependenciesOf(host)[name] === undefined)
-            continue;
-        mappings.set(pluginId, {
-            name,
-            source: dependenciesOf(project)[name] === undefined ? "bundled" : "project"
-        });
-    }
-    const hostDependencies = dependenciesOf(host);
-    const projectDependencies = dependenciesOf(project);
-    const folders = new Set();
+    const { packageRoot, projectRoot, dependencyRoot } = npmPluginRoots({ ...options, side });
     const records = [];
-    for (const [pluginId, mapping] of mappings) {
-        const declared = (_b = hostDependencies[mapping.name]) !== null && _b !== void 0 ? _b : projectDependencies[mapping.name];
-        if (declared === undefined) {
-            if (options.skipInvalid)
-                continue;
-            throw new Error(`Missing npm plugin dependency: ${mapping.name}. Run npm install in the project directory.`);
-        }
-        let entry;
-        try {
-            entry = readPackageEntry(mapping.source === "project" ? projectRoot : packageRoot, mapping.name);
-        }
-        catch (error) {
-            if (options.skipInvalid)
-                continue;
-            throw error;
-        }
-        const record = recordFromPackage(pluginId, mapping.name, mapping.source, entry.root, entry.metadata, side);
+    for (const item of npmPlugins.resolveNpmPlugins(packageRoot, side, {
+        projectRoot,
+        runtimeDirectory: dependencyRoot,
+        skipInvalid: options.skipInvalid
+    })) {
+        const metadata = readJson(path_1.default.join(item.packageRoot, "package.json"));
+        if (!metadata)
+            continue;
+        const record = recordFromPackage(item.id, item.name, item.source, item.packageRoot, metadata, side);
         if (!record) {
-            if (options.skipInvalid || mapping.source === "project")
-                continue;
-            throw new Error(`Invalid ${side !== null && side !== void 0 ? side : "plugin"} entry in npm plugin ${mapping.name}.`);
-        }
-        const folder = record.folder;
-        if (folders.has(folder)) {
             if (options.skipInvalid)
                 continue;
-            throw new Error(`Duplicate npm plugin asset directory: ${folder}.`);
+            throw new Error(`Invalid ${side !== null && side !== void 0 ? side : "plugin"} entry in npm plugin ${item.name}.`);
         }
-        folders.add(folder);
         records.push(record);
     }
     return records;
@@ -10713,10 +10694,9 @@ async function acquireProjectLock(projectRoot) {
         }
     }
 }
-function npmPluginOperationPending() {
-    const { packageRoot, projectRoot } = npmPluginRoots();
-    return (operations.size > 0 ||
-        [packageRoot, projectRoot].some((root) => fs_extra_1.default.existsSync(path_1.default.join(root, LOCK_NAME))));
+function npmPluginOperationPending(side) {
+    const { dependencyRoot } = npmPluginRoots({ side });
+    return operations.size > 0 || fs_extra_1.default.existsSync(path_1.default.join(dependencyRoot, LOCK_NAME));
 }
 function withProjectLock(projectRoot, operation) {
     var _a;
@@ -10752,19 +10732,16 @@ async function installNpmPlugin(options) {
         throw new Error(`Invalid plugin id: ${options.pluginId}`);
     if (!VERSION.test(version))
         throw new Error(`Invalid plugin version: ${version}`);
-    const { packageRoot, projectRoot } = npmPluginRoots(options);
-    return withProjectLock(projectRoot, async () => {
-        var _a, _b;
+    const { packageRoot, projectRoot, dependencyRoot } = npmPluginRoots(options);
+    return withProjectLock(dependencyRoot, async () => {
+        var _a, _b, _c, _d, _e;
         const host = readJson(path_1.default.join(packageRoot, "package.json"));
         if (!host)
             throw new Error(`Missing runtime package metadata: ${packageRoot}`);
-        const hostId = (_a = Object.entries(mappingsOf(host)).find(([, value]) => value === name && dependenciesOf(host)[name] !== undefined)) === null || _a === void 0 ? void 0 : _a[0];
-        const targetRoot = hostId && dependenciesOf(readProjectManifest(projectRoot))[name] === undefined
-            ? packageRoot
-            : projectRoot;
+        const hostId = (_a = Object.entries(mappingsOf(host)).find(([, value]) => value === name)) === null || _a === void 0 ? void 0 : _a[0];
+        const targetRoot = dependencyRoot;
         if (options.pluginId &&
             mappingsOf(host)[options.pluginId] &&
-            dependenciesOf(host)[String(mappingsOf(host)[options.pluginId])] !== undefined &&
             mappingsOf(host)[options.pluginId] !== name)
             throw new Error(`BUNDLED:${options.pluginId}`);
         const original = readProjectManifest(targetRoot);
@@ -10774,7 +10751,7 @@ async function installNpmPlugin(options) {
             try {
                 previousVersion = readPackageEntry(targetRoot, name).metadata.version || previous;
             }
-            catch (_c) {
+            catch (_f) {
                 /* Keep the declared spec if the previous package is incomplete. */
             }
         }
@@ -10793,24 +10770,32 @@ async function installNpmPlugin(options) {
                 "--save-exact",
                 "--no-fund",
                 "--no-audit",
-                "--ignore-scripts"
+                "--ignore-scripts",
+                "--workspaces=false"
             ], targetRoot);
             const entry = readPackageEntry(targetRoot, name);
             const pluginId = options.pluginId || stringValue((_b = objectValue(entry.metadata.elementspanel)) === null || _b === void 0 ? void 0 : _b.id);
             if (!PLUGIN_ID.test(pluginId))
                 throw new Error(`Invalid plugin id in ${name}.`);
-            if (mappingsOf(host)[pluginId] &&
-                dependenciesOf(host)[String(mappingsOf(host)[pluginId])] !== undefined &&
-                mappingsOf(host)[pluginId] !== name)
+            if (mappingsOf(host)[pluginId] && mappingsOf(host)[pluginId] !== name)
                 throw new Error(`Plugin id ${pluginId} belongs to a bundled dependency.`);
             if (hostId && pluginId !== hostId)
                 throw new Error(`The package ${name} changed its plugin id from ${hostId} to ${pluginId}.`);
             const mapped = mappingsOf(readProjectManifest(targetRoot))[pluginId];
             if (mapped !== undefined && mapped !== name)
                 throw new Error(`Plugin id ${pluginId} is already installed as ${String(mapped)}.`);
-            const record = recordFromPackage(pluginId, name, targetRoot === packageRoot ? "bundled" : "project", entry.root, entry.metadata, side);
+            const record = recordFromPackage(pluginId, name, hostId ? "bundled" : "project", entry.root, entry.metadata, side);
             if (!record)
                 throw new Error(`The package ${name} does not provide a ${side} plugin named ${pluginId}.`);
+            if (side === "panel") {
+                const expected = (_d = objectValue((_c = objectValue(entry.metadata.elementspanel)) === null || _c === void 0 ? void 0 : _c.panel)) === null || _d === void 0 ? void 0 : _d.frontendAssets;
+                const available = (_e = objectValue(host.elementspanel)) === null || _e === void 0 ? void 0 : _e.frontendAssets;
+                if ((hostId || expected !== undefined) &&
+                    (!Array.isArray(expected) ||
+                        !Array.isArray(available) ||
+                        expected.some((file) => typeof file !== "string" || !available.includes(file))))
+                    throw new Error(`Frontend assets in ${name} do not match this panel. Update the panel or install a matching plugin version.`);
+            }
             if (/^[0-9]/.test(version) && record.version !== version)
                 throw new Error(`The installed package ${name} is ${record.version}, expected ${version}.`);
             if (!process.env.EPANEL_PACKAGE_ROOT &&
@@ -10854,7 +10839,8 @@ async function installNpmPlugin(options) {
                         "--save",
                         "--no-fund",
                         "--no-audit",
-                        "--ignore-scripts"
+                        "--ignore-scripts",
+                        "--workspaces=false"
                     ]
                     : [
                         "--prefix",
@@ -10863,7 +10849,8 @@ async function installNpmPlugin(options) {
                         name,
                         "--no-fund",
                         "--no-audit",
-                        "--ignore-scripts"
+                        "--ignore-scripts",
+                        "--workspaces=false"
                     ], targetRoot);
             }
             catch (rollback) {
@@ -10887,22 +10874,29 @@ async function uninstallNpmPlugin(pluginId, options = {}) {
         throw new Error(`Invalid plugin id: ${pluginId}`);
     if (isEssentialNpmPlugin(pluginId))
         throw new Error(`The essential plugin "${pluginId}" cannot be uninstalled.`);
-    const { packageRoot, projectRoot } = npmPluginRoots(options);
-    return withProjectLock(projectRoot, async () => {
+    const { packageRoot, projectRoot, dependencyRoot } = npmPluginRoots(options);
+    return withProjectLock(dependencyRoot, async () => {
         var _a, _b;
-        const host = readJson(path_1.default.join(packageRoot, "package.json"));
-        const bundledName = mappingsOf(host)[pluginId];
-        const targetRoot = typeof bundledName === "string" &&
-            dependenciesOf(host)[bundledName] !== undefined &&
-            dependenciesOf(readProjectManifest(projectRoot))[bundledName] === undefined
-            ? packageRoot
-            : projectRoot;
+        const targetRoot = dependencyRoot;
         const manifest = readProjectManifest(targetRoot);
-        const name = (_a = mappingsOf(manifest)[pluginId]) !== null && _a !== void 0 ? _a : (_b = listNpmPlugins(undefined, { packageRoot, projectRoot, skipInvalid: true }).find((item) => item.pluginId === pluginId)) === null || _b === void 0 ? void 0 : _b.name;
+        const name = (_a = mappingsOf(manifest)[pluginId]) !== null && _a !== void 0 ? _a : (_b = listNpmPlugins(options.side, { packageRoot, projectRoot, skipInvalid: true }).find((item) => item.pluginId === pluginId)) === null || _b === void 0 ? void 0 : _b.name;
         if (typeof name !== "string" || !PACKAGE_NAME.test(name))
             return null;
-        const record = listNpmPlugins(undefined, { packageRoot, projectRoot, skipInvalid: true }).find((item) => item.pluginId === pluginId);
-        await runNpm(["--prefix", targetRoot, "uninstall", name, "--no-fund", "--no-audit", "--ignore-scripts"], targetRoot);
+        const record = listNpmPlugins(options.side, {
+            packageRoot,
+            projectRoot,
+            skipInvalid: true
+        }).find((item) => item.pluginId === pluginId);
+        await runNpm([
+            "--prefix",
+            targetRoot,
+            "uninstall",
+            name,
+            "--no-fund",
+            "--no-audit",
+            "--ignore-scripts",
+            "--workspaces=false"
+        ], targetRoot);
         const updated = readProjectManifest(targetRoot);
         const plugins = { ...mappingsOf(updated) };
         delete plugins[pluginId];
@@ -11076,11 +11070,11 @@ const plugin_npm_1 = __webpack_require__("../common/src/plugin_npm.ts");
 /** Poll package boundaries, allowing npm to finish replacing files before reconciliation. */
 function watchNpmPlugins(ctx, side, reload, changed) {
     const stamp = () => {
-        const { packageRoot, projectRoot } = (0, plugin_npm_1.npmPluginRoots)();
+        const { packageRoot, dependencyRoot } = (0, plugin_npm_1.npmPluginRoots)({ side });
         if (!node_fs_1.default.existsSync(node_path_1.default.join(packageRoot, "package.json")))
             return "";
         const files = [];
-        for (const root of [packageRoot, projectRoot])
+        for (const root of [packageRoot, dependencyRoot])
             for (const name of [
                 "package.json",
                 "package-lock.json",
@@ -11104,7 +11098,7 @@ function watchNpmPlugins(ctx, side, reload, changed) {
     let candidate = applied;
     let busy = false;
     ctx.setInterval(() => {
-        if (busy || (0, plugin_npm_1.npmPluginOperationPending)())
+        if (busy || (0, plugin_npm_1.npmPluginOperationPending)(side))
             return;
         try {
             const next = stamp();
@@ -12127,6 +12121,226 @@ module.exports = require("util");
 "use strict";
 module.exports = require("zlib");
 
+/***/ },
+
+/***/ "../../scripts/runtime/npm-plugins.cjs"
+(module, __unused_webpack_exports, __webpack_require__) {
+
+const fs = __webpack_require__("node:fs");
+const path = __webpack_require__("node:path");
+const { createRequire } = __webpack_require__("node:module");
+
+const readJson = (filename) => JSON.parse(fs.readFileSync(filename, "utf8"));
+const readOptional = (filename) => {
+  try {
+    return readJson(filename);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+};
+const validId = /^[a-z][a-z0-9_-]{1,63}$/;
+const validName = /^(?:@[a-z0-9_.-]+\/)?epanel-plugin-[a-z0-9_.-]+$/;
+
+function packageManifest(root, name) {
+  const localRequire = createRequire(path.join(root, "package.json"));
+  const filename = (localRequire.resolve.paths(name) || [])
+    .map((directory) => path.join(directory, name, "package.json"))
+    .find((candidate) => fs.existsSync(candidate));
+  if (!filename) throw new Error(`Missing npm package: ${name}`);
+  return fs.realpathSync(filename);
+}
+
+function within(root, filename) {
+  const relative = path.relative(root, filename);
+  return (
+    relative === "" ||
+    (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+  );
+}
+
+function projectRoot(packageRoot) {
+  if (process.env.EPANEL_PROJECT_ROOT) return path.resolve(process.env.EPANEL_PROJECT_ROOT);
+  const parent = path.resolve(packageRoot, "..");
+  if (path.basename(parent) === "core") return path.dirname(parent);
+  // An installed runtime sits at <project>/node_modules/@scope/<side>; the
+  // project itself is three levels above the package. A development checkout
+  // sits below core/ and is handled above.
+  const scope = parent;
+  const nodeModules = path.dirname(scope);
+  if (path.basename(nodeModules) === "node_modules" && path.basename(scope).startsWith("@")) {
+    return path.dirname(nodeModules);
+  }
+  return parent;
+}
+
+function projectManifestFile(packageRoot, side, options = {}) {
+  const selectedSide =
+    side ||
+    readJson(path.join(packageRoot, "package.json")).elementspanel?.side ||
+    path.basename(packageRoot);
+  if (!["panel", "daemon"].includes(selectedSide)) throw new Error("Missing runtime side.");
+  const directory =
+    options.runtimeDirectory ||
+    (!options.projectRoot && process.env.EPANEL_RUNTIME_ROOT) ||
+    path.join(options.projectRoot || projectRoot(packageRoot), selectedSide);
+  return path.join(path.resolve(directory), "package.json");
+}
+
+function mappingOf(manifest) {
+  const plugins = manifest?.elementspanel?.plugins;
+  return plugins && typeof plugins === "object" && !Array.isArray(plugins) ? plugins : {};
+}
+
+function dependenciesOf(manifest) {
+  const dependencies = manifest?.dependencies;
+  return dependencies && typeof dependencies === "object" ? dependencies : {};
+}
+
+/**
+ * Resolve plugins declared in the side's package.json, including hoisted npm
+ * installations. The host catalogue reserves built-in ids without owning their
+ * versions. Other explicitly mapped plugins remain dormant until enabled.
+ * Runtime startup passes skipInvalid so an optional package being removed does
+ * not stop the host; the caller separately validates the small set of core
+ * plugins.
+ */
+function resolveNpmPlugins(packageRoot, side, options = {}) {
+  const skipInvalid = options.skipInvalid === true;
+  const host = readJson(path.join(packageRoot, "package.json"));
+  const selectedSide = side || host.elementspanel?.side || path.basename(packageRoot);
+  const projectFile = projectManifestFile(packageRoot, selectedSide, options);
+  const project = readOptional(projectFile);
+  const dependencyRoot = path.dirname(projectFile);
+
+  // The side manifest owns every dependency; the host only reserves identities.
+  const configured = new Map();
+  for (const [id, name] of Object.entries(mappingOf(project)))
+    configured.set(id, { name, source: "project" });
+  for (const name of Object.keys(dependenciesOf(project))) {
+    if (!validName.test(name) || [...configured.values()].some((item) => item.name === name))
+      continue;
+    try {
+      const metadata = readJson(packageManifest(dependencyRoot, name));
+      const id = metadata.elementspanel?.id;
+      if (validId.test(id) && !configured.has(id))
+        configured.set(id, { name, source: "project", automatic: true });
+    } catch {
+      /* Ignore incomplete npm installations until the next scan. */
+    }
+  }
+  for (const [id, name] of Object.entries(mappingOf(host))) {
+    if (dependenciesOf(project)[name] !== undefined)
+      configured.set(id, {
+        name,
+        source: "bundled",
+        automatic: true
+      });
+    else if (configured.has(id)) {
+      if (!skipInvalid) throw new Error(`Plugin id ${id} belongs to built-in package ${name}.`);
+      configured.delete(id);
+    }
+  }
+
+  const projectDependencies = dependenciesOf(project);
+  const folders = new Set();
+  const records = [];
+
+  for (const [id, mapping] of configured) {
+    const name = mapping.name;
+    if (
+      !validId.test(id) ||
+      typeof name !== "string" ||
+      !validName.test(name) ||
+      projectDependencies[name] === undefined
+    ) {
+      if (skipInvalid) continue;
+      throw new Error(`Invalid npm plugin dependency: ${id}.`);
+    }
+
+    let manifestPath;
+    let failure;
+    try {
+      manifestPath = packageManifest(dependencyRoot, name);
+    } catch (error) {
+      failure = error;
+    }
+    if (!manifestPath) {
+      if (skipInvalid) continue;
+      throw new Error(`Missing npm plugin ${name}. Run npm install in ${dependencyRoot}.`, {
+        cause: failure
+      });
+    }
+    let metadata;
+    try {
+      metadata = readJson(manifestPath);
+    } catch (error) {
+      if (skipInvalid) continue;
+      throw error;
+    }
+    const definition = metadata.elementspanel?.[selectedSide];
+    // A project dependency may only ship one side; the other side simply does
+    // not see it. A built-in plugin declared by the runtime must carry this side.
+    if (!definition) {
+      if (mapping.source === "project" || skipInvalid) continue;
+      throw new Error(`Invalid ${selectedSide} entry in npm plugin ${name}.`);
+    }
+    const pluginRoot = path.dirname(manifestPath);
+    if (
+      typeof definition.directory !== "string" ||
+      typeof definition.folder !== "string" ||
+      !validId.test(definition.folder) ||
+      path.isAbsolute(definition.directory)
+    ) {
+      if (skipInvalid) continue;
+      throw new Error(`Npm plugin entry escapes its package: ${name}.`);
+    }
+    const directory = path.resolve(pluginRoot, definition.directory);
+    if (directory === pluginRoot || !within(pluginRoot, directory)) {
+      if (skipInvalid) continue;
+      throw new Error(`Npm plugin entry escapes its package: ${name}.`);
+    }
+    let entries;
+    try {
+      entries = readJson(path.join(directory, "plugin.json"));
+    } catch (error) {
+      if (skipInvalid) continue;
+      throw error;
+    }
+    if (
+      metadata.elementspanel?.id !== id ||
+      typeof metadata.version !== "string" ||
+      !metadata.version.trim() ||
+      !entries ||
+      typeof entries !== "object" ||
+      Array.isArray(entries)
+    ) {
+      if (skipInvalid) continue;
+      throw new Error(`Invalid npm plugin identity or version in package.json: ${name}.`);
+    }
+    if (folders.has(definition.folder)) {
+      if (skipInvalid) continue;
+      throw new Error(`Duplicate npm plugin asset directory: ${definition.folder}.`);
+    }
+    folders.add(definition.folder);
+    records.push({
+      id,
+      name,
+      version: metadata.version,
+      source: mapping.source,
+      defaultEnabled: mapping.automatic === true || mapping.source !== "project",
+      packageRoot: pluginRoot,
+      directory,
+      folder: definition.folder,
+      dependencies: Object.keys(metadata.dependencies || {})
+    });
+  }
+  return records;
+}
+
+module.exports = { resolveNpmPlugins, projectManifestFile };
+
+
 /***/ },
 
 /***/ "../../scripts/workspace-layout.cjs"