@imenam/mcp-design 1.0.3 → 1.0.5

package/dist/shared/icons/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Bibliotheque d'icones embarquee (Lucide, licence ISC).
+ *
+ * Un noeud `icon` stocke un NOM, jamais un trace : le JSON du design reste
+ * lisible — "shopping-cart" dit a l'agent qui le relit ce que la forme
+ * represente, ce qu'une grappe d'ellipses dessinees a la main ne dit plus — et
+ * une icone se restyle sans se redessiner.
+ *
+ * Le trace n'existe qu'au moment du rendu, resolu ici. Comme `render.ts`, ce
+ * module ne depend d'aucune librairie : il est charge par le serveur MCP comme
+ * par le bundle de la GUI.
+ */
+import { LUCIDE_VERSION } from "./icon-data.js";
+export { LUCIDE_VERSION };
+/**
+ * Cote de la grille dans laquelle chaque icone est dessinee.
+ *
+ * C'est le repere de `strokeWidth` : une icone posee dans une boite de 96px
+ * avec strokeWidth 2 rend un trait de 8px a l'ecran, parce que l'ensemble du
+ * trace est mis a l'echelle. L'unite est celle de la grille, pas celle du
+ * document — c'est la seule qui donne le meme rendu a toutes les tailles.
+ */
+export declare const ICON_GRID = 24;
+/** Epaisseur de trait de reference de Lucide, dans la grille de 24. */
+export declare const DEFAULT_ICON_STROKE_WIDTH = 2;
+/** Un element SVG du trace : son nom de balise et ses attributs de geometrie. */
+export type IconElement = [string, Record<string, string>];
+export declare function hasIcon(name: string): boolean;
+/** Trace de l'icone dans la grille de 24, ou `null` si le nom est inconnu. */
+export declare function iconElements(name: string): IconElement[] | null;
+export declare function iconNames(): string[];
+export declare function iconCount(): number;
+/**
+ * Trace affiche a la place d'une icone dont le nom n'existe pas.
+ *
+ * Un carre en pointilles et un point d'interrogation : le meme SVG sert au
+ * canvas, a l'export et a la capture, donc une exception y serait fatale
+ * partout a la fois. Un design ouvert apres un renommage de la bibliotheque
+ * doit rester ouvrable, et montrer OU le probleme se situe.
+ */
+export declare const UNKNOWN_ICON_ELEMENTS: IconElement[];
+/**
+ * Selection couverte par la description de `add_nodes` : de quoi composer une
+ * interface complete sans aucun aller-retour. Le reste de la bibliotheque
+ * s'atteint par `search_icons`.
+ */
+export declare const CORE_ICONS: readonly string[];

package/dist/shared/icons/index.js

@@ -0,0 +1,107 @@
+/**
+ * Bibliotheque d'icones embarquee (Lucide, licence ISC).
+ *
+ * Un noeud `icon` stocke un NOM, jamais un trace : le JSON du design reste
+ * lisible — "shopping-cart" dit a l'agent qui le relit ce que la forme
+ * represente, ce qu'une grappe d'ellipses dessinees a la main ne dit plus — et
+ * une icone se restyle sans se redessiner.
+ *
+ * Le trace n'existe qu'au moment du rendu, resolu ici. Comme `render.ts`, ce
+ * module ne depend d'aucune librairie : il est charge par le serveur MCP comme
+ * par le bundle de la GUI.
+ */
+import { ICON_DATA_JSON, LUCIDE_VERSION } from "./icon-data.js";
+export { LUCIDE_VERSION };
+/**
+ * Cote de la grille dans laquelle chaque icone est dessinee.
+ *
+ * C'est le repere de `strokeWidth` : une icone posee dans une boite de 96px
+ * avec strokeWidth 2 rend un trait de 8px a l'ecran, parce que l'ensemble du
+ * trace est mis a l'echelle. L'unite est celle de la grille, pas celle du
+ * document — c'est la seule qui donne le meme rendu a toutes les tailles.
+ */
+export const ICON_GRID = 24;
+/** Epaisseur de trait de reference de Lucide, dans la grille de 24. */
+export const DEFAULT_ICON_STROKE_WIDTH = 2;
+let cache = null;
+function library() {
+    // Analyse au premier acces : un serveur stdio qui ne dessine aucune icone ne
+    // paie pas le cout des 1800 traces.
+    if (cache === null)
+        cache = JSON.parse(ICON_DATA_JSON);
+    return cache;
+}
+export function hasIcon(name) {
+    return Object.prototype.hasOwnProperty.call(library(), name);
+}
+/** Trace de l'icone dans la grille de 24, ou `null` si le nom est inconnu. */
+export function iconElements(name) {
+    return library()[name] ?? null;
+}
+export function iconNames() {
+    return Object.keys(library());
+}
+export function iconCount() {
+    return iconNames().length;
+}
+/**
+ * Trace affiche a la place d'une icone dont le nom n'existe pas.
+ *
+ * Un carre en pointilles et un point d'interrogation : le meme SVG sert au
+ * canvas, a l'export et a la capture, donc une exception y serait fatale
+ * partout a la fois. Un design ouvert apres un renommage de la bibliotheque
+ * doit rester ouvrable, et montrer OU le probleme se situe.
+ */
+export const UNKNOWN_ICON_ELEMENTS = [
+    ["rect", { x: "2", y: "2", width: "20", height: "20", rx: "4", "stroke-dasharray": "3 3" }],
+    ["path", { d: "M9.5 9.5a2.5 2.5 0 1 1 3.5 2.3V14" }],
+    ["circle", { cx: "12", cy: "17.5", r: ".5", fill: "currentColor" }],
+];
+/**
+ * Selection couverte par la description de `add_nodes` : de quoi composer une
+ * interface complete sans aucun aller-retour. Le reste de la bibliotheque
+ * s'atteint par `search_icons`.
+ */
+export const CORE_ICONS = [
+    // Navigation et mise en page
+    "house", "search", "menu", "x", "chevron-left", "chevron-right", "chevron-up", "chevron-down",
+    "arrow-left", "arrow-right", "arrow-up", "arrow-down", "arrow-up-right", "arrow-down-right",
+    "external-link", "ellipsis", "ellipsis-vertical", "funnel", "sliders-horizontal", "settings",
+    "layout-dashboard", "layout-grid", "panel-left", "panel-right", "list", "list-checks", "table",
+    "columns-3", "rows-3", "maximize", "minimize", "expand", "shrink", "move", "grip-vertical", "grip-horizontal",
+    // Actions
+    "plus", "minus", "check", "circle-check", "circle-x", "circle-alert", "circle-question-mark",
+    "triangle-alert", "info", "ban", "trash-2", "pencil", "pen-line", "copy", "clipboard", "clipboard-check",
+    "scissors", "save", "download", "upload", "share-2", "send", "link", "unlink", "refresh-cw", "rotate-cw",
+    "undo", "redo", "lock", "lock-open", "eye", "eye-off", "star", "heart", "bookmark", "flag",
+    "bell", "bell-off", "thumbs-up", "thumbs-down",
+    // Personnes et communication
+    "user", "users", "user-plus", "user-check", "circle-user", "contact", "mail", "mail-open",
+    "message-circle", "message-square", "messages-square", "phone", "phone-call", "video", "video-off",
+    "mic", "mic-off", "headphones", "at-sign",
+    // Documents et medias
+    "file", "file-text", "file-plus", "files", "folder", "folder-open", "folder-plus", "archive",
+    "book", "book-open", "newspaper", "notebook-pen", "sticky-note", "paperclip", "printer",
+    "image", "images", "camera", "film", "music", "play", "circle-play", "pause", "volume-2", "volume-x",
+    // Temps et lieux
+    "calendar", "calendar-days", "clock", "timer", "hourglass", "alarm-clock", "map-pin", "map",
+    "navigation", "compass", "globe", "plane", "car", "truck", "bike", "train-front", "ship",
+    // Commerce
+    "shopping-cart", "shopping-bag", "shopping-basket", "credit-card", "wallet", "banknote", "coins",
+    "dollar-sign", "euro", "percent", "receipt", "tag", "tags", "gift", "package", "package-check",
+    // Donnees et statuts
+    "chart-line", "chart-bar", "chart-pie", "chart-column", "trending-up", "trending-down", "activity",
+    "gauge", "target", "award", "trophy", "zap", "flame", "sparkles", "wand-sparkles", "lightbulb", "rocket",
+    // Technique
+    "database", "server", "cloud", "cloud-upload", "cloud-download", "hard-drive", "cpu", "monitor",
+    "smartphone", "tablet", "laptop", "keyboard", "mouse-pointer", "wifi", "wifi-off", "bluetooth",
+    "battery", "plug", "power", "terminal", "code", "code-xml", "braces", "bug", "git-branch",
+    "git-commit-horizontal", "shield", "shield-check", "key", "key-round", "fingerprint-pattern",
+    "scan", "qr-code", "barcode",
+    // Nature et divers
+    "sun", "moon", "cloud-rain", "snowflake", "wind", "droplet", "leaf", "tree-pine", "mountain",
+    "loader-circle", "circle-dot", "dot", "text-align-start", "text-align-center", "text-align-end",
+    "bold", "italic", "underline", "type", "palette", "brush", "pipette", "ruler", "crop", "layers",
+    "box", "shapes", "circle", "square", "triangle", "hexagon", "face-slightly-smiling",
+    "face-slightly-frowning", "face-neutral", "handshake", "hand", "languages", "accessibility",
+];

package/dist/shared/icons/search.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Recherche d'icones par nom et par synonyme.
+ *
+ * Separe de `index.ts` a dessein : le rendu n'a besoin que de la geometrie, et
+ * l'index de mots-cles (deux fois le poids du reste) ne doit peser ni sur le
+ * demarrage du serveur, ni sur le premier affichage du canvas. Il n'est charge
+ * que par l'outil `search_icons` et par le selecteur de la GUI.
+ */
+export declare function iconKeywords(name: string): string[];
+export interface IconMatch {
+    name: string;
+    /** Synonymes qui ont fait ressortir l'icone — ce qui explique un resultat inattendu. */
+    keywords: string[];
+    score: number;
+}
+/**
+ * Icones correspondant a une requete en langage naturel.
+ *
+ * Un terme non reconnu ne vide pas le resultat : les scores s'additionnent, si
+ * bien qu'une requete de trois mots dont un seul existe dans la bibliotheque
+ * retourne quand meme quelque chose d'utile.
+ */
+export declare function searchIcons(query: string, limit?: number): IconMatch[];
+/**
+ * Noms proches d'un nom d'icone refuse — ce qui transforme une erreur en indice.
+ *
+ * Les synonymes comptent autant que les noms : c'est ce qui rattrape les
+ * renommages de la bibliotheque, ou "home" ne designe plus rien mais reste le
+ * synonyme de "house".
+ */
+export declare function suggestIcons(name: string, limit?: number): string[];

package/dist/shared/icons/search.js

@@ -0,0 +1,104 @@
+/**
+ * Recherche d'icones par nom et par synonyme.
+ *
+ * Separe de `index.ts` a dessein : le rendu n'a besoin que de la geometrie, et
+ * l'index de mots-cles (deux fois le poids du reste) ne doit peser ni sur le
+ * demarrage du serveur, ni sur le premier affichage du canvas. Il n'est charge
+ * que par l'outil `search_icons` et par le selecteur de la GUI.
+ */
+import { hasIcon, iconNames } from "./index.js";
+import { ICON_KEYWORDS_JSON } from "./icon-keywords.js";
+let cache = null;
+function keywords() {
+    if (cache === null)
+        cache = JSON.parse(ICON_KEYWORDS_JSON);
+    return cache;
+}
+export function iconKeywords(name) {
+    return keywords()[name] ?? [];
+}
+function tokenize(query) {
+    return query
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/\p{Diacritic}/gu, "")
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 0);
+}
+/**
+ * Score d'une icone pour un terme : le nom prime sur les synonymes, et un debut
+ * de mot prime sur une occurrence au milieu. Sans cette hierarchie, "user"
+ * remonte d'abord les vingt variantes composees plutot que l'icone "user".
+ *
+ * Le RANG du synonyme compte autant que sa presence : les mots-cles sont
+ * ordonnes du plus au moins caracteristique. "home" est le premier synonyme de
+ * "house" et le quatrieme de "lamp" — sans cette decote, une recherche sur
+ * "home" sortait une lampe avant une maison.
+ */
+function scoreToken(name, tags, token) {
+    if (name === token)
+        return 1000;
+    const segments = name.split("-");
+    const byName = segments.includes(token) ? (segments[0] === token ? 400 : 250) : name.includes(token) ? 120 : 0;
+    const exact = tags.indexOf(token);
+    const prefix = exact >= 0 ? -1 : tags.findIndex((tag) => tag.startsWith(token));
+    const byTag = exact >= 0
+        ? Math.max(80, 300 - exact * 25)
+        : prefix >= 0
+            ? Math.max(40, 110 - prefix * 10)
+            : tags.some((tag) => tag.includes(token))
+                ? 30
+                : 0;
+    // Le meilleur des deux, jamais leur somme : "close" doit sortir "x", dont
+    // c'est le premier synonyme, avant "panel-top-close" qui le porte dans son nom.
+    return Math.max(byName, byTag);
+}
+/**
+ * Icones correspondant a une requete en langage naturel.
+ *
+ * Un terme non reconnu ne vide pas le resultat : les scores s'additionnent, si
+ * bien qu'une requete de trois mots dont un seul existe dans la bibliotheque
+ * retourne quand meme quelque chose d'utile.
+ */
+export function searchIcons(query, limit = 24) {
+    const tokens = tokenize(query);
+    if (tokens.length === 0)
+        return [];
+    const index = keywords();
+    const matches = [];
+    for (const name of iconNames()) {
+        const tags = index[name] ?? [];
+        let score = 0;
+        let matched = 0;
+        for (const token of tokens) {
+            const value = scoreToken(name, tags, token);
+            if (value > 0)
+                matched += 1;
+            score += value;
+        }
+        if (score === 0)
+            continue;
+        // Une icone qui repond a TOUS les termes passe devant : "credit card" doit
+        // sortir "credit-card", pas les trente icones contenant "card". Le bonus est
+        // proportionnel et non forfaitaire, sinon deux correspondances tiedes
+        // passeraient devant une icone dont le NOM est exactement le terme cherche.
+        if (matched === tokens.length && tokens.length > 1)
+            score *= 1.5;
+        matches.push({ name, keywords: tags, score });
+    }
+    return matches
+        .sort((a, b) => b.score - a.score || a.name.length - b.name.length || a.name.localeCompare(b.name))
+        .slice(0, Math.max(1, limit));
+}
+/**
+ * Noms proches d'un nom d'icone refuse — ce qui transforme une erreur en indice.
+ *
+ * Les synonymes comptent autant que les noms : c'est ce qui rattrape les
+ * renommages de la bibliotheque, ou "home" ne designe plus rien mais reste le
+ * synonyme de "house".
+ */
+export function suggestIcons(name, limit = 6) {
+    if (hasIcon(name))
+        return [];
+    return searchIcons(name, limit).map((match) => match.name);
+}

package/dist/shared/instances.d.ts

@@ -0,0 +1,39 @@
+import type { RenderNode } from "./render.js";
+/**
+ * Groupes reutilisables : composants et instances.
+ *
+ * Un noeud `instance` est une FEUILLE en stockage : il ne porte qu'une
+ * reference (`componentId`) vers le groupe qu'il reproduit. Son contenu n'est
+ * jamais persiste — il est reconstruit ici, a la volee, par `expandInstances`.
+ *
+ * C'est ce qui donne la propagation : editer le groupe source met a jour toutes
+ * ses instances d'un coup, et `get_changes` ne signale qu'un seul changement au
+ * lieu de N copies. En contrepartie, rien ne se surcharge dans une instance —
+ * une copie qui doit diverger se detache (`detach_instances`).
+ *
+ * Comme `render.ts` et `tree.ts`, ce module ne depend d'aucune librairie : il
+ * est importe aussi bien par le serveur MCP que par le canvas du navigateur.
+ */
+/** Separe l'id de l'instance de celui du noeud du composant : "n_ab12~n_title". */
+export declare const INSTANCE_ID_SEPARATOR = "~";
+/** Vrai si l'id designe un noeud issu d'une expansion : il n'existe pas en stockage. */
+export declare function isExpandedId(id: string): boolean;
+/**
+ * Id du noeud reellement stocke derriere un id rendu : l'instance elle-meme
+ * pour un noeud expanse, l'id inchange sinon. C'est par la que passe toute
+ * selection venue du canvas — cliquer dans une instance selectionne l'instance.
+ */
+export declare function instanceRootOf(id: string): string;
+/**
+ * Remplace chaque noeud `instance` par un `group` equivalent suivi d'une copie
+ * du sous-arbre de son composant, les ids des copies etant prefixes par celui de
+ * l'instance.
+ *
+ * Le resultat ne contient plus aucun noeud `instance` : tous les consommateurs
+ * en aval (calcul de disposition, rendu SVG, export HTML/JSX, canvas) travaillent
+ * sur des groupes ordinaires, sans une seule branche supplementaire.
+ *
+ * Le groupe source, lui, reste dans la liste : il est visible sur la planche,
+ * comme un composant principal dans Figma.
+ */
+export declare function expandInstances<T extends RenderNode>(nodes: T[]): T[];

package/dist/shared/instances.js

@@ -0,0 +1,94 @@
+import { childrenByParent } from "./tree.js";
+/**
+ * Groupes reutilisables : composants et instances.
+ *
+ * Un noeud `instance` est une FEUILLE en stockage : il ne porte qu'une
+ * reference (`componentId`) vers le groupe qu'il reproduit. Son contenu n'est
+ * jamais persiste — il est reconstruit ici, a la volee, par `expandInstances`.
+ *
+ * C'est ce qui donne la propagation : editer le groupe source met a jour toutes
+ * ses instances d'un coup, et `get_changes` ne signale qu'un seul changement au
+ * lieu de N copies. En contrepartie, rien ne se surcharge dans une instance —
+ * une copie qui doit diverger se detache (`detach_instances`).
+ *
+ * Comme `render.ts` et `tree.ts`, ce module ne depend d'aucune librairie : il
+ * est importe aussi bien par le serveur MCP que par le canvas du navigateur.
+ */
+/** Separe l'id de l'instance de celui du noeud du composant : "n_ab12~n_title". */
+export const INSTANCE_ID_SEPARATOR = "~";
+/**
+ * Profondeur maximale d'imbrication d'instances. La garde anti-recursion de
+ * `validateHierarchy` rend le cas impossible en stockage ; ce plafond protege
+ * le rendu d'un fichier ecrit a la main.
+ */
+const MAX_INSTANCE_DEPTH = 8;
+/** Vrai si l'id designe un noeud issu d'une expansion : il n'existe pas en stockage. */
+export function isExpandedId(id) {
+    return id.includes(INSTANCE_ID_SEPARATOR);
+}
+/**
+ * Id du noeud reellement stocke derriere un id rendu : l'instance elle-meme
+ * pour un noeud expanse, l'id inchange sinon. C'est par la que passe toute
+ * selection venue du canvas — cliquer dans une instance selectionne l'instance.
+ */
+export function instanceRootOf(id) {
+    const separator = id.indexOf(INSTANCE_ID_SEPARATOR);
+    return separator === -1 ? id : id.slice(0, separator);
+}
+function derivedId(prefix, id) {
+    return prefix === "" ? id : `${prefix}${INSTANCE_ID_SEPARATOR}${id}`;
+}
+/**
+ * Remplace chaque noeud `instance` par un `group` equivalent suivi d'une copie
+ * du sous-arbre de son composant, les ids des copies etant prefixes par celui de
+ * l'instance.
+ *
+ * Le resultat ne contient plus aucun noeud `instance` : tous les consommateurs
+ * en aval (calcul de disposition, rendu SVG, export HTML/JSX, canvas) travaillent
+ * sur des groupes ordinaires, sans une seule branche supplementaire.
+ *
+ * Le groupe source, lui, reste dans la liste : il est visible sur la planche,
+ * comme un composant principal dans Figma.
+ */
+export function expandInstances(nodes) {
+    if (!nodes.some((node) => node.type === "instance"))
+        return nodes;
+    const children = childrenByParent(nodes);
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const result = [];
+    /** Ids d'origine deja emis a leur place normale, pour le filet de fin. */
+    const emitted = new Set();
+    const visit = (node, prefix, parentId, chain) => {
+        const id = derivedId(prefix, node.id);
+        if (prefix === "")
+            emitted.add(node.id);
+        if (node.type !== "instance") {
+            result.push({ ...node, id, parentId });
+            for (const child of children.get(node.id) ?? [])
+                visit(child, prefix, id, chain);
+            return;
+        }
+        // L'instance devient le groupe qu'elle represente : sa position, sa
+        // rotation et son opacite s'appliquent au contenu du composant.
+        result.push({ ...node, id, parentId, type: "group", componentId: undefined });
+        const source = node.componentId === undefined ? undefined : byId.get(node.componentId);
+        // Reference invalide, recursive ou trop profonde : l'instance se rend vide
+        // plutot que de boucler. La validation, elle, refuse d'ecrire ces cas.
+        if (!source || source.type !== "group")
+            return;
+        if (chain.includes(source.id) || chain.length >= MAX_INSTANCE_DEPTH)
+            return;
+        const nested = [...chain, source.id];
+        for (const child of children.get(source.id) ?? [])
+            visit(child, id, id, nested);
+    };
+    for (const node of children.get(null) ?? [])
+        visit(node, "", null, []);
+    // Meme filet que `flattenPreOrder` : un noeud dont le parent a disparu est
+    // rendu a la racine plutot que de devenir invisible.
+    for (const node of nodes) {
+        if (!emitted.has(node.id))
+            visit(node, "", null, []);
+    }
+    return result;
+}

package/dist/shared/node-defaults.d.ts

@@ -20,6 +20,8 @@ export declare const NODE_STYLE_FIELDS: Record<NodeKind, ReadonlyArray<keyof Ren
  * et ne peuvent pas etre ecrits directement — ni par l'agent, ni par la GUI.
  */
 export declare const GROUP_DERIVED_FIELDS: ReadonlyArray<keyof RenderNode>;
+/** Types dont la taille est deduite du contenu, donc jamais ecrite directement. */
+export declare const SIZE_DERIVED_KINDS: readonly NodeKind[];
 export declare const NODE_GEOMETRY_FIELDS: ReadonlyArray<keyof RenderNode>;
 export declare function defaultNodeName(type: NodeKind, index: number): string;
 export declare function nodeKindLabel(type: NodeKind): string;

package/dist/shared/node-defaults.js

@@ -1,6 +1,7 @@
-export const NODE_KINDS = ["rect", "ellipse", "line", "text", "group"];
+import { DEFAULT_ICON_STROKE_WIDTH, ICON_GRID } from "./icons/index.js";
+export const NODE_KINDS = ["rect", "ellipse", "line", "text", "icon", "group", "instance"];
 /** Types que l'utilisateur peut dessiner directement ; un groupe se cree a partir d'une selection. */
-export const DRAWABLE_KINDS = ["rect", "ellipse", "line", "text"];
+export const DRAWABLE_KINDS = ["rect", "ellipse", "line", "text", "icon"];
 export const NODE_DEFAULTS = {
     rect: { width: 200, height: 120, fill: "#e8e8e6", stroke: "#1a1a18", strokeWidth: 1, radius: 8 },
     ellipse: { width: 160, height: 160, fill: "#e8e8e6", stroke: "#1a1a18", strokeWidth: 1 },
@@ -18,8 +19,19 @@ export const NODE_DEFAULTS = {
         // En pixels, comme x/y/fontSize — jamais un multiplicateur.
         lineHeight: 32,
     },
+    // Taille de la grille de Lucide : une icone posee sans consigne rend au
+    // format pour lequel son trace a ete dessine.
+    icon: {
+        width: ICON_GRID,
+        height: ICON_GRID,
+        fill: "none",
+        stroke: "#1a1a18",
+        strokeWidth: DEFAULT_ICON_STROKE_WIDTH,
+    },
     // Un groupe n'a pas de taille propre : elle est deduite de son contenu.
     group: { width: 0, height: 0 },
+    // Une instance non plus : sa taille est celle du composant qu'elle reproduit.
+    instance: { width: 0, height: 0 },
 };
 /** Champs stylistiques acceptés par type — tout le reste est refusé à la création comme au patch. */
 export const NODE_STYLE_FIELDS = {
@@ -27,13 +39,19 @@ export const NODE_STYLE_FIELDS = {
     ellipse: ["fill", "stroke", "strokeWidth"],
     line: ["stroke", "strokeWidth"],
     text: ["text", "color", "fontSize", "fontFamily", "fontWeight", "fontStyle", "textAlign", "lineHeight"],
+    icon: ["icon", "fill", "stroke", "strokeWidth"],
     group: [],
+    // Rien ne se surcharge dans une instance : son apparence est celle de son
+    // composant. Seul le lien lui-meme se change, ce qui l'echange de composant.
+    instance: ["componentId"],
 };
 /**
  * Champs deduits du contenu d'un groupe. Ils sont recalcules a chaque mutation
  * et ne peuvent pas etre ecrits directement — ni par l'agent, ni par la GUI.
  */
 export const GROUP_DERIVED_FIELDS = ["width", "height"];
+/** Types dont la taille est deduite du contenu, donc jamais ecrite directement. */
+export const SIZE_DERIVED_KINDS = ["group", "instance"];
 export const NODE_GEOMETRY_FIELDS = [
     "x",
     "y",
@@ -47,7 +65,9 @@ const LABELS = {
     ellipse: "Ellipse",
     line: "Ligne",
     text: "Texte",
+    icon: "Icône",
     group: "Groupe",
+    instance: "Instance",
 };
 export function defaultNodeName(type, index) {
     return `${LABELS[type]} ${index}`;
@@ -57,10 +77,18 @@ export function nodeKindLabel(type) {
 }
 /** Taille minimale garantissant qu'un noeud reste sélectionnable à la souris. */
 export function clampNodeSize(type, width, height) {
-    if (type === "group")
-        return { width, height }; // taille deduite du contenu
+    // Groupe et instance : taille deduite du contenu.
+    if (SIZE_DERIVED_KINDS.includes(type))
+        return { width, height };
     if (type === "line")
         return { width, height }; // les deltas négatifs encodent la direction
+    // Une icone est carree : son trace l'est, et une boite rectangulaire ne
+    // ferait que laisser du vide sur les cotes. Le cote suit la plus petite
+    // dimension demandee, ce qui rend un cadrage a la souris previsible.
+    if (type === "icon") {
+        const side = Math.max(1, Math.min(Math.abs(width), Math.abs(height)));
+        return { width: side, height: side };
+    }
     if (type === "text")
         return { width: Math.max(20, Math.abs(width)), height: Math.max(16, Math.abs(height)) };
     return { width: Math.max(1, Math.abs(width)), height: Math.max(1, Math.abs(height)) };

package/dist/shared/node-fields.d.ts

@@ -21,6 +21,8 @@ export declare const NODE_FIELD_DOCS: {
     stroke: string;
     strokeWidth: string;
     radius: string;
+    icon: string;
+    componentId: string;
     text: string;
     color: string;
     fontSize: string;

package/dist/shared/node-fields.js

@@ -8,7 +8,7 @@
  */
 export const NODE_FIELD_DOCS = {
     id: "Explicit id. Generated when omitted; must be unique within the design.",
-    type: "Kind of node: rect, ellipse, line, text or group.",
+    type: "Kind of node: rect, ellipse, line, text, icon, group or instance.",
     name: "Layer name shown in the GUI. Purely descriptive.",
     parentId: "Id of the containing group, or null for the root level of the artboard. " +
         "Changing it reparents the node — its x/y are then read in the new parent's space, so it moves on screen. " +
@@ -25,10 +25,23 @@ export const NODE_FIELD_DOCS = {
         "On a group, derived from the content and read-only.",
     rotation: "Rotation in degrees, clockwise, around the centre of the bounding box. 0 = upright.",
     opacity: "Opacity, from 0 (fully transparent) to 1 (fully opaque).",
-    fill: 'CSS colour filling the interior, e.g. "#ffffff" or "rgba(0,0,0,0.4)". rect and ellipse only.',
-    stroke: "CSS colour of the outline — of the stroke itself on a line node.",
-    strokeWidth: "Thickness of the outline, in pixels. 0 or omitted means no outline.",
+    fill: 'CSS colour filling the interior, e.g. "#ffffff" or "rgba(0,0,0,0.4)". rect, ellipse and icon. On an icon it is "none" by default — the shape is drawn by its stroke.',
+    stroke: "CSS colour of the outline — of the stroke itself on a line node, of the whole drawing on an icon.",
+    strokeWidth: "Thickness of the outline, in pixels. 0 or omitted means no outline. " +
+        "On an ICON this is the only exception to the pixel rule: it is expressed in the icon's own 24x24 grid " +
+        "(2 = the library's regular weight, 1.5 = light, 2.5 = bold), so it scales with the icon. " +
+        "An icon 96px wide with strokeWidth 2 draws an 8px line on screen — never raise it to compensate for a large size.",
     radius: "Corner radius, in pixels. rect only; clamped to half of the shortest side.",
+    icon: "Name of the icon to draw, from the bundled Lucide library, e.g. \"shopping-cart\", \"circle-check\", \"user\". " +
+        "Required on an icon node. NEVER approximate an icon out of rects, ellipses and lines: name it here instead — " +
+        "the result is sharp at any size, restyles in one field, and stays readable to whoever reads the design later. " +
+        "Call search_icons to find a name from a description (it also understands synonyms, so \"basket\" finds \"shopping-cart\"). " +
+        "The node's box is square: the drawing is scaled uniformly to fit it and centred, never stretched.",
+    componentId: "Instance nodes only: id of the GROUP this instance mirrors. The group's content is NOT copied — it is resolved " +
+        "at render time, so editing the group updates every instance of it at once, and a repeated block stays a single " +
+        "node to read and to change. Whenever the same block appears more than once (cards, list rows, menu items, " +
+        "buttons), build it once as a group and add instances of it instead of duplicating it. " +
+        "Change this field to swap an instance over to another group; use detach_instances when one copy must diverge.",
     text: "Text content. It is NEVER auto-wrapped: only explicit \\n characters start a new line.",
     color: "CSS colour of the text.",
     fontSize: "Font size, in pixels (same meaning as the CSS font-size property).",

package/dist/shared/render.d.ts

@@ -7,14 +7,17 @@
  * importable depuis le bundle GUI.
  */
 import { normalizedBox } from "./tree.js";
+import { type IconElement } from "./icons/index.js";
 export { normalizedBox };
 export type { Box, Point } from "./tree.js";
 export interface RenderNode {
     id: string;
-    type: "rect" | "ellipse" | "line" | "text" | "group";
+    type: "rect" | "ellipse" | "line" | "text" | "icon" | "group" | "instance";
     name: string;
     /** Groupe conteneur, ou null a la racine. Les coordonnees sont relatives a ce parent. */
     parentId: string | null;
+    /** Instance : id du groupe reproduit. Resolu par `expandInstances` avant tout rendu. */
+    componentId?: string;
     x: number;
     y: number;
     width: number;
@@ -25,6 +28,8 @@ export interface RenderNode {
     stroke?: string;
     strokeWidth?: number;
     radius?: number;
+    /** Nom de l'icone dans la bibliotheque embarquee, p.ex. "shopping-cart". Type `icon` uniquement. */
+    icon?: string;
     text?: string;
     color?: string;
     fontSize?: number;
@@ -66,6 +71,9 @@ export declare function defaultLineHeight(fontSize: number): number;
 export declare function textMetrics(node: RenderNode): {
     fontSize: number;
     lineStep: number;
+    /** Hauteur occupée par les lignes, interligne compris. */
+    blockHeight: number;
+    blockOffset: number;
     /** Ligne de base de la première ligne, mesurée depuis le haut de la boîte. */
     firstBaseline: number;
     anchor: string;
@@ -81,6 +89,31 @@ export declare function groupTransform(node: RenderNode, localCenter: {
     cx: number;
     cy: number;
 }): string;
+/**
+ * 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 declare function iconPlacement(node: RenderNode): {
+    x: number;
+    y: number;
+    scale: number;
+    size: number;
+};
+/** Trace du noeud, ou le carre en pointilles si le nom d'icone est inconnu. */
+export declare function iconElementsOf(node: RenderNode): IconElement[];
+/**
+ * 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 declare function iconStyle(node: RenderNode): Record<string, string>;
+export declare function iconElementToSvg([tag, attributes]: IconElement): string;
 /**
  * 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