@imenam/mcp-design 1.0.10 → 1.0.12

package/README.md

@@ -4,10 +4,13 @@ Un canvas de design pilotable par un agent, avec une interface graphique où l'u
 
 L'agent compose une planche (formes, texte) via des outils MCP. L'utilisateur ouvre la GUI, déplace, retaille, recolore, réécrit. L'agent relit ensuite **exactement ce qui a changé** et l'intègre dans le code de l'application.
 
+L'utilisateur peut aussi, sans toucher au design, **épingler des remarques** sur une page, un élément ou une zone. Il les transmet en un retour nommé que l'agent lit avec `get_feedback`, captures comprises ; l'agent déclare ensuite ce qu'il a traité avec `mark_feedback_processed`, et l'utilisateur suit l'avancement de chaque retour dans la page « Retours ».
+
 ```
 Agent ──add_nodes/update_nodes──▶  Design  ◀──glisser-déposer──  Utilisateur (GUI)
   ▲                                                                    │
-  └──────────── get_changes ──── diff depuis la dernière baseline ──────┘
+  ├──────────── get_changes ──── diff depuis la dernière baseline ──────┤
+  └──────────── get_feedback ─── remarques transmises (retour n°N) ─────┘
 ```
 
 ---
@@ -72,7 +75,7 @@ Exemple d'entrée générée :
 | `APP_NAME` | Nom affiché dans le dashboard du proxy. `PROXY_APP_NAME` puis `GUI_NAME` sont acceptés en repli. |
 | `APP_PATH_PREFIX` | Préfixe de namespace ajouté au chemin **par défaut** (ex. `/abc123` → `/abc123/design-gui`). Sert à isoler plusieurs instances sous un même proxy. |
 | `APP_GROUP` | Section repliable du dashboard du proxy (facultatif). |
-| `MCP_DESIGN_DATA_DIR` | Répertoire de stockage des designs. `MCP_DATA_DIR` est accepté en repli. Défaut : `<package>/.design-data`. |
+| `MCP_DESIGN_DATA_DIR` | Répertoire de stockage des designs et des remarques. `MCP_DATA_DIR` est accepté en repli. Défaut : `<package>/.design-data`. |
 | `MCP_LOG_DIR` | Répertoire des logs. Défaut : `<data>/logs`. |
 
 `PROXY_URL` et `APP_PORT` s'excluent : `PROXY_URL` prime si les deux sont renseignés. **Si aucune des deux n'est définie, la GUI est simplement désactivée** — les outils MCP continuent de fonctionner.
@@ -90,7 +93,7 @@ Chaque requête traverse la garde de [`@imenam/mcp-gui-interface`](https://www.n
 - à tout en-tête `Host` autre que `localhost`, `127.0.0.1` ou `::1` (protection contre le DNS rebinding) ;
 - aux modifications (méthodes autres que `GET`, `HEAD`, `OPTIONS`) venues d'un autre site, d'après `Sec-Fetch-Site` ou, à défaut, `Origin` (sont admis : la machine elle-même, le proxy de `PROXY_URL`).
 
-Un design est un simple fichier JSON dans `<data>/designs/<id>.json` — lisible, diffable, versionnable.
+Un design est un simple fichier JSON dans `<data>/designs/<id>.json` — lisible, diffable, versionnable. Les images qu'il affiche sont dans `<data>/images/`.
 
 ---
 
@@ -112,6 +115,7 @@ Un design est un simple fichier JSON dans `<data>/designs/<id>.json` — lisible
 | Outil | Effet |
 |---|---|
 | `add_nodes` | Ajoute un ou plusieurs éléments par-dessus les autres. |
+| `add_image` | Importe une image (chemin absolu d'un fichier PNG, JPEG, GIF, WebP ou SVG) et la pose par-dessus les autres éléments. |
 | `update_nodes` | Patche des éléments existants — seuls les champs fournis changent. |
 | `delete_nodes` | Supprime des éléments par identifiant. Supprimer un groupe emporte son contenu. |
 | `duplicate_nodes` | Copie des éléments ou des groupes avec tout leur contenu, sous de nouveaux identifiants. `offset_x`/`offset_y` et `count` disposent une série de copies, `parent_id` les dépose dans un groupe. Avec `target_design_id`, la copie va dans une **autre planche** : les éléments gardent leur position à l'écran, et les composants reproduits par les instances copiées sont copiés avec elles, une seule fois, à la racine. |
@@ -119,7 +123,7 @@ Un design est un simple fichier JSON dans `<data>/designs/<id>.json` — lisible
 | `ungroup_nodes` | Dissout des groupes : leur contenu remonte d'un niveau, toujours sans bouger. |
 | `detach_instances` | Rompt le lien d'une instance avec son composant : son contenu devient des éléments ordinaires. |
 
-Sept types d'éléments : `rect`, `ellipse`, `line`, `text`, `icon`, `group` et `instance`. Seul `type` est obligatoire — sauf pour `icon`, qui a besoin du nom de l'icône ; tout le reste tombe sur des valeurs par défaut visibles, donc `{ "type": "rect" }` suffit à créer quelque chose qu'on voit à l'écran.
+Huit types d'éléments : `rect`, `ellipse`, `line`, `text`, `icon`, `image`, `group` et `instance`. Seul `type` est obligatoire — sauf pour `icon`, qui a besoin du nom de l'icône, et `image`, qui a besoin du nom d'une image importée ; tout le reste tombe sur des valeurs par défaut visibles, donc `{ "type": "rect" }` suffit à créer quelque chose qu'on voit à l'écran.
 
 **Champs communs** — `name`, `parentId`, `x`, `y`, `width`, `height` (en pixels, origine en haut à gauche), `rotation` (degrés, autour du centre de la boîte), `opacity` (0–1).
 
@@ -132,6 +136,7 @@ Sept types d'éléments : `rect`, `ellipse`, `line`, `text`, `icon`, `group` et
 | `line` | `stroke`, `strokeWidth` — le trait va de `(x, y)` à `(x + width, y + height)`, donc les deltas négatifs encodent la direction |
 | `text` | `text`, `color`, `fontSize`, `fontFamily`, `fontWeight`, `fontStyle`, `textAlign`, `lineHeight` (en px) |
 | `icon` | `icon` (obligatoire — le nom du dessin), `fill`, `stroke`, `strokeWidth` |
+| `image` | `image` (obligatoire — le nom de l'image dans la médiathèque), `fit` (`cover` par défaut, `contain`, `fill`) |
 | `group` | aucun — c'est un pur conteneur |
 | `instance` | `componentId` (obligatoire — le groupe reproduit) ; rien d'autre, son apparence vient de ce groupe |
 
@@ -161,6 +166,25 @@ Côté GUI, l'outil « Icône » de la barre d'outils (raccourci `I`) ouvre un s
 
 La bibliothèque est figée dans le dépôt par `npm run generate-icons` ([`scripts/generate-icons.js`](scripts/generate-icons.js)) : ni le serveur publié ni le bundle de la GUI ne dépendent de Lucide à l'exécution, et la géométrie d'un design ne peut pas changer au gré d'un `npm install`.
 
+### Images
+
+`add_image` pose une vraie image — photo, logo, illustration, capture — là où une icône ou des formes ne suffisent pas.
+
+```json
+{ "design_id": "landing", "file_path": "C:/projets/site/assets/hero.jpg", "x": 0, "y": 80, "width": 1440 }
+```
+
+- **Le fichier est copié** dans `<MCP_DESIGN_DATA_DIR>/images/`, sous un nom tiré de l'empreinte de son contenu (`img_3f9a1c2b7d4e5f60.jpg`). Le design ne stocke que ce nom : le JSON reste lisible, une même image importée deux fois n'est stockée qu'une fois, et la planche ne dépend plus de l'emplacement du fichier d'origine. La médiathèque est commune à toutes les planches du dossier de données.
+- **Taille** : sans `width` ni `height`, la boîte prend les dimensions naturelles de l'image ; avec une seule des deux, l'autre suit ses proportions.
+- **`fit`** dit comment l'image remplit sa boîte : `cover` la remplit en rognant le débordement, `contain` la montre en entier, `fill` l'étire.
+- **Réutiliser une image** : la réponse d'`add_image` donne son nom ; un nœud `{ "type": "image", "image": "img_…" }` dans `add_nodes` la repose sans second import. Un nom absent de la médiathèque est refusé à l'écriture.
+- Le format est reconnu d'après le contenu du fichier, pas d'après son extension ; 20 Mo au plus.
+- Derrière [`@imenam/mcp-http-gateway`](https://www.npmjs.com/package/@imenam/mcp-http-gateway), l'outil déclare la paire `file_path` / `file_content` : le relais lit le fichier sur la machine de l'agent et en transmet le contenu (dossier autorisé par `GATEWAY_INLINE_ROOTS`).
+
+Le canvas charge les images depuis le worker (`GET /api/images/<nom>`). `screenshot_design`, les captures des remarques et `export_design` les intègrent en data URI : un export `svg`, `html` ou `jsx` s'ouvre tel quel, sans la médiathèque — mais il pèse le poids des images qu'il contient ; pour une planche illustrée, préférez `destination_path` à un retour en ligne.
+
+Dans la GUI, une image se déplace, se redimensionne et se pivote comme les autres éléments ; l'inspecteur règle son cadrage.
+
 ### Hiérarchie
 
 Chaque élément porte un `parentId` : `null` à la racine de la planche, sinon l'identifiant d'un `group`. **Les coordonnées sont exprimées dans l'espace du parent** : un élément à la racine se positionne par rapport à la planche, un élément dans un groupe par rapport à l'origine de ce groupe.
@@ -241,6 +265,17 @@ Un lot est intégralement validé avant la moindre écriture : une entrée inval
 
 **`get_changes` n'acquitte jamais ce qu'il montre.** Seul `mark_synced` déplace la baseline, et il ne doit être appelé qu'une fois les modifications réellement reportées dans le code. Un simple appel de lecture ne peut donc pas faire disparaître un diff que l'agent n'a pas encore traité.
 
+### Lire les remarques de l'utilisateur
+
+| Outil | Effet |
+|---|---|
+| `get_feedback` | Renvoie le plus ancien retour qui a encore des remarques à traiter (le dernier quand tout est traité), ou celui demandé par `round`. Pour chaque remarque : son identifiant, la page, puis la page entière, l'élément visé (id, nom, chemin, boîte) ou la zone et les éléments cités, le texte et son état de traitement. Les captures d'éléments et de zones suivent **en images**, numérotées comme dans le texte ; `captures: false` les omet. La réponse se termine par la liste de tous les retours et de leur avancement. |
+| `mark_feedback_processed` | Déclare traitées des remarques d'un retour (`round`, `remark_ids` — toutes si omis), avec une `note` sur ce qui a été fait. C'est ce que l'utilisateur voit dans la page « Retours ». |
+
+Un retour est **figé** au moment où l'utilisateur clique sur « Terminer les retours » : `get_feedback` peut le relire autant de fois que nécessaire, rien ne change. Seuls son nom (renommable dans la GUI) et le suivi du traitement évoluent ; **lire un retour ne le marque jamais traité**, seul `mark_feedback_processed` (ou l'utilisateur) le fait. Le texte est celui que la GUI affiche en aperçu avant l'enregistrement — même fonction de mise en forme, donc même contenu. Tant qu'aucun retour n'existe, l'outil dit combien de remarques attendent encore dans la GUI.
+
+Les remarques vivent dans `<MCP_DESIGN_DATA_DIR>/feedback/remarks.json`, les captures PNG dans `<MCP_DESIGN_DATA_DIR>/feedback/captures/` : le même dossier de données que les designs, celui fixé par la configuration du projet.
+
 ### GUI
 
 | Outil | Effet |
@@ -263,6 +298,13 @@ screenshot_design { design_id: "landing" }    ← ce que ça donne réellement,
 export_design { design_id: "landing", format: "html" }
   … l'agent reporte les valeurs dans le code de l'application …
 mark_synced   { design_id: "landing" }        ← acquittement
+
+  … l'utilisateur passe en mode Remarques, commente, clique « Terminer les retours »,
+    puis dit à l'agent qu'il a terminé …
+
+get_feedback  {}                              ← retour à traiter : remarques + captures
+  … l'agent applique les remarques …
+mark_feedback_processed { round: 1, remark_ids: ["rm_…"], note: "…" }   ← suivi visible dans la GUI
 ```
 
 ---
@@ -290,6 +332,26 @@ La sauvegarde est automatique et différée. Une modification faite par l'agent
 
 Le badge « n à synchroniser » d'une planche indique le nombre de modifications que l'agent n'a pas encore acquittées.
 
+### Mode Remarques
+
+La bascule **Édition / Remarques** de la barre d'outils (raccourci `M`) passe le canvas en lecture : rien ne s'y déplace, et le rail de droite affiche les remarques à la place de l'inspecteur.
+
+- **Remarque sur un élément** — un clic vise le **groupe le plus haut**, comme en édition ; un nouveau clic à l'intérieur descend d'un niveau, `Alt+clic` vise l'élément exact. La bulle de saisie affiche le chemin de l'élément : un clic sur un niveau vise ce parent.
+- **Remarque sur une zone** — glisser trace un rectangle. La bulle montre l'aperçu de la zone et les **éléments détectés** : un élément entièrement compris est cité tel quel, un groupe qui déborde est ouvert pour citer ceux de ses éléments que la zone touche, un élément qui déborde est marqué « en partie » et décoché par défaut.
+- **Remarque sur la page** — depuis le panneau, une seule remarque en cours par page.
+- **Captures** — pour un élément ou une zone, « Joindre une capture » (coché par défaut) enregistre un PNG de ce que l'utilisateur commentait, rendu par le serveur au moment de la remarque.
+- **Pastilles** — chaque remarque d'élément ou de zone porte un numéro sur la planche ; survoler une carte du panneau met sa cible en évidence, cliquer une pastille désigne sa carte.
+- **Terminer les retours** — demande un **nom** pour le retour (« Retour n°N » proposé), choisit le périmètre (cette page ou toutes) et les remarques à transmettre, et montre exactement le texte que l'agent recevra. L'enregistrement fige un **retour numéroté et nommé**.
+- **Après l'envoi** — les remarques restent visibles en lecture seule, marquées « Transmise · *nom du retour* », puis « Traitée » une fois traitées : pastille creuse, zone en pointillés. Une case du panneau les masque. Une remarque dont l'élément a disparu depuis le signale.
+
+### Page « Retours »
+
+Le bouton **Retours** de la barre d'outils (avec le nombre de retours pas encore entièrement traités) ouvre la liste de tous les retours, du plus récent au plus ancien, chacun avec son état — *À traiter*, *En cours* (n/total), *Traité* — et une barre d'avancement. Le détail d'un retour reprend ses remarques page par page, avec leur capture, et pour chacune : *À traiter*, ou *Traitée par l'agent / par vous* avec la date et la note de l'agent. Le nom du retour se modifie en place ; une case coche ou rouvre une remarque à la main, et « Tout marquer comme traité » (ou « Tout rouvrir ») agit sur tout le retour affiché ; le même bouton en haut de la page traite d'un coup tous les retours en attente, après confirmation. Une remarque déjà traitée par l'agent garde son auteur et sa note ; « Ouvrir la page » ramène sur la planche en mode Remarques. `Échap` ferme la page.
+
+Les retours créés avant l'arrivée des noms reçoivent « Retour n°N », et aucune de leurs remarques n'est considérée comme traitée.
+
+`Ctrl+Entrée` enregistre une remarque, `Échap` la ferme, puis quitte le mode. Le badge violet d'une page dans la liste compte ses remarques non transmises.
+
 ---
 
 ## Architecture
@@ -301,7 +363,7 @@ Deux processus, conformément au standard de l'écosystème (`@imenam/mcp-gui-in
 
 Les deux communiquent par IPC. Le worker se termine proprement quand le master disparaît (canal IPC fermé, PID parent absent) et quand une autre instance est déjà enregistrée (HTTP 409), ce qui évite les GUI orphelines.
 
-`shared/render.ts` contient le rendu SVG d'un élément, `shared/tree.ts` la résolution de la hiérarchie en coordonnées document, `shared/instances.ts` l'expansion des instances en groupes, `shared/node-defaults.ts` les valeurs par défaut et `shared/icons/` la bibliothèque d'icônes. Tous sont importés **à la fois** par l'exporteur côté serveur et par le canvas côté navigateur : ce que l'utilisateur voit est exactement ce que `export_design` — et donc `screenshot_design`, qui rasterise ce même SVG via resvg — produit.
+`shared/feedback.ts` porte le modèle des remarques, la détection des éléments d'une zone et la mise en forme d'un retour ; le serveur et la GUI l'importent tous deux, ce qui garantit que l'aperçu affiché est le texte transmis. `shared/render.ts` contient le rendu SVG d'un élément, `shared/tree.ts` la résolution de la hiérarchie en coordonnées document, `shared/instances.ts` l'expansion des instances en groupes, `shared/node-defaults.ts` les valeurs par défaut et `shared/icons/` la bibliothèque d'icônes. Tous sont importés **à la fois** par l'exporteur côté serveur et par le canvas côté navigateur : ce que l'utilisateur voit est exactement ce que `export_design` — et donc `screenshot_design`, qui rasterise ce même SVG via resvg — produit.
 
 Les invariants de hiérarchie — parent existant et de type `group`, absence de cycle (y compris dans le graphe composant/instance), taille des groupes et des instances recalculée, ordre préfixe — sont appliqués dans `DesignStore.mutate`, donc sur **tout** chemin d'écriture : outil MCP comme sauvegarde depuis la GUI.
 

package/dist/shared/feedback.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Remarques de l'utilisateur sur un design, et retours transmis à l'agent.
+ *
+ * Une remarque vise la page entière, un élément, ou une zone rectangulaire de la
+ * planche. Tant qu'elle est un brouillon, l'utilisateur la modifie librement ;
+ * « Terminer les retours » fige les remarques cochées dans un retour numéroté,
+ * nommé, que l'agent lit avec `get_feedback`. Une remarque transmise ne se
+ * modifie plus : le retour qui la contient reste exactement ce que l'agent a
+ * reçu. Seul son traitement évolue, déclaré par l'agent avec
+ * `mark_feedback_processed` ou par l'utilisateur dans la page des retours.
+ *
+ * Comme `render.ts` et `tree.ts`, ce module ne dépend d'aucune librairie : il
+ * est importé par le serveur MCP comme par la GUI, qui s'en sert pour afficher
+ * l'aperçu exact du retour avant de l'enregistrer.
+ */
+import type { RenderNode } from "./render.js";
+import { type Box } from "./tree.js";
+export type RemarkStatus = "draft" | "sent";
+/** Élément de la planche cité par une remarque. */
+export interface RemarkElement {
+    id: string;
+    name: string;
+    type: RenderNode["type"];
+}
+export type RemarkTarget = {
+    kind: "page";
+} | {
+    kind: "node";
+    element: RemarkElement;
+    /** Noms des groupes englobants puis de l'élément, de la racine vers lui. */
+    path: string[];
+    /** Boîte de l'élément au moment de la remarque, en coordonnées document. */
+    box: Box;
+} | {
+    kind: "area";
+    /** Zone tracée, en coordonnées document. */
+    box: Box;
+    /** Éléments de la zone que l'utilisateur a choisi de citer. */
+    elements: RemarkElement[];
+};
+export type RemarkKind = RemarkTarget["kind"];
+export interface Remark {
+    id: string;
+    designId: string;
+    /** Numéro de la pastille sur la planche ; null pour la remarque de page. */
+    number: number | null;
+    target: RemarkTarget;
+    text: string;
+    /** Nom du fichier PNG de la capture, ou null sans capture. */
+    capture: string | null;
+    status: RemarkStatus;
+    /** Retour qui contient la remarque, une fois transmise. */
+    round: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Traitement d'une remarque transmise : qui l'a déclarée traitée, quand, et ce qui a été fait. */
+export interface RemarkProcessing {
+    at: string;
+    by: "agent" | "user";
+    note: string | null;
+}
+/** Remarque telle qu'elle figure dans un retour transmis. */
+export interface RoundRemark {
+    id: string;
+    designId: string;
+    designName: string;
+    number: number | null;
+    target: RemarkTarget;
+    text: string;
+    capture: string | null;
+    /** Null tant que la remarque n'est pas traitée. */
+    processed: RemarkProcessing | null;
+}
+export interface FeedbackRound {
+    number: number;
+    /** Nom donné par l'utilisateur en terminant sa revue. */
+    title: string;
+    submittedAt: string;
+    remarks: RoundRemark[];
+}
+export type RoundStatus = "pending" | "in_progress" | "done";
+/** Avancement d'un retour : à traiter, en cours, ou entièrement traité. */
+export declare function roundProgress(round: Pick<FeedbackRound, "remarks">): {
+    done: number;
+    total: number;
+    status: RoundStatus;
+};
+/** Nom proposé pour un retour avant que l'utilisateur ne le change. */
+export declare function defaultRoundTitle(number: number): string;
+/** Élément touché par une zone. `partial` : il en déborde. */
+export interface AreaHit extends RemarkElement {
+    partial: boolean;
+}
+/**
+ * Éléments qu'une zone recouvre, au niveau le plus utile pour les nommer.
+ *
+ * Un élément entièrement compris dans la zone est cité tel quel, sans détailler
+ * son contenu. Un groupe qui en déborde est ouvert, pour citer ceux de ses
+ * éléments que la zone touche. Un élément sans contenu qui en déborde (forme,
+ * texte, instance) est cité comme partiel. Les instances ne sont jamais
+ * ouvertes : leur contenu n'existe pas en stockage.
+ */
+export declare function elementsInArea(nodes: RenderNode[], area: Box): AreaHit[];
+/** Noms des groupes englobants puis de l'élément, de la racine vers lui. */
+export declare function nodePath(nodes: RenderNode[], id: string): string[];
+/** Cible d'une remarque sur un élément, calculée sur l'état courant du design. */
+export declare function nodeTarget(nodes: RenderNode[], id: string): Extract<RemarkTarget, {
+    kind: "node";
+}>;
+export declare function roundBox(box: Box): Box;
+/**
+ * Ordre de lecture d'un lot de remarques : les pages dans l'ordre où elles
+ * apparaissent, puis dans chaque page la remarque de page d'abord et les autres
+ * par numéro de pastille. Le serveur fige un retour dans cet ordre, la GUI
+ * affiche son aperçu dans le même.
+ */
+export declare function orderRemarks<T extends Pick<Remark, "designId" | "number">>(remarks: T[]): T[];
+export declare const PATH_SEPARATOR = " \u203A ";
+/**
+ * Texte d'un retour, tel que l'agent le reçoit.
+ *
+ * La GUI l'affiche en aperçu avant l'enregistrement : c'est la même fonction,
+ * donc le même texte. Chaque remarque porte son identifiant, que l'agent passe
+ * à `mark_feedback_processed`. Les captures sont numérotées dans l'ordre des
+ * remarques ; `get_feedback` joint les images dans cet ordre.
+ */
+export declare function formatFeedbackRound(round: Pick<FeedbackRound, "number" | "title" | "submittedAt" | "remarks">): string;

package/dist/shared/feedback.js

@@ -0,0 +1,165 @@
+/**
+ * Remarques de l'utilisateur sur un design, et retours transmis à l'agent.
+ *
+ * Une remarque vise la page entière, un élément, ou une zone rectangulaire de la
+ * planche. Tant qu'elle est un brouillon, l'utilisateur la modifie librement ;
+ * « Terminer les retours » fige les remarques cochées dans un retour numéroté,
+ * nommé, que l'agent lit avec `get_feedback`. Une remarque transmise ne se
+ * modifie plus : le retour qui la contient reste exactement ce que l'agent a
+ * reçu. Seul son traitement évolue, déclaré par l'agent avec
+ * `mark_feedback_processed` ou par l'utilisateur dans la page des retours.
+ *
+ * Comme `render.ts` et `tree.ts`, ce module ne dépend d'aucune librairie : il
+ * est importé par le serveur MCP comme par la GUI, qui s'en sert pour afficher
+ * l'aperçu exact du retour avant de l'enregistrer.
+ */
+import { expandInstances } from "./instances.js";
+import { ancestorsOf, boundsOf, boxesIntersect, childrenByParent, computeLayout } from "./tree.js";
+/** Avancement d'un retour : à traiter, en cours, ou entièrement traité. */
+export function roundProgress(round) {
+    const total = round.remarks.length;
+    const done = round.remarks.filter((remark) => remark.processed !== null).length;
+    return { done, total, status: done === 0 ? "pending" : done === total ? "done" : "in_progress" };
+}
+/** Nom proposé pour un retour avant que l'utilisateur ne le change. */
+export function defaultRoundTitle(number) {
+    return `Retour n°${number}`;
+}
+function contains(outer, inner) {
+    return (inner.x >= outer.x &&
+        inner.y >= outer.y &&
+        inner.x + inner.width <= outer.x + outer.width &&
+        inner.y + inner.height <= outer.y + outer.height);
+}
+/**
+ * Éléments qu'une zone recouvre, au niveau le plus utile pour les nommer.
+ *
+ * Un élément entièrement compris dans la zone est cité tel quel, sans détailler
+ * son contenu. Un groupe qui en déborde est ouvert, pour citer ceux de ses
+ * éléments que la zone touche. Un élément sans contenu qui en déborde (forme,
+ * texte, instance) est cité comme partiel. Les instances ne sont jamais
+ * ouvertes : leur contenu n'existe pas en stockage.
+ */
+export function elementsInArea(nodes, area) {
+    const layout = computeLayout(expandInstances(nodes));
+    const children = childrenByParent(nodes);
+    const hits = [];
+    const visit = (node) => {
+        const box = boundsOf(layout, node.id);
+        if (box.width <= 0 && box.height <= 0)
+            return;
+        if (!boxesIntersect(box, area))
+            return;
+        const element = { id: node.id, name: node.name, type: node.type };
+        if (contains(area, box)) {
+            hits.push({ ...element, partial: false });
+            return;
+        }
+        const content = node.type === "group" ? (children.get(node.id) ?? []) : [];
+        if (content.length > 0)
+            content.forEach(visit);
+        else
+            hits.push({ ...element, partial: true });
+    };
+    (children.get(null) ?? []).forEach(visit);
+    return hits;
+}
+/** Noms des groupes englobants puis de l'élément, de la racine vers lui. */
+export function nodePath(nodes, id) {
+    const node = nodes.find((candidate) => candidate.id === id);
+    if (!node)
+        return [];
+    return [...ancestorsOf(nodes, id).reverse().map((ancestor) => ancestor.name), node.name];
+}
+/** Cible d'une remarque sur un élément, calculée sur l'état courant du design. */
+export function nodeTarget(nodes, id) {
+    const node = nodes.find((candidate) => candidate.id === id);
+    if (!node)
+        throw new Error(`Node "${id}" not found in the design.`);
+    const box = boundsOf(computeLayout(expandInstances(nodes)), id);
+    return {
+        kind: "node",
+        element: { id: node.id, name: node.name, type: node.type },
+        path: nodePath(nodes, id),
+        box: roundBox(box),
+    };
+}
+export function roundBox(box) {
+    const round = (value) => Math.round(value * 100) / 100;
+    return { x: round(box.x), y: round(box.y), width: round(box.width), height: round(box.height) };
+}
+/**
+ * Ordre de lecture d'un lot de remarques : les pages dans l'ordre où elles
+ * apparaissent, puis dans chaque page la remarque de page d'abord et les autres
+ * par numéro de pastille. Le serveur fige un retour dans cet ordre, la GUI
+ * affiche son aperçu dans le même.
+ */
+export function orderRemarks(remarks) {
+    const pages = [...new Set(remarks.map((remark) => remark.designId))];
+    return [...remarks].sort((a, b) => pages.indexOf(a.designId) - pages.indexOf(b.designId) || (a.number ?? 0) - (b.number ?? 0));
+}
+export const PATH_SEPARATOR = " › ";
+function formatBox(box) {
+    const round = (value) => Math.round(value);
+    return `x ${round(box.x)}, y ${round(box.y)}, ${round(box.width)}×${round(box.height)}`;
+}
+function formatElement(element) {
+    return `${element.id} "${element.name}" (${element.type})`;
+}
+function indent(text, prefix) {
+    return text
+        .split("\n")
+        .map((line) => `${prefix}${line}`)
+        .join("\n");
+}
+/**
+ * Texte d'un retour, tel que l'agent le reçoit.
+ *
+ * La GUI l'affiche en aperçu avant l'enregistrement : c'est la même fonction,
+ * donc le même texte. Chaque remarque porte son identifiant, que l'agent passe
+ * à `mark_feedback_processed`. Les captures sont numérotées dans l'ordre des
+ * remarques ; `get_feedback` joint les images dans cet ordre.
+ */
+export function formatFeedbackRound(round) {
+    const pages = new Map();
+    for (const remark of round.remarks) {
+        const list = pages.get(remark.designId);
+        if (list)
+            list.push(remark);
+        else
+            pages.set(remark.designId, [remark]);
+    }
+    const progress = roundProgress(round);
+    const lines = [
+        `Feedback round ${round.number} "${round.title}" — submitted ${round.submittedAt} — ` +
+            `${round.remarks.length} remark(s) on ${pages.size} page(s), ${progress.done} processed.`,
+        "Coordinates are design pixels in the artboard's space, as in get_design.",
+    ];
+    let image = 0;
+    for (const [designId, remarks] of pages) {
+        lines.push("", `Page "${remarks[0].designName}" (${designId})`);
+        for (const remark of remarks) {
+            const capture = remark.capture ? ` — capture: image ${++image}` : "";
+            const target = remark.target;
+            let head;
+            if (target.kind === "page") {
+                head = `- ${remark.id} [whole page]`;
+            }
+            else if (target.kind === "node") {
+                head =
+                    `- ${remark.id} [#${remark.number} · element] ${formatElement(target.element)} — ` +
+                        `path: ${target.path.join(PATH_SEPARATOR)} — box ${formatBox(target.box)}${capture}`;
+            }
+            else {
+                const elements = target.elements.length > 0 ? target.elements.map(formatElement).join(", ") : "no element selected";
+                head = `- ${remark.id} [#${remark.number} · area] box ${formatBox(target.box)} — elements: ${elements}${capture}`;
+            }
+            lines.push(head, indent(remark.text, "    "));
+            if (remark.processed) {
+                const note = remark.processed.note ? `: ${remark.processed.note}` : "";
+                lines.push(`    ✓ processed by ${remark.processed.by} at ${remark.processed.at}${note}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}

package/dist/shared/node-defaults.js

@@ -1,6 +1,6 @@
 import { defaultLineHeight } from "./render.js";
 import { DEFAULT_ICON_STROKE_WIDTH, ICON_GRID } from "./icons/index.js";
-export const NODE_KINDS = ["rect", "ellipse", "line", "text", "icon", "group", "instance"];
+export const NODE_KINDS = ["rect", "ellipse", "line", "text", "icon", "image", "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", "icon"];
 export const NODE_DEFAULTS = {
@@ -34,6 +34,9 @@ export const NODE_DEFAULTS = {
         stroke: "#1a1a18",
         strokeWidth: DEFAULT_ICON_STROKE_WIDTH,
     },
+    // Une image importee sans taille prend ses dimensions naturelles : celles-ci
+    // ne servent qu'a un noeud ecrit a la main sans largeur ni hauteur.
+    image: { width: 200, height: 150, fit: "cover" },
     // 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.
@@ -46,6 +49,7 @@ export const NODE_STYLE_FIELDS = {
     line: ["stroke", "strokeWidth"],
     text: ["text", "color", "fontSize", "fontFamily", "fontWeight", "fontStyle", "textAlign", "lineHeight"],
     icon: ["icon", "fill", "stroke", "strokeWidth"],
+    image: ["image", "fit"],
     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.
@@ -72,6 +76,7 @@ const LABELS = {
     line: "Ligne",
     text: "Texte",
     icon: "Icône",
+    image: "Image",
     group: "Groupe",
     instance: "Instance",
 };

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

@@ -22,6 +22,8 @@ export declare const NODE_FIELD_DOCS: {
     strokeWidth: string;
     radius: string;
     icon: string;
+    image: string;
+    fit: string;
     componentId: string;
     text: string;
     color: 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, icon, group or instance.",
+    type: "Kind of node: rect, ellipse, line, text, icon, image, 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. " +
@@ -40,6 +40,10 @@ export const NODE_FIELD_DOCS = {
         "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.",
+    image: "Image nodes only: name of the stored image file, e.g. \"img_3f9a1c2b7d4e.png\". It is returned by add_image, which is the way " +
+        "to bring a new picture into the design; reuse the same name to place that picture again without importing it twice.",
+    fit: "Image nodes only: how the picture fills its box. cover (default) fills the whole box and crops the overflow, " +
+        "contain shows the whole picture inside the box, leaving empty bands, fill stretches it to the box.",
     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, " +

package/dist/shared/render.d.ts

@@ -6,13 +6,13 @@
  * Ce module ne dépend volontairement d'aucune librairie (pas de zod) pour rester
  * importable depuis le bundle GUI.
  */
-import { normalizedBox } from "./tree.js";
+import { normalizedBox, type Box } 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" | "icon" | "group" | "instance";
+    type: "rect" | "ellipse" | "line" | "text" | "icon" | "image" | "group" | "instance";
     name: string;
     /** Groupe conteneur, ou null a la racine. Les coordonnees sont relatives a ce parent. */
     parentId: string | null;
@@ -30,6 +30,10 @@ export interface RenderNode {
     radius?: number;
     /** Nom de l'icone dans la bibliotheque embarquee, p.ex. "shopping-cart". Type `icon` uniquement. */
     icon?: string;
+    /** Nom du fichier dans la mediatheque, p.ex. "img_3f9a1c2b7d4e.png". Type `image` uniquement. */
+    image?: string;
+    /** Remplissage de la boite par l'image. Type `image` uniquement. */
+    fit?: "cover" | "contain" | "fill";
     text?: string;
     color?: string;
     fontSize?: number;
@@ -131,13 +135,28 @@ export declare function iconElementsOf(node: RenderNode): IconElement[];
  * en noir sur une icone blanche.
  */
 export declare function iconStyle(node: RenderNode): Record<string, string>;
+/**
+ * Adresse d'une image de la mediatheque dans le SVG produit.
+ *
+ * Elle depend de qui lit le SVG : le canvas la charge depuis l'API du worker,
+ * resvg et les exports autonomes ont besoin des octets en data URI.
+ */
+export type ImageHref = (image: string) => string;
+export interface RenderOptions {
+    /** Obligatoire des que la planche contient une image. */
+    imageHref?: ImageHref;
+}
+/** Valeur de `preserveAspectRatio` correspondant au `fit` du noeud. */
+export declare function imageAspect(node: RenderNode): string;
+/** Adresse de l'image du noeud ; echoue si l'appelant n'a pas dit comment la resoudre. */
+export declare function imageSource(node: RenderNode, options: RenderOptions): 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
  * `documentToSvg` (serveur) ou par le canvas (navigateur).
  */
-export declare function nodeToSvg(node: RenderNode): string;
+export declare function nodeToSvg(node: RenderNode, options?: RenderOptions): string;
 export interface RenderDocument {
     name: string;
     width: number;
@@ -145,7 +164,13 @@ export interface RenderDocument {
     background: string;
     nodes: RenderNode[];
 }
-export declare function documentToSvg(doc: RenderDocument): string;
+export declare function documentToSvg(doc: RenderDocument, options?: RenderOptions): string;
+/**
+ * SVG cadré sur une zone rectangulaire de la planche, en coordonnées document.
+ * Tout ce qui recoupe la zone y figure, coupé à ses bords ; les éléments
+ * semi-transparents qui ne la recoupent pas sont omis.
+ */
+export declare function regionToSvg(doc: RenderDocument, region: Box, options?: RenderOptions): string;
 /**
  * SVG cadré sur un seul élément — l'élément et son contenu, rien d'autre.
  *
@@ -153,4 +178,4 @@ export declare function documentToSvg(doc: RenderDocument): string;
  * position document : le viewBox peut alors être exprimé dans le même repère
  * que `computeLayout`, donc directement sur la boîte englobante de l'élément.
  */
-export declare function subtreeToSvg(doc: RenderDocument, nodeId: string, padding?: number): string;
+export declare function subtreeToSvg(doc: RenderDocument, nodeId: string, padding?: number, options?: RenderOptions): string;