@synthetic-ai/illustrator-mcp 0.3.0

package/server.mjs

@@ -0,0 +1,726 @@
+#!/usr/bin/env node
+/**
+ * Illustrator MCP — Synthetic
+ * Puente WebSocket ↔ plugin CEP «Synthetic Illustrator MCP». El plugin corre dentro de
+ * Illustrator y ejecuta ExtendScript; este server expone las tools.
+ *
+ * Arquitectura calcada de photoshop-mcp (el más limpio de los productos Synthetic:
+ * WebSocket, cero código específico de sistema operativo, no lanza ningún .exe) --
+ * mismo motivo por el que Illustrator MCP arranca ya multiplataforma desde v0.1,
+ * sin el problema que tuvo AE MCP (detección de rutas de instalación de Windows).
+ *
+ * Convención (estilo Synthetic):
+ *   - Diagnóstico/app:  il_healthcheck, il_info
+ *   - Escape hatches:   run_jsx, run_jsx_json
+ *   - Dominio:          verbo_sustantivo en snake_case, sin prefijo
+ *                       (list_layers, get_document_info, create_document…)
+ *
+ * ESTADO: v0.3 -- 136 tools (88 más vía apply_named_effect, ver abajo).
+ * Todo lo de v0.2 (conexión/diagnóstico, documentos/capas, items, paths,
+ * formas, texto, color, artboards, export) más: gradientes, símbolos,
+ * máscaras de recorte, brushes, alinear/distribuir (geometría propia, sin
+ * depender de comandos de menú), paths/transformaciones avanzadas (flip,
+ * shear), guías, grupos de color/spot colors, trazo avanzado (dashes/cap/
+ * join/miter), texto avanzado (find & replace, leading, estilos de
+ * párrafo/carácter), items vinculados/embebidos, capas avanzadas (color,
+ * duplicar, reordenar), selección avanzada (misma fill, invertir),
+ * patrones, 4 efectos en vivo con parámetros reales (drop shadow, feather,
+ * round corners, offset path) + apply_named_effect (88 efectos más
+ * confirmados en vivo con parámetros por defecto -- Illustrator Effects:
+ * glows, distorsión, 3D, todos los Warp, convertir a forma; Photoshop
+ * Effects: blur, artístico, trazo de pincel, boceto, textura, pixelar --
+ * más apply_live_effect_raw como escape hatch de XML crudo para los casos
+ * que necesiten parámetros no probados), y reproducir acciones existentes.
+ * Todo probado en vivo contra Illustrator real; 5 bugs reales encontrados y
+ * corregidos en el camino (Layer no tiene duplicate(), GradientColor.angle/
+ * length no se aplican via script en esta versión de Illustrator, JSON no
+ * existe en el motor de ExtendScript, characterAttributes.leading se
+ * ignora mientras autoLeading esté activo, y el XML del efecto Drop Shadow
+ * solo acepta offset/blur/opacidad -- sus parámetros de color/blend mode
+ * tiraban error 'PARM' con cualquier valor probado).
+ * Pendiente (necesita los IDs internos reales de executeMenuCommand, que
+ * Illustrator no expone por introspección ni tiene documentados en ningún
+ * lado -- probados 7 candidatos entre strings extraídos del binario real
+ * de PathfinderUI.aip y nombres razonables, todos fallaron limpio o
+ * colgaron la app sin lograr nada; abandonado): pathfinder booleano
+ * (unite/minus/intersect/exclude/divide/trim/merge/crop), blends,
+ * distorsión de envolvente, malla degradada. Los efectos 3D SÍ están
+ * cubiertos (vía apply_named_effect, no vía menú).
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import WebSocket from "ws";
+import { z } from "zod";
+import https from "https";
+import os from "os";
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+
+const PORT = Number(process.env.IL_MCP_PORT || 41220);
+const WS_URL = "ws://127.0.0.1:" + PORT;
+
+// ── Language (i18n) ─────────────────────────────────────────────────────
+// Dictionaries come from synthetic-idiomas (vendored into ./i18n by
+// scripts/sync-i18n.mjs — don't edit those files here). The language is
+// picked ONCE at startup: IL_MCP_LANG → SYNTHETIC_LANG → the settings.json the
+// panel's ⚙ language selector writes (next to its license.json in CEP's
+// USER_DATA) → English. MCP clients only read tool descriptions at session
+// start, so a language change applies after restarting this server.
+const require = createRequire(import.meta.url);
+const { createServerI18n, patchMcpServerToolsList } = require("./i18n/node.cjs");
+const i18n = createServerI18n({
+  localesDir: path.join(path.dirname(fileURLToPath(import.meta.url)), "i18n", "locales"),
+  envVar: "IL_MCP_LANG",
+  settingsFolder: "com.synthetic.illustrator-mcp.bridge",
+});
+process.stderr.write(`[illustrator-mcp] language: ${i18n.language} (source: ${i18n.languageSource})\n`);
+
+// ── Device identity (para el límite de 2 dispositivos por licencia) ────────
+// Mismo archivo compartido que ae-mcp/premiere-mcp/photoshop-mcp a propósito:
+// una máquina física cuenta como UN dispositivo contra el límite, no uno por
+// producto instalado en ella.
+function getMachineId() {
+  try {
+    const dir = path.join(os.homedir(), ".synthetic");
+    const file = path.join(dir, "device-id");
+    if (fs.existsSync(file)) {
+      const id = fs.readFileSync(file, "utf8").trim();
+      if (id) return id;
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    const id = crypto.randomUUID();
+    fs.writeFileSync(file, id, "utf8");
+    return id;
+  } catch {
+    return "volatile-" + crypto.randomUUID();
+  }
+}
+function getDeviceLabel() {
+  try { return `${os.hostname()} (${process.platform})`; } catch { return null; }
+}
+const MACHINE_ID = getMachineId();
+const DEVICE_LABEL = getDeviceLabel();
+
+// ── License validation ──────────────────────────────────────────────────
+const LICENSE_KEY = process.env.IL_MCP_LICENSE;
+const LICENSE_VALIDATION_URL = "https://synthetic.com.ar/api/v1/license/validate";
+const LICENSE_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hora
+let _licenseCache = null;
+
+function _httpsPost(url, body) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const data = JSON.stringify(body);
+    const req = https.request(
+      { hostname: parsed.hostname, path: parsed.pathname, method: "POST",
+        headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(data), "User-Agent": "illustrator-mcp/0.1.0" } },
+      (res) => {
+        let raw = "";
+        res.on("data", (c) => { raw += c; });
+        res.on("end", () => { try { resolve(JSON.parse(raw)); } catch { resolve(null); } });
+      }
+    );
+    req.on("error", reject);
+    req.setTimeout(5000, () => { req.destroy(new Error("timeout")); });
+    req.write(data);
+    req.end();
+  });
+}
+
+async function checkLicense() {
+  if (_licenseCache && (Date.now() - _licenseCache.checkedAt) < LICENSE_CACHE_TTL_MS) {
+    return _licenseCache;
+  }
+  if (!LICENSE_KEY) {
+    _licenseCache = { valid: false, plan: null, message: i18n.t("msg.license.noKey"), checkedAt: Date.now() };
+    return _licenseCache;
+  }
+  try {
+    const result = await _httpsPost(LICENSE_VALIDATION_URL, {
+      key: LICENSE_KEY,
+      product: "illustrator-mcp",
+      machineId: MACHINE_ID,
+      deviceLabel: DEVICE_LABEL,
+    });
+    _licenseCache = { ...(result || {}), checkedAt: Date.now() };
+    if (!result) _licenseCache = { valid: false, message: i18n.t("msg.license.serverUnreachableRetry"), checkedAt: Date.now() };
+  } catch {
+    if (_licenseCache && _licenseCache.valid) {
+      _licenseCache.checkedAt = Date.now();
+    } else {
+      _licenseCache = { valid: false, message: i18n.t("msg.license.serverUnreachable"), checkedAt: Date.now() };
+    }
+  }
+  return _licenseCache;
+}
+
+function licenseErrorResponse(toolName) {
+  const msg = (_licenseCache && _licenseCache.message) || i18n.t("msg.license.invalidOrMissing");
+  return text({ error: i18n.t("msg.license.required"), detail: msg, tool: toolName, info: i18n.t("msg.license.getLicense") });
+}
+
+// Tools que funcionan sin licencia (diagnóstico)
+const FREE_TOOLS = new Set(["il_healthcheck", "il_info"]);
+
+/* ---------------- WebSocket: cliente del bridge del panel ----------------
+   El bridge (WebSocket server) lo hostea el panel dentro de Illustrator.
+   Este server MCP se conecta como cliente y reintenta si el panel no está. */
+let sock = null, nextId = 1;
+const pending = new Map();
+function connectBridge() {
+  let s;
+  try { s = new WebSocket(WS_URL); } catch (e) { setTimeout(connectBridge, 2000); return; }
+  s.on("open", () => { sock = s; });
+  s.on("message", (raw) => { let m; try { m = JSON.parse(raw.toString()); } catch { return; } const p = pending.get(m.id); if (p) { pending.delete(m.id); clearTimeout(p.to); p.resolve(m); } });
+  s.on("close", () => { if (sock === s) sock = null; setTimeout(connectBridge, 2000); });
+  s.on("error", () => {});
+}
+connectBridge();
+
+function rpc(cmd, params = {}, timeoutMs = 120000) {
+  return new Promise((resolve) => {
+    if (!sock || sock.readyState !== 1) { resolve({ ok: false, error: i18n.t("msg.bridge.notConnected", { port: PORT }) }); return; }
+    const id = nextId++;
+    const to = setTimeout(() => { pending.delete(id); resolve({ ok: false, error: i18n.t("msg.bridge.timeout", { ms: timeoutMs }) }); }, timeoutMs);
+    pending.set(id, { resolve, to });
+    try { sock.send(JSON.stringify({ id, cmd, params })); } catch (e) { pending.delete(id); clearTimeout(to); resolve({ ok: false, error: "send: " + e.message }); }
+  });
+}
+// host.jsx (ExtendScript) answers in English on purpose — no non-ASCII text
+// inside evalScript. Its known dispatcher errors (thrown by the HELPERS
+// prelude below, or by ilmcp()'s own "unknown cmd") are translated here, on
+// the way out to the AI, in the server language.
+const HOST_ERRORS = [
+  [/^No document open$/, "msg.host.noDocument", []],
+  [/^Layer not found: ([\s\S]*)$/, "msg.host.layerNotFound", ["name"]],
+  [/^Item not found: ([\s\S]*)$/, "msg.host.itemNotFound", ["name"]],
+  [/^Not a group: ([\s\S]*)$/, "msg.host.notAGroup", ["name"]],
+  [/^Not a path: ([\s\S]*)$/, "msg.host.notAPath", ["name"]],
+  [/^Not a compound path: ([\s\S]*)$/, "msg.host.notACompoundPath", ["name"]],
+  [/^unknown cmd: ([\s\S]*)$/, "msg.host.unknownCommand", ["cmd"]],
+  [/^([\s\S]+) \(line (\d+)\)$/, "msg.host.errorAtLine", ["message", "line"]],
+];
+function localizeHostError(o) {
+  if (i18n.language === "en" || !o || typeof o !== "object" || typeof o.error !== "string") return o;
+  for (const [re, key, names] of HOST_ERRORS) {
+    const m = re.exec(o.error);
+    if (m) return { ...o, error: i18n.t(key, Object.fromEntries(names.map((n, i) => [n, m[i + 1]]))) };
+  }
+  return o;
+}
+const text = (o) => ({ content: [{ type: "text", text: typeof o === "string" ? o : JSON.stringify(localizeHostError(o), null, 2) }] });
+
+/* ---------------- prelude ExtendScript (helpers Illustrator) ---------------- */
+const HELPERS = [
+  "function _doc(){if(!app.documents.length)throw 'No document open';return app.activeDocument;}",
+  // Top edge (native AI coords, Y-up) of the active artboard. Illustrator's
+  // ruler origin defaults to the artboard's BOTTOM-left for a fresh document
+  // (confirmed live: artboardRect top/bottom for a 400x400 doc is [0,400,400,0]),
+  // not the top-left some callers might assume -- so a plain '-A.top' style
+  // conversion places shapes outside the artboard. Every tool that accepts a
+  // 'top/y, Y-down, document coordinates' argument must convert through this,
+  // never through a bare negation.
+  "function _abTop(){var doc=_doc();var ab=doc.artboards[doc.artboards.getActiveArtboardIndex()];return ab.artboardRect[1];}",
+  "function _find(n){function r(ls){for(var i=0;i<ls.length;i++){var L=ls[i];if(L.name===n)return L;if(L.layers&&L.layers.length){var x=r(L.layers);if(x)return x;}}return null;}return r(app.activeDocument.layers);}",
+  "function _need(n){var L=_find(n);if(!L)throw 'Layer not found: '+n;return L;}",
+  "function _act(n){var L=_need(n);app.activeDocument.activeLayer=L;return L;}",
+  // Item lookup by name. Document.pageItems is a flat, recursive listing of
+  // every item in the document (including inside groups), so no manual
+  // recursion is needed here unlike _find() for layers above.
+  "function _itemByName(n){var items=_doc().pageItems;for(var i=0;i<items.length;i++){if(items[i].name===n)return items[i];}return null;}",
+  "function _needItem(n){var it=_itemByName(n);if(!it)throw 'Item not found: '+n;return it;}",
+  // Color spec -> Illustrator Color object. {r,g,b} (0-255) | {c,m,y,k} (0-100) | {gray} (0-100).
+  "function _color(spec){if(!spec)return null;if(spec.gray!==undefined){var c=new GrayColor();c.gray=spec.gray;return c;}if(spec.c!==undefined){var c=new CMYKColor();c.cyan=spec.c;c.magenta=spec.m;c.yellow=spec.y;c.black=spec.k;return c;}if(spec.r!==undefined){var c=new RGBColor();c.red=spec.r;c.green=spec.g;c.blue=spec.b;return c;}throw 'Invalid color spec (expected {r,g,b} or {c,m,y,k} or {gray})';}",
+  // Color object -> plain spec, for reading back fill/stroke colors.
+  "function _colorOut(c){if(!c)return null;var t=String(c.typename);if(t==='RGBColor')return{type:'rgb',r:c.red,g:c.green,b:c.blue};if(t==='CMYKColor')return{type:'cmyk',c:c.cyan,m:c.magenta,y:c.yellow,k:c.black};if(t==='GrayColor')return{type:'gray',gray:c.gray};if(t==='SpotColor')return{type:'spot',name:c.spot.name};if(t==='NoColor')return{type:'none'};return{type:t};}",
+  "function _bounds(it){var b=it.geometricBounds;return{left:__pt2(b[0]),top:__pt2(b[1]),right:__pt2(b[2]),bottom:__pt2(b[3]),width:__pt2(b[2]-b[0]),height:__pt2(b[1]-b[3])};}",
+  "function __pt2(v){return Math.round(v*100)/100;}",
+  "function _itemsByNames(names){var out=[];for(var i=0;i<names.length;i++)out.push(_needItem(names[i]));return out;}",
+  "function _needSymbol(n){try{return _doc().symbols.getByName(n);}catch(e){throw 'Symbol not found: '+n;}}",
+  "function _needBrush(n){try{return _doc().brushes.getByName(n);}catch(e){throw 'Brush not found: '+n;}}",
+  "function _needSwatch(n){try{return _doc().swatches.getByName(n);}catch(e){throw 'Swatch not found: '+n;}}",
+].join("\n");
+
+const server = new McpServer(
+  { name: "illustrator", version: "0.3.0" },
+  { instructions: i18n.t("msg.server.instructions") }
+);
+
+function jsxTool(name, description, schema, build, timeout = 120000) {
+  server.tool(name, description, schema, async (a) => {
+    if (!FREE_TOOLS.has(name)) {
+      const lic = await checkLicense();
+      if (!lic.valid) return licenseErrorResponse(name);
+    }
+    return text(await rpc("eval", { code: HELPERS + "\nvar A=" + JSON.stringify(a || {}) + ";\n" + build }, timeout));
+  });
+}
+const S = z;
+
+/* ====================== DIAGNOSTICS / APP ====================== */
+server.tool("il_healthcheck", "Checks the connection to Illustrator: version and active document.", {}, async () => {
+  if (!sock || sock.readyState !== 1) return text({ connected: false, port: PORT, hint: i18n.t("msg.healthcheck.hint") });
+  return text({ connected: true, port: PORT, ...(await rpc("health", {}, 15000)) });
+});
+jsxTool("il_info", "App info: version, open documents.", {},
+  "return {version:app.version, openDocuments:app.documents.length};");
+server.tool("run_jsx", "Runs arbitrary ExtendScript in Illustrator. The code can use 'return'. Returns {ok,data}.", { code: S.string() },
+  async ({ code }) => {
+    const lic = await checkLicense();
+    if (!lic.valid) return licenseErrorResponse("run_jsx");
+    return text(await rpc("eval", { code }, 600000));
+  });
+server.tool("run_jsx_json", "Runs ExtendScript that returns a serializable value (JSON). Same as run_jsx but meant for data.", { code: S.string() },
+  async ({ code }) => {
+    const lic = await checkLicense();
+    if (!lic.valid) return licenseErrorResponse("run_jsx_json");
+    return text(await rpc("eval", { code }, 600000));
+  });
+
+/* ====================== DOCUMENTS / LAYERS (first batch) ====================== */
+server.tool("list_documents", "Lists the open documents.", {}, async () => {
+  const lic = await checkLicense();
+  if (!lic.valid) return licenseErrorResponse("list_documents");
+  return text(await rpc("eval", { code: "var a=[];for(var i=0;i<app.documents.length;i++)a.push(app.documents[i].name);return a;" }));
+});
+server.tool("get_document_info", "Info about the active document: active artboard, artboard count, color space, units, layers.", {}, async () => {
+  const lic = await checkLicense();
+  if (!lic.valid) return licenseErrorResponse("get_document_info");
+  return text(await rpc("documentInfo", {}));
+});
+server.tool("list_layers", "Lists the layer tree of the active document (name, visible, locked, item count by type).", {}, async () => {
+  const lic = await checkLicense();
+  if (!lic.valid) return licenseErrorResponse("list_layers");
+  return text(await rpc("listLayers", {}));
+});
+server.tool("get_layer", "Info about a layer by name.", { name: S.string() }, async ({ name }) => {
+  const lic = await checkLicense();
+  if (!lic.valid) return licenseErrorResponse("get_layer");
+  return text(await rpc("getLayer", { name }));
+});
+jsxTool("create_document", "Creates a new document.", { width: S.number(), height: S.number(), name: S.string().optional() },
+  "var preset=new DocumentPreset(); preset.width=A.width; preset.height=A.height; preset.units=RulerUnits.Points; preset.colorMode=DocumentColorSpace.RGB; var d=app.documents.addDocument(DocumentColorSpace.RGB, preset); if(A.name)d.name=A.name; return 'created: '+d.name;");
+jsxTool("open_document", "Opens a file.", { path: S.string() },
+  "app.open(new File(A.path));return 'opened: '+app.activeDocument.name;");
+jsxTool("save_document", "Saves the active document.", {}, "_doc().save();return 'saved';");
+jsxTool("close_document", "Closes the active document (save=true to save first).", { save: S.boolean().optional() },
+  "_doc().close(A.save?SaveOptions.SAVECHANGES:SaveOptions.DONOTSAVECHANGES);return 'closed';");
+jsxTool("add_layer", "Adds a new layer to the active document.", { name: S.string() },
+  "var L=_doc().layers.add(); L.name=A.name; return 'created: '+L.name;");
+jsxTool("set_layer_visible", "Shows or hides a layer.", { name: S.string(), visible: S.boolean() },
+  "_need(A.name).visible=A.visible; return 'ok';");
+jsxTool("set_layer_locked", "Locks or unlocks a layer.", { name: S.string(), locked: S.boolean() },
+  "_need(A.name).locked=A.locked; return 'ok';");
+jsxTool("delete_layer", "Deletes a layer and everything on it.", { name: S.string() },
+  "_need(A.name).remove(); return 'ok';");
+jsxTool("rename_layer", "Renames a layer.", { name: S.string(), newName: S.string() },
+  "_need(A.name).name=A.newName; return 'ok';");
+
+/* ====================== ITEMS (general) ====================== */
+jsxTool("list_items", "Lists page items in the active document (name, type, bounds). Optionally scoped to one layer by name.", { layer: S.string().optional() },
+  "var items; if(A.layer){items=_need(A.layer).pageItems;}else{items=_doc().pageItems;} var out=[]; for(var i=0;i<items.length;i++){var it=items[i]; var e={name:it.name,type:String(it.typename)}; try{e.bounds=_bounds(it);}catch(x){} out.push(e);} return out;");
+jsxTool("get_item", "Info about a page item by name: type, bounds, layer, and (for paths) fill/stroke.", { name: S.string() },
+  "var it=_needItem(A.name); var r={name:it.name,type:String(it.typename),layer:it.layer.name,hidden:it.hidden,locked:it.locked}; try{r.bounds=_bounds(it);}catch(x){} if(it.typename==='PathItem'){r.filled=it.filled;r.fillColor=_colorOut(it.filled?it.fillColor:null);r.stroked=it.stroked;r.strokeColor=_colorOut(it.stroked?it.strokeColor:null);r.strokeWidth=it.strokeWidth;r.closed=it.closed;} return r;");
+jsxTool("rename_item", "Renames a page item (item names are how other tools address a specific item).", { name: S.string(), newName: S.string() },
+  "_needItem(A.name).name=A.newName; return 'ok';");
+jsxTool("delete_item", "Deletes a page item by name.", { name: S.string() },
+  "_needItem(A.name).remove(); return 'ok';");
+jsxTool("duplicate_item", "Duplicates a page item. Returns the new item's (auto-generated) name.", { name: S.string(), newName: S.string().optional() },
+  "var it=_needItem(A.name); var d=it.duplicate(); if(A.newName)d.name=A.newName; else if(!d.name)d.name=it.name+' copy'; return d.name;");
+jsxTool("set_item_visible", "Shows or hides a page item.", { name: S.string(), visible: S.boolean() },
+  "_needItem(A.name).hidden=!A.visible; return 'ok';");
+jsxTool("set_item_locked", "Locks or unlocks a page item.", { name: S.string(), locked: S.boolean() },
+  "_needItem(A.name).locked=A.locked; return 'ok';");
+jsxTool("move_item", "Moves a page item to an absolute position (top-left of its bounding box, in points).", { name: S.string(), x: S.number(), y: S.number() },
+  "var it=_needItem(A.name); it.position=[A.x, A.y]; return 'ok';");
+jsxTool("translate_item", "Moves a page item relative to its current position, in points.", { name: S.string(), dx: S.number(), dy: S.number() },
+  "var it=_needItem(A.name); var p=it.position; it.position=[p[0]+A.dx, p[1]-A.dy]; return 'ok';");
+jsxTool("resize_item", "Scales a page item by percentage (100 = no change) around its center.", { name: S.string(), scaleX: S.number(), scaleY: S.number().optional() },
+  "var it=_needItem(A.name); it.resize(A.scaleX, A.scaleY===undefined?A.scaleX:A.scaleY); return 'ok';");
+jsxTool("rotate_item", "Rotates a page item by degrees (positive = counter-clockwise) around its center.", { name: S.string(), angle: S.number() },
+  "_needItem(A.name).rotate(A.angle); return 'ok';");
+jsxTool("get_item_bounds", "Geometric bounds (left, top, right, bottom, width, height, in points) of a page item.", { name: S.string() },
+  "return _bounds(_needItem(A.name));");
+jsxTool("move_item_to_layer", "Moves a page item into a different layer.", { name: S.string(), layer: S.string() },
+  "var it=_needItem(A.name); it.move(_need(A.layer), ElementPlacement.PLACEATEND); return 'ok';");
+jsxTool("bring_to_front", "Brings a page item to the front of its layer's stacking order.", { name: S.string() },
+  "_needItem(A.name).zOrder(ZOrderMethod.BRINGTOFRONT); return 'ok';");
+jsxTool("send_to_back", "Sends a page item to the back of its layer's stacking order.", { name: S.string() },
+  "_needItem(A.name).zOrder(ZOrderMethod.SENDTOBACK); return 'ok';");
+jsxTool("bring_forward", "Moves a page item one step forward in its layer's stacking order.", { name: S.string() },
+  "_needItem(A.name).zOrder(ZOrderMethod.BRINGFORWARD); return 'ok';");
+jsxTool("send_backward", "Moves a page item one step backward in its layer's stacking order.", { name: S.string() },
+  "_needItem(A.name).zOrder(ZOrderMethod.SENDBACKWARD); return 'ok';");
+
+/* ====================== GROUPING / SELECTION ====================== */
+jsxTool("group_items", "Groups page items together into a new GroupItem. Returns the group's name.", { names: S.array(S.string()), groupName: S.string().optional() },
+  "var g=_doc().groupItems.add(); if(A.groupName)g.name=A.groupName; for(var i=0;i<A.names.length;i++){_needItem(A.names[i]).move(g, ElementPlacement.PLACEATEND);} return g.name || '(unnamed group)';");
+jsxTool("ungroup_item", "Ungroups a GroupItem, moving its children up to the group's parent.", { name: S.string() },
+  "var g=_needItem(A.name); if(String(g.typename)!=='GroupItem') throw 'Not a group: '+A.name; var parent=g.layer; var kids=[]; for(var i=0;i<g.pageItems.length;i++)kids.push(g.pageItems[i]); for(var j=0;j<kids.length;j++){kids[j].move(parent, ElementPlacement.PLACEATEND);} g.remove(); return kids.length+' item(s) ungrouped';");
+jsxTool("list_group_children", "Lists the direct children of a GroupItem.", { name: S.string() },
+  "var g=_needItem(A.name); if(String(g.typename)!=='GroupItem') throw 'Not a group: '+A.name; var out=[]; for(var i=0;i<g.pageItems.length;i++){var it=g.pageItems[i]; out.push({name:it.name,type:String(it.typename)});} return out;");
+jsxTool("select_items", "Sets the active document selection to the given page items (by name). Pass an empty array to clear.", { names: S.array(S.string()) },
+  "var sel=[]; for(var i=0;i<A.names.length;i++)sel.push(_needItem(A.names[i])); _doc().selection=sel; return sel.length+' item(s) selected';");
+jsxTool("get_selection", "Lists the page items currently selected in the document.", {},
+  "var s=_doc().selection; var out=[]; for(var i=0;i<s.length;i++){out.push({name:s[i].name,type:String(s[i].typename)});} return out;");
+jsxTool("deselect_all", "Clears the active document's selection.", {},
+  "_doc().selection=null; return 'ok';");
+
+/* ====================== PATHS ====================== */
+jsxTool("create_path_from_points",
+  "Creates a PathItem from an array of anchor points ({x,y} in points, document coordinates with Y pointing down as passed here — the tool flips to Illustrator's own Y-up convention internally). Straight segments only (no bezier handles); use set_path_point_handles for curves afterwards.",
+  { points: S.array(S.object({ x: S.number(), y: S.number() })), closed: S.boolean().optional(), name: S.string().optional(), layer: S.string().optional() },
+  "var lyr=A.layer?_need(A.layer):_doc().activeLayer; var p=lyr.pathItems.add(); var pts=[]; for(var i=0;i<A.points.length;i++)pts.push([A.points[i].x, -A.points[i].y]); p.setEntirePath(pts); p.closed=!!A.closed; if(A.name)p.name=A.name; return p.name || '(unnamed path)';");
+jsxTool("get_path_points", "Returns a path's anchor points and bezier handles (in the same Y-down convention create_path_from_points takes).", { name: S.string() },
+  "var p=_needItem(A.name); if(String(p.typename)!=='PathItem') throw 'Not a path: '+A.name; var out=[]; for(var i=0;i<p.pathPoints.length;i++){var pp=p.pathPoints[i]; out.push({anchor:{x:__pt2(pp.anchor[0]),y:__pt2(-pp.anchor[1])},leftDirection:{x:__pt2(pp.leftDirection[0]),y:__pt2(-pp.leftDirection[1])},rightDirection:{x:__pt2(pp.rightDirection[0]),y:__pt2(-pp.rightDirection[1])},pointType:String(pp.pointType)});} return {closed:p.closed, points:out};");
+jsxTool("set_path_points", "Replaces a path's anchor points wholesale (straight segments; same Y-down convention).", { name: S.string(), points: S.array(S.object({ x: S.number(), y: S.number() })), closed: S.boolean().optional() },
+  "var p=_needItem(A.name); if(String(p.typename)!=='PathItem') throw 'Not a path: '+A.name; var pts=[]; for(var i=0;i<A.points.length;i++)pts.push([A.points[i].x, -A.points[i].y]); p.setEntirePath(pts); if(A.closed!==undefined)p.closed=A.closed; return 'ok';");
+jsxTool("set_path_closed", "Opens or closes a path.", { name: S.string(), closed: S.boolean() },
+  "var p=_needItem(A.name); p.closed=A.closed; return 'ok';");
+jsxTool("release_compound_path", "Releases a CompoundPathItem back into its individual PathItems.", { name: S.string() },
+  "var cp=_needItem(A.name); if(String(cp.typename)!=='CompoundPathItem') throw 'Not a compound path: '+A.name; var parent=cp.layer; var kids=[]; for(var i=0;i<cp.pathItems.length;i++)kids.push(cp.pathItems[i]); for(var j=0;j<kids.length;j++)kids[j].move(parent, ElementPlacement.PLACEATEND); return kids.length+' path(s) released';");
+jsxTool("make_compound_path", "Combines path items into a single CompoundPathItem (e.g. for donut shapes with holes). Returns the compound path's name.", { names: S.array(S.string()), name: S.string().optional() },
+  "var sel=[]; for(var i=0;i<A.names.length;i++)sel.push(_needItem(A.names[i])); _doc().selection=sel; app.executeMenuCommand('compoundPath'); var cp=_doc().selection[0]; if(A.name)cp.name=A.name; return cp.name || '(unnamed compound path)';");
+
+/* ====================== SHAPES ====================== */
+jsxTool("add_shape_rectangle", "Adds a rectangle. top/left are in points, document coordinates (Y down).", { top: S.number(), left: S.number(), width: S.number(), height: S.number(), name: S.string().optional(), layer: S.string().optional() },
+  "var lyr=A.layer?_need(A.layer):_doc().activeLayer; var r=lyr.pathItems.rectangle(_abTop()-A.top, A.left, A.width, A.height); if(A.name)r.name=A.name; return r.name || '(unnamed rectangle)';");
+jsxTool("add_shape_rounded_rectangle", "Adds a rounded rectangle.", { top: S.number(), left: S.number(), width: S.number(), height: S.number(), radius: S.number(), name: S.string().optional(), layer: S.string().optional() },
+  "var lyr=A.layer?_need(A.layer):_doc().activeLayer; var r=lyr.pathItems.roundedRectangle(_abTop()-A.top, A.left, A.width, A.height, A.radius, A.radius); if(A.name)r.name=A.name; return r.name || '(unnamed rounded rectangle)';");
+jsxTool("add_shape_ellipse", "Adds an ellipse.", { top: S.number(), left: S.number(), width: S.number(), height: S.number(), name: S.string().optional(), layer: S.string().optional() },
+  "var lyr=A.layer?_need(A.layer):_doc().activeLayer; var e=lyr.pathItems.ellipse(_abTop()-A.top, A.left, A.width, A.height); if(A.name)e.name=A.name; return e.name || '(unnamed ellipse)';");
+jsxTool("add_shape_line", "Adds a straight line segment between two points.", { x1: S.number(), y1: S.number(), x2: S.number(), y2: S.number(), name: S.string().optional(), layer: S.string().optional() },
+  "var lyr=A.layer?_need(A.layer):_doc().activeLayer; var abT=_abTop(); var l=lyr.pathItems.add(); l.setEntirePath([[A.x1,abT-A.y1],[A.x2,abT-A.y2]]); if(A.name)l.name=A.name; return l.name || '(unnamed line)';");
+jsxTool("add_shape_polygon", "Adds a regular polygon centered at (cx, cy).", { cx: S.number(), cy: S.number(), radius: S.number(), sides: S.number().min(3), name: S.string().optional(), layer: S.string().optional() },
+  "var lyr=A.layer?_need(A.layer):_doc().activeLayer; var p=lyr.pathItems.polygon(A.cx, _abTop()-A.cy, A.radius, A.sides); if(A.name)p.name=A.name; return p.name || '(unnamed polygon)';");
+jsxTool("add_shape_star", "Adds a star centered at (cx, cy).", { cx: S.number(), cy: S.number(), outerRadius: S.number(), innerRadius: S.number(), points: S.number().min(3), name: S.string().optional(), layer: S.string().optional() },
+  "var lyr=A.layer?_need(A.layer):_doc().activeLayer; var s=lyr.pathItems.star(A.cx, _abTop()-A.cy, A.outerRadius, A.innerRadius, A.points); if(A.name)s.name=A.name; return s.name || '(unnamed star)';");
+
+/* ====================== TEXT ====================== */
+jsxTool("add_text_frame", "Adds a point-text frame (text anchored at a single point, grows with content) at (x, y).", { x: S.number(), y: S.number(), contents: S.string(), name: S.string().optional(), layer: S.string().optional() },
+  "var lyr=A.layer?_need(A.layer):_doc().activeLayer; var t=lyr.textFrames.pointText([A.x, _abTop()-A.y]); t.contents=A.contents; if(A.name)t.name=A.name; return t.name || '(unnamed text frame)';");
+jsxTool("add_area_text_frame", "Adds an area-text frame: text flows inside a rectangle and wraps.", { top: S.number(), left: S.number(), width: S.number(), height: S.number(), contents: S.string(), name: S.string().optional(), layer: S.string().optional() },
+  "var lyr=A.layer?_need(A.layer):_doc().activeLayer; var rect=lyr.pathItems.rectangle(_abTop()-A.top, A.left, A.width, A.height); rect.filled=false; rect.stroked=false; var t=lyr.textFrames.areaText(rect); t.contents=A.contents; if(A.name)t.name=A.name; return t.name || '(unnamed area text)';");
+jsxTool("get_text_contents", "Returns a text frame's string contents.", { name: S.string() },
+  "var t=_needItem(A.name); return String(t.contents);");
+jsxTool("set_text_contents", "Sets a text frame's string contents.", { name: S.string(), contents: S.string() },
+  "_needItem(A.name).contents=A.contents; return 'ok';");
+jsxTool("set_text_style",
+  "Sets character-level style for a text frame's full contents: font (PostScript name, e.g. 'Helvetica-Bold'), size (pt), fill color, and/or tracking.",
+  { name: S.string(), font: S.string().optional(), size: S.number().optional(), color: S.object({ r: S.number(), g: S.number(), b: S.number() }).optional(), tracking: S.number().optional() },
+  "var t=_needItem(A.name); var attrs=t.textRange.characterAttributes; if(A.font)attrs.textFont=app.textFonts.getByName(A.font); if(A.size!==undefined)attrs.size=A.size; if(A.color)attrs.fillColor=_color(A.color); if(A.tracking!==undefined)attrs.tracking=A.tracking; return 'ok';");
+jsxTool("set_text_justification", "Sets a text frame's paragraph alignment.", { name: S.string(), align: S.enum(["left", "center", "right", "justify"]) },
+  "var map={left:Justification.LEFT,center:Justification.CENTER,right:Justification.RIGHT,justify:Justification.FULLJUSTIFY}; _needItem(A.name).textRange.paragraphAttributes.justification=map[A.align]; return 'ok';");
+jsxTool("list_fonts", "Lists a sample of available font PostScript names (first 200 — Illustrator can have thousands installed).", {},
+  "var out=[]; var n=Math.min(app.textFonts.length,200); for(var i=0;i<n;i++)out.push(app.textFonts[i].name); return out;");
+jsxTool("outline_text", "Converts a text frame to outlines (editable vector paths). Returns the resulting group's name — the original text frame is replaced.", { name: S.string(), newName: S.string().optional() },
+  "var t=_needItem(A.name); var g=t.createOutline(); if(A.newName)g.name=A.newName; return g.name || '(unnamed outline group)';");
+
+/* ====================== COLOR / FILL / STROKE ====================== */
+jsxTool("set_fill_color", "Sets a page item's fill color, or removes the fill if color is omitted.", { name: S.string(), color: S.object({ r: S.number().optional(), g: S.number().optional(), b: S.number().optional(), c: S.number().optional(), m: S.number().optional(), y: S.number().optional(), k: S.number().optional(), gray: S.number().optional() }).optional() },
+  "var it=_needItem(A.name); if(!A.color){it.filled=false;}else{it.filled=true; it.fillColor=_color(A.color);} return 'ok';");
+jsxTool("set_stroke_color", "Sets a page item's stroke color, or removes the stroke if color is omitted.", { name: S.string(), color: S.object({ r: S.number().optional(), g: S.number().optional(), b: S.number().optional(), c: S.number().optional(), m: S.number().optional(), y: S.number().optional(), k: S.number().optional(), gray: S.number().optional() }).optional() },
+  "var it=_needItem(A.name); if(!A.color){it.stroked=false;}else{it.stroked=true; it.strokeColor=_color(A.color);} return 'ok';");
+jsxTool("set_stroke_width", "Sets a page item's stroke width, in points.", { name: S.string(), width: S.number() },
+  "var it=_needItem(A.name); it.stroked=true; it.strokeWidth=A.width; return 'ok';");
+jsxTool("set_opacity", "Sets a page item's opacity (0-100).", { name: S.string(), opacity: S.number().min(0).max(100) },
+  "_needItem(A.name).opacity=A.opacity; return 'ok';");
+jsxTool("set_blend_mode", "Sets a page item's blend mode.", { name: S.string(), mode: S.enum(["normal", "multiply", "screen", "overlay", "darken", "lighten", "colorDodge", "colorBurn", "hardLight", "softLight", "difference", "exclusion", "hue", "saturation", "color", "luminosity"]) },
+  "var map={normal:BlendModes.NORMAL,multiply:BlendModes.MULTIPLY,screen:BlendModes.SCREEN,overlay:BlendModes.OVERLAY,darken:BlendModes.DARKEN,lighten:BlendModes.LIGHTEN,colorDodge:BlendModes.COLORDODGE,colorBurn:BlendModes.COLORBURN,hardLight:BlendModes.HARDLIGHT,softLight:BlendModes.SOFTLIGHT,difference:BlendModes.DIFFERENCE,exclusion:BlendModes.EXCLUSION,hue:BlendModes.HUE,saturation:BlendModes.SATURATIONBLEND,color:BlendModes.COLORBLEND,luminosity:BlendModes.LUMINOSITY}; _needItem(A.name).blendingMode=map[A.mode]; return 'ok';");
+jsxTool("list_swatches", "Lists the document's color swatches.", {},
+  "var out=[]; var sw=_doc().swatches; for(var i=0;i<sw.length;i++){out.push({name:sw[i].name,color:_colorOut(sw[i].color)});} return out;");
+jsxTool("add_swatch", "Adds a new color swatch to the document.", { name: S.string(), color: S.object({ r: S.number().optional(), g: S.number().optional(), b: S.number().optional(), c: S.number().optional(), m: S.number().optional(), y: S.number().optional(), k: S.number().optional(), gray: S.number().optional() }) },
+  "var s=_doc().swatches.add(); s.name=A.name; s.color=_color(A.color); return s.name;");
+jsxTool("apply_swatch", "Applies an existing swatch as a page item's fill or stroke.", { name: S.string(), swatch: S.string(), target: S.enum(["fill", "stroke"]).default("fill") },
+  "var it=_needItem(A.name); var sw=_doc().swatches.getByName(A.swatch); if(A.target==='stroke'){it.stroked=true; it.strokeColor=sw.color;}else{it.filled=true; it.fillColor=sw.color;} return 'ok';");
+
+/* ====================== ARTBOARDS ====================== */
+jsxTool("list_artboards", "Lists the document's artboards (name, bounds).", {},
+  "var out=[]; var abs=_doc().artboards; for(var i=0;i<abs.length;i++){var r=abs[i].artboardRect; out.push({index:i,name:abs[i].name,left:__pt2(r[0]),top:__pt2(r[1]),right:__pt2(r[2]),bottom:__pt2(r[3]),width:__pt2(r[2]-r[0]),height:__pt2(r[1]-r[3])});} return out;");
+jsxTool("add_artboard", "Adds a new artboard.", { left: S.number(), top: S.number(), width: S.number(), height: S.number(), name: S.string().optional() },
+  "var ab=_doc().artboards.add([A.left, A.top, A.left+A.width, A.top-A.height]); if(A.name)ab.name=A.name; return ab.name;");
+jsxTool("rename_artboard", "Renames an artboard by index.", { index: S.number(), name: S.string() },
+  "_doc().artboards[A.index].name=A.name; return 'ok';");
+jsxTool("delete_artboard", "Deletes an artboard by index (a document must keep at least one).", { index: S.number() },
+  "_doc().artboards.remove(A.index); return 'ok';");
+jsxTool("set_active_artboard", "Sets which artboard index is active (affects tools that default to 'the active artboard', e.g. get_document_info).", { index: S.number() },
+  "_doc().artboards.setActiveArtboardIndex(A.index); return 'ok';");
+
+/* ====================== EXPORT ====================== */
+jsxTool("export_png", "Exports the active document (or one artboard) as a transparent PNG-24.", { path: S.string(), scale: S.number().default(100), artboardIndex: S.number().optional(), transparent: S.boolean().default(true) },
+  "var opts=new ExportOptionsPNG24(); opts.artBoardClipping=true; opts.horizontalScale=A.scale; opts.verticalScale=A.scale; opts.transparency=A.transparent; if(A.artboardIndex!==undefined)_doc().artboards.setActiveArtboardIndex(A.artboardIndex); _doc().exportFile(new File(A.path), ExportType.PNG24, opts); return 'exported: '+A.path;");
+jsxTool("export_jpg", "Exports the active document (or one artboard) as a JPEG.", { path: S.string(), scale: S.number().default(100), quality: S.number().min(0).max(100).default(90), artboardIndex: S.number().optional() },
+  "var opts=new ExportOptionsJPEG(); opts.artBoardClipping=true; opts.horizontalScale=A.scale; opts.verticalScale=A.scale; opts.qualitySetting=A.quality; if(A.artboardIndex!==undefined)_doc().artboards.setActiveArtboardIndex(A.artboardIndex); _doc().exportFile(new File(A.path), ExportType.JPEG, opts); return 'exported: '+A.path;");
+jsxTool("export_svg", "Exports the active document as SVG.", { path: S.string() },
+  "var opts=new ExportOptionsSVG(); _doc().exportFile(new File(A.path), ExportType.SVG, opts); return 'exported: '+A.path;");
+jsxTool("export_pdf", "Saves the active document as a PDF (via Save As, not Export — PDF is a native save format in Illustrator).", { path: S.string() },
+  "var opts=new PDFSaveOptions(); _doc().saveAs(new File(A.path), opts); return 'saved: '+A.path;");
+jsxTool("save_document_as", "Saves the active document as a new .ai file.", { path: S.string() },
+  "_doc().saveAs(new File(A.path)); return 'saved: '+A.path;");
+
+/* ====================== GRADIENTS ====================== */
+// GradientColor.angle/.length are confirmed broken in this Illustrator
+// version when set via script (silently ignored, always reads back 0/80
+// regardless of what's assigned) -- verified live, not shipped as params.
+jsxTool("list_gradients", "Lists the document's gradients (name, type, stop count).", {},
+  "var out=[]; var gs=_doc().gradients; for(var i=0;i<gs.length;i++){out.push({name:gs[i].name,type:String(gs[i].type),stops:gs[i].gradientStops.length});} return out;");
+jsxTool("create_gradient",
+  "Creates a linear or radial gradient with 2+ color stops (position 0-100). Returns the gradient's name.",
+  { name: S.string(), type: S.enum(["linear", "radial"]).default("linear"), stops: S.array(S.object({ position: S.number().min(0).max(100), color: S.object({ r: S.number().optional(), g: S.number().optional(), b: S.number().optional(), c: S.number().optional(), m: S.number().optional(), y: S.number().optional(), k: S.number().optional(), gray: S.number().optional() }), opacity: S.number().min(0).max(100).optional() })).min(2) },
+  "var g=_doc().gradients.add(); g.name=A.name; g.type=A.type==='radial'?GradientType.RADIAL:GradientType.LINEAR; var stops=g.gradientStops; while(stops.length<A.stops.length)stops.add(); for(var i=0;i<A.stops.length;i++){var s=stops[i]; s.rampPoint=A.stops[i].position; s.color=_color(A.stops[i].color); if(A.stops[i].opacity!==undefined)s.opacity=A.stops[i].opacity;} return g.name;");
+jsxTool("get_gradient", "Returns a gradient's type and stops.", { name: S.string() },
+  "var g=_doc().gradients.getByName(A.name); var out=[]; for(var i=0;i<g.gradientStops.length;i++){var s=g.gradientStops[i]; out.push({position:s.rampPoint,opacity:s.opacity,color:_colorOut(s.color)});} return {type:String(g.type), stops:out};");
+jsxTool("delete_gradient", "Deletes a gradient from the document.", { name: S.string() },
+  "_doc().gradients.getByName(A.name).remove(); return 'ok';");
+jsxTool("apply_gradient_fill", "Fills a page item with an existing gradient.", { name: S.string(), gradient: S.string() },
+  "var it=_needItem(A.name); var gc=new GradientColor(); gc.gradient=_doc().gradients.getByName(A.gradient); it.filled=true; it.fillColor=gc; return 'ok';");
+jsxTool("apply_gradient_stroke", "Strokes a page item with an existing gradient.", { name: S.string(), gradient: S.string() },
+  "var it=_needItem(A.name); var gc=new GradientColor(); gc.gradient=_doc().gradients.getByName(A.gradient); it.stroked=true; it.strokeColor=gc; return 'ok';");
+
+/* ====================== SYMBOLS ====================== */
+jsxTool("list_symbols", "Lists the document's symbols.", {},
+  "var out=[]; var ss=_doc().symbols; for(var i=0;i<ss.length;i++)out.push(ss[i].name); return out;");
+jsxTool("create_symbol_from_item", "Creates a new symbol definition from a page item. Illustrator replaces the source item in place with an instance of the new symbol.", { name: S.string(), itemName: S.string() },
+  "var it=_needItem(A.itemName); var s=_doc().symbols.add(it); s.name=A.name; return s.name;");
+jsxTool("place_symbol_instance", "Places an instance of an existing symbol at (x, y).", { symbol: S.string(), x: S.number(), y: S.number(), name: S.string().optional(), layer: S.string().optional() },
+  "var lyr=A.layer?_need(A.layer):_doc().activeLayer; var sym=_needSymbol(A.symbol); var inst=lyr.symbolItems.add(sym); inst.position=[A.x, _abTop()-A.y]; if(A.name)inst.name=A.name; return inst.name || '(unnamed symbol instance)';");
+jsxTool("break_symbol_link", "Breaks a symbol instance's link, converting it back to regular editable artwork. Returns the resulting item's name.", { name: S.string() },
+  "var inst=_needItem(A.name); if(String(inst.typename)!=='SymbolItem') throw 'Not a symbol instance: '+A.name; var art=inst.breakLink(); return art.name || '(unnamed)';");
+jsxTool("set_symbol_instance_symbol", "Re-points an existing symbol instance to a different symbol definition.", { name: S.string(), symbol: S.string() },
+  "var inst=_needItem(A.name); if(String(inst.typename)!=='SymbolItem') throw 'Not a symbol instance: '+A.name; inst.symbol=_needSymbol(A.symbol); return 'ok';");
+jsxTool("rename_symbol", "Renames a symbol definition.", { name: S.string(), newName: S.string() },
+  "_needSymbol(A.name).name=A.newName; return 'ok';");
+jsxTool("delete_symbol", "Deletes a symbol definition from the document (existing instances become regular art).", { name: S.string() },
+  "_needSymbol(A.name).remove(); return 'ok';");
+
+/* ====================== CLIPPING MASKS ====================== */
+jsxTool("make_clipping_mask",
+  "Groups items and uses one of them (maskItemName, must be a path/compound path) as a clipping mask for the rest. Returns the group's name.",
+  { names: S.array(S.string()).min(2), maskItemName: S.string(), groupName: S.string().optional() },
+  "var mask=_needItem(A.maskItemName); var g=_doc().groupItems.add(); mask.move(g, ElementPlacement.PLACEATBEGINNING); for(var i=0;i<A.names.length;i++){if(A.names[i]===A.maskItemName)continue; _needItem(A.names[i]).move(g, ElementPlacement.PLACEATEND);} g.clipped=true; if(A.groupName)g.name=A.groupName; return g.name || '(unnamed clip group)';");
+jsxTool("release_clipping_mask", "Releases a clipping group back into its individual items (un-clips and ungroups).", { name: S.string() },
+  "var g=_needItem(A.name); if(String(g.typename)!=='GroupItem') throw 'Not a group: '+A.name; g.clipped=false; var parent=g.layer; var kids=[]; for(var i=0;i<g.pageItems.length;i++)kids.push(g.pageItems[i]); for(var j=0;j<kids.length;j++)kids[j].move(parent, ElementPlacement.PLACEATEND); g.remove(); return kids.length+' item(s) released';");
+jsxTool("set_group_clipped", "Low-level: directly sets whether an existing group's topmost item is used as its clipping mask.", { name: S.string(), clipped: S.boolean() },
+  "var g=_needItem(A.name); if(String(g.typename)!=='GroupItem') throw 'Not a group: '+A.name; g.clipped=A.clipped; return 'ok';");
+
+/* ====================== BRUSHES ====================== */
+jsxTool("list_brushes", "Lists the document's brushes by name (Illustrator's scripting API doesn't expose the brush type -- art/calligraphic/pattern/scatter -- so it isn't included).", {},
+  "var out=[]; var bs=_doc().brushes; for(var i=0;i<bs.length;i++)out.push(bs[i].name); return out;");
+jsxTool("apply_brush_to_path", "Applies an existing brush to a path's stroke.", { brush: S.string(), name: S.string() },
+  "var it=_needItem(A.name); it.stroked=true; _needBrush(A.brush).applyTo(it); return 'ok';");
+
+/* ====================== ALIGN / DISTRIBUTE ====================== */
+// Pure geometry (no executeMenuCommand): computed from each item's own
+// geometricBounds, so it works headlessly and doesn't depend on undocumented
+// internal menu-command IDs.
+jsxTool("align_items",
+  "Aligns items to their own combined bounding box on one edge/axis.",
+  { names: S.array(S.string()).min(1), edge: S.enum(["left", "right", "top", "bottom", "centerH", "centerV"]) },
+  "var items=_itemsByNames(A.names); var L=Infinity,R=-Infinity,T=-Infinity,B=Infinity; for(var i=0;i<items.length;i++){var b=items[i].geometricBounds; if(b[0]<L)L=b[0]; if(b[2]>R)R=b[2]; if(b[1]>T)T=b[1]; if(b[3]<B)B=b[3];} for(var j=0;j<items.length;j++){var it=items[j],b2=it.geometricBounds,p=it.position; var w=b2[2]-b2[0],h=b2[1]-b2[3]; if(A.edge==='left')it.position=[L,p[1]]; else if(A.edge==='right')it.position=[R-w,p[1]]; else if(A.edge==='top')it.position=[p[0],T]; else if(A.edge==='bottom')it.position=[p[0],B+h]; else if(A.edge==='centerH')it.position=[(L+R)/2-w/2,p[1]]; else if(A.edge==='centerV')it.position=[p[0],(T+B)/2+h/2];} return items.length+' item(s) aligned';");
+jsxTool("distribute_items",
+  "Distributes 3+ items with equal spacing between their edges, along one axis.",
+  { names: S.array(S.string()).min(3), axis: S.enum(["horizontal", "vertical"]) },
+  "var items=_itemsByNames(A.names); var horiz=A.axis==='horizontal'; items.sort(function(a,b){var ba=a.geometricBounds,bb=b.geometricBounds; return horiz?(ba[0]-bb[0]):(bb[1]-ba[1]);}); var first=items[0].geometricBounds, last=items[items.length-1].geometricBounds; if(horiz){var span=last[2]-first[0]; var totalW=0; for(var i=0;i<items.length;i++){var b=items[i].geometricBounds; totalW+=(b[2]-b[0]);} var gap=(span-totalW)/(items.length-1); var x=first[0]; for(var j=0;j<items.length;j++){var it=items[j],b2=it.geometricBounds,p=it.position; it.position=[x,p[1]]; x+=(b2[2]-b2[0])+gap;}}else{var spanV=first[1]-last[3]; var totalH=0; for(var i2=0;i2<items.length;i2++){var b3=items[i2].geometricBounds; totalH+=(b3[1]-b3[3]);} var gapV=(spanV-totalH)/(items.length-1); var y=first[1]; for(var k=0;k<items.length;k++){var it2=items[k],b4=it2.geometricBounds,p2=it2.position,h=b4[1]-b4[3]; it2.position=[p2[0],y]; y-=h+gapV;}} return items.length+' item(s) distributed';");
+
+/* ====================== TRANSFORM (advanced) ====================== */
+jsxTool("flip_item", "Flips a page item horizontally and/or vertically around its own center.", { name: S.string(), horizontal: S.boolean().optional(), vertical: S.boolean().optional() },
+  "var it=_needItem(A.name); it.resize(A.horizontal?-100:100, A.vertical?-100:100); return 'ok';");
+jsxTool("shear_item", "Shears (slants) a page item by degrees along one axis, around its own center.", { name: S.string(), angle: S.number(), axis: S.enum(["horizontal", "vertical"]).default("horizontal") },
+  "var it=_needItem(A.name); var rad=A.angle*Math.PI/180; var m=app.getIdentityMatrix(); if(A.axis==='horizontal')m.mValueC=Math.tan(rad); else m.mValueB=Math.tan(rad); it.transform(m, true, true, true, true, 100, Transformation.CENTER); return 'ok';");
+
+/* ====================== GUIDES ====================== */
+jsxTool("convert_item_to_guide", "Converts a path item into a non-printing ruler guide.", { name: S.string() },
+  "var it=_needItem(A.name); it.guides=true; return 'ok';");
+jsxTool("release_guide", "Converts a guide back into a regular, editable path.", { name: S.string() },
+  "var it=_needItem(A.name); it.guides=false; return 'ok';");
+
+/* ====================== SWATCHES / COLOR GROUPS (advanced) ====================== */
+jsxTool("delete_swatch", "Deletes a color swatch from the document.", { name: S.string() },
+  "_needSwatch(A.name).remove(); return 'ok';");
+jsxTool("list_swatch_groups", "Lists the document's swatch groups (color groups) and the swatches in each.", {},
+  "var out=[]; var sgs=_doc().swatchGroups; for(var i=0;i<sgs.length;i++){var g=sgs[i]; var names=[]; var sw=g.getAllSwatches(); for(var j=0;j<sw.length;j++)names.push(sw[j].name); out.push({name:g.name,swatches:names});} return out;");
+jsxTool("create_swatch_group", "Creates a new swatch group (color group) containing the given existing swatches.", { name: S.string(), swatches: S.array(S.string()).min(1) },
+  "var g=_doc().swatchGroups.add(); g.name=A.name; for(var i=0;i<A.swatches.length;i++)g.addSwatch(_needSwatch(A.swatches[i])); return g.name;");
+jsxTool("add_spot_color", "Creates a new spot color from a CMYK/RGB/gray value and registers it in the document's swatches.", { name: S.string(), color: S.object({ r: S.number().optional(), g: S.number().optional(), b: S.number().optional(), c: S.number().optional(), m: S.number().optional(), y: S.number().optional(), k: S.number().optional(), gray: S.number().optional() }) },
+  "var spot=_doc().spots.add(); spot.name=A.name; spot.colorType=ColorModel.SPOT; spot.color=_color(A.color); return spot.name;");
+jsxTool("list_spot_colors", "Lists the document's spot colors.", {},
+  "var out=[]; var sp=_doc().spots; for(var i=0;i<sp.length;i++)if(String(sp[i].colorType)==='ColorModel.SPOT')out.push(sp[i].name); return out;");
+
+/* ====================== STROKE (advanced) ====================== */
+jsxTool("set_stroke_dashes", "Sets a path's dash pattern (lengths in points, e.g. [4,2] for dash-gap-dash-gap). Pass an empty array for a solid line.", { name: S.string(), dashes: S.array(S.number()) },
+  "var it=_needItem(A.name); it.strokeDashes=A.dashes; return 'ok';");
+jsxTool("set_stroke_cap", "Sets a path's stroke end cap style.", { name: S.string(), cap: S.enum(["butt", "round", "projecting"]) },
+  "var map={butt:StrokeCap.BUTTENDCAP,round:StrokeCap.ROUNDENDCAP,projecting:StrokeCap.PROJECTINGENDCAP}; _needItem(A.name).strokeCap=map[A.cap]; return 'ok';");
+jsxTool("set_stroke_join", "Sets a path's stroke corner join style.", { name: S.string(), join: S.enum(["miter", "round", "bevel"]) },
+  "var map={miter:StrokeJoin.MITERENDJOIN,round:StrokeJoin.ROUNDENDJOIN,bevel:StrokeJoin.BEVELENDJOIN}; _needItem(A.name).strokeJoin=map[A.join]; return 'ok';");
+jsxTool("set_stroke_miter_limit", "Sets a path's miter limit (1-500; only affects miter joins).", { name: S.string(), limit: S.number().min(1).max(500) },
+  "_needItem(A.name).strokeMiterLimit=A.limit; return 'ok';");
+
+/* ====================== TEXT (advanced) ====================== */
+jsxTool("find_replace_text", "Finds and replaces a substring across every text frame in the active document. Returns how many frames were changed.", { find: S.string(), replace: S.string() },
+  "var tf=_doc().textFrames; var count=0; for(var i=0;i<tf.length;i++){var s=String(tf[i].contents); if(s.indexOf(A.find)>=0){tf[i].contents=s.split(A.find).join(A.replace); count++;}} return count+' text frame(s) changed';");
+jsxTool("set_text_leading", "Sets a text frame's line leading (spacing), in points. Turns off auto-leading (text defaults to it), since a leading value assigned while auto-leading is on is silently ignored.", { name: S.string(), leading: S.number() },
+  "var attrs=_needItem(A.name).textRange.characterAttributes; attrs.autoLeading=false; attrs.leading=A.leading; return 'ok';");
+jsxTool("list_paragraph_styles", "Lists the document's named paragraph styles.", {},
+  "var out=[]; var ps=_doc().paragraphStyles; for(var i=0;i<ps.length;i++)out.push(ps[i].name); return out;");
+jsxTool("list_character_styles", "Lists the document's named character styles.", {},
+  "var out=[]; var cs=_doc().characterStyles; for(var i=0;i<cs.length;i++)out.push(cs[i].name); return out;");
+jsxTool("apply_paragraph_style", "Applies a named paragraph style to a text frame's full contents.", { name: S.string(), style: S.string() },
+  "var t=_needItem(A.name); _doc().paragraphStyles.getByName(A.style).applyTo(t.textRange, true); return 'ok';");
+jsxTool("apply_character_style", "Applies a named character style to a text frame's full contents.", { name: S.string(), style: S.string() },
+  "var t=_needItem(A.name); _doc().characterStyles.getByName(A.style).applyTo(t.textRange, true); return 'ok';");
+
+/* ====================== LINKS / PLACED ITEMS ====================== */
+jsxTool("list_placed_items", "Lists placed (linked or embedded) raster/vector files in the document.", {},
+  "var out=[]; var pl=_doc().placedItems; for(var i=0;i<pl.length;i++){var p=pl[i]; var f=null; try{f=p.file?p.file.fsName:null;}catch(e){} out.push({name:p.name,file:f});} return out;");
+jsxTool("relink_placed_item", "Repoints a placed item to a different file on disk.", { name: S.string(), path: S.string() },
+  "var it=_needItem(A.name); if(String(it.typename)!=='PlacedItem') throw 'Not a placed item: '+A.name; it.file=new File(A.path); return 'ok';");
+jsxTool("embed_placed_item", "Embeds a linked placed item into the document (no longer references the external file).", { name: S.string() },
+  "var it=_needItem(A.name); if(String(it.typename)!=='PlacedItem') throw 'Not a placed item: '+A.name; it.embed(); return 'ok';");
+
+/* ====================== LAYERS (advanced) ====================== */
+jsxTool("set_layer_color", "Sets a layer's selection/outline color (shown in the Layers panel and as the selection-highlight color for its items), not its artwork.", { name: S.string(), color: S.object({ r: S.number(), g: S.number(), b: S.number() }) },
+  "_need(A.name).color=_color(A.color); return 'ok';");
+jsxTool("duplicate_layer", "Duplicates a layer and everything on it (Layer has no direct duplicate() in Illustrator's DOM, so this creates a new layer and duplicates each item into it). Returns the new layer's name.", { name: S.string(), newName: S.string().optional() },
+  "var L=_need(A.name); var d=_doc().layers.add(); d.name=A.newName||(L.name+' copy'); d.move(L, ElementPlacement.PLACEAFTER); var kids=[]; for(var i=0;i<L.pageItems.length;i++)kids.push(L.pageItems[i]); for(var j=0;j<kids.length;j++)kids[j].duplicate(d, ElementPlacement.PLACEATEND); return d.name;");
+jsxTool("move_layer", "Reorders a layer to the front, back, or relative to another layer.", { name: S.string(), position: S.enum(["front", "back", "before", "after"]), relativeTo: S.string().optional() },
+  "var L=_need(A.name); if(A.position==='front')L.zOrder(ZOrderMethod.BRINGTOFRONT); else if(A.position==='back')L.zOrder(ZOrderMethod.SENDTOBACK); else if(A.position==='before')L.move(_need(A.relativeTo), ElementPlacement.PLACEBEFORE); else if(A.position==='after')L.move(_need(A.relativeTo), ElementPlacement.PLACEAFTER); return 'ok';");
+
+/* ====================== SELECTION (advanced) ====================== */
+jsxTool("select_same_fill_color", "Selects every page item in the document whose fill color matches a reference item's fill color exactly.", { referenceName: S.string() },
+  "function _colorEq(a,b){if(a.type!==b.type)return false; if(a.type==='rgb')return a.r===b.r&&a.g===b.g&&a.b===b.b; if(a.type==='cmyk')return a.c===b.c&&a.m===b.m&&a.y===b.y&&a.k===b.k; if(a.type==='gray')return a.gray===b.gray; if(a.type==='spot')return a.name===b.name; return true;} var ref=_needItem(A.referenceName); if(!ref.filled) throw 'Reference item has no fill: '+A.referenceName; var refOut=_colorOut(ref.fillColor); var items=_doc().pageItems; var sel=[]; for(var i=0;i<items.length;i++){var it=items[i]; try{if(it.filled && _colorEq(_colorOut(it.fillColor),refOut))sel.push(it);}catch(e){}} _doc().selection=sel; return sel.length+' item(s) selected';");
+jsxTool("invert_selection", "Selects every page item that is NOT currently selected, and deselects everything that was.", {},
+  "var cur=_doc().selection; var all=_doc().pageItems; var inv=[]; for(var j=0;j<all.length;j++){var found=false; for(var k=0;k<cur.length;k++)if(cur[k]===all[j]){found=true;break;} if(!found)inv.push(all[j]);} _doc().selection=inv; return inv.length+' item(s) selected';");
+
+/* ====================== DOCUMENT (advanced) ====================== */
+jsxTool("get_ruler_units", "Returns the document's ruler units.", {},
+  "return String(_doc().rulerUnits);");
+jsxTool("set_ruler_units", "Sets the document's ruler units.", { units: S.enum(["points", "inches", "millimeters", "centimeters", "pixels", "picas"]) },
+  "var map={points:RulerUnits.Points,inches:RulerUnits.Inches,millimeters:RulerUnits.Millimeters,centimeters:RulerUnits.Centimeters,pixels:RulerUnits.Pixels,picas:RulerUnits.Picas}; _doc().rulerUnits=map[A.units]; return 'ok';");
+
+/* ====================== PATTERNS ====================== */
+jsxTool("list_patterns", "Lists the document's pattern swatches.", {},
+  "var out=[]; var ps=_doc().patterns; for(var i=0;i<ps.length;i++)out.push(ps[i].name); return out;");
+jsxTool("apply_pattern_fill", "Fills a page item with an existing pattern swatch.", { name: S.string(), pattern: S.string() },
+  "var it=_needItem(A.name); it.filled=true; it.fillColor=_doc().patterns.getByName(A.pattern); return 'ok';");
+
+/* ====================== EFFECTS (Live Effects appearance) ======================
+   pageItem.applyEffect(xml) is Illustrator's real live-effects API, but Adobe
+   never fully documented each effect's XML dict schema -- these 4 use the
+   XML shape that's been reliably reported by the scripting community for
+   many CC versions. Flagged for a live smoke test (not yet done -- the
+   bridge was down while this batch was written) before considering this
+   category done; apply_live_effect_raw is the safety valve if any of the
+   four turn out wrong for this Illustrator version. */
+jsxTool("apply_live_effect_raw", "Escape hatch: applies an arbitrary live effect by its internal name and raw XML parameter dictionary (e.g. name='Adobe Drop Shadow', xml='<LiveEffect name=\"Adobe Drop Shadow\"><Dict>...</Dict></LiveEffect>'). For effects not covered by a dedicated tool.", { name: S.string(), xml: S.string() },
+  "_needItem(A.name).applyEffect(A.xml); return 'ok';");
+jsxTool("apply_drop_shadow_effect", "Applies a live Drop Shadow appearance effect (non-destructive, editable/removable in the Appearance panel). Always black -- the effect's own color/blend-mode parameters rejected every value tried live, so this only exposes what's confirmed working.", { name: S.string(), offsetX: S.number().default(2.117), offsetY: S.number().default(2.117), blur: S.number().default(1.764), opacity: S.number().min(0).max(100).default(75) },
+  "var it=_needItem(A.name); var xml='<LiveEffect name=\"Adobe Drop Shadow\"><Dict data=\"R X '+A.offsetX+' R Y '+A.offsetY+' R B '+A.blur+' R op '+A.opacity+' \"/></LiveEffect>'; it.applyEffect(xml); return 'ok';");
+jsxTool("apply_feather_effect", "Applies a live Feather appearance effect (soft-fades the item's edge).", { name: S.string(), radius: S.number().min(0).default(5) },
+  "var it=_needItem(A.name); var xml='<LiveEffect name=\"Adobe Feather\"><Dict data=\"R fthr '+A.radius+' \"/></LiveEffect>'; it.applyEffect(xml); return 'ok';");
+jsxTool("apply_round_corners_effect", "Applies a live Round Corners appearance effect to a path.", { name: S.string(), radius: S.number().min(0).default(10) },
+  "var it=_needItem(A.name); var xml='<LiveEffect name=\"Adobe Round Corners\"><Dict data=\"R rc_radius '+A.radius+' \"/></LiveEffect>'; it.applyEffect(xml); return 'ok';");
+jsxTool("apply_offset_path_effect", "Applies a live Offset Path appearance effect (grows/shrinks a path's outline).", { name: S.string(), offset: S.number(), joins: S.enum(["miter", "round", "bevel"]).default("miter"), miterLimit: S.number().default(4) },
+  "var it=_needItem(A.name); var jmap={miter:0,round:1,bevel:2}; var xml='<LiveEffect name=\"Adobe Offset Path\"><Dict data=\"R offset '+A.offset+' I lineJoin '+jmap[A.joins]+' R miterLimit '+A.miterLimit+' \"/></LiveEffect>'; it.applyEffect(xml); return 'ok';");
+
+const NAMED_EFFECTS = {
+  innerGlow: "Adobe Inner Glow", outerGlow: "Adobe Outer Glow", scribble: "Adobe Scribble",
+  roughen: "Adobe Roughen", transform: "Adobe Transform", tweak: "Adobe Tweak",
+  zigZag: "Adobe Zig Zag", freeDistort: "Adobe Free Distort", rasterize: "Adobe Rasterize",
+  trimMarks: "Adobe Trim Marks", outlineObject: "Adobe Outline Object",
+  gaussianBlur: "Adobe Gaussian Blur", radialBlur: "Adobe Radial Blur", smartBlur: "Adobe Smart Blur", motionBlur: "Adobe Motion Blur",
+  coloredPencil: "Adobe Colored Pencil", cutout: "Adobe Cutout", dryBrush: "Adobe Dry Brush", filmGrain: "Adobe Film Grain",
+  fresco: "Adobe Fresco", neonGlow: "Adobe Neon Glow", paintDaubs: "Adobe Paint Daubs", paletteKnife: "Adobe Palette Knife",
+  plasticWrap: "Adobe Plastic Wrap", posterEdges: "Adobe Poster Edges", roughPastels: "Adobe Rough Pastels",
+  smudgeStick: "Adobe Smudge Stick", sponge: "Adobe Sponge", underpainting: "Adobe Underpainting", watercolor: "Adobe Watercolor",
+  accentedEdges: "Adobe Accented Edges", angledStrokes: "Adobe Angled Strokes", crosshatch: "Adobe Crosshatch",
+  darkStrokes: "Adobe Dark Strokes", inkOutlines: "Adobe Ink Outlines", spatter: "Adobe Spatter",
+  sprayedStrokes: "Adobe Sprayed Strokes", sumiE: "Adobe Sumi-e",
+  diffuseGlow: "Adobe Diffuse Glow", glass: "Adobe Glass", oceanRipple: "Adobe Ocean Ripple",
+  colorHalftone: "Adobe Color Halftone", crystallize: "Adobe Crystallize", mezzotint: "Adobe Mezzotint", pointillize: "Adobe Pointillize",
+  basRelief: "Adobe Bas Relief", chalkAndCharcoal: "Adobe Chalk &amp; Charcoal", charcoal: "Adobe Charcoal", chrome: "Adobe Chrome",
+  conteCrayon: "Adobe Conte Crayon", graphicPen: "Adobe Graphic Pen", halftonePattern: "Adobe Halftone Pattern",
+  notePaper: "Adobe Note Paper", photocopy: "Adobe Photocopy", plaster: "Adobe Plaster", reticulation: "Adobe Reticulation",
+  stamp: "Adobe Stamp", tornEdges: "Adobe Torn Edges", waterPaper: "Adobe Water Paper", glowingEdges: "Adobe Glowing Edges",
+  craquelure: "Adobe Craquelure", grain: "Adobe Grain", mosaicTiles: "Adobe Mosaic Tiles", patchwork: "Adobe Patchwork",
+  stainedGlass: "Adobe Stained Glass", texturizer: "Adobe Texturizer",
+  warpArc: "Adobe Warp Arc", warpArcLower: "Adobe Warp Arc Lower", warpArcUpper: "Adobe Warp Arc Upper", warpArch: "Adobe Warp Arch",
+  warpBulge: "Adobe Warp Bulge", warpShellLower: "Adobe Warp Shell Lower", warpShellUpper: "Adobe Warp Shell Upper",
+  warpFlag: "Adobe Warp Flag", warpWave: "Adobe Warp Wave", warpFish: "Adobe Warp Fish", warpRise: "Adobe Warp Rise",
+  warpFisheye: "Adobe Warp Fisheye", warpInflate: "Adobe Warp Inflate", warpSqueeze: "Adobe Warp Squeeze", warpTwist: "Adobe Warp Twist",
+  threeDExtrude: "Adobe 3D Extrude", threeDBevel: "Adobe 3D Bevel", threeDRevolve: "Adobe 3D Revolve", threeDRotate: "Adobe 3D Rotate",
+  shapeRectangle: "Adobe Shape Rectangle", shapeRoundedRectangle: "Adobe Shape Rounded Rectangle", shapeEllipse: "Adobe Shape Ellipse",
+};
+server.tool("apply_named_effect",
+  "Applies one of 87 confirmed-working Illustrator live effects by short name, with default parameters (or a raw XML <Dict> override for fine control -- see apply_live_effect_raw for the format). Covers most of Effect > Illustrator Effects and Effect > Photoshop Effects. Non-destructive/editable in the Appearance panel like the 4 dedicated effect tools (drop shadow, feather, round corners, offset path), which take real typed parameters instead and should be preferred when available.",
+  { name: S.string(), effect: S.enum(Object.keys(NAMED_EFFECTS)), dictXml: S.string().optional() },
+  async (a) => {
+    const lic = await checkLicense();
+    if (!lic.valid) return licenseErrorResponse("apply_named_effect");
+    const effectName = NAMED_EFFECTS[a.effect];
+    const dict = a.dictXml || "";
+    const code = HELPERS + "\nvar A=" + JSON.stringify({ name: a.name }) + ";\n" +
+      `_needItem(A.name).applyEffect('<LiveEffect name="${effectName}"><Dict data="${dict}"/></LiveEffect>'); return 'ok';`;
+    return text(await rpc("eval", { code }));
+  });
+
+/* ====================== ACTIONS ====================== */
+jsxTool("play_action", "Plays an existing Illustrator action (from the Actions panel) by name and set name.", { action: S.string(), set: S.string() },
+  "app.doScript(A.action, A.set); return 'ok';");
+
+// Translate tools/list (descriptions) into the server language. Must run
+// AFTER every tool is registered and BEFORE connect(). No-op in English.
+patchMcpServerToolsList(server, i18n);
+
+// ── CLI: --doctor ────────────────────────────────────────────────────────
+const cliArgs = process.argv.slice(2);
+if (cliArgs.includes("--doctor")) {
+  (async () => {
+    const lines = [];
+    const ok = (msg) => lines.push("OK    " + msg);
+    const fail = (msg) => lines.push("FAIL  " + msg);
+    const info = (msg) => lines.push("INFO  " + msg);
+
+    lines.push(i18n.t("msg.doctor.title"));
+    lines.push("");
+
+    const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+    if (nodeMajor >= 18) ok(i18n.t("msg.doctor.nodeOk", { version: process.version }));
+    else fail(i18n.t("msg.doctor.nodeTooOld", { version: process.version }));
+
+    if (!LICENSE_KEY) {
+      fail(i18n.t("msg.doctor.licenseNotSet"));
+    } else {
+      const result = await checkLicense();
+      if (result.valid) ok(i18n.t("msg.doctor.licenseValid", { plan: result.plan || i18n.t("msg.doctor.licensePlanActive") }));
+      else fail(i18n.t("msg.doctor.licenseFailed", { message: result.message || i18n.t("msg.doctor.licenseInvalid") }));
+    }
+
+    info(i18n.t("msg.doctor.bridgeConnecting", { url: WS_URL }));
+    const bridgeUp = await new Promise((resolve) => {
+      let s;
+      try { s = new WebSocket(WS_URL); } catch { resolve(false); return; }
+      const timer = setTimeout(() => { try { s.terminate(); } catch {} resolve(false); }, 3000);
+      s.on("open", () => { clearTimeout(timer); try { s.close(); } catch {} resolve(true); });
+      s.on("error", () => { clearTimeout(timer); resolve(false); });
+    });
+    if (bridgeUp) ok(i18n.t("msg.doctor.bridgeOk"));
+    else fail(i18n.t("msg.doctor.bridgeFail"));
+
+    info(i18n.t("msg.doctor.language", { language: i18n.language, source: i18n.languageSource }));
+
+    lines.push("");
+    lines.push(i18n.t("msg.doctor.support"));
+    process.stdout.write(lines.join("\n") + "\n");
+    process.exit(0);
+  })();
+} else {
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+}