@imenam/mcp-design 1.0.4 → 1.0.5

package/dist/src/core/node-factory.js

@@ -1,14 +1,50 @@
 import { DesignNodeSchema } from "../../shared/schemas/design.schema.js";
-import { GROUP_DERIVED_FIELDS, NODE_DEFAULTS, NODE_GEOMETRY_FIELDS, NODE_STYLE_FIELDS, clampNodeSize, defaultNodeName, } from "../../shared/node-defaults.js";
+import { GROUP_DERIVED_FIELDS, NODE_DEFAULTS, NODE_GEOMETRY_FIELDS, NODE_STYLE_FIELDS, SIZE_DERIVED_KINDS, clampNodeSize, defaultNodeName, } from "../../shared/node-defaults.js";
+import { CORE_ICONS, hasIcon, iconCount } from "../../shared/icons/index.js";
+import { suggestIcons } from "../../shared/icons/search.js";
 import { shortId } from "./ids.js";
 export class DesignError extends Error {
 }
 const GEOMETRY = NODE_GEOMETRY_FIELDS;
 const ALLOWED = NODE_STYLE_FIELDS;
 const DERIVED = GROUP_DERIVED_FIELDS;
+/**
+ * Valide le nom d'icone d'un noeud `icon`.
+ *
+ * Un nom refuse doit repartir avec une piste : sans cela l'agent retombe sur ce
+ * qu'on cherche precisement a eviter — reconstituer l'icone a coups d'ellipses.
+ * Les suggestions passent par les synonymes de la bibliotheque, ce qui rattrape
+ * aussi bien une faute qu'un renommage ("home" -> "house").
+ */
+function requireIconName(value) {
+    const name = typeof value === "string" ? value.trim() : "";
+    if (name === "") {
+        throw new DesignError(`An "icon" node needs an "icon" field naming the icon to draw, e.g. "shopping-cart". ` +
+            `Call search_icons to find one among the ${iconCount()} available, or pick from: ${CORE_ICONS.slice(0, 24).join(", ")}...`);
+    }
+    if (hasIcon(name))
+        return name;
+    const suggestions = suggestIcons(name);
+    throw new DesignError(`Unknown icon "${name}".` +
+        (suggestions.length > 0 ? ` Closest matches: ${suggestions.join(", ")}.` : "") +
+        ` Call search_icons to search the ${iconCount()} available icons by description.`);
+}
 /** Champs geometriques réellement modifiables pour un type donné. */
 function geometryFieldsFor(type) {
-    return type === "group" ? GEOMETRY.filter((field) => !DERIVED.includes(field)) : GEOMETRY;
+    return SIZE_DERIVED_KINDS.includes(type) ? GEOMETRY.filter((field) => !DERIVED.includes(field)) : GEOMETRY;
+}
+/**
+ * Valide le lien d'un noeud `instance` vers son composant. L'existence du
+ * groupe cible, elle, est verifiee par `validateHierarchy` : elle depend de la
+ * planche entiere, pas du seul noeud.
+ */
+function requireComponentId(value) {
+    const componentId = typeof value === "string" ? value.trim() : "";
+    if (componentId === "") {
+        throw new DesignError(`An "instance" node needs a "componentId" field naming the GROUP it mirrors, e.g. { type: "instance", componentId: "g_card" }. ` +
+            `Build the block once with group_nodes, then instantiate it — editing the group then updates every instance at once.`);
+    }
+    return componentId;
 }
 function readParentId(value) {
     if (value === null)
@@ -34,7 +70,7 @@ function requireFiniteNumber(value, field) {
 export function buildNode(input, existingIds, index) {
     const type = input.type;
     if (!type || !(type in NODE_DEFAULTS)) {
-        throw new DesignError(`Unknown node type "${String(input.type)}". Expected one of: rect, ellipse, line, text.`);
+        throw new DesignError(`Unknown node type "${String(input.type)}". Expected one of: ${Object.keys(NODE_DEFAULTS).join(", ")}.`);
     }
     const id = typeof input.id === "string" && input.id.trim() !== "" ? input.id.trim() : shortId("n");
     if (existingIds.has(id))
@@ -58,6 +94,15 @@ export function buildNode(input, existingIds, index) {
         if (input[field] !== undefined)
             draft[field] = input[field];
     }
+    if (type === "instance")
+        draft.componentId = requireComponentId(draft.componentId);
+    if (type === "icon") {
+        draft.icon = requireIconName(draft.icon);
+        // Un calque nomme "Icône 7" ne dit rien au relecteur ; le nom de l'icone,
+        // lui, porte deja le sens. C'est le nom par defaut le plus utile.
+        if (!(typeof input.name === "string" && input.name.trim() !== ""))
+            draft.name = String(draft.icon);
+    }
     const size = clampNodeSize(type, Number(draft.width), Number(draft.height));
     draft.width = size.width;
     draft.height = size.height;
@@ -86,11 +131,16 @@ export function applyPatch(node, patch) {
         if (patch[field] !== undefined)
             next[field] = patch[field];
     }
+    if (node.type === "icon" && patch.icon !== undefined)
+        next.icon = requireIconName(patch.icon);
+    // Changer le lien echange l'instance de composant, comme un "swap instance".
+    if (node.type === "instance" && patch.componentId !== undefined)
+        next.componentId = requireComponentId(patch.componentId);
     const editable = ["name", "parentId", ...geometryFieldsFor(node.type), ...ALLOWED[node.type]];
     const unknownFields = Object.keys(patch).filter((key) => key !== "id" && !editable.includes(key));
     if (unknownFields.length > 0) {
-        const derived = unknownFields.filter((key) => node.type === "group" && DERIVED.includes(key));
-        const reason = derived.length > 0 ? ` The size of a group is derived from its content and cannot be set.` : "";
+        const derived = unknownFields.filter((key) => SIZE_DERIVED_KINDS.includes(node.type) && DERIVED.includes(key));
+        const reason = derived.length > 0 ? ` The size of a ${node.type} is derived from its content and cannot be set.` : "";
         throw new DesignError(`Field(s) [${unknownFields.join(", ")}] cannot be set on a "${node.type}" node.${reason} ` +
             `Allowed: ${editable.join(", ")}.`);
     }

package/dist/src/core/screenshot.d.ts

@@ -28,4 +28,16 @@ export interface Screenshot {
     sourceHeight: number;
     scale: number;
 }
+/**
+ * Rasterisation d'un SVG quelconque, avec la police de secours du systeme.
+ *
+ * Partagee par la capture d'un design et par la planche de vignettes de
+ * `search_icons` : une seule configuration de resvg, donc un seul endroit ou le
+ * rendu du texte peut diverger.
+ */
+export declare function rasterize(svg: string, scale: number): {
+    png: Buffer;
+    width: number;
+    height: number;
+};
 export declare function screenshotDesign(design: Design, options?: ScreenshotOptions): Screenshot;

package/dist/src/core/screenshot.js

@@ -25,6 +25,21 @@ function svgSize(svg) {
     const height = Number(/\bheight="([\d.]+)"/.exec(svg)?.[1] ?? 0);
     return { width, height };
 }
+/**
+ * Rasterisation d'un SVG quelconque, avec la police de secours du systeme.
+ *
+ * Partagee par la capture d'un design et par la planche de vignettes de
+ * `search_icons` : une seule configuration de resvg, donc un seul endroit ou le
+ * rendu du texte peut diverger.
+ */
+export function rasterize(svg, scale) {
+    const resvg = new Resvg(svg, {
+        fitTo: { mode: "zoom", value: scale },
+        font: { loadSystemFonts: true, defaultFontFamily: "Segoe UI", sansSerifFamily: "Segoe UI" },
+    });
+    const rendered = resvg.render();
+    return { png: Buffer.from(rendered.asPng()), width: rendered.width, height: rendered.height };
+}
 export function screenshotDesign(design, options = {}) {
     const doc = toDocument(design);
     const padding = Math.max(0, options.padding ?? 0);
@@ -37,13 +52,9 @@ export function screenshotDesign(design, options = {}) {
     const requested = Math.max(0.05, Math.min(8, options.scale ?? 1));
     // L'écrêtage ne peut que réduire : un zoom demandé plus petit reste respecté.
     const scale = Math.min(requested, maxDimension / Math.max(source.width, source.height));
-    const resvg = new Resvg(svg, {
-        fitTo: { mode: "zoom", value: scale },
-        font: { loadSystemFonts: true, defaultFontFamily: "Segoe UI", sansSerifFamily: "Segoe UI" },
-    });
-    const rendered = resvg.render();
+    const rendered = rasterize(svg, scale);
     return {
-        png: Buffer.from(rendered.asPng()),
+        png: rendered.png,
         width: rendered.width,
         height: rendered.height,
         sourceWidth: source.width,

package/dist/src/index.js

@@ -13,6 +13,7 @@ import { DesignStore } from "./core/design-store.js";
 import { NODE_DEFAULTS } from "./core/node-factory.js";
 import { EXPORT_FORMATS } from "./core/export.js";
 import { MIN_LINE_HEIGHT_PX } from "../shared/render.js";
+import { CORE_ICONS, iconCount } from "../shared/icons/index.js";
 import { NODE_FIELD_DOCS } from "../shared/node-fields.js";
 import { REORDER_DIRECTIONS } from "../shared/tree.js";
 import { normalizeDesignGroup } from "../shared/schemas/design.schema.js";
@@ -28,11 +29,13 @@ import { duplicateNodes, MAX_DUPLICATE_COPIES } from "./tools/duplicate-nodes.js
 import { groupNodes } from "./tools/group-nodes.js";
 import { groupDesigns } from "./tools/group-designs.js";
 import { ungroupNodes } from "./tools/ungroup-nodes.js";
+import { detachInstances } from "./tools/detach-instances.js";
 import { getChanges } from "./tools/get-changes.js";
 import { markSynced } from "./tools/mark-synced.js";
 import { exportDesignTool } from "./tools/export-design.js";
 import { screenshotDesignTool } from "./tools/screenshot-design.js";
 import { reorderNodesTool } from "./tools/reorder-nodes.js";
+import { searchIconsTool, DEFAULT_ICON_RESULTS, MAX_ICON_RESULTS } from "./tools/search-icons.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // Les flags CLI sont traités avant toute initialisation : ils s'exécutent dans le
@@ -319,8 +322,22 @@ const NODE_FIELDS_DOC = "Every length is in PIXELS (x, y, width, height, strokeW
     "height are derived from its content and cannot be set. " +
     "Fields accepted per type — rect: fill, stroke, strokeWidth, radius; ellipse: fill, stroke, strokeWidth; " +
     "line: stroke, strokeWidth (the line goes from (x, y) to (x + width, y + height)); " +
-    "text: text, color, fontSize, fontFamily, fontWeight, fontStyle, textAlign, lineHeight. " +
+    "text: text, color, fontSize, fontFamily, fontWeight, fontStyle, textAlign, lineHeight; " +
+    "icon: icon (required — the name of the drawing), fill, stroke, strokeWidth; " +
+    "instance: componentId (required — the id of the group it mirrors); nothing else, its look comes from that group. " +
     "Any field left out falls back to a sensible default, so a node can be created from its type alone.";
+/**
+ * Consigne sur les icones, repetee partout ou un noeud se cree.
+ *
+ * Sans elle, un agent qui n'a que des formes a sa disposition approxime une
+ * icone avec trois ellipses et deux traits : le rendu est mediocre, et la
+ * maquette relue plus tard ne dit plus ce que ce tas de formes representait.
+ */
+const ICON_DOC = `DRAW ICONS WITH AN "icon" NODE, NEVER OUT OF SHAPES. ${iconCount()} icons (Lucide) are built in: give the icon's name in the "icon" field ` +
+    `and the drawing is resolved at render time — sharp at any size, restyled with a single field, and still readable to whoever opens the design later. ` +
+    `Assembling a cart, a bell or a chevron out of rects, ellipses and lines is the failure mode to avoid. ` +
+    `Common names, enough for most interfaces: ${CORE_ICONS.join(", ")}. ` +
+    `For anything else, call search_icons with a description — it also matches synonyms.`;
 /**
  * Propriétés d'un noeud exposées à l'agent. Les descriptions viennent de
  * shared/node-fields.ts, partagées avec le schéma zod : l'unité d'un champ n'est
@@ -340,6 +357,8 @@ const NODE_PROPERTIES = {
     stroke: { type: "string", description: NODE_FIELD_DOCS.stroke },
     strokeWidth: { type: "number", minimum: 0, description: NODE_FIELD_DOCS.strokeWidth },
     radius: { type: "number", minimum: 0, description: NODE_FIELD_DOCS.radius },
+    icon: { type: "string", description: NODE_FIELD_DOCS.icon },
+    componentId: { type: "string", description: NODE_FIELD_DOCS.componentId },
     text: { type: "string", description: NODE_FIELD_DOCS.text },
     color: { type: "string", description: NODE_FIELD_DOCS.color },
     fontSize: { type: "number", exclusiveMinimum: 0, description: NODE_FIELD_DOCS.fontSize },
@@ -362,6 +381,18 @@ const HIERARCHY_DOC = "STRUCTURE THE ARTBOARD AS A TREE OF NESTED GROUPS, NOT AS
     "Build the hierarchy as you go: create a \"group\" node and, in the SAME add_nodes call, give its children that group's id as parentId — a child's x/y are then " +
     "read from the group's origin, so the whole block moves as one. Name each group after what it is (\"Header\", \"Card / Pricing\", \"Nav item\"), never \"Groupe 1\": " +
     "those names are what the user reads in the layer panel and what an export turns into component names.";
+/**
+ * Consigne sur les groupes reutilisables, repetee partout ou une repetition se
+ * cree. Sans elle, l'agent recopie le meme bloc N fois : le fichier gonfle, et
+ * la moindre retouche doit etre refaite autant de fois.
+ */
+const INSTANCE_DOC = "REPEAT A BLOCK WITH INSTANCES, NOT WITH COPIES. When the same block appears more than once (cards, list rows, " +
+    "menu items, buttons), build it ONCE as a group, then add nodes of type \"instance\" pointing at that group with " +
+    "componentId. An instance stores no content of its own: editing the group updates every instance at once, and the " +
+    "repeated block stays a single thing to read and to change — the way a main component works in Figma. " +
+    "Nothing can be overridden inside an instance (that is what keeps them in sync): when one copy must differ, either " +
+    "make it a second group, or call detach_instances on it. Instances can be nested (a card instance holding a button " +
+    "instance), but a component can never contain itself.";
 const DESIGN_ID_DOC = "Id of the design, as returned by list_designs or create_design.";
 const GROUP_PATH_DOC = "Page group this design belongs to, as a path like \"Marketing\" or \"Marketing/Landing\" (the \"/\" nests sub-groups). Pages sharing a path are folded together in the sidebar, which is how a project with many pages stays readable. Omit or pass null to leave the page at the root.";
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -429,7 +460,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: `Add one or more nodes on top of the design. Node types: ${Object.keys(NODE_DEFAULTS).join(", ")}. ` +
                 NODE_FIELDS_DOC +
                 " Nodes are drawn in array order, so the last one added sits on top. " +
-                HIERARCHY_DOC,
+                HIERARCHY_DOC +
+                " " +
+                ICON_DOC +
+                " " +
+                INSTANCE_DOC,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -440,7 +475,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         items: {
                             type: "object",
                             properties: {
-                                type: { type: "string", enum: ["rect", "ellipse", "line", "text", "group"], description: NODE_FIELD_DOCS.type },
+                                type: {
+                                    type: "string",
+                                    enum: ["rect", "ellipse", "line", "text", "icon", "group", "instance"],
+                                    description: NODE_FIELD_DOCS.type,
+                                },
                                 ...NODE_PROPERTIES,
                             },
                             required: ["type"],
@@ -456,6 +495,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: "Patch existing nodes. Each entry needs an id plus only the fields to change; everything else is preserved. " +
                 "Changing parentId is how an existing element is moved into (or out of) a group, which is the way to deepen a structure that came out too flat. " +
                 NODE_FIELDS_DOC +
+                " On an instance, only name, position, rotation, opacity, parentId and componentId apply — patch the nodes of its " +
+                "component to change how every instance looks. " +
                 " The whole batch is validated before anything is written, so an invalid entry changes nothing.",
             inputSchema: {
                 type: "object",
@@ -480,7 +521,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "delete_nodes",
-            description: "Remove nodes from a design by id. Deleting a group also deletes everything inside it.",
+            description: "Remove nodes from a design by id. Deleting a group also deletes everything inside it. " +
+                "A group still mirrored by instances cannot be deleted — delete those instances too, or detach them first.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -493,7 +535,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         {
             name: "duplicate_nodes",
             description: "Copy elements or whole groups. A group is copied with everything inside it, and every copy gets fresh ids. " +
-                "This is the tool for repeated structures — a card, a list row, a section — build one carefully, then copy it and patch only what differs. " +
+                "Use it for a one-off copy that is MEANT TO DIVERGE. For a block repeated identically, do not copy it: " +
+                "instantiate it instead (add_nodes with type \"instance\"), so a single edit updates every occurrence. " +
                 "Copies land next to the originals by default; use offset_x/offset_y to place them, count to lay out a series, and parent_id to drop them into another group.",
             inputSchema: {
                 type: "object",
@@ -520,7 +563,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             name: "group_nodes",
             description: "Wrap existing nodes into a new group, so they can be moved, hidden or reordered together. The nodes must currently share the same parent, and nothing moves on screen: their coordinates are rebased onto the new group. " +
                 "Call it repeatedly to build depth: group the nodes of one card, then group the cards into a row, then the row with its heading into a section. " +
-                HIERARCHY_DOC,
+                "A group is also what an instance mirrors: group a block once, then repeat it with instances. " +
+                HIERARCHY_DOC +
+                " " +
+                INSTANCE_DOC,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -534,7 +580,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "ungroup_nodes",
-            description: "Dissolve groups: their content moves up one level, keeping its position on screen. The groups themselves are removed.",
+            description: "Dissolve groups: their content moves up one level, keeping its position on screen. The groups themselves are removed. " +
+                "A group still mirrored by instances cannot be dissolved — detach those instances first.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -544,6 +591,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["design_id", "group_ids"],
             },
         },
+        {
+            name: "detach_instances",
+            description: "Break the link between instances and their component: the content becomes ordinary nodes, editable one by one, " +
+                "and stops following the component. This is the way out when a single copy must differ — nothing can be overridden " +
+                "inside an instance. Each node keeps its id, name and position; it simply becomes a group. An instance nested " +
+                "inside the component stays an instance.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    design_id: { type: "string", description: DESIGN_ID_DOC },
+                    node_ids: { type: "array", items: { type: "string" }, description: "Ids of the instances to detach.", minItems: 1 },
+                },
+                required: ["design_id", "node_ids"],
+            },
+        },
         {
             name: "reorder_nodes",
             description: "Change the stacking order of nodes — which one is drawn on top of which. This is the layer panel, agent side. " +
@@ -654,6 +716,27 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["design_id"],
             },
         },
+        {
+            name: "search_icons",
+            description: `Find an icon by description among the ${iconCount()} built into the canvas (Lucide), and get its name for the "icon" field of an "icon" node. ` +
+                `Search in English, one concept at a time ("cart", "warning", "user profile"); synonyms are matched too, so "basket" finds "shopping-cart". ` +
+                `The common icons are already listed in add_nodes — call this tool for anything they do not cover, not before every icon.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: 'What the icon should depict, e.g. "shopping cart", "download", "alert".' },
+                    limit: {
+                        type: "number",
+                        description: `How many results to return (default ${DEFAULT_ICON_RESULTS}, max ${MAX_ICON_RESULTS}).`,
+                    },
+                    preview: {
+                        type: "boolean",
+                        description: "Return a thumbnail sheet of the results alongside their names (default true). Set false to save context.",
+                    },
+                },
+                required: ["query"],
+            },
+        },
         {
             name: "reconnect_gui",
             description: "Relaunch the GUI worker and re-register it with the proxy. Use it when the canvas is unreachable, or after starting the proxy server.",
@@ -718,6 +801,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 notifyDesignChanged(result.design.id);
                 return result;
             }
+            case "detach_instances": {
+                const result = detachInstances(store, params);
+                notifyDesignChanged(result.design.id);
+                return result;
+            }
             case "reorder_nodes": {
                 const result = reorderNodesTool(store, params);
                 notifyDesignChanged(result.design.id);
@@ -739,6 +827,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return exportDesignTool(store, params);
             case "screenshot_design":
                 return screenshotDesignTool(store, params);
+            case "search_icons":
+                return searchIconsTool(params);
             case "reconnect_gui":
                 return await reconnectGui(params);
             default:

package/dist/src/tools/add-nodes.js

@@ -18,7 +18,13 @@ export function addNodes(store, args) {
     const design = store.mutate(id, "agent", (draft) => {
         draft.nodes.push(...created);
     });
-    const lines = created.map((n) => `- ${n.id} — "${n.name}" (${n.type}) at ${Math.round(n.x)},${Math.round(n.y)} size ${Math.round(n.width)}x${Math.round(n.height)}`);
+    // Les tailles sont relues APRES l'écriture : celle d'un groupe — ou d'une
+    // instance — est déduite de son contenu, donc inconnue avant la mutation.
+    const byId = new Map(design.nodes.map((n) => [n.id, n]));
+    const lines = created.map((node) => {
+        const n = byId.get(node.id) ?? node;
+        return `- ${n.id} — "${n.name}" (${n.type}) at ${Math.round(n.x)},${Math.round(n.y)} size ${Math.round(n.width)}x${Math.round(n.height)}`;
+    });
     return {
         ...textResult([`Added ${created.length} node(s) to "${design.name}":`, ...lines].join("\n")),
         design,

package/dist/src/tools/delete-nodes.js

@@ -1,5 +1,5 @@
 import { DesignError } from "../core/node-factory.js";
-import { withDescendants } from "../core/hierarchy.js";
+import { survivingInstancesOf, withDescendants } from "../core/hierarchy.js";
 import { requireString, textResult } from "./types.js";
 export function deleteNodes(store, args) {
     const id = requireString(args, "design_id");
@@ -17,6 +17,15 @@ export function deleteNodes(store, args) {
     // des noeuds orphelins pointant vers un parent disparu.
     const toRemove = withDescendants(current.nodes, nodeIds.map((nodeId) => String(nodeId)));
     const nested = toRemove.size - nodeIds.length;
+    // Un composant encore instancie ne peut pas disparaitre : ses instances
+    // n'auraient plus rien a reproduire.
+    const orphaned = survivingInstancesOf(current.nodes, toRemove);
+    if (orphaned.length > 0) {
+        const groups = [...new Set(orphaned.map((instance) => instance.componentId))];
+        throw new DesignError(`Group(s) ${groups.join(", ")} are still mirrored by ${orphaned.length} instance(s) (${orphaned
+            .map((instance) => instance.id)
+            .join(", ")}). Delete those instances too, or run detach_instances on them first.`);
+    }
     const design = store.mutate(id, "agent", (draft) => {
         draft.nodes = draft.nodes.filter((n) => !toRemove.has(n.id));
     });

package/dist/src/tools/detach-instances.d.ts

@@ -0,0 +1,14 @@
+import type { DesignStore } from "../core/design-store.js";
+import type { MutationResult } from "./add-nodes.js";
+/**
+ * Rompt le lien d'une instance avec son composant : le contenu devient des
+ * noeuds ordinaires, editables un par un, et cesse de suivre le composant.
+ *
+ * C'est la soupape du modele : rien ne se surcharge dans une instance, donc une
+ * copie qui doit diverger se detache. Le noeud garde son id, son nom et sa
+ * position — il devient simplement un groupe, a la meme place dans la pile.
+ *
+ * Une instance imbriquee dans le composant reste, elle, une instance : detacher
+ * une carte ne detache pas les boutons qu'elle contient.
+ */
+export declare function detachInstances(store: DesignStore, args: Record<string, unknown> | undefined): MutationResult;

package/dist/src/tools/detach-instances.js

@@ -0,0 +1,61 @@
+import { childrenByParent } from "../../shared/tree.js";
+import { cloneSubtrees } from "../core/clone.js";
+import { DesignError } from "../core/node-factory.js";
+import { requireString, textResult } from "./types.js";
+/**
+ * Rompt le lien d'une instance avec son composant : le contenu devient des
+ * noeuds ordinaires, editables un par un, et cesse de suivre le composant.
+ *
+ * C'est la soupape du modele : rien ne se surcharge dans une instance, donc une
+ * copie qui doit diverger se detache. Le noeud garde son id, son nom et sa
+ * position — il devient simplement un groupe, a la meme place dans la pile.
+ *
+ * Une instance imbriquee dans le composant reste, elle, une instance : detacher
+ * une carte ne detache pas les boutons qu'elle contient.
+ */
+export function detachInstances(store, args) {
+    const id = requireString(args, "design_id");
+    const nodeIds = args?.node_ids;
+    if (!Array.isArray(nodeIds) || nodeIds.length === 0) {
+        throw new Error(`"node_ids" is required and must be a non-empty array of instance ids.`);
+    }
+    const current = store.get(id);
+    const byId = new Map(current.nodes.map((node) => [node.id, node]));
+    const instances = nodeIds.map((raw) => {
+        const node = byId.get(String(raw));
+        if (!node)
+            throw new DesignError(`Node "${String(raw)}" not found in design "${id}".`);
+        if (node.type !== "instance") {
+            throw new DesignError(`Node "${node.id}" is a "${node.type}", not an instance — nothing to detach.`);
+        }
+        return node;
+    });
+    const children = childrenByParent(current.nodes);
+    let materialized = 0;
+    const design = store.mutate(id, "agent", (draft) => {
+        const result = [];
+        for (const node of draft.nodes) {
+            const instance = instances.find((candidate) => candidate.id === node.id);
+            if (!instance) {
+                result.push(node);
+                continue;
+            }
+            // L'instance prend la place du groupe qu'elle reproduisait, au meme rang
+            // dans la pile ; le contenu du composant est copie juste derriere.
+            result.push({ ...node, type: "group", componentId: undefined });
+            const sourceChildren = (children.get(instance.componentId ?? "") ?? []).map((child) => child.id);
+            const clone = cloneSubtrees(current.nodes, sourceChildren);
+            const rootSet = new Set(clone.rootIds);
+            for (const copy of clone.copies) {
+                result.push(rootSet.has(copy.id) ? { ...copy, parentId: node.id } : copy);
+            }
+            materialized += clone.copies.length;
+        }
+        draft.nodes = result;
+    });
+    return {
+        ...textResult(`Detached ${instances.length} instance(s) in "${design.name}": ${materialized} node(s) are now ordinary nodes ` +
+            `and no longer follow their component.`),
+        design,
+    };
+}

package/dist/src/tools/duplicate-nodes.js

@@ -1,6 +1,6 @@
-import { descendantIds, withoutRedundantDescendants } from "../../shared/tree.js";
+import { withoutRedundantDescendants } from "../../shared/tree.js";
+import { cloneSubtrees } from "../core/clone.js";
 import { DesignError } from "../core/node-factory.js";
-import { shortId } from "../core/ids.js";
 import { requireString, textResult } from "./types.js";
 /** Décalage par défaut d'une copie, en pixels : assez pour la voir, assez peu pour la retrouver. */
 const DEFAULT_OFFSET = 20;
@@ -56,36 +56,28 @@ export function duplicateNodes(store, args) {
             parentId = parent.id;
         }
     }
-    // Le sous-arbre complet de chaque racine, dans l'ordre du document : l'ordre
-    // d'empilement relatif des copies reste celui des originaux.
-    const included = new Set(roots);
-    for (const rootId of roots)
-        for (const descendant of descendantIds(current.nodes, rootId))
-            included.add(descendant);
-    const source = current.nodes.filter((node) => included.has(node.id));
     const copies = [];
     const createdRootIds = [];
     for (let copyIndex = 1; copyIndex <= count; copyIndex++) {
-        const idMap = new Map(source.map((node) => [node.id, shortId(node.type === "group" ? "g" : "n")]));
-        for (const node of source) {
-            const isRoot = roots.includes(node.id);
-            const copy = {
-                ...structuredClone(node),
-                id: idMap.get(node.id),
-                // Seules les racines sont décalées et reparentées : les descendants sont
-                // exprimés dans l'espace de leur parent et suivent donc tout seuls.
-                parentId: isRoot
-                    ? parentId === undefined
-                        ? node.parentId
-                        : parentId
-                    : (idMap.get(node.parentId ?? "") ?? node.parentId),
-                x: node.x + (isRoot ? offsetX * copyIndex : 0),
-                y: node.y + (isRoot ? offsetY * copyIndex : 0),
-            };
-            copies.push(copy);
-            if (isRoot)
-                createdRootIds.push(copy.id);
+        // Un sous-arbre complet par copie : les ids sont neufs et les liens
+        // parent/enfant recables (cf. src/core/clone.ts).
+        const clone = cloneSubtrees(current.nodes, roots);
+        const rootSet = new Set(clone.rootIds);
+        for (const copy of clone.copies) {
+            // Seules les racines sont decalees et reparentees : les descendants sont
+            // exprimes dans l'espace de leur parent et suivent donc tout seuls.
+            if (!rootSet.has(copy.id)) {
+                copies.push(copy);
+                continue;
+            }
+            copies.push({
+                ...copy,
+                parentId: parentId === undefined ? copy.parentId : parentId,
+                x: copy.x + offsetX * copyIndex,
+                y: copy.y + offsetY * copyIndex,
+            });
         }
+        createdRootIds.push(...clone.rootIds);
     }
     const design = store.mutate(id, "agent", (draft) => {
         draft.nodes.push(...copies);

package/dist/src/tools/search-icons.d.ts

@@ -0,0 +1,12 @@
+import { type ImageToolResult } from "./types.js";
+/** Au-dela, la planche coute plus de contexte qu'elle n'aide a choisir. */
+export declare const MAX_ICON_RESULTS = 48;
+export declare const DEFAULT_ICON_RESULTS = 24;
+/**
+ * Recherche d'une icone par description.
+ *
+ * C'est la traine longue de la bibliotheque : les icones les plus courantes
+ * sont deja listees dans la description de `add_nodes`, donc un agent qui
+ * habille une interface ordinaire n'a pas besoin de passer par ici.
+ */
+export declare function searchIconsTool(args: Record<string, unknown> | undefined): ImageToolResult;