slides-studio-mcp 0.1.0-beta.7 → 0.1.0

package/README.md

@@ -1,15 +1,15 @@
 # Slide Studio MCP
 
-Local-first MCP companion for the hosted [Slide Studio test editor](https://slides-mcp-poc-0821.pages.dev). It exposes complete 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 [Slide Studio editor](https://slides-editor.pages.dev). It exposes complete project, slide, text, image, layer, history, rendering, and export controls to any stdio MCP client while the editor remains in the browser.
 
 ```bash
-npx slides-studio-mcp@beta setup
+npx slides-studio-mcp@latest setup
 ```
 
 If an agent is doing the setup itself, it should select its current client and run non-interactively:
 
 ```bash
-npx slides-studio-mcp@beta setup --client=codex --yes
+npx slides-studio-mcp@latest setup --client=codex --yes
 ```
 
 Replace `codex` with `claude`, `hermes`, `opencode`, or `openclaw` for the agent doing the setup. OpenCode prints the version-appropriate JSON to merge into its config. Other detected clients are configured through their official CLI.
@@ -19,16 +19,18 @@ Replace `codex` with `claude`, `hermes`, `opencode`, or `openclaw` for the agent
 Some clients do not add a newly configured MCP server to the tool catalog of the already-running session. The same validated tool surface is available through the package CLI, so the current agent can continue immediately:
 
 ```bash
-npx -y slides-studio-mcp@beta call get_design_guidance
-npx -y slides-studio-mcp@beta call list_editors
-npx -y slides-studio-mcp@beta call begin_edit_session --json '{"editorId":"EDITOR_ID","purpose":"Build my deck"}'
-npx -y slides-studio-mcp@beta call create_project --json '{"editSessionId":"SESSION_ID","name":"My presentation"}'
+npx -y slides-studio-mcp@latest call get_design_guidance
+npx -y slides-studio-mcp@latest call list_editors
+npx -y slides-studio-mcp@latest call begin_edit_session --json '{"editorId":"EDITOR_ID","purpose":"Build my deck"}'
+npx -y slides-studio-mcp@latest call create_project --json '{"editSessionId":"SESSION_ID","name":"My presentation"}'
 ```
 
 Every MCP tool name and JSON argument shape works with `call`. The CLI-only `list_tools` helper lists all names compactly, or returns schemas for the requested names. The CLI automatically applies the guidance gate for each invocation and prints compact JSON. `render_slide` writes image output to a temporary `previewPath` instead of dumping base64 into the terminal.
 
 Always use `list_editors` to check the browser connection. Do not open Slide Studio or click **Connect AI** through a sandboxed, remote, or agent-controlled browser: that is a different browser session and may not have access to the user's local companion. If no editor is listed, ask the user to open the editor in their normal browser on the same computer and connect there, then retry `list_editors`.
 
+Browser reconnection is automatic. For a transient `EDITOR_DISCONNECTED`, `EDITOR_RELOADED`, dropped browser request, or newly empty editor list, wait briefly and retry `list_editors`; do not restart a healthy daemon. Use `restart` only for an explicit companion protocol mismatch or when `doctor` reports that the daemon itself is unhealthy. Restarting invalidates current browser session tokens and should not be used as generic connection recovery.
+
 Hermes can refresh native tools without restarting by running `/reload-mcp`, then `/reload-skills`. Claude may still need a new session to register a newly added plain stdio server, but its current session can use the CLI fallback instead of stopping.
 
 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.
@@ -36,15 +38,15 @@ The companion binds only to `127.0.0.1`. There is no hosted relay: projects rema
 Any MCP client can launch it with:
 
 ```bash
-npx -y slides-studio-mcp@beta serve
+npx -y slides-studio-mcp@latest serve
 ```
 
 Useful commands:
 
 ```bash
-npx slides-studio-mcp@beta setup --dry-run
-npx slides-studio-mcp@beta doctor
-npx slides-studio-mcp@beta restart
+npx slides-studio-mcp@latest setup --dry-run
+npx slides-studio-mcp@latest doctor
+npx slides-studio-mcp@latest restart
 ```
 
 `restart` gracefully replaces an outdated local companion. Reload the real browser editor afterward; current MCP clients automatically recover their daemon registration.
@@ -57,4 +59,4 @@ For parallel editing, the parent agent must reserve a different connected editor
 
 Browser writes use revision-checked IndexedDB transactions and cross-tab synchronization. A stale tab cannot replace a newer project snapshot; it reloads the canonical copy and returns `STALE_PROJECT` so the agent can inspect and retry.
 
-Open the test editor in the user's normal local browser, click **Connect AI**, and call `get_design_guidance` before editing. The server provides `render_slide` so agents can inspect actual pixels without permanently storing previews.
+Open the editor in the user's normal local browser, click **Connect AI**, and call `get_design_guidance` before editing. The server provides `render_slide` so agents can inspect actual pixels without permanently storing previews.

package/guidance/design.md

@@ -5,12 +5,15 @@ Read this before creating or editing slides. Use it as a compact quality bar, th
 ## Defaults that usually look good
 
 - Build for a 9:16 phone canvas and keep one clear idea per slide.
-- Prefer `boxed` text with `backgroundShape: "lines"` for highlighted copy. The per-line treatment is the product's strongest default.
-- Avoid `backgroundShape: "full"` unless a deliberate large label or card is required. A large rectangular text box usually looks heavy.
+- Prefer `boxed` text with `backgroundShape: "lines"` for highlighted copy. Treat per-line boxes as the default; use `full` only for a deliberate card or label.
+- `add_text` and `update_text` automatically preserve width and fit height around all wrapped lines with safety padding. Do not render just to discover clipping or call `fit_text_boxes` after ordinary copy edits.
+- Use `fit_text_boxes` with `mode: "both"` only when you intentionally want width to shrink as well. If automatic fitting rejects copy that cannot fit on one slide, shorten it or split it across slides.
+- After creating or changing any full-box text, call `fit_text_boxes`. A full box must hug its rendered content instead of leaving a large empty rectangle.
 - Use plain or outlined text for supporting copy. Use no more than two text treatments on one slide.
-- Start headlines around 64–88 px and supporting text around 42–60 px. Adjust after rendering.
+- Choose size by role rather than one universal value: titles `92–124`, subtitles `68–84`, body copy `54–68`, captions `44–52`. These are ranges, not fixed presets; render and adjust within them.
+- Do not shrink dense copy below the body range to make it fit. Shorten it or split it across slides. Aim for roughly 3–7 body lines on a slide.
 - Keep important content inside roughly `x: 0.06..0.86` and `y: 0.08..0.78` when the TikTok overlay matters. The right and bottom edges are occupied by interface controls and captions.
-- Give text boxes generous width and height. Leave at least 0.04 of canvas width beyond the visible longest line and enough height for every line plus its background. Never let glyphs or rounded backgrounds touch a box edge.
+- Give text boxes generous width while composing. Per-line backgrounds include protected edge padding; if content or size changes, render again and use `fit_text_boxes` when the box itself should hug the content.
 - Use short lines. Two to four lines for a headline is usually stronger than one dense paragraph.
 - Keep strong contrast between copy and the image. Use black boxed backgrounds with white text or white boxed backgrounds with near-black text.
 - Preserve an obvious focal image. Do not cover faces or the main subject unless the composition intentionally calls for it.
@@ -21,7 +24,7 @@ Read this before creating or editing slides. Use it as a compact quality bar, th
 ## Working method
 
 1. Inspect the editor and use the returned project, slide, asset, and layer IDs.
-2. Create or update one slide at a time. The editor automatically switches to the most recently changed slide.
+2. Create or update one slide at a time. If that project is already visible, the editor follows its most recently changed slide. Work on another project never takes over the user's current view.
 3. Use `apply_operations` when several related edits can be expressed compactly; the browser still shows each operation live.
 4. Call `render_slide` after a meaningful composition change and look at the returned image.
 5. Correct clipping, collisions, weak contrast, unsafe placement, inconsistent spacing, and visual imbalance before continuing.
@@ -31,8 +34,9 @@ Read this before creating or editing slides. Use it as a compact quality bar, th
 
 - Increase width before shrinking type when a line almost fits.
 - Increase height when multiline text or per-line backgrounds approach the top or bottom edge.
+- Use `fit_text_boxes` after changing full-box copy or font size. Use `mode: "height"` when the chosen width must remain fixed.
 - Keep `x + width` and `y + height` within the canvas unless an off-canvas effect is intentional.
-- With boxed text, keep `backgroundShape: "lines"` and do not size the box tightly around the letters; rounded pills need breathing room.
+- With boxed text, keep `backgroundShape: "lines"`; automatic height fitting includes minimum breathing room so rounded pills stay inside the text container.
 - If the result is uncertain, render it. Numeric state is not a visual review.
 
 ## Agent behavior
@@ -42,3 +46,4 @@ Read this before creating or editing slides. Use it as a compact quality bar, th
 - Keep tool responses and progress messages concise.
 - Prefer IDs returned by tools over guessed names or array positions.
 - Do not claim a slide looks good until you have inspected a rendered image.
+- Do not call `open_project` merely to edit or render another project. It intentionally changes the user's browser view; use it only when the user asks to see that project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slides-studio-mcp",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0",
   "description": "Local-first MCP companion for the hosted Slide Studio editor",
   "type": "module",
   "license": "MIT",
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/alexgusevski/tiktokslideeditor.git",
     "directory": "packages/mcp"
   },
-  "homepage": "https://slides-mcp-poc-0821.pages.dev",
+  "homepage": "https://slides-editor.pages.dev",
   "bugs": "https://github.com/alexgusevski/tiktokslideeditor/issues",
   "bin": {
     "slides-studio-mcp": "src/cli.mjs"

package/skill/slide-studio/SKILL.md

@@ -14,15 +14,17 @@ Before using any browser or making edits, call `list_editors`. A registered edit
 - If no editor is listed, ask the user to open the editor in their normal browser on the same computer, click **Connect AI**, and accept the browser permission. Then retry `list_editors`.
 - A loaded MCP server and a connected browser editor are different states. Determine browser connectivity only from `list_editors`, not from a sandbox browser or the agent's tool catalog.
 
-If the MCP reports an outdated companion protocol, run `npx -y slides-studio-mcp@beta restart` once, ask the user to reload their real editor tab, and retry `list_editors`.
+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 slides-studio-mcp@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`.
 
 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 slides-studio-mcp@beta call get_design_guidance
-npx -y slides-studio-mcp@beta call list_editors
-npx -y slides-studio-mcp@beta call list_tools --json '{"names":["add_slide","add_text"]}'
-npx -y slides-studio-mcp@beta call create_project --json '{"name":"My presentation"}'
+npx -y slides-studio-mcp@latest call get_design_guidance
+npx -y slides-studio-mcp@latest call list_editors
+npx -y slides-studio-mcp@latest call list_tools --json '{"names":["add_slide","add_text"]}'
+npx -y slides-studio-mcp@latest call create_project --json '{"name":"My presentation"}'
 ```
 
 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`.
@@ -44,6 +46,8 @@ 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.
 
+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, so do not waste calls on render-fit-render loops. 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 TikTok-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.
 
-Each assigned browser tab automatically opens the latest slide changed through its session. Other tabs synchronize project cards and project state through local browser storage. Use `show_notification` only for short, useful status messages.
+Edits follow the latest changed slide only when their project is already visible. Creating or editing another project must not take over the user's current browser view. `open_project` and `set_view` intentionally navigate, so call them only when the user asks to see that project. Other tabs synchronize project cards and project state through local browser storage. Use `show_notification` only for short, useful status messages.

package/src/agent-identity.mjs

@@ -0,0 +1,48 @@
+const KNOWN_AGENTS = [
+  { label: "Hermes", matches: ["hermes"] },
+  { label: "Claude", matches: ["claude", "anthropic"] },
+  { label: "Codex", matches: ["codex", "openai"] },
+  { label: "OpenCode", matches: ["opencode"] },
+  { label: "OpenClaw", matches: ["openclaw"] },
+];
+
+const GENERIC_CLIENT_NAMES = new Set([
+  "ai agent",
+  "agent",
+  "client",
+  "mcp",
+  "mcp agent",
+  "mcp client",
+  "slide studio cli fallback",
+]);
+
+export function canonicalAgentName(value) {
+  const name = String(value || "").trim();
+  const normalized = name.toLowerCase();
+  return KNOWN_AGENTS.find(({ matches }) => matches.some((match) => normalized.includes(match)))?.label || name || null;
+}
+
+export function isGenericAgentName(value) {
+  return GENERIC_CLIENT_NAMES.has(String(value || "").trim().toLowerCase());
+}
+
+export function detectHostAgent(explicitName = null, environment = process.env, runtime = process) {
+  const configured = canonicalAgentName(explicitName || environment.SLIDE_STUDIO_AGENT);
+  if (configured) return configured;
+  const environmentKeys = Object.keys(environment).filter((key) => environment[key]).join(" ");
+  const evidence = [
+    runtime.execPath,
+    ...(runtime.argv || []),
+    environment.PATH,
+    environment.TERM_PROGRAM,
+    environment.npm_execpath,
+    environmentKeys,
+  ].filter(Boolean).join(" ").toLowerCase();
+  return KNOWN_AGENTS.find(({ matches }) => matches.some((match) => evidence.includes(match)))?.label || "MCP agent";
+}
+
+export function preferHostAgent(reportedName, hostName) {
+  const reported = canonicalAgentName(reportedName);
+  const host = canonicalAgentName(hostName) || "MCP agent";
+  return !reported || isGenericAgentName(reported) ? host : reported;
+}

package/src/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { companionDoctor, companionRestart } from "./companion.mjs";
-import { PACKAGE_NAME, PACKAGE_VERSION, TEST_EDITOR_URL } from "./config.mjs";
+import { EDITOR_URL, PACKAGE_NAME, PACKAGE_VERSION } from "./config.mjs";
 import { runSetup } from "./setup.mjs";
 import { serveMcp } from "./stdio-server.mjs";
 
@@ -8,7 +8,8 @@ const [command = "serve", ...arguments_] = process.argv.slice(2);
 
 async function main() {
   if (command === "serve") {
-    await serveMcp();
+    const agentName = arguments_.find((value) => value.startsWith("--agent="))?.slice("--agent=".length) || null;
+    await serveMcp({ agentName });
     return;
   }
   if (command === "setup") {
@@ -22,7 +23,7 @@ async function main() {
   }
   if (command === "doctor") {
     const health = await companionDoctor();
-    process.stdout.write(`${JSON.stringify({ package: PACKAGE_NAME, packageVersion: PACKAGE_VERSION, editor: TEST_EDITOR_URL, daemon: health }, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({ package: PACKAGE_NAME, packageVersion: PACKAGE_VERSION, editor: EDITOR_URL, daemon: health }, null, 2)}\n`);
     return;
   }
   if (command === "restart") {
@@ -35,7 +36,7 @@ async function main() {
     return;
   }
   if (command === "help" || command === "--help" || command === "-h") {
-    process.stdout.write(`Slide Studio MCP ${PACKAGE_VERSION}\n\nUsage:\n  slides-studio-mcp serve\n  slides-studio-mcp setup [--client=claude,codex,hermes,opencode,openclaw] [--yes] [--dry-run]\n  slides-studio-mcp call <tool> [--json '{"key":"value"}'] [--stdin]\n  slides-studio-mcp doctor\n  slides-studio-mcp restart\n  slides-studio-mcp version\n`);
+    process.stdout.write(`Slide Studio MCP ${PACKAGE_VERSION}\n\nUsage:\n  slides-studio-mcp serve [--agent=claude|codex|hermes|opencode|openclaw]\n  slides-studio-mcp setup [--client=claude,codex,hermes,opencode,openclaw] [--yes] [--dry-run]\n  slides-studio-mcp call <tool> [--json '{"key":"value"}'] [--stdin]\n  slides-studio-mcp doctor\n  slides-studio-mcp restart\n  slides-studio-mcp version\n`);
     return;
   }
   throw new Error(`Unknown command: ${command}`);

package/src/companion.mjs

@@ -3,6 +3,7 @@ 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 { preferHostAgent } from "./agent-identity.mjs";
 
 const DAEMON_ENTRY = fileURLToPath(new URL("daemon.mjs", import.meta.url));
 
@@ -33,7 +34,7 @@ async function healthyState() {
   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 slides-studio-mcp@beta restart\`, then reload the editor.`);
+      const error = new Error(`Local companion ${result.version || "unknown"} uses protocol ${result.protocolVersion}; ${PACKAGE_VERSION} requires protocol ${PROTOCOL_VERSION}. Run \`npx -y slides-studio-mcp@latest restart\`, then reload the editor.`);
       error.code = "EPROTOCOL";
       throw error;
     }
@@ -91,7 +92,7 @@ export async function createCompanion(initialName = "MCP agent", initialVersion
     clientId,
     get daemon() { return { pid: state.pid, url: BRIDGE_URL, version: state.version, packageVersion: PACKAGE_VERSION }; },
     async identify(name, version) {
-      clientName = name || clientName;
+      clientName = preferHostAgent(name, clientName);
       clientVersion = version || clientVersion;
       await register();
     },

package/src/config.mjs

@@ -11,9 +11,9 @@ export const PROTOCOL_VERSION = 3;
 export const BRIDGE_HOST = "127.0.0.1";
 export const BRIDGE_PORT = Number(process.env.SLIDE_STUDIO_BRIDGE_PORT) || 43117;
 export const BRIDGE_URL = `http://${BRIDGE_HOST}:${BRIDGE_PORT}`;
-export const TEST_EDITOR_URL = "https://slides-mcp-poc-0821.pages.dev";
+export const EDITOR_URL = "https://slides-editor.pages.dev";
 export const ALLOWED_ORIGINS = new Set((process.env.SLIDE_STUDIO_ALLOWED_ORIGINS || [
-  TEST_EDITOR_URL,
+  EDITOR_URL,
   "http://127.0.0.1:4173",
   "http://localhost:4173",
 ].join(",")).split(",").map((value) => value.trim()).filter(Boolean));

package/src/daemon.mjs

@@ -10,14 +10,15 @@ import {
 
 const MAX_JSON_BYTES = 40 * 1024 * 1024;
 const MAX_MEDIA_BYTES = 25 * 1024 * 1024;
-const EDITOR_TTL_MS = Number(process.env.SLIDE_STUDIO_EDITOR_TTL_MS) || 15_000;
+const EDITOR_TTL_MS = Number(process.env.SLIDE_STUDIO_EDITOR_TTL_MS) || 60_000;
 const CLIENT_TTL_MS = 45_000;
 const MEDIA_TTL_MS = 5 * 60_000;
 const COMMAND_TIMEOUT_MS = 90_000;
 const EDIT_SESSION_TTL_MS = Number(process.env.SLIDE_STUDIO_EDIT_SESSION_TTL_MS) || 5 * 60_000;
 const MAX_AUDIT_EVENTS = 500;
 const MAX_AUDIT_BYTES = 2 * 1024 * 1024;
-const EVENT_POLL_TIMEOUT_MS = Number(process.env.SLIDE_STUDIO_EVENT_POLL_TIMEOUT_MS) || 5 * 60_000;
+const EVENT_POLL_TIMEOUT_MS = Number(process.env.SLIDE_STUDIO_EVENT_POLL_TIMEOUT_MS) || 500;
+const MAX_EVENT_POLL_TIMEOUT_MS = 5_000;
 const daemonSecret = randomBytes(32).toString("base64url");
 const editors = new Map();
 const clients = new Map();
@@ -34,11 +35,17 @@ function log(message) {
   process.stderr.write(`[slide-studio-daemon] ${message}\n`);
 }
 
+function editorHasInflightCommand(editorId) {
+  for (const pending of inflight.values()) if (pending.editorId === editorId) return true;
+  return false;
+}
+
 function activeEditors() {
   const cutoff = Date.now() - EDITOR_TTL_MS;
   return [...editors.values()].filter((editor) => (
     editor.lastSeen >= cutoff
     || Boolean(editor.poll && !editor.poll.destroyed && !editor.poll.writableEnded)
+    || editorHasInflightCommand(editor.id)
   ));
 }
 
@@ -525,6 +532,12 @@ const server = createServer(async (request, response) => {
       focusedEditorId = editor.id;
       return sendJson(response, 200, { ok: true, editorId: editor.id }, cors);
     }
+    if (url.pathname === "/heartbeat" && request.method === "POST") {
+      const body = await readJson(request);
+      const editor = requireEditor(request, response, body.editorId, cors);
+      if (!editor) return;
+      return sendJson(response, 200, { ok: true, editorId: editor.id }, cors);
+    }
     if (url.pathname === "/disconnect" && request.method === "POST") {
       const body = await readJson(request);
       const editor = requireEditor(request, response, body.editorId, cors);
@@ -535,6 +548,10 @@ const server = createServer(async (request, response) => {
     if (url.pathname === "/events" && request.method === "GET") {
       const editor = requireEditor(request, response, url.searchParams.get("editorId"), cors);
       if (!editor) return;
+      const requestedWait = Number(url.searchParams.get("wait"));
+      const waitMs = url.searchParams.has("wait") && Number.isFinite(requestedWait)
+        ? Math.min(MAX_EVENT_POLL_TIMEOUT_MS, Math.max(0, requestedWait))
+        : EVENT_POLL_TIMEOUT_MS;
       editor.cors = cors;
       if (editor.poll) endEditorPoll(editor);
       editor.poll = response;
@@ -546,10 +563,12 @@ const server = createServer(async (request, response) => {
         editor.lastSeen = Date.now();
       });
       deliverNext(editor);
-      if (editor.poll) editor.pollTimer = setTimeout(() => {
+      if (editor.poll && waitMs === 0) {
+        endEditorPoll(editor);
+      } else if (editor.poll) editor.pollTimer = setTimeout(() => {
         if (editor.poll !== response) return;
         endEditorPoll(editor);
-      }, EVENT_POLL_TIMEOUT_MS);
+      }, waitMs);
       editor.pollTimer?.unref();
       return;
     }
@@ -650,7 +669,11 @@ setInterval(() => {
     clientsChanged = true;
   }
   for (const [id, editor] of editors) {
-    if (editor.lastSeen >= now - EDITOR_TTL_MS || (editor.poll && !editor.poll.destroyed && !editor.poll.writableEnded)) continue;
+    if (
+      editor.lastSeen >= now - EDITOR_TTL_MS
+      || (editor.poll && !editor.poll.destroyed && !editor.poll.writableEnded)
+      || editorHasInflightCommand(id)
+    ) continue;
     disconnectEditor(id, "Browser editor connection expired.");
   }
   if (clientsChanged) broadcastAgents();

package/src/mcp-server.mjs

@@ -2,7 +2,7 @@ import { mkdir, readFile, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { McpServer } from "@modelcontextprotocol/server";
 import * as z from "zod/v4";
-import { GUIDANCE_PATH, PACKAGE_NAME, PACKAGE_VERSION, TEST_EDITOR_URL } from "./config.mjs";
+import { EDITOR_URL, GUIDANCE_PATH, PACKAGE_NAME, PACKAGE_VERSION } from "./config.mjs";
 
 const id = z.string().min(1).max(160);
 const optionalId = id.optional();
@@ -15,6 +15,7 @@ const targetProject = { editSessionId, projectId: optionalId, expectedRevision }
 const targetSlide = { editSessionId, projectId: optionalId, slideId: optionalId, expectedRevision };
 const textFields = {
   text: z.string().max(4000).optional(), x: unit.optional(), y: unit.optional(), width: positiveUnit.optional(), height: positiveUnit.optional(),
+  role: z.enum(["title", "subtitle", "body", "caption"]).optional().describe("Semantic size role. Recommended ranges: title 92-124, subtitle 68-84, body 54-68, caption 44-52."),
   size: z.number().min(20).max(180).optional(), style: z.enum(["plain", "outline", "boxed"]).optional(),
   outlineWidth: z.number().min(0).max(40).optional(), color: color.optional(), background: z.enum(["white", "black"]).optional(),
   backgroundShape: z.enum(["lines", "full"]).optional(), align: z.enum(["left", "center", "right"]).optional(),
@@ -34,7 +35,7 @@ function textResult(value, summary = value) {
 }
 
 function compactMutation(value) {
-  const keys = ["id", "editSessionId", "editorId", "projectId", "slideId", "revision", "leaseExpiresAt", "purpose", "released", "opened", "createdSlideId", "createdTextId", "createdImageId", "createdLayers", "assetId", "deletedAssetId", "deletedProjectId", "deletedSlideId", "deletedLayerIds", "updatedTextIds", "updatedImageIds", "applied", "path", "bytes"];
+  const keys = ["id", "editSessionId", "editorId", "projectId", "slideId", "revision", "leaseExpiresAt", "purpose", "released", "opened", "createdSlideId", "createdTextId", "fittedTextBox", "createdImageId", "createdLayers", "assetId", "deletedAssetId", "deletedProjectId", "deletedSlideId", "deletedLayerIds", "updatedTextIds", "fittedTextBoxes", "updatedImageIds", "applied", "path", "bytes"];
   return Object.fromEntries(keys.flatMap((key) => value?.[key] == null ? [] : [[key, value[key]]]));
 }
 
@@ -55,7 +56,7 @@ function operationLabel(toolName) {
     create_project: "Creating a project…", update_project: "Updating the project…", delete_project: "Deleting a project…",
     open_project: "Opening a project…", add_slide: "Adding a slide…", update_slide: "Updating a slide…",
     duplicate_slide: "Duplicating a slide…", reorder_slides: "Reordering slides…", delete_slide: "Deleting a slide…",
-    add_text: "Adding text…", update_text: "Updating text…", import_asset: "Importing a local image…",
+    add_text: "Adding text…", update_text: "Updating text…", fit_text_boxes: "Fitting text boxes…", import_asset: "Importing a local image…",
     update_asset: "Updating an image asset…", delete_asset: "Deleting an image asset…", add_image: "Placing an image…",
     update_image: "Updating an image…", delete_layers: "Deleting layers…", duplicate_layers: "Duplicating layers…",
     reorder_layers: "Reordering layers…", undo: "Undoing the last edit…", redo: "Redoing the last edit…",
@@ -85,7 +86,7 @@ async function prepareOperation(companion, toolName, args) {
   const type = ({
     create_project: "project.create", open_project: "project.open", update_project: "project.update", delete_project: "project.delete",
     add_slide: "slide.add", update_slide: "slide.update", duplicate_slide: "slide.duplicate", reorder_slides: "slide.reorder", delete_slide: "slide.delete",
-    add_text: "text.add", update_text: "text.update", import_asset: "asset.import", update_asset: "asset.update", delete_asset: "asset.delete",
+    add_text: "text.add", update_text: "text.update", fit_text_boxes: "text.fit", import_asset: "asset.import", update_asset: "asset.update", delete_asset: "asset.delete",
     add_image: "image.add", update_image: "image.update", delete_layers: "layer.delete", duplicate_layers: "layer.duplicate", reorder_layers: "layer.reorder",
     undo: "history.undo", redo: "history.redo", set_view: "view.update", render_slide: "slide.render", inspect_editor: "editor.inspect",
   })[toolName];
@@ -98,7 +99,7 @@ export async function createSlideStudioMcpServer(companion) {
   let guidanceRead = false;
   let identifiedAs = null;
   const server = new McpServer({ name: PACKAGE_NAME, version: PACKAGE_VERSION }, {
-    instructions: `First call list_editors and use the registered local browser tab. Never open or connect Slide Studio through a sandboxed agent browser. If no editor is listed, ask the user to open ${TEST_EDITOR_URL} in their normal browser and click Connect AI. Before edits call get_design_guidance, then begin_edit_session; pass editSessionId to every edit and end it in cleanup. Parallel editing workers require distinct editor sessions. Use render_slide to inspect actual pixels.`,
+    instructions: `First call list_editors and use the registered local browser tab. Never open or connect Slide Studio through a sandboxed agent browser. If no editor is listed, retry briefly because browser reconnection is automatic, then ask the user to open ${EDITOR_URL} in their normal browser and click Connect AI. Never restart a healthy companion for a transient editor disconnect; restart only for an explicit protocol mismatch or failed daemon health check. Before edits call get_design_guidance, then begin_edit_session; pass editSessionId to every edit and end it in cleanup. Parallel editing workers require distinct editor sessions. Use render_slide to inspect actual pixels.`,
     capabilities: { tools: {}, resources: {} },
   });
 
@@ -148,19 +149,20 @@ export async function createSlideStudioMcpServer(companion) {
   register("inspect_editor", "Inspect projects, slides, assets, and every text/image layer without returning image bytes.", z.object({ ...targetSlide, includeAllProjects: z.boolean().default(true) }).strict(), (args) => browserOperation(companion, "inspect_editor", args), { readOnlyHint: true });
   register("show_notification", "Show a short visual notification in a connected editor for status or marketing demos.", z.object({ editSessionId, message: z.string().min(1).max(240), tone: z.enum(["agent", "success", "info", "error"]).default("agent") }).strict(), ({ editSessionId, ...args }) => companion.call("notify", { ...args, editSessionId }), { destructiveHint: false, idempotentHint: false });
 
-  register("create_project", "Create an empty project. If the dashboard is visible, its card appears live; adding the first slide opens the editor.", z.object({ editSessionId, name: z.string().min(1).max(160) }).strict(), (args) => browserOperation(companion, "create_project", args), { destructiveHint: false });
-  register("open_project", "Open a project and optionally a specific slide without changing content.", z.object({ editSessionId, projectId: id, slideId: optionalId }).strict(), (args) => browserOperation(companion, "open_project", args), { destructiveHint: false, idempotentHint: true });
+  register("create_project", "Create an empty project without changing the user's current browser view. Its dashboard card appears live when the dashboard is open.", z.object({ editSessionId, name: z.string().min(1).max(160) }).strict(), (args) => browserOperation(companion, "create_project", args), { destructiveHint: false });
+  register("open_project", "Explicitly navigate the browser to a project and optionally a specific slide without changing content. Use only when the user asks to show it.", z.object({ editSessionId, projectId: id, slideId: optionalId }).strict(), (args) => browserOperation(companion, "open_project", args), { destructiveHint: false, idempotentHint: true });
   register("update_project", "Rename a project.", z.object({ ...targetProject, name: z.string().min(1).max(160) }).strict(), (args) => browserOperation(companion, "update_project", args), { destructiveHint: true });
   register("delete_project", "Delete a project from browser storage.", z.object({ ...targetProject, projectId: id }).strict(), (args) => browserOperation(companion, "delete_project", args), { destructiveHint: true });
 
-  register("add_slide", "Add and open a slide using a solid color or local background image path.", z.object({ ...targetProject, name: z.string().max(160).optional(), index: z.number().int().min(0).optional(), backgroundColor: color.optional(), backgroundPath: z.string().min(1).optional() }).strict(), (args) => browserOperation(companion, "add_slide", args), { destructiveHint: false });
-  register("update_slide", "Rename a slide, replace its background, or change background pan/zoom. The browser opens this slide.", z.object({ ...targetSlide, name: z.string().max(160).optional(), backgroundColor: color.optional(), backgroundPath: z.string().min(1).optional(), imageScale: z.number().min(1).max(3).optional(), imageX: unit.optional(), imageY: unit.optional() }).strict(), (args) => browserOperation(companion, "update_slide", args), { destructiveHint: true });
-  register("duplicate_slide", "Duplicate a slide with all layers and open the copy.", z.object({ ...targetSlide, name: z.string().max(160).optional() }).strict(), (args) => browserOperation(companion, "duplicate_slide", args), { destructiveHint: false });
+  register("add_slide", "Add a slide using a solid color or local background image path. The browser follows it only when that project is already visible.", z.object({ ...targetProject, name: z.string().max(160).optional(), index: z.number().int().min(0).optional(), backgroundColor: color.optional(), backgroundPath: z.string().min(1).optional() }).strict(), (args) => browserOperation(companion, "add_slide", args), { destructiveHint: false });
+  register("update_slide", "Rename a slide, replace its background, or change background pan/zoom. The browser follows it only when that project is already visible.", z.object({ ...targetSlide, name: z.string().max(160).optional(), backgroundColor: color.optional(), backgroundPath: z.string().min(1).optional(), imageScale: z.number().min(1).max(3).optional(), imageX: unit.optional(), imageY: unit.optional() }).strict(), (args) => browserOperation(companion, "update_slide", args), { destructiveHint: true });
+  register("duplicate_slide", "Duplicate a slide with all layers. The browser follows the copy only when that project is already visible.", z.object({ ...targetSlide, name: z.string().max(160).optional() }).strict(), (args) => browserOperation(companion, "duplicate_slide", args), { destructiveHint: false });
   register("reorder_slides", "Set the complete slide order using every slide ID exactly once.", z.object({ ...targetProject, slideIds: z.array(id).min(1) }).strict(), (args) => browserOperation(companion, "reorder_slides", args), { destructiveHint: true });
   register("delete_slide", "Delete one slide.", z.object({ ...targetSlide, slideId: id }).strict(), (args) => browserOperation(companion, "delete_slide", args), { destructiveHint: true });
 
-  register("add_text", "Add a text layer. Coordinates and dimensions are normalized to the 9:16 canvas; attractive defaults use generous bounds and per-line boxes.", z.object({ ...targetSlide, ...textFields, text: z.string().min(1).max(4000) }).strict(), (args) => browserOperation(companion, "add_text", args), { destructiveHint: false });
-  register("update_text", "Update one or more text layers, including content, geometry, color, style, alignment, rotation, and stacking.", z.object({ ...targetSlide, updates: z.array(z.object({ id, ...textFields }).strict()).min(1).max(100) }).strict(), (args) => browserOperation(companion, "update_text", args), { destructiveHint: true });
+  register("add_text", "Add a text layer. Choose a semantic role and a size within its readable range. Width is preserved while height is fitted automatically with safe padding; boxed text defaults to the preferred per-line background.", z.object({ ...targetSlide, ...textFields, text: z.string().min(1).max(4000) }).strict(), (args) => browserOperation(companion, "add_text", args), { destructiveHint: false });
+  register("update_text", "Update one or more text layers. Every updated layer automatically keeps its width and refits its height with safe padding, so a render-fit-render loop is unnecessary.", z.object({ ...targetSlide, updates: z.array(z.object({ id, ...textFields }).strict()).min(1).max(100) }).strict(), (args) => browserOperation(companion, "update_text", args), { destructiveHint: true });
+  register("fit_text_boxes", "Explicitly resize text boxes to their rendered content. add_text and update_text already fit height automatically; use mode=both only when you also want to shrink width.", z.object({ ...targetSlide, textIds: z.array(id).min(1).max(100), mode: z.enum(["height", "both"]).default("both") }).strict(), (args) => browserOperation(companion, "fit_text_boxes", args), { destructiveHint: true });
 
   register("import_asset", "Import a local image file into the active project's reusable asset library. Image bytes stay local.", z.object({ ...targetSlide, path: z.string().min(1), name: z.string().max(160).optional() }).strict(), (args) => browserOperation(companion, "import_asset", args), { destructiveHint: false });
   register("update_asset", "Rename a reusable image asset.", z.object({ ...targetProject, assetId: id, name: z.string().min(1).max(160) }).strict(), (args) => browserOperation(companion, "update_asset", args), { destructiveHint: true });

package/src/setup.mjs

@@ -3,7 +3,7 @@ import { cp, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { PACKAGE_NAME, PACKAGE_ROOT, PACKAGE_VERSION, TEST_EDITOR_URL } from "./config.mjs";
+import { EDITOR_URL, PACKAGE_NAME, PACKAGE_ROOT, PACKAGE_VERSION } from "./config.mjs";
 
 const supported = ["claude", "codex", "hermes", "opencode", "openclaw"];
 
@@ -17,10 +17,10 @@ function commandVersion(command) {
 }
 
 function shellCommand(client, specifier) {
-  if (client === "claude") return ["claude", "mcp", "add", "--scope", "user", "--transport", "stdio", "slide-studio", "--", "npx", "-y", specifier, "serve"];
-  if (client === "codex") return ["codex", "mcp", "add", "slide-studio", "--", "npx", "-y", specifier, "serve"];
-  if (client === "hermes") return ["hermes", "mcp", "add", "slide-studio", "--command", "npx", "--args", "-y", specifier, "serve"];
-  if (client === "openclaw") return ["openclaw", "mcp", "add", "slide-studio", "--command", "npx", "--arg", "-y", "--arg", specifier, "--arg", "serve"];
+  if (client === "claude") return ["claude", "mcp", "add", "--scope", "user", "--transport", "stdio", "slide-studio", "--", "npx", "-y", specifier, "serve", "--agent=claude"];
+  if (client === "codex") return ["codex", "mcp", "add", "slide-studio", "--", "npx", "-y", specifier, "serve", "--agent=codex"];
+  if (client === "hermes") return ["hermes", "mcp", "add", "slide-studio", "--command", "npx", "--args", "-y", specifier, "serve", "--agent=hermes"];
+  if (client === "openclaw") return ["openclaw", "mcp", "add", "slide-studio", "--command", "npx", "--arg", "-y", "--arg", specifier, "--arg", "serve", "--arg", "--agent=openclaw"];
   return null;
 }
 
@@ -35,7 +35,7 @@ function quote(value) {
 }
 
 function openCodeSnippet(specifier, version = commandVersion("opencode")) {
-  const server = { type: "local", command: ["npx", "-y", specifier, "serve"] };
+  const server = { type: "local", command: ["npx", "-y", specifier, "serve", "--agent=opencode"] };
   return JSON.stringify(Number(version?.split(".")[0]) >= 2
     ? { mcp: { servers: { "slide-studio": server } } }
     : { mcp: { "slide-studio": { ...server, enabled: true } } }, null, 2);
@@ -60,12 +60,13 @@ export async function runSetup(arguments_) {
   const clientArgument = arguments_.find((value) => value.startsWith("--client="))?.slice("--client=".length);
   const requested = clientArgument ? clientArgument.split(",").map((value) => value.trim().toLowerCase()) : supported.filter(commandExists);
   const clients = [...new Set(requested)].filter((client) => supported.includes(client));
-  const specifier = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
+  const releaseTag = PACKAGE_VERSION.includes("-beta.") ? "beta" : "latest";
+  const specifier = `${PACKAGE_NAME}@${releaseTag}`;
   const dryRun = flags.has("--dry-run");
   const assumeYes = flags.has("--yes") || flags.has("-y");
   if (!clients.length) throw new Error("No supported agent CLI was detected. Use --client=claude,codex,hermes,opencode,openclaw or copy the generic stdio config below.");
 
-  process.stdout.write(`Slide Studio MCP ${PACKAGE_VERSION}\nDetected: ${clients.join(", ")}\nEditor: ${TEST_EDITOR_URL}\n\n`);
+  process.stdout.write(`Slide Studio MCP ${PACKAGE_VERSION}\nDetected: ${clients.join(", ")}\nEditor: ${EDITOR_URL}\n\n`);
   for (const client of clients) {
     const command = shellCommand(client, specifier);
     if (command) process.stdout.write(`${client}: ${command.map(quote).join(" ")}\n`);
@@ -97,7 +98,7 @@ export async function runSetup(arguments_) {
     else process.stderr.write(`Could not configure ${client}; its command is printed above for manual setup.\n`);
   }
   const skillTargets = await installSkill();
-  process.stdout.write(`\nConfigured: ${configured.join(", ") || "none automatically"}\nSkill installed in:\n${skillTargets.map((value) => `  ${value}`).join("\n")}\n\nOpen ${TEST_EDITOR_URL} in your normal local browser and click Connect AI. Do not use a sandboxed agent browser.\n`);
+  process.stdout.write(`\nConfigured: ${configured.join(", ") || "none automatically"}\nSkill installed in:\n${skillTargets.map((value) => `  ${value}`).join("\n")}\n\nOpen ${EDITOR_URL} in your normal local browser and click Connect AI. Do not use a sandboxed agent browser.\n`);
   process.stdout.write(`First connection check (no browser automation): npx -y ${specifier} call list_editors\n`);
   if (clients.includes("hermes")) process.stdout.write("Hermes can also refresh native tools in place with /reload-mcp and /reload-skills.\n");
   if (clients.includes("claude")) process.stdout.write("Claude may require a new session for native MCP registration; use the CLI fallback immediately instead of stopping.\n");

package/src/stdio-server.mjs

@@ -1,9 +1,10 @@
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { detectHostAgent } from "./agent-identity.mjs";
 import { createCompanion } from "./companion.mjs";
 import { createSlideStudioMcpServer } from "./mcp-server.mjs";
 
-export async function serveMcp() {
-  const companion = await createCompanion();
+export async function serveMcp({ agentName = null } = {}) {
+  const companion = await createCompanion(detectHostAgent(agentName));
   const handle = serveStdio(() => createSlideStudioMcpServer(companion), {
     legacy: "serve",
     onerror: (error) => process.stderr.write(`[slides-studio-mcp] ${error.message}\n`),