@imenam/mcp-design 1.0.1

package/dist/shared/tree.js

@@ -0,0 +1,223 @@
+/** Boîte englobante normalisée (largeur/hauteur toujours positives). */
+export function normalizedBox(node) {
+    const x = node.width < 0 ? node.x + node.width : node.x;
+    const y = node.height < 0 ? node.y + node.height : node.y;
+    return { x, y, width: Math.abs(node.width), height: Math.abs(node.height) };
+}
+/** Enfants directs de chaque parent, dans l'ordre du tableau (donc l'ordre d'empilement). */
+export function childrenByParent(nodes) {
+    const map = new Map();
+    for (const node of nodes) {
+        const siblings = map.get(node.parentId);
+        if (siblings)
+            siblings.push(node);
+        else
+            map.set(node.parentId, [node]);
+    }
+    return map;
+}
+export function rootNodes(nodes) {
+    return nodes.filter((node) => node.parentId === null);
+}
+/** Chaîne des ancêtres, du parent direct jusqu'à la racine. */
+export function ancestorsOf(nodes, id) {
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const chain = [];
+    let current = byId.get(id)?.parentId ?? null;
+    // La borne empêche une boucle infinie si un cycle a échappé à la validation.
+    while (current !== null && chain.length <= nodes.length) {
+        const parent = byId.get(current);
+        if (!parent)
+            break;
+        chain.push(parent);
+        current = parent.parentId;
+    }
+    return chain;
+}
+/** Ancêtre le plus haut d'un élément, ou l'élément lui-même s'il est à la racine. */
+export function outermostAncestor(nodes, id) {
+    const chain = ancestorsOf(nodes, id);
+    return chain.length > 0 ? chain[chain.length - 1] : nodes.find((node) => node.id === id);
+}
+/** Identifiants de tous les descendants d'un élément (lui-même exclu). */
+export function descendantIds(nodes, id) {
+    const children = childrenByParent(nodes);
+    const found = new Set();
+    const queue = [id];
+    while (queue.length > 0) {
+        for (const child of children.get(queue.pop()) ?? []) {
+            if (found.has(child.id))
+                continue;
+            found.add(child.id);
+            queue.push(child.id);
+        }
+    }
+    return found;
+}
+/**
+ * Réécrit la liste à plat en parcours préfixe : chaque parent est suivi de son
+ * sous-arbre. L'ordre relatif entre frères — donc l'empilement — est préservé.
+ *
+ * Le stockage garde ainsi une forme unique pour un même arbre, ce qui évite au
+ * diff de signaler un réordonnancement là où rien n'a bougé visuellement.
+ */
+export function flattenPreOrder(nodes) {
+    const children = childrenByParent(nodes);
+    const emitted = new Set();
+    const result = [];
+    const visit = (node) => {
+        if (emitted.has(node.id))
+            return;
+        emitted.add(node.id);
+        result.push(node);
+        for (const child of children.get(node.id) ?? [])
+            visit(child);
+    };
+    for (const node of children.get(null) ?? [])
+        visit(node);
+    // Filet : un noeud dont le parent a disparu reste dans la liste plutôt que d'être perdu.
+    for (const node of nodes)
+        visit(node);
+    return result;
+}
+const ORIGIN = { x: 0, y: 0 };
+function unionBox(boxes) {
+    if (boxes.length === 0)
+        return null;
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const box of boxes) {
+        minX = Math.min(minX, box.x);
+        minY = Math.min(minY, box.y);
+        maxX = Math.max(maxX, box.x + box.width);
+        maxY = Math.max(maxY, box.y + box.height);
+    }
+    return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+/**
+ * Résout toute la hiérarchie en coordonnées document, en une passe.
+ *
+ * La rotation n'entre pas dans le calcul des boîtes : comme pour un rectangle
+ * pivoté, la boîte d'un groupe pivoté reste sa boîte non pivotée. C'est ce que
+ * le cadre de sélection affiche déjà, et le rendu, lui, applique bien la rotation.
+ */
+export function computeLayout(nodes) {
+    const children = childrenByParent(nodes);
+    const origin = new Map();
+    const bounds = new Map();
+    const visit = (node, spaceOrigin) => {
+        if (node.type !== "group") {
+            const local = normalizedBox(node);
+            const box = { x: spaceOrigin.x + local.x, y: spaceOrigin.y + local.y, width: local.width, height: local.height };
+            bounds.set(node.id, box);
+            return box;
+        }
+        const groupOrigin = { x: spaceOrigin.x + node.x, y: spaceOrigin.y + node.y };
+        origin.set(node.id, groupOrigin);
+        const childBoxes = (children.get(node.id) ?? []).map((child) => visit(child, groupOrigin));
+        // Un groupe vide n'a pas de contenu à englober : il reste un point, ce qui
+        // le laisse sélectionnable dans la liste des calques sans polluer le canvas.
+        const box = unionBox(childBoxes) ?? { x: groupOrigin.x, y: groupOrigin.y, width: 0, height: 0 };
+        bounds.set(node.id, box);
+        return box;
+    };
+    for (const node of children.get(null) ?? [])
+        visit(node, ORIGIN);
+    // Les éléments dont le parent a disparu sont rendus à la racine plutôt que
+    // d'être silencieusement invisibles.
+    for (const node of nodes) {
+        if (!bounds.has(node.id))
+            visit(node, ORIGIN);
+    }
+    return { origin, bounds };
+}
+/** Origine de l'espace de coordonnées dans lequel vit un élément. */
+export function spaceOriginOf(layout, parentId) {
+    return (parentId === null ? undefined : layout.origin.get(parentId)) ?? ORIGIN;
+}
+export function boundsOf(layout, id) {
+    return layout.bounds.get(id) ?? { x: 0, y: 0, width: 0, height: 0 };
+}
+/** Boîte englobante commune à plusieurs éléments, en coordonnées document. */
+export function unionBoundsOf(layout, ids) {
+    return unionBox(ids.map((id) => layout.bounds.get(id)).filter((box) => box !== undefined));
+}
+// --- Ordre d'empilement -----------------------------------------------------
+export const REORDER_DIRECTIONS = ["front", "back", "forward", "backward"];
+/**
+ * Retire d'une sélection les éléments dont un ancêtre est déjà sélectionné.
+ *
+ * Déplacer un enfant en même temps que son groupe n'a pas de sens : le groupe
+ * emporte déjà son contenu, et les deux gestes s'appliqueraient dans des
+ * fratries différentes.
+ */
+export function withoutRedundantDescendants(nodes, ids) {
+    const selected = new Set(ids);
+    return ids.filter((id) => !ancestorsOf(nodes, id).some((ancestor) => selected.has(ancestor.id)));
+}
+/**
+ * Change l'ordre d'empilement d'un ou plusieurs éléments.
+ *
+ * L'empilement est **relatif à la fratrie** : un élément ne peut passer devant
+ * que ses frères, jamais devant le contenu d'un autre groupe — c'est le groupe
+ * lui-même qu'il faut alors déplacer. Chaque fratrie concernée est réordonnée
+ * indépendamment, puis la liste plate est reconstruite en parcours préfixe.
+ *
+ * `forward`/`backward` décalent d'un cran ; `front`/`back` vont au bout. Un
+ * élément déjà au bout de sa fratrie ne bouge pas, et un lot d'éléments garde
+ * son ordre relatif d'origine.
+ */
+export function reorderNodes(nodes, ids, direction) {
+    const targets = new Set(withoutRedundantDescendants(nodes, ids));
+    if (targets.size === 0)
+        return nodes;
+    const children = childrenByParent(nodes);
+    for (const [parentId, siblings] of children) {
+        const moving = siblings.filter((node) => targets.has(node.id));
+        if (moving.length === 0)
+            continue;
+        let next = [...siblings];
+        if (direction === "front") {
+            next = [...next.filter((node) => !targets.has(node.id)), ...moving];
+        }
+        else if (direction === "back") {
+            next = [...moving, ...next.filter((node) => !targets.has(node.id))];
+        }
+        else {
+            const step = direction === "forward" ? 1 : -1;
+            const indexes = next.map((node, index) => (targets.has(node.id) ? index : -1)).filter((index) => index >= 0);
+            // On part du bord vers lequel on pousse, sinon deux éléments adjacents se
+            // marchent dessus et le lot se désagrège.
+            for (const index of step === 1 ? indexes.reverse() : indexes) {
+                const swap = index + step;
+                if (swap < 0 || swap >= next.length || targets.has(next[swap].id))
+                    continue;
+                [next[index], next[swap]] = [next[swap], next[index]];
+            }
+        }
+        children.set(parentId, next);
+    }
+    const emitted = new Set();
+    const flat = [];
+    const visit = (parentId) => {
+        for (const node of children.get(parentId) ?? []) {
+            if (emitted.has(node.id))
+                continue;
+            emitted.add(node.id);
+            flat.push(node);
+            visit(node.id);
+        }
+    };
+    visit(null);
+    // Filet identique à flattenPreOrder : un noeud dont le parent a disparu reste
+    // dans la liste plutôt que d'être perdu.
+    for (const node of nodes) {
+        if (!emitted.has(node.id)) {
+            emitted.add(node.id);
+            flat.push(node);
+        }
+    }
+    return flat;
+}

package/dist/src/cli/setup-mcp.d.ts

@@ -0,0 +1,5 @@
+export interface SetupMcpOptions {
+    cwd: string;
+    force: boolean;
+}
+export declare function runSetupMcp({ cwd, force }: SetupMcpOptions): number;

package/dist/src/cli/setup-mcp.js

@@ -0,0 +1,87 @@
+import fs from "fs";
+import path from "path";
+const SERVER_NAME = "mcp-design";
+const PACKAGE_NAME = "@imenam/mcp-design";
+/** Slashes POSIX : évite les backslashes échappés dans le JSON, et Node les accepte sous Windows. */
+function toPosixPath(dir) {
+    return dir.replace(/\\/g, "/");
+}
+/** "mcp-design" -> "Mcp-design" */
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/** "mon_projet-web" -> "Mon Projet Web" */
+function toDisplayName(folder) {
+    return folder.split(/[-_]+/).filter(Boolean).map(capitalize).join(" ");
+}
+/**
+ * Valeurs volontairement vides : chaque variable est inactive tant qu'elle n'est
+ * pas remplie (PROXY_URL vide = GUI désactivée), donc le fichier généré est
+ * utilisable tel quel, jamais à moitié cassé.
+ */
+function buildServerEntry(codeRoot) {
+    const folder = path.basename(codeRoot) || "design";
+    return {
+        command: "npx",
+        args: ["-y", PACKAGE_NAME],
+        env: {
+            PROXY_URL: "http://localhost:",
+            APP_GROUP: capitalize(folder),
+            APP_NAME: `Design ${toDisplayName(folder)}`,
+            APP_PATH: `/design-${folder}`,
+            MCP_DESIGN_DATA_DIR: toPosixPath(path.join(codeRoot, ".design-data")),
+            MCP_LOG_DIR: "",
+        },
+    };
+}
+const GENERATED_VARS = [
+    ["PROXY_URL", "URL du proxy pour exposer la GUI (compléter le port)"],
+    ["APP_GROUP", "groupe d'affichage dans le dashboard du proxy"],
+    ["APP_NAME", "nom affiché de la GUI dans le dashboard du proxy"],
+    ["APP_PATH", "chemin de montage de la GUI derrière le proxy"],
+    ["MCP_DESIGN_DATA_DIR", "répertoire de stockage des designs (pré-rempli)"],
+    ["MCP_LOG_DIR", "répertoire des logs (défaut : <data>/logs)"],
+];
+export function runSetupMcp({ cwd, force }) {
+    const target = path.join(cwd, ".mcp.json");
+    let config = {};
+    const exists = fs.existsSync(target);
+    if (exists) {
+        const raw = fs.readFileSync(target, "utf-8").trim();
+        if (raw !== "") {
+            try {
+                config = JSON.parse(raw);
+            }
+            catch (err) {
+                console.error(`Erreur : ${target} contient du JSON invalide (${err.message}).`);
+                console.error("Corrigez le fichier ou supprimez-le, puis relancez la commande.");
+                return 1;
+            }
+        }
+        if (typeof config !== "object" || config === null || Array.isArray(config)) {
+            console.error(`Erreur : ${target} ne contient pas un objet JSON.`);
+            return 1;
+        }
+    }
+    if (typeof config.mcpServers !== "object" || config.mcpServers === null || Array.isArray(config.mcpServers)) {
+        config.mcpServers = {};
+    }
+    const alreadyPresent = Object.prototype.hasOwnProperty.call(config.mcpServers, SERVER_NAME);
+    if (alreadyPresent && !force) {
+        console.error(`Le serveur "${SERVER_NAME}" est déjà configuré dans ${target}.`);
+        console.error("Relancez avec --force pour écraser cette entrée (les autres serveurs sont préservés).");
+        return 1;
+    }
+    config.mcpServers[SERVER_NAME] = buildServerEntry(cwd);
+    fs.writeFileSync(target, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    const action = alreadyPresent ? "remplacée" : exists ? "ajoutée" : "créée";
+    console.log(`Configuration ${SERVER_NAME} ${action} dans ${target}`);
+    console.log("");
+    console.log('À compléter dans le champ "env" :');
+    for (const [name, description] of GENERATED_VARS) {
+        console.log(`  ${name.padEnd(24)} ${description}`);
+    }
+    console.log("");
+    console.log("Une variable laissée vide est simplement inactive.");
+    return 0;
+}

package/dist/src/core/design-store.d.ts

@@ -0,0 +1,61 @@
+import { type Design, type DesignSummary } from "../../shared/schemas/design.schema.js";
+export interface CreateDesignInput {
+    name: string;
+    width?: number;
+    height?: number;
+    background?: string;
+}
+export interface MutateOptions {
+    /**
+     * Révision sur laquelle l'édition est basée. Quand elle est fournie et que le
+     * fichier a avancé entre-temps, l'écriture est refusée : sans cette garde, un
+     * éditeur parti d'un état périmé réécrit le document entier et efface le
+     * travail de l'autre.
+     */
+    baseRevision?: number;
+}
+/**
+ * Persistance des designs : un fichier JSON par design dans <dataDir>/designs.
+ * Pas de base de données — un design tient dans quelques dizaines de Ko et le
+ * format doit rester lisible/diffable à la main.
+ */
+export declare class DesignStore {
+    private readonly dataDir;
+    private readonly designsDir;
+    /**
+     * Cache mémoire : la GUI sauvegarde à chaque geste, relire le disque à chaque
+     * fois serait inutile. Chaque entrée retient la signature du fichier au moment
+     * de la lecture — plusieurs processus (une seconde GUI, un second agent MCP)
+     * partagent le même dataDir, le cache ne peut donc jamais faire autorité seul.
+     */
+    private cache;
+    constructor(rootDir: string);
+    getDataDir(): string;
+    private filePath;
+    /** Signature du fichier, ou null s'il n'existe pas encore. */
+    private stampOf;
+    private remember;
+    private write;
+    /**
+     * Sérialise le cycle lire-modifier-écrire entre processus. `wx` échoue si le
+     * fichier existe déjà : c'est l'opération atomique qui départage deux
+     * écrivains concurrents. Non réentrant — ne jamais appeler depuis `fn`.
+     */
+    private withLock;
+    /** Identifiant lisible dérivé du nom, suffixé seulement en cas de collision. */
+    private allocateId;
+    list(): DesignSummary[];
+    has(id: string): boolean;
+    get(id: string): Design;
+    create(input: CreateDesignInput): Design;
+    /**
+     * Applique une mutation et incrémente la révision. `editor` distingue une
+     * modification de l'agent d'une modification faite à la main dans la GUI —
+     * c'est ce qui permet à get_changes de rester lisible.
+     */
+    mutate(id: string, editor: "agent" | "user", fn: (design: Design) => void, options?: MutateOptions): Design;
+    private mutateLocked;
+    /** Fige l'état courant comme nouvelle référence de comparaison. */
+    markSynced(id: string): Design;
+    delete(id: string): void;
+}

package/dist/src/core/design-store.js

@@ -0,0 +1,294 @@
+import fs from "fs";
+import path from "path";
+import { DesignSchema, } from "../../shared/schemas/design.schema.js";
+import { DesignError } from "./node-factory.js";
+import { normalizeHierarchy } from "./hierarchy.js";
+import { migrateDesign } from "./migrate.js";
+import { shortId, slugify } from "./ids.js";
+import { countChanges } from "./diff.js";
+/** Au-delà de ce délai, un verrou est réputé abandonné (processus tué en cours d'écriture). */
+const LOCK_STALE_MS = 10_000;
+const LOCK_RETRY_MS = 25;
+const LOCK_TIMEOUT_MS = 5_000;
+/**
+ * Pause bloquante. Le store est entièrement synchrone — le rendre asynchrone
+ * pour l'attente d'un verrou contaminerait tous les appelants.
+ */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Persistance des designs : un fichier JSON par design dans <dataDir>/designs.
+ * Pas de base de données — un design tient dans quelques dizaines de Ko et le
+ * format doit rester lisible/diffable à la main.
+ */
+export class DesignStore {
+    dataDir;
+    designsDir;
+    /**
+     * Cache mémoire : la GUI sauvegarde à chaque geste, relire le disque à chaque
+     * fois serait inutile. Chaque entrée retient la signature du fichier au moment
+     * de la lecture — plusieurs processus (une seconde GUI, un second agent MCP)
+     * partagent le même dataDir, le cache ne peut donc jamais faire autorité seul.
+     */
+    cache = new Map();
+    constructor(rootDir) {
+        // MCP_DESIGN_DATA_DIR est prioritaire ; MCP_DATA_DIR reste accepté pour rester
+        // aligné sur la convention commune aux autres MCPs de l'écosystème.
+        const configured = process.env.MCP_DESIGN_DATA_DIR?.trim() || process.env.MCP_DATA_DIR?.trim();
+        this.dataDir = configured ? path.resolve(configured) : path.join(rootDir, ".design-data");
+        this.designsDir = path.join(this.dataDir, "designs");
+        fs.mkdirSync(this.designsDir, { recursive: true });
+    }
+    getDataDir() {
+        return this.dataDir;
+    }
+    filePath(id) {
+        return path.join(this.designsDir, `${id}.json`);
+    }
+    /** Signature du fichier, ou null s'il n'existe pas encore. */
+    stampOf(id) {
+        try {
+            const stat = fs.statSync(this.filePath(id));
+            return { mtimeMs: stat.mtimeMs, size: stat.size };
+        }
+        catch {
+            return null;
+        }
+    }
+    remember(design) {
+        const stamp = this.stampOf(design.id);
+        // Sans signature lisible, on préfère ne rien cacher : la prochaine lecture
+        // repartira du disque plutôt que de servir un état peut-être dépassé.
+        if (stamp)
+            this.cache.set(design.id, { design, stamp });
+        else
+            this.cache.delete(design.id);
+    }
+    write(design) {
+        // Écriture atomique : un crash pendant l'écriture ne laisse pas un JSON tronqué.
+        const target = this.filePath(design.id);
+        const tmp = `${target}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(design, null, 2), "utf-8");
+        fs.renameSync(tmp, target);
+        // La signature est relue après le rename : sans ça, la lecture suivante
+        // prendrait notre propre écriture pour une modification externe.
+        this.remember(design);
+    }
+    /**
+     * Sérialise le cycle lire-modifier-écrire entre processus. `wx` échoue si le
+     * fichier existe déjà : c'est l'opération atomique qui départage deux
+     * écrivains concurrents. Non réentrant — ne jamais appeler depuis `fn`.
+     */
+    withLock(id, fn) {
+        const lockPath = `${this.filePath(id)}.lock`;
+        const deadline = Date.now() + LOCK_TIMEOUT_MS;
+        let fd;
+        for (;;) {
+            try {
+                fd = fs.openSync(lockPath, "wx");
+                break;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+                try {
+                    // Un processus tué laisse son verrou derrière lui : passé le délai
+                    // d'obsolescence on le casse, sinon le design serait bloqué à vie.
+                    if (Date.now() - fs.statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+                        fs.unlinkSync(lockPath);
+                        continue;
+                    }
+                }
+                catch {
+                    continue; // Verrou disparu entre le open et le stat : on retente aussitôt.
+                }
+                if (Date.now() > deadline) {
+                    throw new DesignError(`Design "${id}" is being written by another editor and did not free up in ${LOCK_TIMEOUT_MS} ms. Try again in a moment.`);
+                }
+                sleepSync(LOCK_RETRY_MS);
+            }
+        }
+        try {
+            return fn();
+        }
+        finally {
+            fs.closeSync(fd);
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch {
+                // Verrou déjà cassé pour obsolescence par un autre processus.
+            }
+        }
+    }
+    /** Identifiant lisible dérivé du nom, suffixé seulement en cas de collision. */
+    allocateId(name) {
+        const base = slugify(name);
+        if (!fs.existsSync(this.filePath(base)))
+            return base;
+        for (let i = 2; i < 100; i++) {
+            const candidate = `${base}-${i}`;
+            if (!fs.existsSync(this.filePath(candidate)))
+                return candidate;
+        }
+        return `${base}-${shortId("x", 4)}`;
+    }
+    list() {
+        const files = fs.existsSync(this.designsDir)
+            ? fs.readdirSync(this.designsDir).filter((f) => f.endsWith(".json"))
+            : [];
+        const summaries = [];
+        for (const file of files) {
+            const id = file.slice(0, -".json".length);
+            let design;
+            try {
+                design = this.get(id);
+            }
+            catch {
+                continue; // Fichier corrompu ou hors schéma : il ne doit pas casser la liste.
+            }
+            summaries.push({
+                id: design.id,
+                name: design.name,
+                width: design.width,
+                height: design.height,
+                nodeCount: design.nodes.length,
+                updatedAt: design.updatedAt,
+                revision: design.revision,
+                lastEditor: design.lastEditor,
+                pendingChanges: countChanges(design.baseline.nodes, design.nodes),
+            });
+        }
+        return summaries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    has(id) {
+        return fs.existsSync(this.filePath(id));
+    }
+    get(id) {
+        const stamp = this.stampOf(id);
+        const cached = this.cache.get(id);
+        // Le cache ne vaut que tant que le fichier n'a pas bougé sous nos pieds.
+        if (cached && stamp && cached.stamp.mtimeMs === stamp.mtimeMs && cached.stamp.size === stamp.size) {
+            return cached.design;
+        }
+        this.cache.delete(id);
+        const file = this.filePath(id);
+        if (!fs.existsSync(file)) {
+            throw new DesignError(`Design "${id}" not found. Use list_designs to see the available designs.`);
+        }
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(file, "utf-8"));
+        }
+        catch (err) {
+            throw new DesignError(`Design "${id}" is not readable: ${err.message}`);
+        }
+        // Mise à niveau du format avant validation : un fichier écrit par une
+        // version antérieure reste lisible, et n'est réécrit qu'en cas de changement.
+        const migrated = migrateDesign(raw);
+        const parsed = DesignSchema.safeParse(migrated ?? raw);
+        if (!parsed.success) {
+            throw new DesignError(`Design "${id}" does not match the expected schema: ${parsed.error.issues
+                .map((i) => `${i.path.join(".")} ${i.message}`)
+                .join("; ")}`);
+        }
+        if (migrated) {
+            // Best effort : un répertoire de données en lecture seule ne doit pas
+            // empêcher de lire le design, la migration reste appliquée en mémoire.
+            // Écriture volontairement hors verrou : `get` est appelé depuis l'intérieur
+            // de `withLock`, et le verrou n'est pas réentrant. Le contenu écrit est
+            // celui qu'on vient de lire, la mise à niveau ne perd donc rien.
+            try {
+                this.write(parsed.data);
+            }
+            catch {
+                this.cache.delete(id);
+            }
+            return parsed.data;
+        }
+        if (stamp)
+            this.cache.set(id, { design: parsed.data, stamp });
+        return parsed.data;
+    }
+    create(input) {
+        const name = input.name?.trim();
+        if (!name)
+            throw new DesignError(`"name" is required to create a design.`);
+        const width = input.width ?? 1440;
+        const height = input.height ?? 900;
+        if (!Number.isFinite(width) || width <= 0)
+            throw new DesignError(`"width" must be a positive number.`);
+        if (!Number.isFinite(height) || height <= 0)
+            throw new DesignError(`"height" must be a positive number.`);
+        const now = new Date().toISOString();
+        const design = {
+            id: this.allocateId(name),
+            name,
+            width,
+            height,
+            background: input.background ?? "#ffffff",
+            nodes: [],
+            createdAt: now,
+            updatedAt: now,
+            revision: 0,
+            lastEditor: "agent",
+            baseline: { revision: 0, at: now, nodes: [] },
+        };
+        this.write(design);
+        return design;
+    }
+    /**
+     * Applique une mutation et incrémente la révision. `editor` distingue une
+     * modification de l'agent d'une modification faite à la main dans la GUI —
+     * c'est ce qui permet à get_changes de rester lisible.
+     */
+    mutate(id, editor, fn, options = {}) {
+        // Tout le cycle lire-modifier-écrire tient dans le verrou : hors de là, deux
+        // processus peuvent lire le même état puis s'écraser l'un l'autre.
+        return this.withLock(id, () => this.mutateLocked(id, editor, fn, options));
+    }
+    mutateLocked(id, editor, fn, options) {
+        const current = this.get(id);
+        if (options.baseRevision !== undefined && options.baseRevision !== current.revision) {
+            throw new DesignError(`Design "${id}" has changed since it was loaded: your edit is based on revision ${options.baseRevision}, ` +
+                `the stored design is at revision ${current.revision}. Reload it with get_design and reapply your change — ` +
+                `writing now would discard the other editor's work.`);
+        }
+        const draft = structuredClone(current);
+        fn(draft);
+        // Les invariants de hiérarchie sont vérifiés ici, une seule fois : aucun
+        // appelant — outil MCP ou sauvegarde depuis la GUI — ne peut les contourner.
+        draft.nodes = normalizeHierarchy(draft.nodes);
+        draft.revision = current.revision + 1;
+        draft.updatedAt = new Date().toISOString();
+        draft.lastEditor = editor;
+        const parsed = DesignSchema.safeParse(draft);
+        if (!parsed.success) {
+            throw new DesignError(`Resulting design is invalid: ${parsed.error.issues.map((i) => `${i.path.join(".")} ${i.message}`).join("; ")}`);
+        }
+        this.write(parsed.data);
+        return parsed.data;
+    }
+    /** Fige l'état courant comme nouvelle référence de comparaison. */
+    markSynced(id) {
+        return this.withLock(id, () => {
+            const current = this.get(id);
+            const now = new Date().toISOString();
+            const next = {
+                ...structuredClone(current),
+                baseline: { revision: current.revision, at: now, nodes: structuredClone(current.nodes) },
+            };
+            this.write(next);
+            return next;
+        });
+    }
+    delete(id) {
+        const file = this.filePath(id);
+        if (!fs.existsSync(file)) {
+            throw new DesignError(`Design "${id}" not found.`);
+        }
+        fs.unlinkSync(file);
+        this.cache.delete(id);
+    }
+}