carouselbot 0.2.0 → 0.3.1

package/README.md

@@ -1,11 +1,15 @@
 # CarouselBot MCP
 
-Local-first MCP companion for the hosted [CarouselBot editor](https://carousel.bot). It exposes project, slide, text, image, layer, history, rendering, and export controls to any stdio MCP client while the editor remains in the browser.
+Local-first MCP companion for the hosted [CarouselBot editor](https://carousel.bot). It exposes project, folder, slide, text, image, layer, history, rendering, and export controls to any stdio MCP client while the editor remains in the browser.
 
 ```bash
 npx carouselbot@latest setup
 ```
 
+Setup pins that exact package version in the generated MCP configuration, refreshes
+the agent skill, and automatically upgrades an older shared daemon. Rerun the
+command when you intentionally want to update.
+
 For non-interactive agent setup, select the current client explicitly:
 
 ```bash
@@ -22,17 +26,33 @@ The same validated tool surface is available through the package CLI when a runn
 npx -y carouselbot@latest call get_design_guidance
 npx -y carouselbot@latest call list_editors
 npx -y carouselbot@latest call begin_edit_session --json '{"editorId":"EDITOR_ID","purpose":"Build my deck"}'
-npx -y carouselbot@latest call create_project --json '{"editSessionId":"SESSION_ID","name":"My presentation"}'
+npx -y carouselbot@latest call create_project --json '{"editSessionId":"SESSION_ID","name":"My presentation","folderPath":"/campaigns"}'
 ```
 
 Every MCP tool name and JSON argument shape works with `call`. The CLI-only `list_tools` helper lists names compactly or returns selected schemas. `render_slide` writes image output to a temporary `previewPath` instead of dumping base64 into the terminal.
 
+Folders use exact canonical slash paths such as `/campaigns` and are derived from project membership. Pass `folderPath` to `create_project` to create a project in a folder. Use `move_project` with another slash path to move it between folders, or with `folderPath: null` to move it back to the dashboard root. Embedded slashes are part of the virtual path and do not create a nested UI hierarchy. Because folders are implicit, moving the last project out removes the empty folder card automatically. `inspect_editor` returns each project's current folder path.
+
 Always use `list_editors` to check the browser connection. Do not open CarouselBot or click **Connect AI** through a sandboxed, remote, or agent-controlled browser: that is a different browser session and may not reach the local companion.
 
-Browser reconnection is automatic. Retry transient disconnects; use `restart` only for an explicit protocol mismatch or failed daemon health check. Hermes can refresh native tools with `/reload-mcp` and `/reload-skills`. Claude may need a new session to register a newly added server, but the CLI fallback works immediately.
+Browser and MCP-process reconnection are automatic, including after a compatible daemon upgrade. The MCP checks the daemon's advertised internal actions rather than trusting the browser protocol number alone. Retry transient disconnects; use `restart` only when automatic recovery or `doctor` reports a failed daemon health check. An already-running host may still need to refresh its native tool catalog when a release adds entirely new tool names; the CLI fallback works immediately without waiting for that refresh.
 
 The companion binds only to `127.0.0.1`. There is no hosted relay: projects remain in browser IndexedDB and local images remain on the user's computer.
 
+## Installed fonts
+
+CarouselBot can use fonts installed on the same Mac as the companion. Open a text layer's font control once and choose **Allow local fonts**. The permission is stored in that browser; until it is granted, agent calls return `FONT_PERMISSION_REQUIRED`.
+
+Agents use project-scoped IDs rather than CSS family guesses:
+
+```text
+list_local_fonts({ query: "Didot" })
+import_font({ editSessionId, projectId, localFontId })
+add_text({ editSessionId, projectId, slideId, text, fontId })
+```
+
+`list_project_fonts` reports faces already embedded in a project. `add_text` and `update_text` accept the returned `fontId`, plus optional `fontWeight`, `fontStyle`, and variable-axis settings. The companion returns opaque local font IDs and never exposes font paths. A selected face is transferred over the authenticated loopback connection, persisted only in the browser's local IndexedDB project, and loaded before fitting or rendering. If the exact bytes are missing or invalid, rendering reports `FONT_UNAVAILABLE` instead of silently using a fallback.
+
 Any MCP client can launch it with:
 
 ```bash

package/guidance/design.md

@@ -20,6 +20,7 @@ Read this before creating or editing slides. Use it as a compact quality bar, th
 - Align related text layers consistently. Center is a safe default; use left alignment for editorial layouts.
 - Use rotation sparingly. Small intentional angles can add energy; arbitrary angles make carousels feel inconsistent.
 - Reuse a small palette and consistent type scale across the project.
+- For an installed Mac font, select an exact face with `list_local_fonts`, import its opaque ID with `import_font`, and apply only the returned project `fontId`. Reuse project faces through `list_project_fonts`; never guess family strings.
 
 ## Working method
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carouselbot",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Local-first MCP companion for the hosted CarouselBot editor",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
+    "fontkit": "^2.0.4",
     "zod": "^4.4.3"
   },
   "publishConfig": {

package/skill/carouselbot/SKILL.md

@@ -16,18 +16,20 @@ Before using any browser or making edits, call `list_editors`. A registered edit
 
 Browser reconnection is automatic. After `EDITOR_DISCONNECTED`, `EDITOR_RELOADED`, a dropped browser request, or an empty `list_editors` result that follows a working connection, wait briefly and retry `list_editors` several times. Do not restart the companion for a transient browser disconnect: restarting invalidates every browser session and makes recovery slower. If the editor does not return, ask the user to keep or reload the real editor tab; preserve completed project work and begin a new edit session after it reconnects.
 
-Run `npx -y carouselbot@latest restart` only when the MCP explicitly reports an outdated companion protocol or `doctor` reports that the daemon itself is unhealthy. After a necessary restart, ask the user to reload their real editor tab and retry `list_editors`.
+The MCP checks the shared daemon's actual internal capabilities before advertising tools. It automatically replaces an outdated daemon, keeps the MCP process alive, and lets the remembered browser connection reconnect. Do not ask the user to reload MCP or restart Hermes for daemon recovery.
+
+If an advertised tool nevertheless returns `UNSUPPORTED_INTERNAL_ACTION` or `Unknown internal action`, stop after that first failure; do not fan out parallel retries that can trip the host's whole-server circuit breaker. Retry `list_editors` once so automatic recovery can finish, then retry the original tool once. If recovery itself reports that no compatible companion could start, run `npx -y carouselbot@latest doctor` and then `npx -y carouselbot@latest restart` once. Only ask the user to reload their real editor tab if it does not reconnect automatically. Never restart the companion for a transient browser disconnect.
 
 If the native MCP tools are not registered in the current session, do not stop or ask for a restart. Use the same validated tools through the local CLI fallback:
 
 ```bash
 npx -y carouselbot@latest call get_design_guidance
 npx -y carouselbot@latest call list_editors
-npx -y carouselbot@latest call list_tools --json '{"names":["add_slide","add_text"]}'
-npx -y carouselbot@latest call create_project --json '{"name":"My presentation"}'
+npx -y carouselbot@latest call list_tools --json '{"names":["create_project","move_project","add_slide","add_text"]}'
+npx -y carouselbot@latest call create_project --json '{"name":"My presentation","folderPath":"/campaigns"}'
 ```
 
-Every tool accepts the same JSON arguments as MCP. Use `list_tools` without arguments for compact discovery or pass `{"names":[...]}` to retrieve selected schemas. Prefer `apply_operations` for batches. `render_slide` writes its returned image to a temporary local `previewPath`; inspect that file and remove the temporary directory after the review. Hermes can load the native tools in place with `/reload-mcp` and refresh this skill with `/reload-skills`.
+Every tool accepts the same JSON arguments as MCP. Use `list_tools` without arguments for compact discovery or pass `{"names":[...]}` to retrieve selected schemas. Prefer `apply_operations` for batches. `render_slide` writes its returned image to a temporary local `previewPath`; inspect that file and remove the temporary directory after the review. A daemon replacement never requires `/reload-mcp`. Hermes only needs `/reload-mcp` when a package update adds entirely new native tool names to an already-running agent session; use the CLI fallback immediately in that rare case. A newly installed skill becomes active in the next session or after `/reload-skills`, but correctness must never depend on the user doing that manually.
 
 Before the first mutation in a task, call `get_design_guidance`. The server intentionally rejects mutations until this guidance has been read.
 
@@ -46,6 +48,17 @@ With only one agent and one editor, the server can create an implicit session fo
 
 Inspect the assigned editor before editing and keep the returned IDs and revision. Work on the assigned project and slide. Pass `expectedRevision` for sensitive mutations. If `STALE_PROJECT` is returned, the browser has reloaded the canonical IndexedDB copy; inspect again and retry with current IDs. Prefer `apply_operations` for compact related changes while preserving logical order.
 
+When the user asks for a font installed on their Mac, use the deterministic two-ID flow:
+
+1. Call `list_local_fonts` with a family/style query and choose an exact face from its metadata. Never guess a CSS family or construct a `localFontId`.
+2. Call `import_font` with that opaque `localFontId`. Keep the returned project-scoped `fontId`.
+3. Pass the returned `fontId` to `add_text` or `update_text`. Import and application are separate calls for a newly selected face; do not invent a batch placeholder.
+4. Render and inspect the result. Use `list_project_fonts` to reuse faces already embedded in the project.
+
+If listing returns `FONT_PERMISSION_REQUIRED`, ask the user to open the real CarouselBot tab and choose **Allow local fonts** from the text font control, then retry. Do not bypass this with browser automation. Font paths and bytes are intentionally unavailable to agents. If rendering reports `FONT_UNAVAILABLE`, preserve the editable text, report the missing face, and ask the user to replace or re-import it rather than accepting fallback pixels.
+
+Dashboard folders are implicit and use exact canonical slash paths such as `/campaigns`. Set `folderPath` when calling `create_project` to create the project inside a folder. Call `move_project` with another slash path to move it between folders, or with `folderPath: null` to move it back to the dashboard root. Embedded slashes remain part of one virtual path rather than creating a nested UI hierarchy. Moving the final project out of a folder removes that empty folder automatically. Use `inspect_editor` to read each project's current `folderPath`.
+
 Use readable role-based type ranges: title `92–124`, subtitle `68–84`, body `54–68`, caption `44–52`. Do not solve dense copy by dropping below the body range; shorten it or split it across slides. `add_text` and `update_text` automatically preserve width and fit height around every wrapped line with safe padding. For highlighted text, prefer `style: "boxed"` with `backgroundShape: "lines"`. Use `backgroundShape: "full"` only for a deliberate card. Call `fit_text_boxes` with `mode: "both"` only when you intentionally want the width to shrink too.
 
 After each meaningful composition or after a short batch, call `render_slide` and inspect the returned image. Fix clipping, spacing, contrast, unsafe overlay placement, and weak hierarchy before claiming the slide is finished. Use `export_slide` or `export_project` only when local files are requested; do not overwrite existing files unless authorized.

package/src/companion.mjs

@@ -2,10 +2,15 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
-import { BRIDGE_URL, DAEMON_STATE_PATH, PACKAGE_VERSION, PROTOCOL_VERSION } from "./config.mjs";
+import {
+  BRIDGE_URL, DAEMON_API_VERSION, DAEMON_INTERNAL_ACTIONS, DAEMON_STATE_PATH,
+  PACKAGE_VERSION, PROTOCOL_VERSION,
+} from "./config.mjs";
 import { preferHostAgent } from "./agent-identity.mjs";
 
 const DAEMON_ENTRY = fileURLToPath(new URL("daemon.mjs", import.meta.url));
+const START_TIMEOUT_MS = 8_000;
+const STOP_TIMEOUT_MS = 8_000;
 
 const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 
@@ -23,62 +28,158 @@ async function daemonRequest(state, path, init = {}) {
   if (!response.ok) {
     const error = new Error(value.error || `Local companion returned ${response.status}.`);
     error.status = response.status;
+    if (value.code) error.code = value.code;
+    if (value.details) error.details = value.details;
     throw error;
   }
   return value;
 }
 
-async function healthyState() {
+function compatibilityIssue(health, { requireCurrentVersion = false } = {}) {
+  if (health.protocolVersion !== PROTOCOL_VERSION) {
+    return `browser protocol ${health.protocolVersion ?? "unknown"} (requires ${PROTOCOL_VERSION})`;
+  }
+  const advertisedActions = new Set(Array.isArray(health.capabilities?.internalActions) ? health.capabilities.internalActions : []);
+  const missingActions = DAEMON_INTERNAL_ACTIONS.filter((action) => !advertisedActions.has(action));
+  if (missingActions.length) return `missing internal actions: ${missingActions.join(", ")}`;
+  const advertisedApiVersion = Number(health.daemonApiVersion);
+  if (!Number.isInteger(advertisedApiVersion) || advertisedApiVersion < DAEMON_API_VERSION) {
+    return `daemon API ${health.daemonApiVersion ?? "unknown"} (requires ${DAEMON_API_VERSION})`;
+  }
+  if (requireCurrentVersion && health.version !== PACKAGE_VERSION) {
+    return `package ${health.version || "unknown"} (requires ${PACKAGE_VERSION})`;
+  }
+  return null;
+}
+
+function stateWithHealth(state, health) {
+  return {
+    ...state,
+    pid: health.pid || state.pid,
+    version: health.version || state.version || null,
+    protocolVersion: health.protocolVersion,
+    daemonApiVersion: health.daemonApiVersion,
+    capabilities: health.capabilities,
+  };
+}
+
+async function inspectDaemon(options = {}) {
   const state = await readState();
   if (!state?.secret || state.port == null) return null;
   try {
-    const result = await daemonRequest(state, "/internal/health");
-    if (result.protocolVersion !== PROTOCOL_VERSION) {
-      const error = new Error(`Local companion ${result.version || "unknown"} uses protocol ${result.protocolVersion}; ${PACKAGE_VERSION} requires protocol ${PROTOCOL_VERSION}. Run \`npx -y carouselbot@latest restart\`, then reload the editor.`);
-      error.code = "EPROTOCOL";
-      throw error;
-    }
-    return state;
-  } catch (error) {
-    if (error.code === "EPROTOCOL") throw error;
+    const health = await daemonRequest(state, "/internal/health");
+    return { state: stateWithHealth(state, health), health, issue: compatibilityIssue(health, options) };
+  } catch {
     return null;
   }
 }
 
-async function ensureDaemon() {
-  const existing = await healthyState();
-  if (existing) return existing;
+async function processIsRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch { return false; }
+}
+
+async function stopDaemon({ state, health }) {
+  const pid = Number(health?.pid || state?.pid);
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  let shutdownAccepted = false;
+  try {
+    const response = await daemonRequest(state, "/internal/shutdown", { method: "POST", body: "{}" });
+    shutdownAccepted = response?.pid === pid;
+  } catch { /* Older companions may not expose graceful shutdown. */ }
+  if (!shutdownAccepted) {
+    try { process.kill(pid, "SIGTERM"); } catch { return; }
+  }
+  const deadline = Date.now() + STOP_TIMEOUT_MS;
+  while (Date.now() < deadline && await processIsRunning(pid)) await wait(100);
+  if (await processIsRunning(pid)) {
+    try { process.kill(pid, "SIGTERM"); } catch { /* It already stopped. */ }
+    const forcedDeadline = Date.now() + 2_000;
+    while (Date.now() < forcedDeadline && await processIsRunning(pid)) await wait(100);
+  }
+}
+
+let ensureQueue = Promise.resolve();
+
+async function ensureDaemonOnce({ forceReplace = false, requireCurrentVersion = false } = {}) {
+  const options = { requireCurrentVersion };
+  const existing = await inspectDaemon(options);
+  if (existing && !forceReplace && !existing.issue) return existing.state;
+  if (existing) await stopDaemon(existing);
+
   const child = spawn(process.execPath, [DAEMON_ENTRY], {
     detached: true,
     stdio: "ignore",
     env: process.env,
   });
   child.unref();
-  const deadline = Date.now() + 8000;
+
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  let lastIssue = existing?.issue || null;
   while (Date.now() < deadline) {
     await wait(100);
-    const state = await healthyState();
-    if (state) return state;
+    const candidate = await inspectDaemon(options);
+    if (!candidate) continue;
+    if (!candidate.issue) return candidate.state;
+    lastIssue = candidate.issue;
   }
-  throw new Error("Could not start the local CarouselBot companion. Run `npx carouselbot doctor` for details.");
+  const detail = lastIssue ? ` Last companion was incompatible: ${lastIssue}.` : "";
+  throw new Error(`Could not start a compatible local CarouselBot companion.${detail} Run \`npx -y carouselbot@latest doctor\` for details.`);
+}
+
+function ensureDaemon(options = {}) {
+  const operation = ensureQueue.then(() => ensureDaemonOnce(options));
+  ensureQueue = operation.catch(() => {});
+  return operation;
+}
+
+function unsupportedInternalAction(error) {
+  return error?.code === "UNSUPPORTED_INTERNAL_ACTION" || /Unknown internal action:/i.test(error?.message || "");
 }
 
 export async function createCompanion(initialName = "MCP agent", initialVersion = null) {
+  // Compatibility is resolved before the stdio server advertises its tools. A
+  // stale shared daemon is replaced in place; this MCP process stays alive and
+  // the browser's remembered loopback connection reconnects automatically.
   let state = await ensureDaemon();
   const clientId = randomUUID();
   let clientName = initialName;
   let clientVersion = initialVersion;
   let closed = false;
+  let unsupportedRecovery = null;
+  const repairedUnsupportedActions = new Set();
 
   const rawPost = (path, body) => daemonRequest(state, path, { method: "POST", body: JSON.stringify(body) });
   const register = () => rawPost("/internal/client/connect", { clientId, name: clientName, version: clientVersion });
+  const recoverUnsupportedAction = (action) => {
+    if (unsupportedRecovery) return unsupportedRecovery;
+    if (repairedUnsupportedActions.has(action)) return null;
+    repairedUnsupportedActions.add(action);
+    const recovery = (async () => {
+      state = await ensureDaemon({ forceReplace: true });
+      await register();
+    })();
+    const trackedRecovery = recovery.finally(() => {
+      if (unsupportedRecovery === trackedRecovery) unsupportedRecovery = null;
+    });
+    unsupportedRecovery = trackedRecovery;
+    return unsupportedRecovery;
+  };
   const post = async (path, body) => {
     try {
       return await rawPost(path, body);
     } catch (error) {
-      if (closed || (error.status && error.status !== 401)) throw error;
-      state = await ensureDaemon();
-      await register();
+      const unsupportedAction = path === "/internal/call" && unsupportedInternalAction(error) ? body.action : null;
+      if (closed || (error.status && error.status !== 401 && !unsupportedAction)) throw error;
+      if (unsupportedAction) {
+        const recovery = recoverUnsupportedAction(unsupportedAction);
+        if (!recovery) throw error;
+        await recovery;
+      } else {
+        state = await ensureDaemon();
+        await register();
+      }
       return rawPost(path, body);
     }
   };
@@ -90,11 +191,20 @@ export async function createCompanion(initialName = "MCP agent", initialVersion
 
   return {
     clientId,
-    get daemon() { return { pid: state.pid, url: BRIDGE_URL, version: state.version, packageVersion: PACKAGE_VERSION }; },
+    get daemon() {
+      return {
+        pid: state.pid,
+        url: BRIDGE_URL,
+        version: state.version,
+        packageVersion: PACKAGE_VERSION,
+        daemonApiVersion: state.daemonApiVersion,
+        capabilities: state.capabilities,
+      };
+    },
     async identify(name, version) {
       clientName = preferHostAgent(name, clientName);
       clientVersion = version || clientVersion;
-      await register();
+      await post("/internal/client/connect", { clientId, name: clientName, version: clientVersion });
     },
     async call(action, body = {}) {
       const response = await post("/internal/call", { clientId, action, ...body });
@@ -112,29 +222,34 @@ export async function createCompanion(initialName = "MCP agent", initialVersion
 export async function companionDoctor() {
   const state = await ensureDaemon();
   const health = await daemonRequest(state, "/internal/health");
-  return { ...health, url: BRIDGE_URL, stateFile: DAEMON_STATE_PATH };
+  return { ...health, packageVersion: PACKAGE_VERSION, compatible: true, url: BRIDGE_URL, stateFile: DAEMON_STATE_PATH };
+}
+
+export async function companionUpgrade() {
+  const previous = await inspectDaemon();
+  const state = await ensureDaemon({ requireCurrentVersion: true });
+  const health = await daemonRequest(state, "/internal/health");
+  return {
+    ...health,
+    packageVersion: PACKAGE_VERSION,
+    compatible: true,
+    upgraded: Boolean(previous && previous.health.version !== health.version),
+    previousPid: previous?.health.pid || null,
+    url: BRIDGE_URL,
+    stateFile: DAEMON_STATE_PATH,
+  };
 }
 
 export async function companionRestart() {
-  const previous = await readState();
-  if (previous?.secret && Number.isInteger(previous.pid) && previous.pid > 0) {
-    const health = await daemonRequest(previous, "/internal/health").catch(() => null);
-    if (health?.pid === previous.pid) {
-      await daemonRequest(previous, "/internal/shutdown", { method: "POST", body: "{}" }).catch(() => {
-        try { process.kill(previous.pid, "SIGTERM"); } catch { /* It already stopped. */ }
-      });
-      const deadline = Date.now() + 8000;
-      while (Date.now() < deadline) {
-        try {
-          process.kill(previous.pid, 0);
-          await wait(100);
-        } catch {
-          break;
-        }
-      }
-    }
-  }
-  const state = await ensureDaemon();
+  const previous = await inspectDaemon();
+  const state = await ensureDaemon({ forceReplace: true });
   const health = await daemonRequest(state, "/internal/health");
-  return { ...health, url: BRIDGE_URL, stateFile: DAEMON_STATE_PATH, previousPid: previous?.pid || null };
+  return {
+    ...health,
+    packageVersion: PACKAGE_VERSION,
+    compatible: true,
+    url: BRIDGE_URL,
+    stateFile: DAEMON_STATE_PATH,
+    previousPid: previous?.health.pid || null,
+  };
 }

package/src/config.mjs

@@ -8,6 +8,26 @@ export const PACKAGE_JSON = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.
 export const PACKAGE_NAME = PACKAGE_JSON.name;
 export const PACKAGE_VERSION = PACKAGE_JSON.version;
 export const PROTOCOL_VERSION = 3;
+// The browser protocol changes only when the hosted editor and companion can no
+// longer communicate. Internal MCP-to-daemon actions evolve independently, so
+// advertise them explicitly instead of treating a matching browser protocol as
+// proof that two installed package versions are compatible.
+export const DAEMON_API_VERSION = 1;
+export const DAEMON_INTERNAL_ACTIONS = Object.freeze([
+  "batch",
+  "begin_edit_session",
+  "browser",
+  "end_edit_session",
+  "list_edit_sessions",
+  "list_editors",
+  "list_local_fonts",
+  "list_recent_operations",
+  "notify",
+  "prepare_font",
+  "prepare_media",
+  "select_editor",
+  "write_export",
+]);
 export const BRIDGE_HOST = "127.0.0.1";
 export const BRIDGE_PORT = Number(process.env.CAROUSELBOT_BRIDGE_PORT || process.env.SLIDE_STUDIO_BRIDGE_PORT) || 43117;
 export const BRIDGE_URL = `http://${BRIDGE_HOST}:${BRIDGE_PORT}`;