Pixerate/canvas-pixerate

Pixerate-Canvas

Das Canvas ist ein xyflow-Graph (React Flow / SvelteFlow): ein Array aus Knoten und Kanten. Ein Knoten ist { id, type, position: { x, y }, width?, height?, parentId?, zIndex?, data }; Kanten sind { id, source, target, label? }. Alles, was ein Design-Feature kennt, lebt in node.data, sodass es Kopieren, Einfügen und JSON überlebt:

• data.label / data.name: Textinhalt und Ebenenname. data.shape: ein Formknoten ({ kind: rect | ellipse | polygon | star | path, fill, stroke, strokeWidth, ... }).
• data.layout: ein Auto-Layout-Rahmen (mode horizontal / vertikal / grid, gap, padding, alignMain, alignCross, sizing); seine Kinder sind die Knoten, deren parentId der Rahmen ist, in der Reihenfolge des Knoten-Arrays. data.childLayout: die Größenanpassung eines Kindes (fixed / hug / fill) und Constraints.
• data.component (eine Hauptkomponente), data.componentSet (ein Satz von Varianten), data.instance ({ componentId, properties }) und data.componentOverrides.
• data.locked, data.animation (Keyframe-Tracks), data.tokenBindings (Design-Token).

Positionen sind in Canvas- (Flow-) Einheiten; die Position eines Kindes ist relativ zu seinem Elternteil. Knoten-IDs stammen von get_editor_state; Komponenten- und Set-IDs von list_components. Tools, die ids oder id erwarten, verwenden standardmäßig die aktuelle Auswahl, wenn Sie sie weglassen. Übergeben Sie IDs daher explizit, es sei denn, Sie haben gerade mit canvas_select ausgewählt. Siehe pixerate-agent-tools für Namensräume, run_commands Batching und Fehlercodes.

Workflow-Fähigkeiten

Laden Sie für diese Aufgaben auch die Workflow-Fähigkeit: Sie enthält die Methode, die Überprüfungen zwischen den Schritten und die Fallstricke und verwendet die unten stehenden Tools.

• pixerate-canvas-design-system-components: Komponenten, Instanzen, Varianten-Sets und Overrides.
• pixerate-canvas-layout: Ausrichten, Verteilen, Ordnen und Sperren.

Arbeitsmethode

1. Lesen. get_editor_state mit includeDocument: false gibt canvas.nodes und canvas.edges zurück. Rufen Sie für ein Designsystem auch list_components und inspect_instance auf, bevor Sie eine Instanz ändern.
2. Planen Sie zuerst die Struktur: Welche Rahmen, welche wiederverwendbaren Komponenten und Varianten, welcher Abstandsmaßstab. Erstellen Sie die Hauptkomponente einmal und platzieren Sie dann Instanzen; kopieren Sie keine Knoten von Hand.
3. Schreiben. Verwenden Sie die dedizierten Tools für Graph-Bearbeitungen (canvas_add_node, canvas_connect, canvas_update_node) und Komponenten (create_component, create_instance, ...). Verwenden Sie run_commands mit atomic: true für Anordnungs-, Form- und Animationsbefehle und immer dann, wenn mehrere Schritte ein einziger Rückgängig-Schritt sein sollen (ein Parameter "$0.ids[0]" verwendet eine ID, die ein früherer Schritt zurückgegeben hat).
4. Aufräumen. canvas_layout für Graphen; canvas.align* / canvas.distribute* für Designs; Ebenenreihenfolge mit canvas.bringToFront und verwandten Befehlen; sperren Sie fertige Hintergründe mit canvas.lock.
5. Ansehen. view_editor (Standard-Viewport, JPEG, 1024 px) sobald ein Batch erledigt ist; verwenden Sie scope: "canvas" für die gesamte Zeichnung. Beheben Sie Überlappungen, Fehlausrichtungen und abgeschnittenen Text und zeigen Sie sie dann dem Benutzer mit canvas_select oder canvas_highlight.

Zusammenarbeit mit dem Benutzer (dieser erstellt etwas, und Sie fügen ungefragt hinzu): Schlagen Sie vor, anstatt zu bearbeiten. propose_nodes zeigt Geister, die der Benutzer annimmt oder ablehnt, und nichts erreicht das Canvas oder seine Historie bis dahin. Halten Sie jeden Vorschlag klein und auf eine Idee bezogen (eine Bildunterschrift, die nächste Karte in einer Serie, ein fehlender Verbinder), geben Sie ihm einen title und eine einzeilige rationale und verankern Sie ihn an dem Knoten, den er ergänzt, mit nearNodeId. Akzeptieren Sie niemals Ihre eigenen Vorschläge, es sei denn, der Benutzer hat Sie darum gebeten. Ziehen Sie veraltete mit reject_proposal zurück: Wenn der Benutzer etwas ändert, auf dem ein Vorschlag aufbaut, zeigt list_proposals ihn unter missing.

Best Practices

• Design-System-Denken. Alles, was zweimal vorkommt, sollte eine Komponente sein: Erstellen Sie eine Hauptkomponente, combine_as_variants für Zustände und Größen (State=Default, State=Hover, Size=Small), dann create_instance überall. Ändern Sie die Hauptkomponente, um jede Instanz zu ändern; verwenden Sie Overrides nur für pro-verwendeten Inhalt (Label-Text, ein Icon-Wechsel). Benennen Sie Varianten-Eigenschaften und -Werte konsistent (Title Case für Eigenschaften, kurze Werte) und halten Sie Kombinationen eindeutig.

• Benennen Sie Ebenen, die einen Variantenwechsel überleben müssen, mit einem stabilen data.name. Der Abgleich fällt auf data.label zurück, was bei Text dessen Inhalt ist und sich zwischen Varianten unterscheidet.

• Verwenden Sie Komponenten-Eigenschaften, kein Trennen. Wechseln Sie Varianten und setzen Sie Text- oder boolesche Eigenschaften mit set_instance_properties; swap_instance für eine andere Komponente. Trennen Sie nur, wenn die Instanz nicht mehr ihrer Hauptkomponente folgen soll.

• Abstandsmaßstab. Wählen Sie eine Basiseinheit (4 oder 8) und verwenden Sie Vielfache für Abstände und Ränder. Platzieren Sie Zeilen und Stapel in Auto-Layout-Rahmen (data.layout), anstatt Kinder von Hand zu positionieren, damit sie bei Inhaltsänderungen neu fließen.

• Ausrichtung und Verteilung. Richten Sie an einer gemeinsamen Kante oder Mitte aus und verteilen Sie dann mit gleichen Abständen; ein Design wirkt geordnet, wenn Kanten ausgerichtet sind. Sperren Sie einen Knoten, den Sie als Anker verwenden möchten: gesperrte Knoten bewegen sich nie, zählen aber weiterhin zu den Auswahlgrenzen.

• Schichtung. Hintergründe hinten, Inhalt darüber, Overlays oben. Verwenden Sie die Umschichtungsbefehle; sie setzen zIndex pro Geschwistergruppe und ordnen das Array nie neu.

• Graph-Layout. Ordnen Sie Abläufe in eine Richtung an (LR für Pipelines, TB für Hierarchien), halten Sie Kanten kurz, beschriften Sie Kanten nur, wenn die Beziehung nicht offensichtlich ist.

• Bewegung. Verwenden Sie ease-out (oder ease-out-back für ein leichtes Überschwingen) für Dinge, die eintreffen, ease-in für Dinge, die verschwinden, ease-in-out für Bewegungen zwischen zwei Ruhepunkten und linear nur für kontinuierliche Bewegung wie Rotation. Halten Sie UI-Übergänge zwischen 150 und 400 ms und Eintritte unter etwa 600 ms; staffeln Sie verwandte Elemente um 30 bis 80 ms mit delay, anstatt alles auf einmal zu bewegen. Animieren Sie opacity, x, y, scale und rotation; Farb-Überblendungen interpolieren in OKLab.

• Bürstenstriche. Verwenden Sie einen Pinsel, wenn der Benutzer einen handgezeichneten Look wünscht (Skizzieren, Tinte, Bleistift, Marker); verwenden Sie klare Striche für Diagramme und UI. Senden Sie alle 2 bis 8 Canvas-Einheiten Punkte entlang einer Kurve und formen Sie die Linie mit einem kurzen pressure-Profil (verjüngte Enden: [0.2, 0.9, 1, 0.9, 0.2]), anstatt viele Punkte unterschiedlicher Breite. Lassen Sie width weg, um die voreingestellte Größe des Pinsels zu verwenden (canvas.listBrushes gibt sie); übergeben Sie sie nur, um den Strich feiner oder kräftiger zu machen.

• Pinsel-Charakter. Jeder Pinsel zeichnet mit seinem eigenen Charakter: Holzkohle und Pastell sind breit und körnig (sie erfassen die Zahnung des Papiers), ebenso wie Kreide und Bleistift; Bleistift ist fein und leicht körnig; Tinte, Marker, Pinselstift, Kugelschreiber, Gelstift und Fineliner sind sauber (der Fineliner behält eine Breite), die Airbrush ist ein weicher Sprühnebel. Die Körnung und das Zittern werden pro Strich festgelegt, sodass ein Strich immer gleich aussieht und benachbarte Striche ein Blatt Papier teilen. Wählen Sie den Pinsel für den Look, dann die Farbe; für eine Skizze verwenden Sie einen oder zwei Pinsel, anstatt alle. Ein Pinsel mit einer Standardfarbe (Kugelschreiber blau, Marker gelb, Kreide) malt in dieser, wenn Sie keine color übergeben; übergeben Sie color, um eine andere zu verwenden. Standardwerte für Hell/Dunkel (Kreide) werden für das Farbschema des Canvas aufgelöst (canvas.setColorScheme; der Host stimmt normalerweise mit seinem Theme überein).

• Einrichten des Stifts für die Person, nicht Zeichnen. canvas.selectBrush wählt den Pinsel aus, mit dem die Person von Hand zeichnet, wie die Pinselauswahl: Es nimmt die Standardfarbe des Pinsels, es sei denn, sie haben ihre eigene gesperrt (canvas.setColorLocked, „Meine Farbe behalten“) oder Sie übergeben keepColour. Ein so übernommener Standard folgt dem Schema, bis eine andere Farbe eingestellt wird. Respektieren Sie eine Sperre, die die Person gesetzt hat; entsperren Sie sie nicht, um ihre Farbe zu ändern. Dies sind Editor-Zustände, keine Rückgängig-Schritte, und beeinflussen nicht canvas.drawFreehand, das seinen eigenen brush und color nimmt.

• Mit Gesten annotieren, nicht mit Punkten. Um Arbeit wie ein Designer einen Ausdruck zu markieren, verwenden Sie die Gestenbefehle (canvas.circle, canvas.underline, canvas.arrow, canvas.bracket, canvas.strike, canvas.cross, canvas.check) mit Knoten-IDs ({ "nodeId": "..." }) oder Boxen, anstatt Punkte für canvas.drawFreehand zu ermitteln. Ein Aufruf zeichnet eine handgezeichnete Markierung. Eine Annotation hilft, wenn Sie auf etwas auf dem Canvas zeigen, während Sie darüber sprechen: Kreisen Sie die Auswahl ein, unterstreichen Sie die relevante Linie, zeichnen Sie einen Pfeil von einem Muster zu seiner Verwendung, klammern Sie eine Gruppe, die Sie beschreiben, streichen oder kreuzen Sie eine abgelehnte Option durch, haken Sie eine genehmigte ab. Überspringen Sie sie, wenn auf nichts auf dem Canvas Bezug genommen wird, und beschränken Sie sich auf wenige Markierungen pro Punkt: Eine mit Markierungen bedeckte Seite sagt nichts.

• Gestik-Stil. Verwenden Sie eine Farbe für einen Review-Durchgang (ein roter oder starker blauer Stift liest sich als Markup über den meisten Designs), den Marker nur für Kreise und Unterstreichungen und denselben brush (marker oder ink-pen) für jede Markierung eines Durchgangs, wenn sie handgezeichnet aussehen sollen. Markierungen werden durch ihre Anfrage gesetzt; wenn Sie sie erneut anfordern, wird dieselbe Markierung gezeichnet; übergeben Sie einen anderen seed für eine andere Version. Setzen Sie eine Randnotiz (einen Textknoten) neben eine Klammer oder an das Ende eines Pfeils, wenn die Markierung Worte benötigt.

Tool-Referenz

Lesen

Tool	Verwenden Sie es, um
get_editor_state	Den Canvas-Graphen (canvas.nodes, canvas.edges) und standardmäßig auch das Prompt-Dokument auslesen. Übergeben Sie includeDocument: false bei einer Nur-Canvas-Aufgabe, um das Ergebnis klein zu halten, includeCanvas: false für nur den Prompt. Rufen Sie es zuerst und erneut nach vom Benutzer vorgenommenen Änderungen auf.
view_editor	Ein Bild des Editors erhalten: scope viewport (Standard) oder canvas (die Grenzen der gesamten Zeichnung), format jpeg (Standard) oder png, maxEdge in Pixeln (Standard 1024). Verwenden Sie es nach einem Batch, um Überlappungen, Balance und Lesbarkeit zu beurteilen; Agent-Cursor werden weggelassen.
capture_view	Einen Teil des Canvas screenshotten, um ein Ergebnis zu überprüfen: region viewport (Standard, wie auf dem Bildschirm), content (jeder Knoten), selection, nodes (mit ids von get_editor_state) oder rect (Canvas-Einheiten); padding (Standard 16), maxEdge (Standard 1024), format png (Standard) oder jpeg. Das Ergebnis gibt das aufgenommene rect und scale an, sodass Bildpixel (px, py) dem Canvas-Punkt (rect.x + px / scale, rect.y + py / scale) entspricht. Bevorzugen Sie nodes, um das, was Sie gerade hinzugefügt haben, in voller Detailtreue zu inspizieren. Auswahlboxen und Agent-Cursor werden weggelassen, es sei denn, includeOverlays wird verwendet.
list_components	Hauptkomponenten (id, name, Variantenwerte, Instanzanzahl) und Komponenten-Sets mit ihren Variantenoptionen auflisten. Rufen Sie es vor create_instance, swap_instance oder einem Varianten-Tool auf, um IDs und die genauen Eigenschaftsnamen und -werte zu erhalten.
inspect_instance	Eine Instanz (oder eine Ebene darin; Standard ist der erste ausgewählte Knoten) beschreiben: ihre Hauptkomponente, Variante, Komponenteneigenschaftswerte mit Typen und pro-Ebene-Overrides. Rufen Sie es vor set_instance_properties oder reset_overrides auf, damit Sie die richtigen Eigenschaftsnamen und Override-Gruppen verwenden.

Schreiben: Graph

Tool	Verwenden Sie es, um
canvas_add_node	Einen Knoten hinzufügen: node (id optional und muss unbenutzt sein, type vom Host registriert, data, position, width, height, parentId für einen Rahmen). Lassen Sie position weg, um es automatisch ohne Überlappungen neben nearNodeId auf side (Standard right) zu platzieren, was auch eine Kante von diesem Knoten aus verbindet, oder neben dem letzten Knoten. Gibt die neue Knoten-ID und Kanten-ID zurück.
canvas_connect	Eine Kante von source zu target (zwei verschiedene vorhandene Knoten) hinzufügen, mit einem optionalen label. Gibt die Kanten-ID zurück.
canvas_update_node	Felder in die data eines Knotens zusammenführen (z. B. { "label": "Checkout" }). Behandeln Sie die Zusammenführung als flach: übergeben Sie verschachtelte Objekte wie shape oder layout vollständig. Es verschiebt oder ändert die Größe von Knoten nicht.
canvas_remove_nodes	Knoten und ihre Kanten löschen; jede ID muss vorhanden sein. Destruktiv: Bestätigen Sie mit dem Benutzer, bevor Sie von ihm erstellte Inhalte entfernen.
canvas_layout	Den Graphen automatisch anordnen: direction LR (Standard), TB, RL oder BT. incremental (Standard true) behält Knoten, die bereits eine Position haben; übergeben Sie false, um alles neu anzuordnen. Knoten genau bei (0, 0) gelten als nicht platziert.
canvas_select	Die Auswahl ersetzen (eine leere Liste löscht sie). Verwenden Sie es, um dem Benutzer ein Ergebnis zu zeigen und um Befehle zu adressieren, die auf die Auswahl wirken.
canvas_highlight	Knoten aufblinken lassen, um den Benutzer darauf hinzuweisen: color (Standard #3b82f6), durationMs (Standard 2000, max 60000). Ändert nichts.

Aufklappen und Einklappen

Hosts mit aufklappbaren Knoten (eine Aufgabe, die sich in Unteraufgaben öffnet, ein Gantt-Balken in seine Schritte) fügen diese hinzu. Aufklappen zeigt die untergeordneten Knoten des Knotens und verschiebt die umgebenden Knoten, um Platz zu schaffen; Einklappen entfernt die untergeordneten Knoten und setzt die verschobenen Knoten zurück. Es ist eine Ansichtsänderung, keine Bearbeitung: Es ist kein Rückgängig-Schritt und wird nicht mit dem Dokument gespeichert. Der Host entscheidet, was die untergeordneten Knoten sind.

Tool	Verwenden Sie es, um
list_explodable_nodes	Die Knoten auflisten, die aufklappbar sind (id, label, exploded, collapsing), die IDs, die jetzt exploded und collapsing sind, ob mehrere gleichzeitig geöffnet sein können (multiple), und den readOnly-Grund, wenn das Aufklappen deaktiviert ist. Rufen Sie es zuerst auf: Es ist die einzige Quelle für aufklappbare IDs.
explode_node	node aufklappen (eine ID von list_explodable_nodes). Sofern nicht multiple, wird der zuvor aufgeklappte Knoten eingeklappt (er kommt in collapsed zurück). Das Aufklappen eines bereits aufgeklappten Knotens ändert nichts (changed: false). Gibt die jetzt exploded IDs zurück. Verwenden Sie dann get_editor_state oder capture_view, um die untergeordneten Knoten zu lesen oder zu sehen.
collapse_node	Einen aufgeklappten node einklappen. Gibt die IDs zurück, die immer noch exploded sind, und diejenigen, die immer noch collapsing sind (ihre untergeordneten Knoten verlassen, wenn die Einklapp-Animation endet). Schlägt fehl, wenn der Knoten nicht aufgeklappt ist.

Vorschläge (vorschlagen, nicht bearbeiten)

Hosts, die es Agenten erlauben, Ergänzungen vorzuschlagen, fügen diese hinzu. Ein Vorschlag sind neue Knoten und Kanten, die als Geister (nicht ziehbar, auswählbar oder gespeichert) angezeigt werden. Annehmen fügt sie als einen Rückgängig-Schritt hinzu, aufgezeichnet als erstellt von wem auch immer sie vorgeschlagen hat (agent:<id>); Ablehnen lässt das Canvas und seine Historie unberührt.

| ...

[truncated for translation]