html2pptx-local-mcp 1.1.20 → 1.1.22

package/app/docs/content.js

@@ -179,14 +179,19 @@ npx skills add https://html2pptx.app -a cursor
 # Windsurf
 npx skills add https://html2pptx.app -a windsurf
 
+# Grok Build
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-skills grok
+
 # Preview published skills without installing
 npx skills add https://html2pptx.app --list
 
 # More agents / multiple targets: use the interactive selector
 npx skills add https://html2pptx.app
 
-# Claude Code users: run this one line
-npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude`;
+# Claude Code / Codex / Grok Build users: run the matching one line for MCP.
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp codex
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp grok`;
 
 const SKILL_INSTALL_COMMAND_JA = `# 使うエージェントのコマンドを選択
 # Claude Code
@@ -201,14 +206,19 @@ npx skills add https://html2pptx.app -a cursor
 # Windsurf
 npx skills add https://html2pptx.app -a windsurf
 
+# Grok Build
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-skills grok
+
 # インストールせずに公開Skillを確認
 npx skills add https://html2pptx.app --list
 
 # その他のエージェント / 複数指定は対話形式で選択
 npx skills add https://html2pptx.app
 
-# Claude Codeユーザーはこの1行でOK
-npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude`;
+# Claude Code / Codex / Grok Build ユーザーは MCP 用の該当行を実行。
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp codex
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp grok`;
 
 const SKILL_INVOCATION_EXAMPLE = `# 例: Claude Code でスライド作成 → PPTX出力
 
@@ -243,8 +253,12 @@ const SKILL_AVAILABLE_LIST = [
   },
 ];
 
-const MCP_INSTALL_EXAMPLE = `# Claude Codeユーザーはこの1行でOK
-npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude`;
+const MCP_INSTALL_EXAMPLE = `# Claude Code / Codex / Grok Build ユーザーは該当する1行でOK
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp codex
+
+# Grok Build
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp grok`;
 
 const MCP_CONFIG_EXAMPLE = `// 方法2: 設定ファイルに手動追加
 
@@ -749,7 +763,7 @@ export const DOCS_COPY = {
     skillsDescription:
       'Skills are packaged capabilities that extend AI coding agents with domain-specific knowledge and workflows. The html2pptx.app skill teaches your agent how to author slide-safe HTML, validate it against the PPTX conversion contract, optionally open the local visual editor, export through remote or local MCP workflows, and publish HTML template drafts through its built-in remote MCP publishing workflow. Install once, and your agent can convert natural language instructions into production-ready PowerPoint files or creator-owned HTML drafts.',
     skillsHowItWorks: 'The skill bundles four core capabilities: (1) HTML authoring knowledge -- the rules for writing HTML/CSS that converts cleanly to editable PowerPoint, (2) MCP-based export automation -- connecting to the remote html2pptx.app MCP server or a local stdio MCP server to create jobs, poll status, and retrieve results, (3) local visual editing -- opening edit-slide through a localhost bridge when the user wants to inspect or tweak the HTML before export, and (4) template publishing -- requiring HTML drafts to go through the remote MCP validate/publish loop. The agent should ask before adding a local MCP server because that changes the user’s MCP configuration.',
-    skillsCompatibility: 'Works with 18+ AI agents including Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, Codex, and more. Use the skills CLI command for the specific agent you use, or the interactive selector for other supported agents.',
+    skillsCompatibility: 'Works with 18+ AI agents including Claude Code, Grok Build, Cursor, GitHub Copilot, Windsurf, Cline, Codex, and more. Use the skills CLI command for Claude Code, Codex, Cursor, and Windsurf. For Grok Build, use the Grok-specific skills installer shown below.',
     skillsWorkflowTitle: 'Workflow',
 	    skillsWorkflow: [
 	      'Agent receives a user request (e.g., "Create a deck from these meeting notes")',
@@ -813,7 +827,7 @@ html2pptx edit ./html2pptx/slides.html --no-open`,
         step: '1',
         title: 'Install MCP + Skill',
         icons: ['claude-code', 'codex', 'cursor', 'windsurf'],
-        body: 'Choose the command for the agent you actually use: Claude Code, Codex, Cursor, or Windsurf. For other supported agents or multiple targets, use the interactive selector. Avoid --yes unless you intentionally want to install into every detected agent directory.',
+        body: 'Choose the command for the agent you actually use: Claude Code, Codex, Cursor, or Windsurf. For Grok Build, use the Grok-specific installer. For other supported agents or multiple targets, use the interactive selector. Avoid --yes unless you intentionally want to install into every detected agent directory.',
         code: SKILL_INSTALL_COMMAND_EN,
       },
       {
@@ -850,7 +864,7 @@ echo 'HTML2PPTX_API_KEY=sk_live_xxxx' >> .env`,
     mcpDescription:
       'MCP (Model Context Protocol) is an open protocol that exposes backend capabilities to AI agents through a standardized tool interface. html2pptx.app supports two MCP surfaces: the remote HTTP MCP endpoint at /mcp for export, usage, docs, templates, catalog, and HTML template publishing workflows, and the local stdio MCP server for export tools plus local edit-slide sessions through a localhost bridge. Use remote MCP when the agent needs to convert HTML to PPTX or create an HTML template draft. Use local stdio MCP only when the agent must open, preview, or edit a local HTML file on the user machine; local MCP does not publish templates.',
     mcpSetupTitle: 'Installation & Setup',
-    mcpSetupLead: 'For Claude Code, users can run one command to register both remote export tools and local edit-slide. Remote MCP follows the hosted service; local MCP uses html2pptx-local-mcp@latest so future starts pick up the newest published package.',
+    mcpSetupLead: 'Claude Code, Codex, and Grok Build users can run one command to register both remote export tools and local edit-slide. Remote MCP follows the hosted service; local MCP uses html2pptx-local-mcp@latest so future starts pick up the newest published package.',
     mcpEditorTabs: [
       {
         id: 'claude-code',
@@ -864,16 +878,27 @@ echo 'HTML2PPTX_API_KEY=sk_live_xxxx' >> .env`,
         ],
         tip: 'The installer registers the remote MCP with user scope and writes the local stdio MCP directly to Claude Code user config for better compatibility.',
       },
+      {
+        id: 'grok-build',
+        label: 'Grok Build',
+        icon: 'https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/grok/light.svg',
+        steps: [
+          { title: 'Install MCP for Grok Build', body: 'Run the Grok installer. It registers remote export as `html2pptx` and local edit-slide as `html2pptx-local` through `grok mcp add`.', code: `npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp grok` },
+          { title: 'Install Skills for Grok Build', body: 'Install the published html2pptx skills into Grok Build’s native skills directory. This does not change MCP configuration.', code: `npx --yes --package html2pptx-local-mcp@latest html2pptx-install-skills grok` },
+        ],
+        tip: 'Use `grok inspect` if you want to confirm which project skills and MCP servers Grok discovered.',
+      },
       {
         id: 'codex',
         label: 'Codex',
         icon: 'https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/openai/light.svg',
         steps: [
-          { title: 'Run the CLI command (recommended)', body: 'Add the hosted remote MCP server. OAuth authentication will start automatically.', code: `codex mcp add html2pptx --url https://html2pptx.app/mcp` },
+          { title: 'Run one command (recommended)', body: 'This registers remote export as `html2pptx`, then adds local edit-slide as `html2pptx-local` using the published package.', code: `npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp codex` },
           { title: 'Manual remote setup', body: 'If you only need hosted export tools, add the remote MCP server directly.', code: `codex mcp add html2pptx --url https://html2pptx.app/mcp` },
           { title: 'Optional local stdio MCP for edit-slide', body: 'Use this only when Codex needs to launch local edit-slide for a `.html` file. It runs from the published package, so no repository checkout is required.', code: `codex mcp add html2pptx-local -- npx --yes --package html2pptx-local-mcp@latest html2pptx-mcp` },
-          { title: 'Manual setup via codex.json', body: 'Alternatively, create or edit codex.json in your project root.', code: `{\n  "mcpServers": {\n    "html2pptx": {\n      "type": "url",\n      "url": "https://html2pptx.app/mcp"\n    }\n  }\n}` },
+          { title: 'Manual remote setup via codex.json', body: 'Alternatively, create or edit codex.json in your project root for the hosted remote server.', code: `{\n  "mcpServers": {\n    "html2pptx": {\n      "type": "url",\n      "url": "https://html2pptx.app/mcp"\n    }\n  }\n}` },
         ],
+        tip: 'The installer runs the two Codex MCP add commands in order and continues if either server is already registered.',
       },
       {
         id: 'cursor',
@@ -1593,7 +1618,7 @@ echo 'HTML2PPTX_API_KEY=sk_live_xxxx' >> .env`,
     skillsDescription:
       'Skillsは、AIコーディングエージェントにドメイン固有の知識とワークフローを追加するパッケージ機能です。html2pptx.app のスキルをインストールすると、エージェントがスライド用HTMLの作成方法を理解し、PPTX変換契約に対する検証を行い、必要に応じてローカル Visual Editor を開き、remote MCP または local MCP のワークフローでエクスポートし、内蔵のremote MCP公開ワークフローでHTMLテンプレートdraftを作成できます。自然言語の指示だけで、本番品質のPowerPointファイルや作成者所有のHTML draftを生成できます。',
     skillsHowItWorks: 'スキルには4つのコア機能がバンドルされています: (1) HTMLオーサリング知識 -- 高品質なPowerPointに変換されるHTML/CSSの書き方ルール、(2) MCPベースのエクスポート自動化 -- remote MCP または local stdio MCP に接続してジョブ作成・ステータスポーリング・結果取得を行う仕組み、(3) ローカル Visual Editor -- ユーザーがPPTX出力前にHTMLを目視確認・微調整したい場合に edit-slide を localhost bridge 経由で開く仕組み、(4) テンプレート公開 -- HTML draft を remote MCP の validate/publish ループに限定する仕組みです。local MCP の追加はユーザーのMCP設定を変更するため、エージェントは必ず事前に確認します。',
-    skillsCompatibility: 'Claude Code、Cursor、GitHub Copilot、Windsurf、Cline、Codex 等 18以上のAIエージェントに対応。使うエージェントに対応する skills CLI コマンドを選ぶか、その他の対応エージェントは対話形式で選択します。',
+    skillsCompatibility: 'Claude Code、Grok Build、Cursor、GitHub Copilot、Windsurf、Cline、Codex 等 18以上のAIエージェントに対応。Claude Code、Codex、Cursor、Windsurf は skills CLI コマンドを使います。Grok Build は下に表示している Grok 専用の skills installer を使います。',
     skillsWorkflowTitle: 'ワークフロー',
 	    skillsWorkflow: [
 	      'エージェントがユーザーリクエストを受信（例: 「この会議メモからデッキを作成して」）',
@@ -1657,7 +1682,7 @@ html2pptx edit ./html2pptx/slides.html --no-open`,
         step: '1',
         title: 'MCP + スキルをインストール',
         icons: ['claude-code', 'codex', 'cursor', 'windsurf'],
-        body: 'Claude Code、Codex、Cursor、Windsurf のうち、実際に使うエージェントのコマンドを選んで実行してください。その他の対応エージェントや複数指定の場合は対話形式で選択します。--yes は検出された全エージェントのディレクトリへ入るため、全対応が必要な場合以外は使わないでください。',
+        body: 'Claude Code、Codex、Cursor、Windsurf のうち、実際に使うエージェントのコマンドを選んで実行してください。Grok Build は Grok 専用 installer を使います。その他の対応エージェントや複数指定の場合は対話形式で選択します。--yes は検出された全エージェントのディレクトリへ入るため、全対応が必要な場合以外は使わないでください。',
         code: SKILL_INSTALL_COMMAND_JA,
       },
       {
@@ -1694,7 +1719,7 @@ echo 'HTML2PPTX_API_KEY=sk_live_xxxx' >> .env`,
     mcpDescription:
       'MCP (Model Context Protocol) は、標準化されたツールインターフェースを通じてAIエージェントにバックエンド機能を公開するオープンプロトコルです。html2pptx.app は2種類のMCPサーフェスを提供します。remote HTTP MCP (`/mcp`) はエクスポート、usage、docs、templates、catalog、HTMLテンプレート公開に使います。local stdio MCP は同じエクスポート系ツールに加えて、localhost bridge 経由でローカルHTMLを edit-slide で開くために使います。HTMLをPPTXに変換する、またはHTMLテンプレートdraftを作るなら remote MCP、ユーザーPC上の `.html` を開いてプレビュー・編集するなら local MCP を選びます。local MCP はテンプレート公開には使いません。',
     mcpSetupTitle: 'インストール & セットアップ',
-    mcpSetupLead: 'Claude Codeユーザーは1コマンドで remote export と local edit-slide の両方を登録できます。remote MCP は hosted service 側の更新が反映され、local MCP は html2pptx-local-mcp@latest 経由で起動するため、次回起動時に新しい公開パッケージへ追従できます。',
+    mcpSetupLead: 'Claude Code、Codex、Grok Build は1コマンドで remote export と local edit-slide の両方を登録できます。remote MCP は hosted service 側の更新が反映され、local MCP は html2pptx-local-mcp@latest 経由で起動するため、次回起動時に新しい公開パッケージへ追従できます。',
     mcpEditorTabs: [
       {
         id: 'claude-code',
@@ -1708,16 +1733,27 @@ echo 'HTML2PPTX_API_KEY=sk_live_xxxx' >> .env`,
         ],
         tip: 'このインストーラーは remote MCP を user scope で登録し、互換性のため local stdio MCP は Claude Code の user config に直接書き込みます。',
       },
+      {
+        id: 'grok-build',
+        label: 'Grok Build',
+        icon: 'https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/grok/light.svg',
+        steps: [
+          { title: 'Grok Build 向けに MCP を追加', body: 'Grok installer を実行します。remote export は `html2pptx`、local edit-slide は `html2pptx-local` として `grok mcp add` で登録されます。', code: `npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp grok` },
+          { title: 'Grok Build 向けに Skills を追加', body: '公開済みの html2pptx skills を Grok Build の native skills ディレクトリへ入れます。MCP設定は変更しません。', code: `npx --yes --package html2pptx-local-mcp@latest html2pptx-install-skills grok` },
+        ],
+        tip: 'Grok が検出した project skills と MCP server を確認したい場合は `grok inspect` を使ってください。',
+      },
       {
         id: 'codex',
         label: 'Codex',
         icon: 'https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/openai/light.svg',
         steps: [
-          { title: 'CLIコマンドで追加（推奨）', body: 'hosted remote MCP server を追加します。OAuth認証が自動的に開始されます。', code: `codex mcp add html2pptx --url https://html2pptx.app/mcp` },
+          { title: '1コマンドで追加（推奨）', body: '`html2pptx` として remote export を登録し、`html2pptx-local` として local edit-slide を公開パッケージ経由で追加します。', code: `npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp codex` },
           { title: 'remote だけ手動セットアップ', body: 'PPTX出力などのホスト側ツールだけ必要な場合はこちらを使います。', code: `codex mcp add html2pptx --url https://html2pptx.app/mcp` },
           { title: 'edit-slide 用 local stdio MCP（任意）', body: 'Codex がローカル `.html` を edit-slide で開く必要がある場合だけ追加します。公開パッケージから起動するため、リポジトリの checkout は不要です。', code: `codex mcp add html2pptx-local -- npx --yes --package html2pptx-local-mcp@latest html2pptx-mcp` },
-          { title: 'codex.json で手動セットアップ', body: 'コマンドが使えない場合は、プロジェクトルートの codex.json に以下を追加してください。', code: `{\n  "mcpServers": {\n    "html2pptx": {\n      "type": "url",\n      "url": "https://html2pptx.app/mcp"\n    }\n  }\n}` },
+          { title: 'codex.json で remote を手動セットアップ', body: 'コマンドが使えない場合は、hosted remote server 用にプロジェクトルートの codex.json に以下を追加してください。', code: `{\n  "mcpServers": {\n    "html2pptx": {\n      "type": "url",\n      "url": "https://html2pptx.app/mcp"\n    }\n  }\n}` },
         ],
+        tip: 'インストーラーは Codex の2つの MCP add コマンドを順に実行し、すでに登録済みの場合は継続します。',
       },
       {
         id: 'cursor',

package/lib/local-editor-server.js

@@ -0,0 +1,316 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import net from 'node:net';
+import { access } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  readEditorServerState,
+  writeEditorServerState,
+} from './local-editor-state.js';
+
+const AUTO_PORT = 0;
+const DEFAULT_READY_TIMEOUT_MS = 30000;
+
+export function createLocalEditorServerManager(options = {}) {
+  const sessions = new Map();
+  const launchTimeoutMs = Number.isFinite(options.launchTimeoutMs)
+    ? Math.max(1000, Math.floor(options.launchTimeoutMs))
+    : DEFAULT_READY_TIMEOUT_MS;
+
+  async function ensure(root = process.cwd(), input = {}) {
+    const projectRoot = resolve(root);
+    const requestedPort = normalizePort(input.editorPort ?? process.env.HTML2PPTX_STUDIO_PORT ?? process.env.PORT, AUTO_PORT);
+
+    const registered = await readEditorServerState(projectRoot);
+    if (registered && await isEditorServer(registered.port)) {
+      return {
+        baseUrl: registered.baseUrl,
+        port: registered.port,
+        reused: true,
+      };
+    }
+
+    const existing = sessions.get(projectRoot);
+    if (existing && !existing.child.killed && existing.child.exitCode == null && await isEditorServer(existing.port)) {
+      await writeEditorServerState(projectRoot, {
+        baseUrl: existing.baseUrl,
+        port: existing.port,
+        pid: existing.child.pid,
+      });
+      return {
+        baseUrl: existing.baseUrl,
+        port: existing.port,
+        reused: true,
+      };
+    }
+
+    if (requestedPort !== AUTO_PORT && await isEditorServer(requestedPort)) {
+      const baseUrl = `http://localhost:${requestedPort}`;
+      await writeEditorServerState(projectRoot, {
+        baseUrl,
+        port: requestedPort,
+        pid: null,
+      });
+      return {
+        baseUrl,
+        port: requestedPort,
+        reused: true,
+      };
+    }
+
+    const appRoot = await resolveEditorAppRoot(options);
+    const port = requestedPort === AUTO_PORT ? await getEphemeralPort() : await pickOpenPort(requestedPort);
+    const baseUrl = `http://localhost:${port}`;
+    const invocation = await resolveNextInvocation(appRoot, options);
+
+    const child = spawn(invocation.command, [
+      ...invocation.baseArgs,
+      'dev',
+      '--webpack',
+      '-p',
+      String(port),
+    ], {
+      cwd: appRoot,
+      env: {
+        ...process.env,
+        HTML2PPTX_EDITOR_BASE_URL: baseUrl,
+        NEXT_TELEMETRY_DISABLED: '1',
+        PORT: String(port),
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const session = {
+      child,
+      appRoot,
+      baseUrl,
+      port,
+      stdout: '',
+      stderr: '',
+      startedAt: new Date().toISOString(),
+    };
+    sessions.set(projectRoot, session);
+
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      session.stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      session.stderr += chunk;
+    });
+    child.once('exit', () => {
+      if (sessions.get(projectRoot) === session) sessions.delete(projectRoot);
+    });
+
+    await waitForEditorServer(session, launchTimeoutMs);
+    await writeEditorServerState(projectRoot, {
+      baseUrl,
+      port,
+      pid: child.pid,
+    });
+
+    return {
+      baseUrl,
+      port,
+      pid: child.pid,
+      reused: false,
+    };
+  }
+
+  function stopAll() {
+    for (const session of sessions.values()) {
+      session.child.kill('SIGTERM');
+    }
+    sessions.clear();
+  }
+
+  return {
+    ensure,
+    stopAll,
+  };
+}
+
+export const localEditorServerManager = createLocalEditorServerManager();
+
+export async function ensureLocalEditorServer(root = process.cwd(), options = {}) {
+  return localEditorServerManager.ensure(root, options);
+}
+
+export async function resolveEditorAppRoot(options = {}) {
+  if (options.appRoot) return resolve(options.appRoot);
+  if (process.env.HTML2PPTX_EDITOR_APP_ROOT) return resolve(process.env.HTML2PPTX_EDITOR_APP_ROOT);
+
+  const packageRoot = fileURLToPath(new URL('..', import.meta.url));
+  const packagedAppRoot = join(packageRoot, 'local-editor-app');
+  if (existsSync(join(packagedAppRoot, 'app', 'edit-slide', 'page.jsx'))) {
+    return packagedAppRoot;
+  }
+  if (existsSync(join(packageRoot, 'app', 'edit-slide', 'page.jsx'))) {
+    return packageRoot;
+  }
+
+  throw new Error(
+    'html2pptx local editor app is not bundled. Reinstall html2pptx-local-mcp or pass HTML2PPTX_EDITOR_APP_ROOT.',
+  );
+}
+
+export async function resolveNextInvocation(appRoot, options = {}) {
+  if (options.command) {
+    return {
+      command: options.command,
+      baseArgs: Array.isArray(options.baseArgs) ? options.baseArgs : [],
+    };
+  }
+  if (process.env.HTML2PPTX_NEXT_BIN) {
+    return {
+      command: process.execPath,
+      baseArgs: [process.env.HTML2PPTX_NEXT_BIN],
+    };
+  }
+
+  const nextBin = await findUp(join('node_modules', 'next', 'dist', 'bin', 'next'), appRoot);
+  if (nextBin) {
+    return {
+      command: process.execPath,
+      baseArgs: [nextBin],
+    };
+  }
+
+  return {
+    command: 'npx',
+    baseArgs: ['--yes', 'next'],
+  };
+}
+
+export async function isEditorServer(port) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 1500);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/edit-slide/local-health`, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal,
+    });
+    if (!response.ok) return false;
+    const payload = await response.json();
+    return payload?.app === 'html2pptx-local-editor' && payload?.ok === true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function waitForEditorServer(session, timeoutMs) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const startedAt = Date.now();
+    const tick = async () => {
+      if (await isEditorServer(session.port)) {
+        resolvePromise();
+        return;
+      }
+      if (session.child.exitCode != null || session.child.killed) {
+        rejectPromise(new Error([
+          `html2pptx editor server exited before it was ready on ${session.baseUrl}.`,
+          session.stderr.trim() || session.stdout.trim(),
+        ].filter(Boolean).join(' ')));
+        return;
+      }
+      if (Date.now() - startedAt >= timeoutMs) {
+        session.child.kill('SIGTERM');
+        rejectPromise(new Error([
+          `Timed out after ${timeoutMs}ms while starting html2pptx editor server on ${session.baseUrl}.`,
+          session.stderr.trim(),
+        ].filter(Boolean).join(' ')));
+        return;
+      }
+      setTimeout(tick, 350);
+    };
+    tick();
+  });
+}
+
+async function findUp(relativePath, startDir) {
+  let dir = resolve(startDir);
+  while (true) {
+    const candidate = join(dir, relativePath);
+    if (await exists(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function pickOpenPort(preferredPort) {
+  if (!(await isPortOpen(preferredPort))) return preferredPort;
+
+  for (let port = preferredPort + 1; port < preferredPort + 100; port += 1) {
+    if (!(await isPortOpen(port))) return port;
+  }
+  return getEphemeralPort();
+}
+
+function getEphemeralPort() {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const server = net.createServer();
+    server.once('error', rejectPromise);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      server.close(() => {
+        if (!address || typeof address === 'string') {
+          rejectPromise(new Error('Failed to allocate an editor port.'));
+          return;
+        }
+        resolvePromise(address.port);
+      });
+    });
+  });
+}
+
+function isPortOpen(port) {
+  return new Promise((resolvePromise) => {
+    const socket = net.createConnection({ host: '127.0.0.1', port });
+    socket.once('connect', () => {
+      socket.end();
+      resolvePromise(true);
+    });
+    socket.once('error', () => {
+      socket.destroy();
+      resolvePromise(false);
+    });
+  });
+}
+
+function normalizePort(value, fallback) {
+  if (value == null || value === '') return fallback;
+  const port = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error('editorPort must be an integer from 0 to 65535.');
+  }
+  return port;
+}
+
+function installExitHandlers() {
+  const stop = () => localEditorServerManager.stopAll();
+  process.once('exit', stop);
+  process.once('SIGINT', () => {
+    stop();
+    process.exit(130);
+  });
+  process.once('SIGTERM', () => {
+    stop();
+    process.exit(143);
+  });
+}
+
+installExitHandlers();

package/lib/local-editor-state.js

@@ -0,0 +1,45 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const EDITOR_SERVER_STATE_FILE = '.html2pptx/edit-slide/editor-server.json';
+export const LEGACY_EDITOR_SERVER_STATE_FILE = '.open-slide/editor-server.json';
+
+export async function readEditorServerState(root = process.cwd()) {
+  for (const stateFile of [EDITOR_SERVER_STATE_FILE, LEGACY_EDITOR_SERVER_STATE_FILE]) {
+    try {
+      const raw = await readFile(join(root, stateFile), 'utf8');
+      const state = JSON.parse(raw);
+      const port = Number.parseInt(state?.port, 10);
+      const baseUrl = typeof state?.baseUrl === 'string' ? state.baseUrl : '';
+      if (!Number.isInteger(port) || port <= 0 || !baseUrl.startsWith('http://')) continue;
+      return {
+        ...state,
+        port,
+        baseUrl,
+      };
+    } catch {
+      // Try the next known state location.
+    }
+  }
+  return null;
+}
+
+export async function readRegisteredEditorBaseUrl(root = process.cwd()) {
+  const state = await readEditorServerState(root);
+  return state?.baseUrl || null;
+}
+
+export async function writeEditorServerState(root, { baseUrl, port, pid, managedBy = 'html2pptx-local-mcp' }) {
+  await mkdir(join(root, '.html2pptx', 'edit-slide'), { recursive: true });
+  await writeFile(
+    join(root, EDITOR_SERVER_STATE_FILE),
+    `${JSON.stringify({
+      baseUrl,
+      port,
+      pid,
+      managedBy,
+      updatedAt: new Date().toISOString(),
+    }, null, 2)}\n`,
+    'utf8',
+  );
+}

package/lib/local-slide-editor-launcher.js

@@ -1,13 +1,12 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { access, readFile, realpath, stat } from 'node:fs/promises';
-import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { access, realpath, stat } from 'node:fs/promises';
+import { dirname, extname, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { ensureLocalEditorServer } from './local-editor-server.js';
 
 const ALLOWED_EXTENSIONS = new Set(['.html', '.htm']);
-const EDITOR_SERVER_STATE_FILE = '.html2pptx/edit-slide/editor-server.json';
-const LEGACY_EDITOR_SERVER_STATE_FILE = '.open-slide/editor-server.json';
 const DEFAULT_LAUNCH_TIMEOUT_MS = 10000;
 
 export function createLocalSlideEditorManager(options = {}) {
@@ -33,7 +32,12 @@ export function createLocalSlideEditorManager(options = {}) {
     }
 
     const baseUrl = normalizeEditorBaseUrl(
-      input.baseUrl || process.env.HTML2PPTX_EDITOR_BASE_URL || await readRegisteredEditorBaseUrl(file.root),
+      input.baseUrl ||
+        process.env.HTML2PPTX_EDITOR_BASE_URL ||
+        await resolveEditorBaseUrl(file.root, {
+          ...input,
+          ensureEditorServer: options.ensureEditorServer,
+        }),
     );
     const port = normalizePort(input.port, 0);
     const openBrowser = input.openBrowser === true;
@@ -148,6 +152,14 @@ export function createLocalSlideEditorManager(options = {}) {
 
 export const localSlideEditorManager = createLocalSlideEditorManager();
 
+async function resolveEditorBaseUrl(root, input = {}) {
+  const ensureEditorServer = typeof input.ensureEditorServer === 'function'
+    ? input.ensureEditorServer
+    : ensureLocalEditorServer;
+  const ensured = await ensureEditorServer(root, input);
+  return ensured.baseUrl;
+}
+
 export async function resolveEditableFile(filePath, cwd = process.cwd()) {
   if (typeof filePath !== 'string' || filePath.trim() === '') {
     throw new Error('filePath must be a non-empty .html or .htm path.');
@@ -305,7 +317,7 @@ export function normalizeEditorBaseUrl(raw) {
   try {
     if (!raw) {
       throw new Error(
-        'Local editor UI is not registered. Start it with `node scripts/dev-studio.mjs`, then retry, or pass baseUrl as a loopback editor URL.',
+        'Local editor UI is not available. Reinstall html2pptx-local-mcp or pass baseUrl as a loopback editor URL.',
       );
     }
     const url = new URL(raw);
@@ -330,18 +342,7 @@ function isAllowedEditorBaseUrl(url) {
   return isLoopbackHostname(url.hostname);
 }
 
-export async function readRegisteredEditorBaseUrl(root = process.cwd()) {
-  for (const stateFile of [EDITOR_SERVER_STATE_FILE, LEGACY_EDITOR_SERVER_STATE_FILE]) {
-    try {
-      const raw = await readFile(join(root, stateFile), 'utf8');
-      const state = JSON.parse(raw);
-      if (typeof state?.baseUrl === 'string') return state.baseUrl;
-    } catch {
-      // Try the next known state location.
-    }
-  }
-  return null;
-}
+export { readRegisteredEditorBaseUrl } from './local-editor-state.js';
 
 function isLoopbackHostname(hostname) {
   const host = String(hostname || '').replace(/^\[|\]$/g, '').toLowerCase();