Pixerate/pixerate-canvas

Canevas Pixerate

Le canevas est un graphe xyflow (React Flow / SvelteFlow) : un tableau de nœuds et d'arêtes. Un nœud est { id, type, position: { x, y }, width?, height?, parentId?, zIndex?, data } ; les arêtes sont { id, source, target, label? }. Tout ce qu'une fonctionnalité de conception connaît vit dans node.data, donc il survit aux copier-coller et au JSON :

• data.label / data.name : contenu textuel et nom de calque. data.shape : un nœud de forme ({ kind: rect | ellipse | polygon | star | path, fill, stroke, strokeWidth, ... }).
• data.layout : un cadre de disposition automatique (mode horizontal / vertical / grille, gap, padding, alignMain, alignCross, sizing) ; ses enfants sont les nœuds dont parentId est le cadre, dans l'ordre du tableau de nœuds. data.childLayout : le dimensionnement d'un enfant (fixe / ajusté / rempli) et ses contraintes.
• data.component (un composant principal), data.componentSet (un ensemble de variantes), data.instance ({ componentId, properties }) et data.componentOverrides.
• data.locked, data.animation (pistes d'images clés), data.tokenBindings (jetons de conception).

Les positions sont en unités de canevas (flux) ; la position d'un enfant est relative à son parent. Les identifiants de nœuds proviennent de get_editor_state ; les identifiants de composants et d'ensembles de list_components. Les outils qui prennent des ids ou id utilisent par défaut la sélection actuelle lorsque vous les omettez, donc passez les identifiants explicitement sauf si vous venez de sélectionner avec canvas_select. Voir pixerate-agent-tools pour l'espacement des noms, le regroupement run_commands et les codes d'erreur.

Compétences de flux de travail

Pour ces tâches, chargez également la compétence de flux de travail : elle contient la méthode, les vérifications entre les étapes et les pièges, et utilise les outils ci-dessous.

• pixerate-canvas-design-system-components : composants, instances, ensembles de variantes et surcharges.
• pixerate-canvas-layout : aligner, distribuer, ordonner et verrouiller.

Méthode de travail

1. Lire. get_editor_state avec includeDocument: false renvoie canvas.nodes et canvas.edges. Pour un système de conception, appelez aussi list_components, et inspect_instance avant de modifier une instance.
2. Planifier d'abord la structure : quels cadres, quels composants réutilisables et variantes, quelle échelle d'espacement. Construisez le composant principal une fois, puis placez les instances ; ne copiez pas les nœuds à la main.
3. Écrire. Utilisez les outils dédiés pour les modifications du graphe (canvas_add_node, canvas_connect, canvas_update_node) et les composants (create_component, create_instance, ...). Utilisez run_commands avec atomic: true pour les commandes d'agencement, de forme et d'animation, et chaque fois que plusieurs étapes doivent former une seule étape d'annulation (un paramètre "$0.ids[0]" utilise un identifiant qu'une étape précédente a renvoyé).
4. Ranger. canvas_layout pour les graphes ; canvas.align* / canvas.distribute* pour les conceptions ; ordre des calques avec canvas.bringToFront et similaires ; verrouillez les arrière-plans terminés avec canvas.lock.
5. Regarder. view_editor (viewport par défaut, JPEG, 1024 px) une fois un lot terminé ; utilisez scope: "canvas" pour tout le dessin. Corrigez les chevauchements, les désalignements et le texte coupé, puis montrez à l'utilisateur avec canvas_select ou canvas_highlight.

Travailler aux côtés de l'utilisateur (il construit et vous ajoutez sans qu'on vous le demande) : suggérez plutôt que de modifier. propose_nodes affiche des fantômes que l'utilisateur accepte ou rejette, et rien n'atteint le canevas ou son historique avant cela. Gardez chaque proposition petite et centrée sur une idée (une légende, la carte suivante dans une série, un connecteur manquant), donnez-lui un title et un rationale d'une phrase, et ancrez-la au nœud qu'elle complète avec nearNodeId. N'acceptez jamais vos propres propositions sauf si l'utilisateur vous l'a demandé. Retirez celles qui sont obsolètes avec reject_proposal : lorsque l'utilisateur modifie ce sur quoi une proposition se base, list_proposals l'affiche sous missing.

Bonnes pratiques

• Pensée système de conception. Tout ce qui apparaît deux fois devrait être un composant : créez-en un principal, combine_as_variants pour les états et tailles (State=Default, State=Hover, Size=Small), puis create_instance partout. Modifiez le principal pour modifier chaque instance ; utilisez les surcharges uniquement pour le contenu par utilisation (texte d'étiquette, changement d'icône). Nommez les propriétés et valeurs de variantes de manière cohérente (propriété en casse Titre, valeurs courtes) et gardez les combinaisons uniques.

• Nommez les calques qui doivent survivre à un changement de variante avec un data.name stable. La correspondance se rabat sur data.label, qui pour le texte est son contenu et diffère entre les variantes.

• Utilisez les propriétés de composant, pas le détachement. Changez de variante et définissez les propriétés textuelles ou booléennes avec set_instance_properties ; swap_instance pour un autre composant. Détachez uniquement lorsque l'instance doit cesser de suivre son composant principal.

• Échelle d'espacement. Choisissez une unité de base (4 ou 8) et utilisez des multiples pour les espaces et les rembourrages. Mettez les lignes et les piles dans des cadres de disposition automatique (data.layout) au lieu de positionner les enfants à la main, ainsi ils se réorganisent lorsque le contenu change.

• Alignement et distribution. Alignez sur un bord partagé ou au centre, puis distribuez avec des espaces égaux ; une conception paraît ordonnée lorsque les bords s'alignent. Verrouillez un nœud que vous voulez comme ancre : les nœuds verrouillés ne bougent jamais mais comptent toujours dans les limites de la sélection.

• Superposition. Les arrière-plans à l'arrière, le contenu au-dessus, les superpositions par-dessus. Utilisez les commandes de réorganisation ; elles définissent zIndex par groupe de frères et ne réorganisent jamais le tableau.

• Disposition de graphe. Disposez les flux dans une seule direction (LR pour les pipelines, TB pour les hiérarchies), gardez les arêtes courtes, étiquetez les arêtes uniquement lorsque la relation n'est pas évidente.

• Mouvement. Utilisez ease-out (ou ease-out-back pour un petit dépassement) pour les choses qui arrivent, ease-in pour les choses qui partent, ease-in-out pour les mouvements entre deux lieux de repos, et linear uniquement pour le mouvement continu comme la rotation. Gardez les transitions d'interface utilisateur autour de 150 à 400 ms et les entrées en dessous d'environ 600 ms ; décalez les éléments liés de 30 à 80 ms avec delay plutôt que de tout déplacer à la fois. Animez opacity, x, y, scale et rotation ; les interpolations de couleur s'effectuent en OKLab.

• Traits au pinceau. Utilisez un pinceau lorsque l'utilisateur souhaite un rendu dessiné à la main (croquis, encre, crayon, marqueur) ; gardez les traits simples pour les diagrammes et l'interface utilisateur. Envoyez des points tous les 2 à 8 unités de canevas le long d'une courbe, et façonnez la ligne avec un court profil de pressure (extrémités effilées : [0.2, 0.9, 1, 0.9, 0.2]) plutôt que de nombreux points de différentes largeurs. Laissez width de côté pour utiliser la taille propre au préréglage (canvas.listBrushes donne la valeur) ; passez-la uniquement pour rendre la marque plus fine ou plus grasse.

• Caractère du pinceau. Chaque préréglage dessine avec son propre caractère : le fusain et le pastel sont larges et granuleux (ils accrochent le grain du papier), tout comme le crayon gras et la craie ; le crayon est fin et légèrement granuleux ; l'encre, le marqueur, le stylo pinceau, le stylo à bille, le stylo gel et le finelineur sont nets (le finelineur garde une largeur constante), l'aérographe est une pulvérisation douce. Le grain et l'instabilité sont initialisés par trait, donc un trait a toujours la même apparence, et les traits voisins partagent une seule feuille de papier. Choisissez le pinceau pour le rendu, puis la couleur ; pour un croquis, utilisez un ou deux pinceaux plutôt que tous. Un pinceau avec une couleur par défaut (bleu stylo à bille, jaune surligneur, craie) peint dans cette couleur lorsque vous ne passez pas de color ; passez color pour en utiliser une autre. Les valeurs par défaut clair / foncé (craie) se résolvent selon le jeu de couleurs du canevas (canvas.setColorScheme ; l'hôte correspond généralement à son thème).

• Configurer le stylet pour la personne, pas pour dessiner. canvas.selectBrush choisit le pinceau avec lequel la personne dessine à la main, comme le sélecteur de pinceau : il prend la couleur par défaut du pinceau sauf s'il a verrouillé la sienne (canvas.setColorLocked, "Garder ma couleur") ou si vous passez keepColour. Une valeur par défaut prise de cette manière suit le jeu de couleurs jusqu'à ce qu'une autre couleur soit définie. Respectez un verrou que la personne a défini ; ne le déverrouillez pas pour changer sa couleur. Ce sont des états d'éditeur, pas des étapes d'annulation, et n'affectent pas canvas.drawFreehand, qui prend ses propres brush et color.

• Annotez avec des gestes, pas des points. Pour annoter le travail comme un designer annote une impression, utilisez les commandes gestuelles (canvas.circle, canvas.underline, canvas.arrow, canvas.bracket, canvas.strike, canvas.cross, canvas.check) avec des identifiants de nœuds ({ "nodeId": "..." }) ou des boîtes, plutôt que de calculer des points pour canvas.drawFreehand. Un appel dessine une marque dessinée à la main. Une annotation est utile lorsque vous pointez quelque chose sur le canevas tout en en parlant : entourez le choix, soulignez la ligne qui compte, dessinez une flèche d'un échantillon à l'endroit où il est utilisé, mettez entre parenthèses un groupe que vous décrivez, barrez ou rayez une option rejetée, cochez une option approuvée. Évitez-la lorsque rien sur le canevas n'est référencé, et limitez-la à quelques marques par point : une page couverte de marques ne dit rien.

• Style gestuel. Utilisez une couleur pour un passage de révision (un stylo rouge ou bleu fort se lit comme une annotation sur la plupart des designs), le surligneur uniquement pour les cercles et les soulignements, et le même brush (marker ou ink-pen) pour chaque marque d'un passage si vous voulez qu'elles aient l'air dessinées à la main. Les marques sont initialisées par leur demande, donc redemander dessine la même marque ; passez un autre seed pour un rendu différent. Mettez une note en marge (un nœud de texte) à côté d'une parenthèse ou à la queue d'une flèche lorsque la marque nécessite des mots.

Référence des outils

Lire

Outil	Utilisez-le pour
get_editor_state	Lire le graphe du canevas (canvas.nodes, canvas.edges) et, par défaut, le document d'invite aussi. Passez includeDocument: false pour une tâche qui ne concerne que le canevas afin de garder le résultat petit, includeCanvas: false pour uniquement l'invite. Appelez-le d'abord et à nouveau après les modifications apportées par l'utilisateur.
view_editor	Obtenir une image de l'éditeur : scope viewport (par défaut) ou canvas (les limites de tout le dessin), format jpeg (par défaut) ou png, maxEdge en pixels (par défaut 1024). Utilisez-le après un lot pour juger des chevauchements, de l'équilibre et de la lisibilité ; les curseurs d'agent sont exclus.
capture_view	Capturer une partie du canevas pour vérifier un résultat : region viewport (par défaut, comme à l'écran), content (chaque nœud), selection, nodes (avec ids de get_editor_state) ou rect (unités de canevas) ; padding (par défaut 16), maxEdge (par défaut 1024), format png (par défaut) ou jpeg. Le résultat donne le rect et scale capturés, donc un pixel d'image (px, py) correspond au point de canevas (rect.x + px / scale, rect.y + py / scale). Préférez nodes pour inspecter ce que vous venez d'ajouter en détail. Les boîtes de sélection et les curseurs d'agent sont exclus sauf si includeOverlays.
list_components	Lister les composants principaux (id, nom, valeurs de variantes, nombre d'instances) et les ensembles de composants avec leurs options de variantes. Appelez-le avant create_instance, swap_instance ou tout outil de variante pour obtenir les identifiants et les noms et valeurs exacts des propriétés.
inspect_instance	Décrire une instance (ou un calque à l'intérieur ; par défaut le premier nœud sélectionné) : son composant principal, sa variante, les valeurs des propriétés du composant avec les types, et les surcharges par calque. Appelez-le avant set_instance_properties ou reset_overrides pour utiliser les bons noms de propriétés et groupes de surcharges.

Écrire : graphe

Outil	Utilisez-le pour
canvas_add_node	Ajouter un nœud : node (id optionnel et doit être inutilisé, type enregistré par l'hôte, data, position, width, height, parentId pour un cadre). Laissez position de côté pour le placer automatiquement sans chevauchement à côté de nearNodeId sur side (par défaut right), ce qui connecte également une arête à partir de ce nœud, ou à côté du dernier nœud. Renvoie le nouvel identifiant de nœud et d'arête.
canvas_connect	Ajouter une arête de source à target (deux nœuds existants différents), avec un label optionnel. Renvoie l'identifiant de l'arête.
canvas_update_node	Fusionner des champs dans les data d'un nœud (par exemple { "label": "Checkout" }). Traitez la fusion comme superficielle : passez les objets imbriqués tels que shape ou layout en entier. Ne déplace pas ni ne redimensionne les nœuds.
canvas_remove_nodes	Supprimer des nœuds et leurs arêtes ; chaque identifiant doit exister. Destructeur : confirmez avec l'utilisateur avant de supprimer du contenu qu'il a créé.
canvas_layout	Organiser le graphe automatiquement : direction LR (par défaut), TB, RL ou BT. incremental (par défaut true) maintient les nœuds qui ont déjà une position ; passez false pour tout réorganiser. Les nœuds exactement à (0, 0) sont considérés comme non placés.
canvas_select	Remplacer la sélection (une liste vide l'efface). Utilisez-le pour montrer un résultat à l'utilisateur et pour cibler des commandes qui agissent sur la sélection.
canvas_highlight	Faire clignoter des nœuds pour les signaler à l'utilisateur : color (par défaut #3b82f6), durationMs (par défaut 2000, max 60000). Ne change rien.

Développer et réduire

Les hôtes avec des nœuds extensibles (une tâche qui s'ouvre en sous-tâches, une barre de Gantt en ses étapes) les ajoutent. Développer affiche les nœuds enfants du nœud et déplace les nœuds environnants pour faire de la place ; réduire supprime les enfants et remet les nœuds déplacés en place. C'est un changement de vue, pas une modification : ce n'est pas une étape d'annulation et n'est pas sauvegardé avec le document. L'hôte décide ce que sont les enfants.

Outil	Utilisez-le pour
list_explodable_nodes	Lister les nœuds qui peuvent être développés (id, label, exploded, collapsing), les identifiants exploded et collapsing maintenant, si plusieurs peuvent être ouverts à la fois (multiple), et la raison readOnly si le développement est désactivé. Appelez-le d'abord : c'est la seule source d'identifiants extensibles.
explode_node	Développer node (un identifiant de list_explodable_nodes). Sauf si multiple, le nœud développé auparavant se réduit (il revient dans collapsed). Développer un nœud déjà développé ne change rien (changed: false). Renvoie les identifiants maintenant exploded. Utilisez ensuite get_editor_state ou capture_view pour lire ou voir les enfants.
collapse_node	Réduire un nœud node développé. Renvoie les identifiants toujours exploded et ceux toujours collapsing (leurs enfants partent lorsque l'animation de réduction se termine). Échoue lorsque le nœud n'est pas développé.

Propositions (suggérer, ne pas modifier)

Les hôtes qui permettent aux agents de suggérer des ajouts les ajoutent. Une proposition est de nouveaux nœuds et arêtes affichés comme des fantômes (pas déplaçables, sélectionnables ou sauvegardés). Accepter les ajoute comme une seule étape d'annulation, enregistrée comme ayant été faite par celui qui l'a proposée (agent:<id>) ; rejeter laisse le canevas et son historique intacts.

|

… [tronqué pour la traduction]