@imenam/mcp-design 1.0.3 → 1.0.5

package/dist/shared/render.js

@@ -7,6 +7,8 @@
  * importable depuis le bundle GUI.
  */
 import { boundsOf, childrenByParent, computeLayout, normalizedBox, spaceOriginOf } from "./tree.js";
+import { expandInstances } from "./instances.js";
+import { DEFAULT_ICON_STROKE_WIDTH, ICON_GRID, UNKNOWN_ICON_ELEMENTS, iconElements, } from "./icons/index.js";
 // La géométrie de base vit dans tree.ts (module bas-niveau, sans dépendance vers
 // celui-ci) ; elle reste exposée ici pour tous les appelants existants.
 export { normalizedBox };
@@ -64,11 +66,25 @@ export function textMetrics(node) {
     // multiplicateur : c'est l'unité que l'agent emploie spontanément, et la
     // seule qui se lise directement dans la même échelle que x, y et fontSize.
     const lineStep = node.lineHeight ?? defaultLineHeight(fontSize);
+    const blockHeight = Math.max(1, textLines(node).length) * lineStep;
+    /**
+     * Décalage du bloc de lignes pour le centrer dans la boîte.
+     *
+     * Sans lui, la position verticale du texte dépendrait de l'interligne et non
+     * de la boîte : un lineHeight de 32 sur une ligne de 11px dans une boîte de
+     * 16px poussait la ligne de base à 20px du haut, donc le texte entier sous sa
+     * propre boîte. L'interligne n'espace que les lignes entre elles ; c'est la
+     * boîte qui dit où le texte se pose.
+     */
+    const blockOffset = (Math.abs(node.height) - blockHeight) / 2;
     return {
         fontSize,
         lineStep,
+        /** Hauteur occupée par les lignes, interligne compris. */
+        blockHeight,
+        blockOffset,
         /** Ligne de base de la première ligne, mesurée depuis le haut de la boîte. */
-        firstBaseline: lineStep * 0.5 + fontSize * 0.36,
+        firstBaseline: blockOffset + lineStep * 0.5 + fontSize * 0.36,
         anchor: node.textAlign === "center" ? "middle" : node.textAlign === "right" ? "end" : "start",
         anchorX: node.textAlign === "center"
             ? node.x + node.width / 2
@@ -102,13 +118,58 @@ export function groupTransform(node, localCenter) {
         parts.push(`rotate(${round(node.rotation)} ${round(localCenter.cx)} ${round(localCenter.cy)})`);
     return parts.join(" ");
 }
+/**
+ * Placement du trace d'une icone dans sa boite.
+ *
+ * L'icone est dessinee dans une grille carree : elle est mise a l'echelle
+ * uniformement pour tenir dans la boite, puis centree. Jamais deformee — une
+ * icone etiree se lit immediatement comme un defaut, alors qu'une icone centree
+ * dans une boite trop large reste correcte.
+ */
+export function iconPlacement(node) {
+    const box = normalizedBox(node);
+    const scale = Math.min(box.width, box.height) / ICON_GRID;
+    const size = ICON_GRID * scale;
+    return { x: box.x + (box.width - size) / 2, y: box.y + (box.height - size) / 2, scale, size };
+}
+/** Trace du noeud, ou le carre en pointilles si le nom d'icone est inconnu. */
+export function iconElementsOf(node) {
+    return iconElements(node.icon ?? "") ?? UNKNOWN_ICON_ELEMENTS;
+}
+/**
+ * Attributs de trait d'une icone, exprimes dans la grille de 24.
+ *
+ * `color` fait resoudre les rares `fill="currentColor"` de la bibliotheque vers
+ * la couleur du trait : sans lui, le point d'un graphique en nuage ressortirait
+ * en noir sur une icone blanche.
+ */
+export function iconStyle(node) {
+    return {
+        fill: node.fill ?? "none",
+        stroke: node.stroke ?? "#000000",
+        color: node.stroke ?? "#000000",
+        "stroke-width": String(round(node.strokeWidth ?? DEFAULT_ICON_STROKE_WIDTH)),
+        "stroke-linecap": "round",
+        "stroke-linejoin": "round",
+    };
+}
+function attributesToSvg(attributes) {
+    return Object.entries(attributes)
+        .map(([key, value]) => `${key}="${escapeXml(value)}"`)
+        .join(" ");
+}
+export function iconElementToSvg([tag, attributes]) {
+    return `<${tag} ${attributesToSvg(attributes)} />`;
+}
 /**
  * Markup SVG d'un seul noeud, sans wrapper — utilisé par l'export et par le canvas.
  * Un groupe ne produit rien par lui-meme : c'est un conteneur, rendu par
  * `documentToSvg` (serveur) ou par le canvas (navigateur).
  */
 export function nodeToSvg(node) {
-    if (node.type === "group")
+    // Un groupe est un conteneur ; une instance n'atteint jamais le rendu, elle
+    // est remplacee par un groupe en amont par `expandInstances`.
+    if (node.type === "group" || node.type === "instance")
         return "";
     const transform = rotationTransform(node);
     const transformAttr = transform ? ` transform="${transform}"` : "";
@@ -130,6 +191,14 @@ export function nodeToSvg(node) {
             return (`<line x1="${round(node.x)}" y1="${round(node.y)}" x2="${round(node.x + node.width)}" y2="${round(node.y + node.height)}"` +
                 ` ${shapeAttributes(node)} stroke-linecap="round"${opacityAttr}${transformAttr} />`);
         }
+        case "icon": {
+            // La rotation s'exprime dans l'espace du parent, donc AVANT le placement
+            // du trace : elle fait tourner l'icone posee, pas la grille de 24.
+            const place = iconPlacement(node);
+            const placement = `${transform ? `${transform} ` : ""}translate(${round(place.x)} ${round(place.y)}) scale(${round(place.scale)})`;
+            const body = iconElementsOf(node).map(iconElementToSvg).join("");
+            return `<g transform="${placement}" ${attributesToSvg(iconStyle(node))}${opacityAttr}>${body}</g>`;
+        }
         case "text": {
             const m = textMetrics(node);
             const lines = textLines(node);
@@ -165,8 +234,11 @@ function renderSiblings(nodes, children, layout, depth) {
     });
 }
 export function documentToSvg(doc) {
-    const layout = computeLayout(doc.nodes);
-    const children = childrenByParent(doc.nodes);
+    // Les instances sont resolues ici, une fois pour toutes : en dessous, il n'y
+    // a plus que des groupes ordinaires.
+    const nodes = expandInstances(doc.nodes);
+    const layout = computeLayout(nodes);
+    const children = childrenByParent(nodes);
     // Un groupe devient un <g> : ses enfants gardent leurs coordonnées locales,
     // c'est la transformation du conteneur qui les place.
     const body = renderSiblings(children.get(null) ?? [], children, layout, 0).join("\n");
@@ -184,11 +256,12 @@ export function documentToSvg(doc) {
  * que `computeLayout`, donc directement sur la boîte englobante de l'élément.
  */
 export function subtreeToSvg(doc, nodeId, padding = 0) {
-    const node = doc.nodes.find((candidate) => candidate.id === nodeId);
+    const nodes = expandInstances(doc.nodes);
+    const node = nodes.find((candidate) => candidate.id === nodeId);
     if (!node)
         throw new Error(`Node "${nodeId}" not found in design "${doc.name}".`);
-    const layout = computeLayout(doc.nodes);
-    const children = childrenByParent(doc.nodes);
+    const layout = computeLayout(nodes);
+    const children = childrenByParent(nodes);
     const bounds = boundsOf(layout, nodeId);
     const region = {
         x: bounds.x - padding,

package/dist/shared/schemas/design.schema.d.ts

@@ -14,10 +14,12 @@ import { z } from "zod";
  * stockage reste plat, donc diffable et lisible, tandis que les coordonnees
  * d'un noeud sont exprimees dans l'espace de son parent.
  */
-export declare const NODE_TYPES: readonly ["rect", "ellipse", "line", "text", "group"];
+export declare const NODE_TYPES: readonly ["rect", "ellipse", "line", "text", "icon", "group", "instance"];
 export declare const NodeTypeSchema: z.ZodEnum<{
     ellipse: "ellipse";
     group: "group";
+    icon: "icon";
+    instance: "instance";
     line: "line";
     rect: "rect";
     text: "text";
@@ -39,12 +41,15 @@ export declare const DesignNodeSchema: z.ZodObject<{
     type: z.ZodEnum<{
         ellipse: "ellipse";
         group: "group";
+        icon: "icon";
+        instance: "instance";
         line: "line";
         rect: "rect";
         text: "text";
     }>;
     name: z.ZodString;
     parentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    componentId: z.ZodOptional<z.ZodString>;
     x: z.ZodNumber;
     y: z.ZodNumber;
     width: z.ZodNumber;
@@ -55,6 +60,7 @@ export declare const DesignNodeSchema: z.ZodObject<{
     stroke: z.ZodOptional<z.ZodString>;
     strokeWidth: z.ZodOptional<z.ZodNumber>;
     radius: z.ZodOptional<z.ZodNumber>;
+    icon: z.ZodOptional<z.ZodString>;
     text: z.ZodOptional<z.ZodString>;
     color: z.ZodOptional<z.ZodString>;
     fontSize: z.ZodOptional<z.ZodNumber>;
@@ -81,12 +87,15 @@ export declare const BaselineSchema: z.ZodObject<{
         type: z.ZodEnum<{
             ellipse: "ellipse";
             group: "group";
+            icon: "icon";
+            instance: "instance";
             line: "line";
             rect: "rect";
             text: "text";
         }>;
         name: z.ZodString;
         parentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        componentId: z.ZodOptional<z.ZodString>;
         x: z.ZodNumber;
         y: z.ZodNumber;
         width: z.ZodNumber;
@@ -97,6 +106,7 @@ export declare const BaselineSchema: z.ZodObject<{
         stroke: z.ZodOptional<z.ZodString>;
         strokeWidth: z.ZodOptional<z.ZodNumber>;
         radius: z.ZodOptional<z.ZodNumber>;
+        icon: z.ZodOptional<z.ZodString>;
         text: z.ZodOptional<z.ZodString>;
         color: z.ZodOptional<z.ZodString>;
         fontSize: z.ZodOptional<z.ZodNumber>;
@@ -137,12 +147,15 @@ export declare const DesignSchema: z.ZodObject<{
         type: z.ZodEnum<{
             ellipse: "ellipse";
             group: "group";
+            icon: "icon";
+            instance: "instance";
             line: "line";
             rect: "rect";
             text: "text";
         }>;
         name: z.ZodString;
         parentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        componentId: z.ZodOptional<z.ZodString>;
         x: z.ZodNumber;
         y: z.ZodNumber;
         width: z.ZodNumber;
@@ -153,6 +166,7 @@ export declare const DesignSchema: z.ZodObject<{
         stroke: z.ZodOptional<z.ZodString>;
         strokeWidth: z.ZodOptional<z.ZodNumber>;
         radius: z.ZodOptional<z.ZodNumber>;
+        icon: z.ZodOptional<z.ZodString>;
         text: z.ZodOptional<z.ZodString>;
         color: z.ZodOptional<z.ZodString>;
         fontSize: z.ZodOptional<z.ZodNumber>;
@@ -184,12 +198,15 @@ export declare const DesignSchema: z.ZodObject<{
             type: z.ZodEnum<{
                 ellipse: "ellipse";
                 group: "group";
+                icon: "icon";
+                instance: "instance";
                 line: "line";
                 rect: "rect";
                 text: "text";
             }>;
             name: z.ZodString;
             parentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            componentId: z.ZodOptional<z.ZodString>;
             x: z.ZodNumber;
             y: z.ZodNumber;
             width: z.ZodNumber;
@@ -200,6 +217,7 @@ export declare const DesignSchema: z.ZodObject<{
             stroke: z.ZodOptional<z.ZodString>;
             strokeWidth: z.ZodOptional<z.ZodNumber>;
             radius: z.ZodOptional<z.ZodNumber>;
+            icon: z.ZodOptional<z.ZodString>;
             text: z.ZodOptional<z.ZodString>;
             color: z.ZodOptional<z.ZodString>;
             fontSize: z.ZodOptional<z.ZodNumber>;

package/dist/shared/schemas/design.schema.js

@@ -16,7 +16,7 @@ import { NODE_FIELD_DOCS } from "../node-fields.js";
  * stockage reste plat, donc diffable et lisible, tandis que les coordonnees
  * d'un noeud sont exprimees dans l'espace de son parent.
  */
-export const NODE_TYPES = ["rect", "ellipse", "line", "text", "group"];
+export const NODE_TYPES = ["rect", "ellipse", "line", "text", "icon", "group", "instance"];
 export const NodeTypeSchema = z.enum(NODE_TYPES);
 export const TEXT_ALIGNS = ["left", "center", "right"];
 export const TextAlignSchema = z.enum(TEXT_ALIGNS);
@@ -31,6 +31,12 @@ export const DesignNodeSchema = z.object({
     name: z.string().describe(NODE_FIELD_DOCS.name),
     /** Groupe conteneur, ou null a la racine de la planche. */
     parentId: z.string().nullable().default(null).describe(NODE_FIELD_DOCS.parentId),
+    /**
+     * Instance — le groupe dont ce noeud est une copie liee. Le contenu n'est pas
+     * duplique en stockage : il est resolu au rendu par `shared/instances.ts`,
+     * donc une retouche du groupe source se propage a toutes ses instances.
+     */
+    componentId: z.string().describe(NODE_FIELD_DOCS.componentId).optional(),
     // Boîte englobante, en PIXELS, exprimée dans l'espace du parent. Pour `line`, le trait va de (x, y) à
     // (x + width, y + height), ce qui autorise des largeurs/hauteurs négatives sur ce type uniquement.
     x: z.number().describe(NODE_FIELD_DOCS.x),
@@ -45,6 +51,12 @@ export const DesignNodeSchema = z.object({
     stroke: z.string().describe(NODE_FIELD_DOCS.stroke).optional(),
     strokeWidth: z.number().min(0).describe(NODE_FIELD_DOCS.strokeWidth).optional(),
     radius: z.number().min(0).describe(NODE_FIELD_DOCS.radius).optional(),
+    /**
+     * Icone — un NOM, jamais un trace. Le SVG est resolu au rendu depuis la
+     * bibliotheque embarquee : le fichier reste lisible, l'icone se restyle sans
+     * se redessiner, et un agent qui relit le design sait ce qu'elle represente.
+     */
+    icon: z.string().describe(NODE_FIELD_DOCS.icon).optional(),
     // Texte — fontSize et lineHeight sont tous deux en PIXELS.
     text: z.string().describe(NODE_FIELD_DOCS.text).optional(),
     color: z.string().describe(NODE_FIELD_DOCS.color).optional(),

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

@@ -0,0 +1,23 @@
+import type { DesignNode } from "../../shared/schemas/design.schema.js";
+/**
+ * Copie de sous-arbres avec reattribution des identifiants.
+ *
+ * Deux outils en ont besoin — `duplicate_nodes` pour une copie independante,
+ * `detach_instances` pour materialiser le contenu d'une instance : sans ce
+ * module partage, la meme reecriture des liens parent/enfant existerait en
+ * double, et deux noeuds finiraient tot ou tard par partager un id.
+ */
+/** Les racines et tous leurs descendants, dans l'ordre du document. */
+export declare function subtreeNodes(nodes: DesignNode[], rootIds: string[]): DesignNode[];
+export interface CloneResult {
+    /** Les copies, dans l'ordre du document. Les racines gardent leur `parentId` d'origine. */
+    copies: DesignNode[];
+    /** Ids des copies correspondant aux racines demandees. */
+    rootIds: string[];
+}
+/**
+ * Copie les sous-arbres donnes. Les liens parent/enfant sont recables sur les
+ * copies ; la geometrie, elle, est laissee intacte — le decalage eventuel
+ * appartient a l'appelant.
+ */
+export declare function cloneSubtrees(nodes: DesignNode[], rootIds: string[]): CloneResult;

package/dist/src/core/clone.js

@@ -0,0 +1,34 @@
+import { descendantIds } from "../../shared/tree.js";
+import { shortId } from "./ids.js";
+/**
+ * Copie de sous-arbres avec reattribution des identifiants.
+ *
+ * Deux outils en ont besoin — `duplicate_nodes` pour une copie independante,
+ * `detach_instances` pour materialiser le contenu d'une instance : sans ce
+ * module partage, la meme reecriture des liens parent/enfant existerait en
+ * double, et deux noeuds finiraient tot ou tard par partager un id.
+ */
+/** Les racines et tous leurs descendants, dans l'ordre du document. */
+export function subtreeNodes(nodes, rootIds) {
+    const included = new Set(rootIds);
+    for (const rootId of rootIds)
+        for (const descendant of descendantIds(nodes, rootId))
+            included.add(descendant);
+    return nodes.filter((node) => included.has(node.id));
+}
+/**
+ * Copie les sous-arbres donnes. Les liens parent/enfant sont recables sur les
+ * copies ; la geometrie, elle, est laissee intacte — le decalage eventuel
+ * appartient a l'appelant.
+ */
+export function cloneSubtrees(nodes, rootIds) {
+    const source = subtreeNodes(nodes, rootIds);
+    const idMap = new Map(source.map((node) => [node.id, shortId(node.type === "group" ? "g" : "n")]));
+    const roots = new Set(rootIds);
+    const copies = source.map((node) => ({
+        ...structuredClone(node),
+        id: idMap.get(node.id),
+        parentId: roots.has(node.id) ? node.parentId : (idMap.get(node.parentId ?? "") ?? node.parentId),
+    }));
+    return { copies, rootIds: rootIds.map((id) => idMap.get(id)) };
+}

package/dist/src/core/diff.js

@@ -1,4 +1,4 @@
-import { GROUP_DERIVED_FIELDS } from "../../shared/node-defaults.js";
+import { GROUP_DERIVED_FIELDS, SIZE_DERIVED_KINDS } from "../../shared/node-defaults.js";
 /** Champs recalculés automatiquement : les signaler serait du bruit, pas un changement de design. */
 const DERIVED_GROUP_FIELDS = new Set(GROUP_DERIVED_FIELDS);
 /** Les nombres issus de la GUI portent du bruit sous-pixel qui n'est pas un changement de design. */
@@ -22,7 +22,7 @@ export function diffNodes(before, after) {
         for (const field of fields) {
             if (field === "id" || field === "type")
                 continue;
-            if (node.type === "group" && DERIVED_GROUP_FIELDS.has(field))
+            if (SIZE_DERIVED_KINDS.includes(node.type) && DERIVED_GROUP_FIELDS.has(field))
                 continue;
             const a = previous[field];
             const b = node[field];

package/dist/src/core/export.js

@@ -1,5 +1,7 @@
-import { DEFAULT_FONT_FAMILY, documentToSvg, escapeXml, measuredTextHeight, normalizedBox, textLines, textMetrics, } from "../../shared/render.js";
+import { DEFAULT_FONT_FAMILY, documentToSvg, escapeXml, iconElementToSvg, iconElementsOf, iconStyle, normalizedBox, textLines, textMetrics, } from "../../shared/render.js";
+import { ICON_GRID } from "../../shared/icons/index.js";
 import { boundsOf, childrenByParent, computeLayout } from "../../shared/tree.js";
+import { expandInstances } from "../../shared/instances.js";
 export const EXPORT_FORMATS = ["svg", "html", "jsx", "json", "summary"];
 function round(value) {
     return Math.round(value * 100) / 100;
@@ -7,6 +9,14 @@ function round(value) {
 function toRenderNodes(design) {
     return design.nodes;
 }
+/**
+ * Noeuds tels qu'ils se rendent : chaque instance y est remplacee par une copie
+ * du contenu de son composant. Les exports produisent donc du HTML/JSX complet,
+ * la ou le fichier de design, lui, ne stocke qu'une reference.
+ */
+function toExpandedNodes(design) {
+    return expandInstances(toRenderNodes(design));
+}
 /** "Titre principal" -> "titre-principal" ; sert de nom de classe CSS. */
 function cssClassName(node) {
     const base = node.name
@@ -83,12 +93,43 @@ function nodeCss(node, layout, parentBox) {
         declarations.push(`color: ${node.color ?? "#000000"}`, `font-family: ${node.fontFamily ?? DEFAULT_FONT_FAMILY}`, `font-size: ${round(node.fontSize ?? 24)}px`, `font-weight: ${node.fontWeight ?? 400}`, `line-height: ${round(textMetrics(node).lineStep)}px`, `text-align: ${node.textAlign ?? "left"}`, "white-space: pre-wrap");
         if (node.fontStyle === "italic")
             declarations.push("font-style: italic");
-        declarations.push("height: auto", `min-height: ${round(measuredTextHeight(node))}px`);
+        // Même règle que le canvas : les lignes sont centrées dans la hauteur de la
+        // boîte, laquelle reste celle déclarée. Un bloc flex plutôt qu'un padding
+        // calculé, pour que le centrage tienne si la police de l'intégrateur mesure
+        // autrement ; et pas de min-height, sinon un texte trop grand pour sa boîte
+        // pousserait la mise en page ici alors qu'il déborde simplement sur le canvas.
+        declarations.push("display: flex", "flex-direction: column", "justify-content: center");
     }
     return declarations;
 }
+/** Nom d'attribut inchange : la casse du SVG, pour l'export HTML. */
+const identity = (name) => name;
+/**
+ * SVG inline d'une icone, pour les exports HTML et JSX.
+ *
+ * L'icone est ecrite en clair plutot que tiree d'une dependance : l'export
+ * reste un fichier autonome, ouvrable tel quel, sans `npm install` prealable.
+ * Le viewBox porte la mise a l'echelle, donc le trait garde son epaisseur
+ * relative quelle que soit la taille de la boite.
+ */
+function iconSvg(node, attributeName) {
+    const render = node;
+    const root = { viewBox: `0 0 ${ICON_GRID} ${ICON_GRID}`, width: "100%", height: "100%", ...iconStyle(render) };
+    const attributes = Object.entries(root)
+        .map(([key, value]) => `${attributeName(key)}="${escapeXml(value)}"`)
+        .join(" ");
+    const body = iconElementsOf(render)
+        .map(([tag, attrs]) => attributeName === identity
+        ? iconElementToSvg([tag, attrs])
+        : `<${tag} ${Object.entries(attrs)
+            .map(([key, value]) => `${attributeName(key)}="${escapeXml(value)}"`)
+            .join(" ")} />`)
+        .join("");
+    return `<svg ${attributes}>${body}</svg>`;
+}
 function contextOf(design) {
-    return { layout: computeLayout(toRenderNodes(design)), children: childrenByParent(design.nodes) };
+    const nodes = toExpandedNodes(design);
+    return { layout: computeLayout(nodes), children: childrenByParent(nodes) };
 }
 function toHtml(design) {
     const { layout, children } = contextOf(design);
@@ -107,6 +148,8 @@ function toHtml(design) {
             }
             if (node.type === "text")
                 return [`${pad}<div class="${cls}">${escapeXml(node.text ?? "")}</div>`];
+            if (node.type === "icon")
+                return [`${pad}<div class="${cls}">${iconSvg(node, identity)}</div>`];
             return [`${pad}<div class="${cls}"></div>`];
         });
     };
@@ -172,6 +215,9 @@ function toJsx(design) {
             if (node.type === "text") {
                 return [comment, `${pad}<div style={{ ${style} }}>{${JSON.stringify(node.text ?? "")}}</div>`];
             }
+            if (node.type === "icon") {
+                return [comment, `${pad}<div style={{ ${style} }}>${iconSvg(node, toCamelCase)}</div>`];
+            }
             return [comment, `${pad}<div style={{ ${style} }} />`];
         });
     };
@@ -188,7 +234,13 @@ function toJsx(design) {
 }
 /** Inventaire textuel : ce que l'agent lit quand il veut comprendre sans parser du JSON. */
 export function toSummary(design) {
-    const { layout, children } = contextOf(design);
+    // Le layout vient des noeuds expanses — c'est la seule facon de connaitre
+    // l'encombrement reel d'une instance — mais l'arbre parcouru est celui du
+    // STOCKAGE : l'agent doit lire une instance comme une ligne, pas comme une
+    // copie du composant.
+    const { layout } = contextOf(design);
+    const children = childrenByParent(design.nodes);
+    const byId = new Map(design.nodes.map((node) => [node.id, node]));
     const lines = [
         `# ${design.name} (${design.id})`,
         `Canvas: ${design.width}x${design.height}, background ${design.background}`,
@@ -206,10 +258,21 @@ export function toSummary(design) {
                 lines.push(`${indent}- ${node.id} group "${node.name}" @ ${geometry} — ${count} child(ren)`);
                 walk(children.get(node.id) ?? [], depth + 1);
             }
+            else if (node.type === "instance") {
+                const source = node.componentId === undefined ? undefined : byId.get(node.componentId);
+                lines.push(`${indent}- ${node.id} instance "${node.name}" @ ${geometry} — mirrors group ${node.componentId}` +
+                    `${source ? ` "${source.name}"` : " (missing)"}; edit that group to change every instance of it`);
+            }
             else if (node.type === "text") {
                 const preview = textLines(node).join(" / ");
                 lines.push(`${indent}- ${node.id} text "${node.name}" @ ${geometry} — ${node.fontSize}px/${node.fontWeight} ${node.color} — "${preview}"`);
             }
+            else if (node.type === "icon") {
+                // Le nom de l'icone EST sa semantique : c'est ce qui rend une maquette
+                // relisible par l'agent qui la reprend, screenshot ou pas.
+                lines.push(`${indent}- ${node.id} icon "${node.name}" @ ${geometry} — ${node.icon ?? "?"}, ` +
+                    `stroke ${node.stroke ?? "none"} ${node.strokeWidth ?? 2}/24${node.fill && node.fill !== "none" ? `, fill ${node.fill}` : ""}`);
+            }
             else if (node.type === "line") {
                 lines.push(`${indent}- ${node.id} line "${node.name}" @ ${geometry} — ${node.strokeWidth}px ${node.stroke}`);
             }
@@ -225,6 +288,8 @@ export function toSummary(design) {
 export function exportDesign(design, format) {
     switch (format) {
         case "svg":
+            // `documentToSvg` resout les instances lui-meme : le canvas de la GUI
+            // passe par la meme fonction, avec le meme resultat.
             return documentToSvg({
                 name: design.name,
                 width: design.width,

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

@@ -14,5 +14,12 @@ export declare function validateHierarchy(nodes: DesignNode[]): void;
  */
 export declare function recomputeGroupSizes(nodes: DesignNode[]): DesignNode[];
 export declare function normalizeHierarchy(nodes: DesignNode[]): DesignNode[];
+/**
+ * Instances qui reproduisent l'un de ces groupes et qui SURVIVRAIENT a leur
+ * disparition. Supprimer ou dissoudre un composant encore instancie laisserait
+ * des instances pendantes : les outils s'en servent pour refuser tot, avec un
+ * message qui dit quoi faire.
+ */
+export declare function survivingInstancesOf(nodes: DesignNode[], removedIds: Set<string>): DesignNode[];
 /** Un élément et tous ses descendants — ce qu'une suppression de groupe emporte. */
 export declare function withDescendants(nodes: DesignNode[], ids: string[]): Set<string>;

package/dist/src/core/hierarchy.js

@@ -1,4 +1,6 @@
-import { boundsOf, computeLayout, descendantIds, flattenPreOrder } from "../../shared/tree.js";
+import { boundsOf, childrenByParent, computeLayout, descendantIds, flattenPreOrder } from "../../shared/tree.js";
+import { expandInstances } from "../../shared/instances.js";
+import { SIZE_DERIVED_KINDS } from "../../shared/node-defaults.js";
 import { DesignError } from "./node-factory.js";
 /**
  * Invariants de la hiérarchie, appliqués à chaque mutation.
@@ -21,7 +23,13 @@ export function validateHierarchy(nodes) {
             throw new DesignError(`Node "${node.id}" references a parent "${node.parentId}" that does not exist.`);
         }
         if (parent.type !== "group") {
-            throw new DesignError(`Node "${node.id}" cannot be parented to "${parent.id}" because it is a "${parent.type}", not a group.`);
+            // Le contenu d'une instance appartient a son composant : rien ne s'y
+            // ajoute, ne s'y deplace ni ne s'y reordonne — c'est la meme regle que
+            // dans Figma, et elle tombe toute seule d'un stockage sans sous-arbre.
+            const hint = parent.type === "instance"
+                ? ` The content of an instance belongs to its component: edit the group "${parent.componentId}" instead, or run detach_instances on "${parent.id}" to turn this copy into ordinary nodes.`
+                : "";
+            throw new DesignError(`Node "${node.id}" cannot be parented to "${parent.id}" because it is a "${parent.type}", not a group.${hint}`);
         }
         // Un cycle rendrait le calcul de disposition infini.
         let cursor = parent;
@@ -35,17 +43,66 @@ export function validateHierarchy(nodes) {
         }
     }
 }
+/**
+ * Invariants propres aux instances : un lien valide, et aucun cycle.
+ *
+ * Un cycle (un composant qui contient, meme indirectement, une instance de
+ * lui-meme) rendrait l'expansion infinie. Le rendu s'en protege par un plafond
+ * de profondeur ; ici on refuse simplement de l'ecrire.
+ */
+function validateInstances(nodes) {
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const instances = nodes.filter((node) => node.type === "instance");
+    for (const node of nodes) {
+        if (node.type !== "instance" && node.componentId !== undefined) {
+            throw new DesignError(`"componentId" only applies to an "instance" node, but "${node.id}" is a "${node.type}".`);
+        }
+    }
+    if (instances.length === 0)
+        return;
+    const childrenOf = childrenByParent(nodes);
+    for (const instance of instances) {
+        const source = instance.componentId === undefined ? undefined : byId.get(instance.componentId);
+        if (!source) {
+            throw new DesignError(`Instance "${instance.id}" points at a component "${instance.componentId}" that does not exist in this design. ` +
+                `componentId must be the id of a group of the same design.`);
+        }
+        if (source.type !== "group") {
+            throw new DesignError(`Instance "${instance.id}" points at "${source.id}", which is a "${source.type}". Only a group can be instantiated — ` +
+                `group the block first with group_nodes.`);
+        }
+        // Parcours du contenu du composant : s'il ramene a un composant deja
+        // traverse, l'expansion boucle.
+        const seen = new Set([source.id]);
+        const queue = [source.id];
+        while (queue.length > 0) {
+            for (const child of childrenOf.get(queue.pop()) ?? []) {
+                const target = child.type === "instance" ? (child.componentId ?? "") : child.id;
+                if (child.type === "instance" && seen.has(target)) {
+                    throw new DesignError(`Instance "${instance.id}" would make component "${source.id}" contain itself (through "${child.id}"). ` +
+                        `A component cannot be nested inside itself.`);
+                }
+                if (seen.has(target))
+                    continue;
+                seen.add(target);
+                queue.push(target);
+            }
+        }
+    }
+}
 /**
  * Recalcule la taille de chaque groupe à partir de son contenu. Ces champs sont
  * dérivés : ils existent pour que l'agent puisse lire l'encombrement d'un
  * groupe sans refaire le calcul, jamais pour être écrits.
  */
 export function recomputeGroupSizes(nodes) {
-    if (!nodes.some((node) => node.type === "group"))
+    if (!nodes.some((node) => SIZE_DERIVED_KINDS.includes(node.type)))
         return nodes;
-    const layout = computeLayout(nodes);
+    // Sur les noeuds expanses : la taille d'une instance — et celle du groupe qui
+    // la contient — vient du contenu de son composant.
+    const layout = computeLayout(expandInstances(nodes));
     return nodes.map((node) => {
-        if (node.type !== "group")
+        if (!SIZE_DERIVED_KINDS.includes(node.type))
             return node;
         const box = boundsOf(layout, node.id);
         if (node.width === box.width && node.height === box.height)
@@ -55,8 +112,21 @@ export function recomputeGroupSizes(nodes) {
 }
 export function normalizeHierarchy(nodes) {
     validateHierarchy(nodes);
+    validateInstances(nodes);
     return recomputeGroupSizes(flattenPreOrder(nodes));
 }
+/**
+ * Instances qui reproduisent l'un de ces groupes et qui SURVIVRAIENT a leur
+ * disparition. Supprimer ou dissoudre un composant encore instancie laisserait
+ * des instances pendantes : les outils s'en servent pour refuser tot, avec un
+ * message qui dit quoi faire.
+ */
+export function survivingInstancesOf(nodes, removedIds) {
+    return nodes.filter((node) => node.type === "instance" &&
+        node.componentId !== undefined &&
+        removedIds.has(node.componentId) &&
+        !removedIds.has(node.id));
+}
 /** Un élément et tous ses descendants — ce qu'une suppression de groupe emporte. */
 export function withDescendants(nodes, ids) {
     const all = new Set(ids);