@imenam/mcp-design 1.0.10 → 1.0.11

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.
@@ -241,6 +244,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 +277,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 +311,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 +342,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/render.d.ts

@@ -6,7 +6,7 @@
  * 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";
@@ -146,6 +146,12 @@ export interface RenderDocument {
     nodes: RenderNode[];
 }
 export declare function documentToSvg(doc: RenderDocument): 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): string;
 /**
  * SVG cadré sur un seul élément — l'élément et son contenu, rien d'autre.
  *

package/dist/shared/render.js

@@ -6,7 +6,7 @@
  * Ce module ne dépend volontairement d'aucune librairie (pas de zod) pour rester
  * importable depuis le bundle GUI.
  */
-import { boundsOf, childrenByParent, computeLayout, normalizedBox, spaceOriginOf } from "./tree.js";
+import { boundsOf, boxesIntersect, 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
@@ -238,24 +238,31 @@ export function nodeToSvg(node) {
 /**
  * Rend une liste de noeuds frères, en descendant récursivement dans les groupes.
  * Partagé par le rendu plein document et le rendu cadré sur un seul élément.
+ *
+ * Avec `frame`, un élément semi-transparent qui ne recoupe pas le cadre est
+ * omis : il n'y serait pas visible, et resvg panique — en emportant le
+ * processus — sur un élément semi-transparent dessiné entièrement hors du cadre.
  */
-function renderSiblings(nodes, children, layout, depth) {
+function renderSiblings(nodes, children, layout, depth, frame) {
     const pad = "  ".repeat(depth + 1);
     return nodes.flatMap((node) => {
+        const bounds = boundsOf(layout, node.id);
+        if (frame && node.opacity < 1 && !boxesIntersect(bounds, frame))
+            return [];
         if (node.type !== "group")
             return [`${pad}${nodeToSvg(node)}`];
-        const bounds = boundsOf(layout, node.id);
         const origin = layout.origin.get(node.id) ?? { x: 0, y: 0 };
         const center = { cx: bounds.x + bounds.width / 2 - origin.x, cy: bounds.y + bounds.height / 2 - origin.y };
         const opacity = node.opacity >= 1 ? "" : ` opacity="${round(node.opacity)}"`;
         return [
             `${pad}<g transform="${groupTransform(node, center)}"${opacity}>`,
-            ...renderSiblings(children.get(node.id) ?? [], children, layout, depth + 1),
+            ...renderSiblings(children.get(node.id) ?? [], children, layout, depth + 1, frame),
             `${pad}</g>`,
         ];
     });
 }
-export function documentToSvg(doc) {
+/** Contenu SVG de la planche, en coordonnées document, limité à `frame` s'il est donné. */
+function documentBody(doc, frame) {
     // 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);
@@ -263,13 +270,32 @@ export function documentToSvg(doc) {
     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");
+    return renderSiblings(children.get(null) ?? [], children, layout, 0, frame).join("\n");
+}
+export function documentToSvg(doc) {
+    const body = documentBody(doc);
     return (`<svg xmlns="http://www.w3.org/2000/svg" width="${doc.width}" height="${doc.height}" ` +
         `viewBox="0 0 ${doc.width} ${doc.height}">\n` +
         `  <rect x="0" y="0" width="${doc.width}" height="${doc.height}" fill="${escapeXml(doc.background)}" />\n` +
         (body ? `${body}\n` : "") +
         `</svg>`);
 }
+/**
+ * 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 function regionToSvg(doc, region) {
+    const body = documentBody(doc, region);
+    const width = round(Math.max(1, region.width));
+    const height = round(Math.max(1, region.height));
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" ` +
+        `viewBox="${round(region.x)} ${round(region.y)} ${width} ${height}">\n` +
+        `  <rect x="${round(region.x)}" y="${round(region.y)}" width="${width}" height="${height}" ` +
+        `fill="${escapeXml(doc.background)}" />\n` +
+        (body ? `${body}\n` : "") +
+        `</svg>`);
+}
 /**
  * SVG cadré sur un seul élément — l'élément et son contenu, rien d'autre.
  *