@engine-room/after-effects-mcp 0.2.0 → 0.2.1

package/bin/server.js

@@ -1342,19 +1342,55 @@ function cepExtensionsDir() {
 function installedPanelDir() {
   return path4.join(cepExtensionsDir(), BUNDLE_ID);
 }
+function isWsModuleDir(dir) {
+  try {
+    const pkg = JSON.parse(fs3.readFileSync(path4.join(dir, "package.json"), "utf8"));
+    if (pkg.name !== "ws") return false;
+    return fs3.existsSync(path4.join(dir, "index.js")) && fs3.existsSync(path4.join(dir, "lib", "websocket.js"));
+  } catch {
+    return false;
+  }
+}
 function wsModuleDir() {
+  const candidates = [];
   try {
     const require2 = createRequire(import.meta.url);
     const entry = require2.resolve("ws");
-    const marker = `${path4.sep}node_modules${path4.sep}ws${path4.sep}`;
-    const idx = entry.lastIndexOf(marker);
-    if (idx >= 0) return entry.slice(0, idx + marker.length - 1);
-    return path4.dirname(entry);
+    if (path4.isAbsolute(entry)) {
+      const marker = `${path4.sep}node_modules${path4.sep}ws${path4.sep}`;
+      const idx = entry.lastIndexOf(marker);
+      candidates.push(idx >= 0 ? entry.slice(0, idx + marker.length - 1) : path4.dirname(entry));
+    }
+  } catch {
+  }
+  candidates.push(path4.join(executableDir(), "node_modules", "ws"));
+  candidates.push(path4.join(packageRoot(), "node_modules", "ws"));
+  for (const dir of candidates) {
+    if (isWsModuleDir(dir)) return dir;
+  }
+  return null;
+}
+function listPanelFiles(dir, prefix = "") {
+  const out = [];
+  for (const entry of fs3.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name === ".DS_Store") continue;
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listPanelFiles(path4.join(dir, entry.name), rel));
+    else out.push(rel);
+  }
+  return out;
+}
+function sameContents(a, b) {
+  try {
+    if (fs3.statSync(a).size !== fs3.statSync(b).size) return false;
+    return fs3.readFileSync(a).equals(fs3.readFileSync(b));
   } catch {
-    const beside = path4.join(executableDir(), "node_modules", "ws");
-    return fs3.existsSync(beside) ? beside : null;
+    return false;
   }
 }
+function panelInstallDiff(source, installed) {
+  return listPanelFiles(source).filter((rel) => !sameContents(path4.join(source, rel), path4.join(installed, rel))).sort();
+}
 function copyRecursive(src, dst) {
   const stat = fs3.lstatSync(src);
   if (stat.isDirectory()) {
@@ -1391,10 +1427,14 @@ function hashFile(file) {
   }
 }
 var STALE_PANEL_ADVICE = "Tell the user this in plain language, then do it: the After Effects panel is older than these tools and does not understand everything they can do now. Run setup_panel, then ask them to quit and reopen After Effects. Do not retry the failed call until they confirm it has restarted.";
-function assessPanel(runningHash, installedHash) {
+var PARTIAL_INSTALL_ADVICE = "The installed After Effects panel is a mix of two versions \u2014 some files were updated and others were not, which happens when it is installed while After Effects is open and holding them. Restarting will not fix this. Tell the user to quit After Effects completely, then run setup_panel, then reopen it.";
+function assessPanel(runningHash, installedHash, opts = {}) {
   const shipped = sourceBundleHash();
   if (!shipped) return { state: "unknown", message: "" };
   if (runningHash === shipped) return { state: "current", message: "" };
+  if (opts.installComplete === false) {
+    return { state: "partial-install", message: PARTIAL_INSTALL_ADVICE };
+  }
   if (typeof runningHash !== "string" || runningHash.length === 0) {
     if (installedHash === shipped) {
       return {
@@ -1545,15 +1585,26 @@ async function checkSetup() {
     detail: isInstalled ? installed : `not present at ${installed}`,
     fix: isInstalled ? void 0 : "Run the setup_panel tool to install it."
   });
+  let installComplete = true;
   if (isInstalled && source) {
-    const installedHash = sha256(path6.join(installed, "jsx", "bundle.jsx"));
-    const sourceHash = sha256(path6.join(source, "jsx", "bundle.jsx"));
-    const upToDate = installedHash !== null && installedHash === sourceHash;
+    const differing = panelInstallDiff(source, installed);
+    installComplete = differing.length === 0;
+    const shown = differing.slice(0, 4).join(", ");
     checks.push({
       name: "panelUpToDate",
-      ok: upToDate,
-      detail: upToDate ? "installed panel matches this server version" : "installed panel differs from the version shipped with this server",
-      fix: upToDate ? void 0 : "Run setup_panel to refresh it, then restart After Effects."
+      ok: installComplete,
+      detail: installComplete ? "all installed panel files match the version shipped with this server" : `${differing.length} file(s) differ from the version shipped with this server: ${shown}${differing.length > 4 ? ", \u2026" : ""}`,
+      fix: installComplete ? void 0 : "Quit After Effects completely, then run setup_panel, then reopen it. Installing while AE is open can leave some files updated and others not, which is what this is \u2014 restarting alone will not fix it."
+    });
+  }
+  if (isInstalled) {
+    const panelWs = path6.join(installed, "node_modules", "ws");
+    const wsOk = isWsModuleDir(panelWs);
+    checks.push({
+      name: "panelDependencies",
+      ok: wsOk,
+      detail: wsOk ? "the panel's `ws` module is present and complete" : `the panel's \`ws\` module is missing or incomplete at ${panelWs}`,
+      fix: wsOk ? void 0 : "Quit After Effects completely, then run setup_panel, then reopen it. Without `ws` the panel cannot finish starting, so it never answers on its port."
     });
   }
   const running = await isAfterEffectsRunning();
@@ -1572,12 +1623,14 @@ async function checkSetup() {
     fix: bridge.ok ? void 0 : "If the other checks pass, restart After Effects so the panel reloads."
   });
   if (bridge.ok && source) {
-    const assessment = assessPanel(bridge.bundleHash, sha256(path6.join(installed, "jsx", "bundle.jsx")));
+    const assessment = assessPanel(bridge.bundleHash, sha256(path6.join(installed, "jsx", "bundle.jsx")), {
+      installComplete
+    });
     const ok = assessment.state === "current";
     checks.push({
       name: "panelRunningCurrent",
       ok,
-      detail: ok ? "After Effects is running the panel that ships with these tools" : assessment.state === "restart-needed" ? "After Effects is still running the previous panel \u2014 the update needs a restart to take effect" : assessment.state === "unknown" ? "the running panel is too old to report its version" : "After Effects is running a panel older than these tools",
+      detail: ok ? "After Effects is running the panel that ships with these tools" : assessment.state === "partial-install" ? "the installed panel files are a mix of versions \u2014 a restart cannot resolve this" : assessment.state === "restart-needed" ? "After Effects is still running the previous panel \u2014 the update needs a restart to take effect" : assessment.state === "unknown" ? "the running panel is too old to report its version" : "After Effects is running a panel older than these tools",
       fix: ok ? void 0 : assessment.message
     });
   }
@@ -1598,24 +1651,29 @@ function buildNextSteps(checks, ready) {
   const steps = [];
   if (by("platform")?.ok === false) return [by("platform").fix];
   if (by("panelAssetsPresent")?.ok === false) return [by("panelAssetsPresent").fix];
-  const needsInstall = by("panelInstalled")?.ok === false || by("panelUpToDate")?.ok === false;
+  const brokenInstall = by("panelUpToDate")?.ok === false || by("panelDependencies")?.ok === false;
+  const needsInstall = by("panelInstalled")?.ok === false || brokenInstall;
   const needsDebug = by("cepDebugMode")?.ok === false;
+  const aeRunning = by("afterEffectsRunning")?.ok === true;
+  if (brokenInstall && aeRunning) {
+    steps.push("Quit After Effects completely \u2014 installing while it is open is what leaves the panel half-updated.");
+  }
   if (needsDebug || needsInstall) {
     steps.push("Run the setup_panel tool \u2014 it installs the After Effects panel and enables the Adobe preference that lets AE load it.");
   }
-  if (needsDebug) {
-    steps.push(
-      process.platform === "win32" ? "Quit and reopen After Effects so it re-reads the registry." : "Quit and reopen After Effects. If the panel still does not connect, restart the Mac once \u2014 the Adobe preference sometimes only takes effect after a reboot."
-    );
-  }
   const identity = by("panelIdentity");
   if (identity && identity.ok === false) {
     steps.push(identity.fix);
   }
-  if (by("afterEffectsRunning")?.ok === false) {
+  if (!aeRunning) {
     steps.push(needsInstall ? "Open After Effects 2026 \u2014 the panel loads with it." : "Open After Effects 2026.");
   } else if (needsInstall || by("panelRunningCurrent")?.ok === false) {
-    steps.push("Quit and reopen After Effects so it picks up the panel.");
+    steps.push(brokenInstall ? "Reopen After Effects." : "Quit and reopen After Effects so it picks up the panel.");
+  }
+  if (needsDebug) {
+    steps.push(
+      process.platform === "win32" ? "After Effects re-reads the registry when it launches, so the preference takes effect then." : "If the panel still does not connect after reopening, restart the Mac once \u2014 the Adobe preference sometimes only takes effect after a reboot."
+    );
   }
   if (steps.length === 0 && by("bridgeReachable")?.ok === false) {
     steps.push("Everything is installed but the panel is not answering. Quit and reopen After Effects.");
@@ -1642,6 +1700,12 @@ async function installPanel(opts = {}) {
   if (!fs6.existsSync(path7.join(source, "jsx", "bundle.jsx"))) {
     throw new Error(`The panel at ${source} has no jsx/bundle.jsx. In a git checkout, run \`npm run build:jsx\` first.`);
   }
+  const ws = wsModuleDir();
+  if (!ws) {
+    throw new Error(
+      "Could not find the `ws` module this server ships. The After Effects panel cannot start without it, so nothing has been changed. Reinstall the server, and please report this with your platform and how you installed it."
+    );
+  }
   const target = installedPanelDir();
   const existing = fs6.lstatSync(target, { throwIfNoEntry: false });
   if (existing?.isSymbolicLink() && !opts.force) {
@@ -1665,16 +1729,16 @@ async function installPanel(opts = {}) {
   fs6.mkdirSync(path7.dirname(target), { recursive: true });
   copyRecursive(source, target);
   actions.push(`Installed the panel to ${target}.`);
-  const ws = wsModuleDir();
-  if (ws) {
-    const dest = path7.join(target, "node_modules", "ws");
-    fs6.mkdirSync(path7.dirname(dest), { recursive: true });
-    fs6.rmSync(dest, { recursive: true, force: true });
-    copyRecursive(ws, dest);
-    actions.push("Copied the `ws` module the panel needs at runtime.");
-  } else {
-    notes.push("Could not locate the `ws` module \u2014 the panel's WebSocket events may not work. Reinstall the package if progress notifications fail.");
+  const dest = path7.join(target, "node_modules", "ws");
+  fs6.mkdirSync(path7.dirname(dest), { recursive: true });
+  fs6.rmSync(dest, { recursive: true, force: true });
+  copyRecursive(ws, dest);
+  if (!isWsModuleDir(dest)) {
+    throw new Error(
+      `Copying \`ws\` from ${ws} to ${dest} did not produce a usable copy. The panel cannot start without it. The panel files are installed but the extension is not yet working \u2014 please report this.`
+    );
   }
+  actions.push("Copied the `ws` module the panel needs at runtime.");
   let rebootRecommended = false;
   if (opts.enableDebugMode !== false) {
     const existing2 = await isDebugModeOn();
@@ -1985,7 +2049,7 @@ var GetJobSchema = schemas_exports.GetJob;
 var CancelJobSchema = schemas_exports.CancelJob;
 function createServer() {
   const server = new Server(
-    { name: "after-effects-mcp", version: "0.2.0" },
+    { name: "after-effects-mcp", version: "0.2.1" },
     {
       capabilities: { tools: {}, logging: {}, prompts: {}, resources: {} },
       // Clients that honour this fold it into the system prompt, which is the
@@ -2192,7 +2256,11 @@ function createPanelGate(bridge) {
       if (Date.now() - checkedAt < RECHECK_MS) return null;
       try {
         const health = await bridge.health();
-        const assessment = assessPanel(health.bundleHash, installedBundleHash(installedPanelDir()));
+        const installed = installedPanelDir();
+        const source = panelSourceDir();
+        const assessment = assessPanel(health.bundleHash, installedBundleHash(installed), {
+          installComplete: source ? panelInstallDiff(source, installed).length === 0 : void 0
+        });
         checkedAt = Date.now();
         verdict = assessment.state === "current" || assessment.state === "unknown" ? null : assessment.message;
         if (assessment.state === "unknown" && assessment.message) logger.warn(assessment.message);
@@ -2291,7 +2359,7 @@ ${USAGE}`);
   await server.connect(transport);
   logger.info("MCP server running on stdio");
 }
-var VERSION = "0.2.0";
+var VERSION = "0.2.1";
 main().catch((e) => {
   logger.error("fatal", e.message);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engine-room/after-effects-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Control Adobe After Effects with AI — describe the animation you want and it gets built: layers, keyframes, effects, expressions and text, all editable afterwards.",
   "license": "MIT",

package/panel/CSXS/manifest.xml

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<ExtensionManifest Version="11.0" ExtensionBundleId="games.engine-room.ae-mcp" ExtensionBundleVersion="0.2.0"
+<ExtensionManifest Version="11.0" ExtensionBundleId="games.engine-room.ae-mcp" ExtensionBundleVersion="0.2.1"
                    ExtensionBundleName="AE MCP Bridge" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <ExtensionList>
-    <Extension Id="games.engine-room.ae-mcp.panel" Version="0.2.0" />
+    <Extension Id="games.engine-room.ae-mcp.panel" Version="0.2.1" />
   </ExtensionList>
   <ExecutionEnvironment>
     <HostList>

package/panel/client/main.js

@@ -11,14 +11,12 @@
   var os = require("os");
   var http = require("http");
   var crypto = require("crypto");
-  var WebSocket;
-  try { WebSocket = require("ws"); }
-  catch (e) {
-    // ws is bundled in packages/ae-panel/node_modules; resolve manually if normal require fails.
-    var alt = path.join(__dirname, "..", "node_modules", "ws");
-    WebSocket = require(alt);
-  }
 
+  // The DOM handles and the logger come first so that everything below is able
+  // to report its own failure. `require("ws")` used to run before this point,
+  // so when it threw the exception escaped this whole function before a single
+  // line could be written — the panel sat on "starting…" indefinitely with the
+  // reason nowhere to be seen.
   var $status = document.getElementById("status");
   var $port = document.getElementById("port");
   var $ae = document.getElementById("ae");
@@ -41,6 +39,24 @@
     while ($log.childNodes.length > 80) $log.removeChild($log.lastChild);
   }
 
+  var WebSocket;
+  try { WebSocket = require("ws"); }
+  catch (primary) {
+    // ws is bundled in packages/ae-panel/node_modules; resolve manually if normal require fails.
+    var alt = path.join(__dirname, "..", "node_modules", "ws");
+    try { WebSocket = require(alt); }
+    catch (fallback) {
+      // Nothing below can be built without ws, so this stops here — but it
+      // stops saying why, and naming the fix, rather than looking like a panel
+      // that is still starting up.
+      setStatus("cannot start — the ws module is missing", "err");
+      log("error", "require('ws') failed: " + primary.message);
+      log("error", "and " + alt + ": " + fallback.message);
+      log("error", "Quit After Effects, run the setup_panel tool, then reopen it.");
+      return;
+    }
+  }
+
   var cs = new CSInterface();
   var extDir = cs.getSystemPath(SystemPath.EXTENSION);
   var bundlePath = path.join(extDir, "jsx", "bundle.jsx");

package/panel/jsx/bundle.jsx

@@ -1,5 +1,5 @@
 // Auto-generated bundle. Do not edit directly — edit files in packages/jsx/.
-// Generated 2026-08-12T07:06:29.484Z
+// Generated 2026-08-12T07:48:29.949Z
 
 // ===== core.jsx =====
 

package/panel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engineroom/ae-panel",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": true,
   "description": "Invisible CEP extension hosting an HTTP+WS bridge inside After Effects.",
   "dependencies": {