diff --git a/packages/docs/de/development/contributing.md b/packages/docs/de/development/contributing.md
index 84392c507..3928a71d1 100644
--- a/packages/docs/de/development/contributing.md
+++ b/packages/docs/de/development/contributing.md
@@ -7,7 +7,9 @@ packages/
core/ @open-pencil/core — Engine (keine DOM-Abhängigkeiten)
src/ Szenengraph, Renderer, Layout, Codec, Kiwi, Typen
cli/ @open-pencil/cli — Headless-CLI für .fig-Operationen
- src/commands/ info, tree, find, export
+ src/commands/ info, tree, find, export, eval, analyze
+ mcp/ @open-pencil/mcp — MCP-Server für KI-Werkzeuge
+ src/ stdio + HTTP (Hono) Transporte, 75 Werkzeuge
src/
components/ Vue SFCs (Canvas, Panels, Werkzeugleiste, Farbauswahl)
properties/ Eigenschaftspanel-Abschnitte
@@ -82,6 +84,9 @@ Engine-Quellcode lebt in `packages/core/src/`. Die `src/engine/`- und `src/kiwi/
| `packages/core/src/vector.ts` | Vektornetzwerk-Modell |
| `packages/core/src/kiwi/codec.ts` | Kiwi-Binär-Encoder/Decoder |
| `packages/core/src/kiwi/fig-import.ts` | .fig-Datei-Import-Logik |
+| `packages/core/src/tools/schema.ts` | Vereinheitlichte Werkzeugdefinitionen (KI, MCP, CLI) |
+| `packages/core/src/figma-api.ts` | Figma Plugin API-Implementierung |
+| `packages/mcp/src/server.ts` | MCP-Server-Factory |
| `packages/cli/src/index.ts` | CLI-Einstiegspunkt |
| `src/stores/editor.ts` | Globaler Editor-Zustand |
| `src/composables/use-canvas.ts` | Canvas-Rendering-Composable |
diff --git a/packages/docs/de/development/roadmap.md b/packages/docs/de/development/roadmap.md
index 93a1d5ccf..7daa7de2b 100644
--- a/packages/docs/de/development/roadmap.md
+++ b/packages/docs/de/development/roadmap.md
@@ -1,32 +1,69 @@
# Fahrplan
-## Phase 1 ✅
-SceneGraph, Skia rendering, shapes, selection, zoom/pan, undo/redo, snap guides.
+## Phasen
-## Core-Engine ✅
-Vue 3 + Reka UI panels, properties, layers, toolbar, Yoga auto-layout, inline text editing, canvas rulers.
+### Phase 1: Core-Engine ✅
-## Phase 2 ✅
-.fig import/export, Kiwi codec, clipboard, pen tool, vector networks, groups, Tauri v2 desktop, sections, multi-page, hover highlight, Tier 1 rendering.
+SceneGraph, Skia-Rendering, Grundformen, Auswahl, Zoom/Pan, Rückgängig/Wiederherstellen, Fanglinien.
-## Editor-UI + Layout ✅
-Components, instances, overrides, component sets, variables (COLOR/FLOAT/STRING/BOOLEAN), collections, modes, image export, context menu, rich text formatting.
+### Phase 2: Editor-UI + Layout ✅
-## Phase 3 🟡
-@open-pencil/core, CLI (12 commands), MCP server (29+ tools), AI chat (OpenRouter), JSX renderer, code panel.
+Vue 3 + Reka UI Panels, Eigenschaften, Ebenen, Werkzeugleiste, Yoga Auto-Layout, Inline-Textbearbeitung, Canvas-Lineale.
-**Planned:** port remaining figma-use tools, attached mode, design guidelines, screenshot verification loop.
+### Phase 3: Datei-I/O + Visuelle Features ✅
-## Datei-I/O + Visuelle Features 🔲
-Prototyping, comments, PWA, Linux Tauri builds, performance optimization, full Figma compatibility test suite.
+.fig Import/Export, Kiwi-Codec, Zwischenablage, Stiftwerkzeug, Vektornetzwerke, Gruppen, Tauri v2 Desktop, Sektionen, Mehrseiten, Hover-Hervorhebung, Tier-1-Rendering (Verläufe, Bilderfüllungen, Effekte, Kontur-Eigenschaften, Bögen).
-## Phase 4
+### Phase 4: Komponenten + Variablen ✅
-| Phase | Komponenten + Variablen | Phase 5: KI-Integration & Werkzeuge:Phase 6: Feinschliff + Verteilung:Zeitplan:Geschätzte Dauer:Status |
-|-------|------|-----|
-| Phase 1 | 3 months | ✅ |
-| Core-Engine | 3 months | ✅ |
-| Phase 2 | 2 months | ✅ |
-| Editor-UI + Layout | 2 months | ✅ |
-| Phase 3 | 2 months | 🟡 |
-| Datei-I/O + Visuelle Features | 2 months | 🔲 |
+Komponenten, Instanzen, Overrides, Komponenten-Sets, Variablen (COLOR/FLOAT/STRING/BOOLEAN), Sammlungen, Modi, Bildexport, Kontextmenü, Rich-Text-Formatierung.
+
+### Phase 5: KI-Integration & Werkzeuge ✅
+
+**Geliefert:**
+- @open-pencil/core extrahiert in packages/core/ (keine DOM-Abhängigkeiten)
+- @open-pencil/cli mit headless .fig-Operationen (info, tree, find, export, analyze, node, pages, variables, eval)
+- `eval`-Befehl mit Figma-kompatibler Plugin API für Headless-Skripting
+- KI-Chat: OpenRouter-Direktverbindung, 75 Werkzeuge in `schema.ts`, Modellauswahl, ⌘J
+- 49 zusätzliche KI/MCP-Werkzeuge portiert von figma-use (75 gesamt)
+- MCP-Server (@open-pencil/mcp): stdio + HTTP, 75 Core-Tools + 3 Dateiverwaltungs-Tools
+- Vereinheitlichte Werkzeugdefinitionen: einmal in `schema.ts` definieren, für KI-Chat (valibot), MCP (zod), CLI (eval) adaptieren
+- App-Menüleiste für Browser-Modus (Datei, Bearbeiten, Ansicht, Objekt, Text, Anordnen)
+- Automatisches Speichern: 3s Debounce nach letzter Szenenänderung
+- Multi-Selektion-Eigenschaftspanel mit gemeinsamen/gemischten Werten
+- npm-Veröffentlichung mit Provenance für core, cli und mcp
+
+**Geplant:**
+- Attached Mode: WebSocket zum laufenden Editor
+- Design-Guidelines-System
+- Screenshot-Verification-Loop
+
+### Phase 6: Kollaboration + Distribution 🟡
+
+**Geliefert:**
+- P2P-Kollaboration über Trystero (WebRTC) + Yjs CRDT — kein Server-Relay
+- Awareness-Protokoll: Live-Cursor, Auswahlen, Präsenz
+- Folgemodus: Klick auf Peer-Avatar zum Viewport-Folgen
+- Lokale Persistenz über y-indexeddb
+- Effekt-Rendering: Schlagschatten, innerer Schatten, Ebenen-/Hintergrund-/Vordergrund-Unschärfe
+- Multi-Datei-Tabs: ⌘N/⌘T neuer Tab, ⌘W schließen, ⌘O öffnen
+- Apple Code-Signierung und Notarisierung für macOS
+- Linux-Builds (x64) in CI hinzugefügt
+- VitePress-Dokumentationsseite mit i18n (6 Sprachen)
+
+**Geplant:**
+- Prototyping (Frame-Verbindungen, Übergänge, Animationen)
+- Kommentare (Pin, Threads, Auflösen)
+- PWA-Unterstützung
+- Varianten-Switching, FLOAT/STRING/BOOLEAN Variable UI, variablengesteuertes Theming
+
+## Zeitplan
+
+| Phase | Geschätzte Dauer | Status |
+|-------|-----------------|--------|
+| Phase 1: Core-Engine | 3 Monate | ✅ Abgeschlossen |
+| Phase 2: Editor-UI + Layout | 3 Monate | ✅ Abgeschlossen |
+| Phase 3: Datei-I/O + Visuelle Features | 2 Monate | ✅ Abgeschlossen |
+| Phase 4: Komponenten + Variablen | 2 Monate | ✅ Abgeschlossen |
+| Phase 5: KI-Integration & Werkzeuge | 2 Monate | ✅ Abgeschlossen |
+| Phase 6: Kollaboration + Distribution | 2 Monate | 🟡 In Arbeit |
diff --git a/packages/docs/de/guide/architecture.md b/packages/docs/de/guide/architecture.md
index 1fb180298..3a3ba6eea 100644
--- a/packages/docs/de/guide/architecture.md
+++ b/packages/docs/de/guide/architecture.md
@@ -29,7 +29,7 @@
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
-│ MCP-Server (29+ Werkzeuge) Kollaboration (P2P, Yjs CRDT) │
+│ MCP-Server (75+ Tools, stdio+HTTP) P2P-Kollab. (Trystero + Yjs) │
└──────────────────────────────────────────────────────────────────┘
```
@@ -79,4 +79,12 @@ Inverse-Command-Muster. Vor jeder Änderung werden betroffene Felder als Snapsho
### Zwischenablage
-Figma-kompatible bidirektionale Zwischenablage. Kodiert/dekodiert Kiwi-Binär (gleiches Format wie .fig-Dateien) über native Browser-Kopier/Einfüge-Events.
+Figma-kompatible bidirektionale Zwischenablage. Kodiert/dekodiert Kiwi-Binär (gleiches Format wie .fig-Dateien) über native Browser-Kopier/Einfüge-Events. Paste verarbeitet Vektorpfad-Skalierung, Instanz-Kind-Population aus Komponenten, Component-Set-Erkennung und Override-Anwendung.
+
+### MCP-Server
+
+`@open-pencil/mcp` stellt 75 Core-Tools + 3 Dateiverwaltungs-Tools für KI-Coding-Werkzeuge bereit. Zwei Transporte: stdio für Claude Code/Cursor/Windsurf, HTTP mit Hono + Streamable HTTP für Skripte und CI. Tools werden einmal in `packages/core/src/tools/schema.ts` definiert und für AI-Chat (valibot), MCP (zod) und CLI (eval-Befehl) adaptiert.
+
+### P2P-Kollaboration
+
+Echtzeit-Peer-to-Peer-Kollaboration über Trystero (WebRTC) + Yjs CRDT. Kein Server-Relay — Signalisierung über öffentliche MQTT-Broker, STUN/TURN für NAT-Traversal. Das Awareness-Protokoll bietet Live-Cursor, Auswahlen und Präsenz. Lokale Persistenz über y-indexeddb.
diff --git a/packages/docs/de/guide/comparison.md b/packages/docs/de/guide/comparison.md
index c3883fe44..d45bcd2aa 100644
--- a/packages/docs/de/guide/comparison.md
+++ b/packages/docs/de/guide/comparison.md
@@ -7,7 +7,7 @@ OpenPencil und Penpot sind beides Open-Source-Design-Tools, aber sie unterscheid
| Metrik | Open Pencil | Penpot |
|--------|-------------|--------|
| Total LOC | **~26.000** | **~299.000** |
-| Quelldateien | 125 | ~2.900 |
+| Quelldateien | ~143 | ~2.900 |
| Sprachen | TypeScript, Vue | Clojure, ClojureScript, Rust, JS, SQL, SCSS |
| Rendering-Engine | 1.646 LOC (TS) | 22.000 LOC (Rust/Skia WASM) |
| UI-Code | ~4.500 LOC | ~175.000 LOC (CLJS + SCSS) |
@@ -66,7 +66,7 @@ Open Pencil und Penpot verwenden beide Skia für das Rendering, aber die Impleme
| | Open Pencil | Penpot |
|---|-------------|--------|
-| Beitragsumfang | 125 TS-Dateien | 2.900+ Dateien, 4 Sprachen |
+| Beitragsumfang | ~143 TS-Dateien | 2.900+ Dateien, 4 Sprachen |
| Build-System | Vite + Bun (Sekunden) | Shadow-CLJS + Docker (Minuten) |
| Typensicherheit | TypeScript durchgängig | Clojure (dynamisch typisiert) |
| Tests | Playwright + bun:test | Clojure-Test + Cypress |
@@ -77,7 +77,7 @@ Open Pencil und Penpot verwenden beide Skia für das Rendering, aber die Impleme
| | Open Pencil | Penpot |
|---|-------------|--------|
| CLI | ✅ Headless .fig-Operationen | ❌ Kein CLI |
-| AI-Werkzeuge | 29 Werkzeuge + MCP-Server | Plugin-System |
+| AI-Werkzeuge | 75 Werkzeuge + MCP-Server | Plugin-System |
| JSX-Renderer | ✅ Programmgesteuerte Erstellung | ❌ |
| Eval-Befehl | ✅ Figma Plugin API | ❌ |
| Plugin-System | Über eval/MCP | ✅ Natives Plugin-System |
@@ -97,7 +97,7 @@ Open Pencil und Penpot verwenden beide Skia für das Rendering, aber die Impleme
| | Open Pencil | Penpot |
|---|-------------|--------|
| Integrierter Chat | ✅ OpenRouter-Integration | ❌ |
-| Werkzeugnutzung | 29 Design-Werkzeuge | ❌ |
+| Werkzeugnutzung | 75 Design-Werkzeuge | ❌ |
| MCP-Server | ✅ stdio + HTTP | ❌ |
| Bring your own key | ✅ Kein Vendor-Lock-in | ❌ |
@@ -107,7 +107,7 @@ Open Pencil und Penpot verwenden beide Skia für das Rendering, aber die Impleme
|---|-------------|--------|
| Headless CLI | ✅ 12 Befehle | ❌ |
| Plugin API | Figma-kompatibel | Eigene Plugin API |
-| MCP-Server | ✅ 29+ Werkzeuge | ❌ |
+| MCP-Server | ✅ 75+ Werkzeuge | ❌ |
| Eval-Befehl | ✅ JS-Ausführung | ❌ |
| JSX-Renderer | ✅ Programmatisch | ❌ |
@@ -118,11 +118,11 @@ Open Pencil und Penpot verwenden beide Skia für das Rendering, aber die Impleme
| **Figma-Kompatibilität** | Open Pencil | Natives .fig + Zwischenablage |
| **Programmierbarkeit** | Open Pencil | CLI, eval, JSX, MCP-Server |
| **Desktop-Erlebnis** | Open Pencil | Native Tauri-App, ~5 MB |
-| **KI-Integration** | Open Pencil | 29 Werkzeuge, MCP, integrierter Chat |
+| **KI-Integration** | Open Pencil | 75 Werkzeuge, MCP, integrierter Chat |
| **Codebasis-Einfachheit** | Open Pencil | 11× weniger Code, 1 Sprache |
| **CSS Grid** | Penpot | Yoga unterstützt es noch nicht |
| **SVG-native** | Penpot | SVG ist die Muttersprache |
| **Self-Hosting** | Penpot | Docker-bereit vs. Desktop-only |
| **Ökosystem-Reife** | Penpot | Jahre der Produktion vs. frühe Phase |
-Open Pencil ist architektonisch schlanker — ein Single-Process-CanvasKit-Renderer in ~26K LOC TypeScript, Figma-kompatibel by Design. Penpot ist eine Full-Stack-Plattform mit ~299K LOC über Clojure, ClojureScript, Rust und SCSS, plus eine Docker-Service-Flotte. Der Kompromiss ist, dass Penpot bereits Produktions-Kollaboration, ein Plugin-Ökosystem und serverseitigen Export hat, während Open Pencil noch darauf hinarbeitet.
+Open Pencil ist architektonisch schlanker — ein Single-Process-CanvasKit-Renderer in ~26K LOC TypeScript, Figma-kompatibel by Design. Penpot ist eine Full-Stack-Plattform mit ~299K LOC über Clojure, ClojureScript, Rust und SCSS, plus eine Docker-Service-Flotte. Beide bieten jetzt Echtzeit-Kollaboration (unterschiedliche Architekturen: P2P vs. Server). Penpot hat ein Plugin-Ökosystem und serverseitigen Export; Open Pencil hat Figma-kompatibles Headless-Scripting, 75 KI/MCP-Werkzeuge und eine native Desktop-App.
diff --git a/packages/docs/de/guide/features.md b/packages/docs/de/guide/features.md
index b7b1706eb..0402f84c2 100644
--- a/packages/docs/de/guide/features.md
+++ b/packages/docs/de/guide/features.md
@@ -12,6 +12,8 @@ Design-Tools sind ein Lieferkettenproblem. Wenn Ihr Tool proprietär ist, bestim
Knoten in Figma auswählen, ⌘C, zu OpenPencil wechseln, ⌘V — sie erscheinen mit Füllungen, Konturen, Auto-Layout, Text, Eckenradien, Effekten und Vektornetzwerken. Funktioniert auch umgekehrt.
+Paste verarbeitet komplexe Szenarien: Vektorpfade werden von Figmas `normalizedSize` auf die tatsächlichen Knotenmaße skaliert, Instanz-Kinder werden aus den `symbolData` ihrer Komponente gefüllt, Component-Sets werden erkannt und `symbolOverrides` für Text, Füllungen, Sichtbarkeit und Layout-Eigenschaften angewendet. Schriften, die von eingefügten Textknoten referenziert werden, werden automatisch geladen.
+
## Vektornetzwerke
Das Stiftwerkzeug verwendet Figmas Vektornetzwerk-Modell — keine einfachen Pfade. Klicken für Eckpunkte, Klicken+Ziehen für Bézier-Kurven mit Tangentengriffen. Offene und geschlossene Pfade werden unterstützt.
@@ -87,6 +89,10 @@ Dokumente unterstützen mehrere Seiten wie Figma. Jede Seite hat einen unabhäng
Knoten werden beim Überfahren mit einem formgerechten Umriss hervorgehoben.
+## Erweitertes Rendering (Tier 1)
+
+Der CanvasKit-Renderer unterstützt vollständige Tier-1-Visualfunktionen: Gradientenfüllungen (linear, radial, angular, diamant), Bildfüllungen, Effekte (Schatten, Unschärfe), Kontureigenschaften (Cap, Join, Dash), Bogendaten, Viewport-Culling, Paint-Wiederverwendung und RAF-Zusammenfassung.
+
## Komponenten & Instanzen
Erstellen Sie wiederverwendbare Komponenten aus Frames oder Auswahlen (⌥⌘K). Live-Synchronisation, Override-Unterstützung und Komponenten-Sets (⇧⌘K).
@@ -103,6 +109,10 @@ Ausgewählte Knoten als PNG, JPG oder WEBP exportieren. Skalierung von 0,5× bis
Rechtsklick auf dem Canvas öffnet ein Figma-ähnliches Kontextmenü mit Zwischenablage, Z-Reihenfolge, Gruppierung, Komponenten- und Sichtbarkeitsaktionen.
+## Z-Ordnung, Sichtbarkeit & Sperre
+
+] bringt ausgewählte Knoten nach vorne, [ sendet nach hinten. ⇧⌘H schaltet Sichtbarkeit um. ⇧⌘L schaltet die Sperre um — gesperrte Knoten können nicht vom Canvas aus ausgewählt oder verschoben werden. Knoten zwischen Seiten verschieben über das Kontextmenü „Auf Seite verschieben".
+
## Web- & Desktop-App
OpenPencil läuft im Browser unter [app.openpencil.dev](https://app.openpencil.dev). Die Desktop-App verwendet eine Tauri v2-Shell (~5 MB).
@@ -115,9 +125,60 @@ Im Browser-Modus bietet eine mit reka-ui Menubar erstellte Menüleiste Zugriff a
Dateien werden 3 Sekunden nach der letzten Szenenänderung automatisch gespeichert.
+## P2P-Kollaboration
+
+Echtzeit-Peer-to-Peer-Kollaboration — kein Server erforderlich. Teilen Sie einen Link und bearbeiten Sie gemeinsam. Basiert auf Trystero (WebRTC) für direkte Peer-Verbindungen und Yjs (CRDT) für konfliktfreie Dokumentensynchronisation.
+
+- **Keine Hosting-Kosten** — Signalisierung über öffentliche MQTT-Broker, Daten fließen direkt zwischen Peers
+- **NAT-Traversal** — Google STUN, Cloudflare STUN und Open Relay TURN-Server
+- **Live-Cursor** — Figma-ähnliche farbige Cursor-Pfeile mit weißem Rand und Namens-Pills, im Bildschirmraum gerendert
+- **Präsenz** — sehen Sie, wer im Raum ist, mit farbigen Avataren
+- **Folgemodus** — klicken Sie auf den Avatar eines Peers, um seinem Viewport in Echtzeit zu folgen
+- **Lokale Persistenz** — y-indexeddb hält den Raum über Seitenaktualisierungen hinweg am Leben
+- **Sichere Räume** — IDs werden mit `crypto.getRandomValues()` generiert
+
+## Multi-Datei-Tabs
+
+Öffnen Sie mehrere Dokumente in Tabs innerhalb eines einzigen Fensters. Tab-Leiste mit Schließen-Buttons. Mittelklick zum Schließen eines Tabs.
+
+- ⌘N oder ⌘T — neuer Tab
+- ⌘W — aktuellen Tab schließen
+- ⌘O — Datei in neuem Tab öffnen
+
+Jeder Tab pflegt seinen eigenen Dokumentzustand, Undo-Verlauf und Viewport.
+
+## Effekt-Rendering
+
+Vollständiges Rendering von Figma-Effekten über CanvasKit:
+
+- **Schlagschatten** — Versatz, Unschärferadius, Ausdehnung, Farbe
+- **Innerer Schatten** — eingefügter Schatten mit Versatz, Unschärfe und Farbe
+- **Ebenen-Unschärfe** — Gaußsche Unschärfe auf der gesamten Ebene
+- **Hintergrund-Unschärfe** — Unschärfe des Inhalts hinter der Ebene (Glas-/Matteffekt)
+- **Vordergrund-Unschärfe** — Unschärfe im Vordergrund
+
+Per-Knoten `SkPicture`-Cache bedeutet, dass unveränderte Schatten-/Unschärfe-Knoten aus dem Cache wiedergegeben werden.
+
+## Multi-Selektion-Eigenschaften
+
+Wählen Sie mehrere Knoten aus und bearbeiten Sie gemeinsame Eigenschaften gleichzeitig:
+
+- Gemeinsame Werte werden in allen Abschnitten normal angezeigt (Position, Größe, Darstellung, Füllung, Kontur, Effekte)
+- Unterschiedliche Werte zeigen „Mixed"
+- Breiten- und Höheneingaben funktionieren über die Auswahl
+- Horizontal/vertikal spiegeln gilt für alle ausgewählten Knoten
+
+## ScrubInput
+
+Alle numerischen Eingaben im Eigenschafts-Panel verwenden eine Zieh-zum-Ändern-Interaktion — horizontal ziehen zum Anpassen des Wertes, oder klicken zum direkten Eingeben. Unterstützt Suffix-Anzeige (°, px, %).
+
+## CI/CD-Builds
+
+GitHub Actions baut native Tauri-Desktop-Apps bei Versions-Tags. Die Build-Matrix umfasst macOS (arm64, x64), Windows (x64, arm64) und Linux (x64). macOS-Builds sind mit Apple-Developer-Zertifikaten signiert und notarisiert. Release-Notes werden automatisch aus CHANGELOG.md befüllt.
+
## KI-Chat
-Integrierter KI-Assistent über den KI-Tab oder ⌘J. Kommuniziert direkt mit OpenRouter. **29 Werkzeuge** für Lesen, Erstellen, Ändern und Organisieren von Design-Elementen. **MCP-Server** für externe KI-Coding-Tools.
+Integrierter KI-Assistent über den KI-Tab oder ⌘J. Kommuniziert direkt mit OpenRouter. **75 Werkzeuge** für Lesen, Erstellen, Ändern und Organisieren von Design-Elementen. **MCP-Server** für externe KI-Coding-Tools.
## @open-pencil/core & CLI
@@ -131,6 +192,14 @@ Die Engine ist in `packages/core/` extrahiert. CLI bietet headless .fig-Dateiope
Alle Befehle unterstützen `--json` für maschinenlesbare Ausgabe.
+## JSX-Renderer
+
+Programmatische Design-Erstellung über TreeNode-Builder-Funktionen aus `@open-pencil/core`. Unterstützt Tailwind-ähnliche Kurzform-Props — `w`, `h`, `bg`, `rounded`, `flex`, `gap`, `p`/`px`/`py`.
+
+## Code-Panel
+
+Der Code-Tab im Eigenschafts-Panel zeigt die JSX-Darstellung der aktuellen Auswahl mit Prism.js-Syntaxhervorhebung und einem Kopieren-Button.
+
## Codequalität
Copy-Paste-Erkennung via jscpd — projektweite Duplikation von 15,6% auf 0,62% reduziert.
diff --git a/packages/docs/de/guide/figma-comparison.md b/packages/docs/de/guide/figma-comparison.md
index 0bb0e041a..3ac8a6f12 100644
--- a/packages/docs/de/guide/figma-comparison.md
+++ b/packages/docs/de/guide/figma-comparison.md
@@ -1,11 +1,226 @@
# Figma-Funktionsmatrix
-Detaillierter Feature-für-Feature-Vergleich zwischen OpenPencil und Figma Design.
+Feature-für-Feature-Vergleich der Figma-Design-Funktionen mit dem aktuellen Implementierungsstand von Open Pencil.
-**Abdeckung:** 87 von 152 Figma-Feature-Punkten adressiert — 69 ✅ vollständig unterstützt, 18 🟡 teilweise, 65 🔲 noch nicht. Zuletzt aktualisiert: 2026-03-03.
+::: tip Statuslegende
+✅ Unterstützt — Funktion funktioniert vollständig · 🟡 Teilweise — Grundverhalten vorhanden, einige Unterfunktionen fehlen · 🔲 Noch nicht implementiert
+:::
-Legende: ✅ Vollständig | 🟡 Teilweise | 🔲 Noch nicht
+**Abdeckung:** 88 von 152 Figma-Feature-Punkten adressiert — 70 ✅ vollständig unterstützt, 18 🟡 teilweise, 64 🔲 noch nicht. Zuletzt aktualisiert: 2026-03-04.
-Für technische Details zu jeder Funktion siehe [Funktionen](/de/guide/features). Für den Architekturvergleich mit Penpot siehe [Vergleich](/de/guide/comparison).
+## Benutzeroberfläche & Navigation
-Vollständige Feature-Tabellen finden Sie in der [englischen Version](/guide/figma-comparison).
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Werkzeugleiste mit Design-Tools | ✅ | Untere Leiste (UI3-Stil): Auswählen, Frame, Sektion, Rechteck, Ellipse, Linie, Text, Hand, Stift |
+| Ebenen-Panel (linke Seitenleiste) | ✅ | Baumansicht mit Auf-/Zuklappen, Drag-Neuordnung, Sichtbarkeits-Toggle; skalierbare Breite |
+| Seiten-Panel | ✅ | Seiten hinzufügen, löschen, umbenennen; Viewport-Zustand pro Seite |
+| Eigenschafts-Panel (rechte Seitenleiste) | ✅ | Abschnitte: Darstellung, Füllung, Kontur, Effekte, Typografie, Layout, Position; skalierbare Breite |
+| Zoom & Schwenken | ✅ | Strg+Scroll, Pinch, ⌘+/⌘−/⌘0, Leertaste+Ziehen, mittlere Maustaste, Hand-Werkzeug (H) |
+| Canvas-Lineale | ✅ | Oben/links Lineale mit Auswahl-Bändern und Koordinaten-Badges |
+| Canvas-Hintergrundfarbe | ✅ | Pro-Seite-Hintergrund über Eigenschafts-Panel |
+| Canvas-Hilfslinien | 🔲 | Figma unterstützt ziehbare Hilfslinien von Linealen |
+| Aktionsmenü / Befehlspalette | 🔲 | Figmas Schnellaktionssuche |
+| Kontextmenü | ✅ | Rechtsklick mit Zwischenablage, Z-Ordnung, Gruppierung, Komponente, Sichtbarkeit, Sperre, Verschieben |
+| Tastaturkürzel | 🟡 | Kern-Kürzel + Komponenten + Z-Ordnung + Sichtbarkeit/Sperre implementiert; Skalieren, Pfeil, Bleistift, Spiegeln, Textformatierung noch nicht verbunden |
+| Suchen und Ersetzen | 🔲 | Textsuche/-ersetzung im gesamten Dokument |
+| Ebenenumriss-Ansicht | 🔲 | Drahtgitteransicht aller Ebenen |
+| Benutzerdefinierte Dateiminiatur | 🔲 | Miniatur beim Export generiert, aber kein benutzerdefinierter Auswähler |
+| Nudge-Wert-Einstellungen | 🔲 | Standard 1px/10px; Figma erlaubt benutzerdefinierte Werte |
+| App-Menü (Browser-Modus) | ✅ | Datei, Bearbeiten, Ansicht, Objekt, Text, Anordnen; Tauri verwendet native Menüs |
+| KI-Werkzeuge | 🟡 | 75 Werkzeuge via OpenRouter + MCP-Server; noch keine KI-generierten Bilder oder KI-Suche |
+
+## Ebenen & Formen
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Formwerkzeuge (Rechteck, Ellipse, Linie, Polygon, Stern) | ✅ | Alle Grundformtypen; Polygonseitenzahl und Stern-Innenradius konfigurierbar |
+| Frames | ✅ | Inhalt beschneiden, unabhängiges Koordinatensystem |
+| Gruppen | ✅ | ⌘G zum Gruppieren, ⇧⌘G zum Entgruppieren |
+| Sektionen | ✅ | Titel-Pills, automatische Übernahme überlappender Knoten, luminanzadaptiver Text |
+| Bogen-Werkzeug (Bögen, Halbkreise, Ringe) | ✅ | arcData mit Start-/Endwinkel und Innenradius |
+| Bleistift (Freihand-Werkzeug) | 🔲 | Figmas Freihand-Zeichenwerkzeug |
+| Masken | 🔲 | Formmasken zum Beschneiden von Ebenen |
+| Ebenentypen & Hierarchie | ✅ | 17 Knotentypen, flache Map + Eltern-Kind-Baum |
+| Ebenen auswählen | ✅ | Klick, Umschalt-Klick, Markierungsauswahl |
+| Ausrichtung & Position | ✅ | Position, Drehung, Abmessungen im Panel |
+| Objekte kopieren & einfügen | ✅ | Standard-Zwischenablage + Figma-Kiwi-Binärformat |
+| Ebenen proportional skalieren | 🟡 | Umschalt-Resize hält Proportionen; kein dediziertes Scale-Werkzeug (K) |
+| Ebenen sperren/entsperren | ✅ | ⇧⌘L schaltet Sperre um |
+| Ebenensichtbarkeit umschalten | ✅ | Augen-Icon im Panel + ⇧⌘H-Kürzel |
+| Ebenen umbenennen | 🟡 | Programmatisches Umbenennen via Store; noch kein Inline-Umbenennen-UI |
+| Nach vorne / Nach hinten | ✅ | ] und [ Tastaturkürzel; auch im Kontextmenü |
+| Auf Seite verschieben | ✅ | Knoten zwischen Seiten verschieben via Kontextmenü |
+| Einschränkungen (responsives Resize) | 🔲 | Kanten/Mitte fixieren für Eltern-Resize-Verhalten |
+| Intelligente Auswahl (verteilen/ausrichten) | 🔲 | Gleichmäßig verteilen und ausrichten |
+| Layout-Hilfslinien (Spalten, Zeilen, Raster) | 🔲 | Spalten-/Zeilen-/Raster-Hilfslinien auf Frames |
+| Abstände zwischen Ebenen messen | 🔲 | Alt-Hover zeigt Abstände |
+| Objekte in Masse bearbeiten | ✅ | Multi-Selektion-Panel: gemeinsame Werte normal, unterschiedliche zeigen „Mixed" |
+| Übereinstimmende Objekte identifizieren | 🔲 | Ähnliche Ebenen finden |
+| Eigenschaften kopieren/einfügen | 🔲 | Füllung/Kontur/Effekte zwischen Ebenen kopieren |
+| Eltern-Kind-Beziehungen | ✅ | Vollständige Hierarchie mit parentIndex, Drag-Reparenting |
+
+## Vektor-Werkzeuge
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Vektornetzwerke | ✅ | Figma-kompatibles Modell, keine einfachen Pfade |
+| Stift-Werkzeug | ✅ | Eckpunkte, Bézier-Kurven, offene/geschlossene Pfade |
+| Vektorebenen bearbeiten | 🟡 | Erstellung funktioniert; fortgeschrittene Vertex-Bearbeitung begrenzt |
+| Boolesche Operationen (Vereinigen, Subtrahieren, Schneiden, Ausschließen) | 🔲 | Formen mit Bool-Operationen kombinieren |
+| Ebenen abflachen | 🔲 | Vektorpfade zusammenführen |
+| Konturen in Pfade umwandeln | 🔲 | Outline-Stroke-Befehl |
+| Text in Pfade umwandeln | 🔲 | Text zu Vektorkonturen abflachen |
+| Shape-Builder-Werkzeug | 🔲 | Interaktives Bool-Werkzeug |
+| Pfad-Offset | 🔲 | Inset/Outset eines Vektorpfads |
+| Pfad vereinfachen | 🔲 | Vektorpunktanzahl reduzieren |
+
+## Text & Typografie
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Textwerkzeug & Inline-Bearbeitung | ✅ | Canvas-native Bearbeitung, Phantom-Textarea, Style-Runs (⌘B/I/U, S-Button) |
+| Textrendering (Paragraph API) | ✅ | CanvasKit Paragraph für Formgebung, Zeilenumbrüche, Metriken |
+| Schriftladung (Systemschriften) | ✅ | Inter Standard, font-kit in Tauri mit OnceLock-Cache, queryLocalFonts im Browser |
+| Schriftfamilie & -stärke | ✅ | FontPicker mit virtuellem Scrollen, Suche, CSS-Vorschau |
+| Schriftgröße & Zeilenhöhe | ✅ | Bearbeitbar im Typografie-Abschnitt |
+| Textausrichtung | 🟡 | Grundausrichtung; Figma hat vertikale Ausrichtung und Auto-Breite/-Höhe-Modi |
+| Textstile | 🟡 | Fett/Kursiv/Unterstrichen/Durchgestrichen pro Auswahl; noch keine wiederverwendbaren benannten Stil-Presets |
+| Text-Resize-Modi | 🔲 | Figmas Auto-Breite, Auto-Höhe, Fixgröße-Modi |
+| Aufzählungs- & nummerierte Listen | 🔲 | Listenformatierung im Text |
+| Links im Text | 🔲 | Hyperlinks innerhalb von Textinhalten |
+| Emojis & intelligente Symbole | 🔲 | Emoji-Rendering und Sonderzeichen |
+| OpenType-Funktionen | 🔲 | Ligaturen, stilistische Alternativen, Tabellenziffern |
+| Variable Schriften | 🔲 | Einstellbare Schriftachsen (Stärke, Breite, Neigung) |
+| CJK-Textunterstützung | 🔲 | Chinesisches, japanisches, koreanisches Textrendering |
+| RTL-Textunterstützung | 🔲 | Rechts-nach-links-Textlayout |
+| Icon-Schriften | 🔲 | Spezielle Behandlung für Icon-Schrift-Glyphen |
+
+## Farbe, Verläufe & Bilder
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Farbauswahl (HSV) | ✅ | HSV-Quadrat, Farbton-Regler, Alpha-Regler, Hex-Eingabe |
+| Einfarbige Füllungen | ✅ | Hex-Farbe mit Deckkraft |
+| Linearer Verlauf | ✅ | Verlaufsstopps, Transformationsgriffe |
+| Radialer Verlauf | ✅ | Gerendert über CanvasKit-Shader |
+| Winkel-Verlauf | ✅ | Sweep-/konischer Verlauf |
+| Diamant-Verlauf | ✅ | Vierpunkt-Diamant-Verlauf |
+| Bildfüllungen | ✅ | Aus Blob-Daten dekodiert mit Skalierungsmodi (Füllen, Anpassen, Beschneiden, Kacheln) |
+| Musterfüllungen | 🔲 | Sich wiederholende Bild-/Musterfüllungen |
+| Mischmodi | 🔲 | Ebenen- und Füllungs-Mischmodi (Multiplizieren, Negativ Multiplizieren, Überlagern usw.) |
+| Bilder & Videos hinzufügen | 🟡 | Bildfüllungen gerendert; kein Drag-and-Drop-Import oder Video-Unterstützung |
+| Bild-Eigenschaftsanpassung | 🔲 | Belichtung, Kontrast, Sättigung usw. |
+| Bild zuschneiden | 🔲 | Interaktives Bildzuschneiden |
+| Pipetten-Werkzeug | 🔲 | Farben vom Canvas aufnehmen |
+| Farbbearbeitung bei gemischter Auswahl | 🔲 | Farben in heterogener Auswahl anpassen |
+| Farbmodelle (RGB, HSL, HSB, Hex) | 🟡 | HSV + Hex im Picker; kein HSL- oder RGB-Modus-Umschalter |
+
+## Effekte & Eigenschaften
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Schlagschatten | ✅ | Versatz, Unschärferadius, Farbe über CanvasKit-Filter |
+| Innerer Schatten | ✅ | Eingefügter Schatteneffekt |
+| Ebenen-Unschärfe | ✅ | Gaußsche Unschärfe auf der Ebene |
+| Hintergrund-Unschärfe | ✅ | Inhalt hinter der Ebene unscharf |
+| Vordergrund-Unschärfe | ✅ | Unschärfe im Vordergrund |
+| Konturstärke | ✅ | Konfigurierbar im Eigenschafts-Panel |
+| Kontur-Endung (Rund, Quadrat, Pfeil) | ✅ | NONE, ROUND, SQUARE, ARROW_LINES, ARROW_EQUILATERAL |
+| Kontur-Verbindung (Gehrung, Abschrägung, Rund) | ✅ | Alle drei Verbindungstypen |
+| Strichmuster | ✅ | Strich-An/Strich-Aus-Muster |
+| Eckenradius | ✅ | Einheitlicher und pro-Ecke-Radius mit unabhängigem Toggle |
+| Eckenglättung (iOS-Stil) | 🔲 | Figmas kontinuierliche Eckenabrundung |
+| Mehrere Füllungen/Konturen pro Ebene | 🔲 | Figma erlaubt gestapelte Füllungen und Konturen |
+
+## Auto Layout
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Horizontaler & vertikaler Fluss | ✅ | Yoga-WASM-Flexbox-Engine |
+| Auto Layout umschalten (⇧A) | ✅ | Auf Frame umschalten oder Auswahl umhüllen |
+| Gap (Abstand zwischen Kindern) | ✅ | Konfigurierbar im Panel |
+| Padding (einheitlich & pro Seite) | ✅ | Alle vier Seiten unabhängig |
+| Justify Content | ✅ | Start, Center, End, Space-Between |
+| Align Items | ✅ | Start, Center, End, Stretch |
+| Kindgröße (fix, füllen, anpassen) | ✅ | Größenmodi pro Kind |
+| Wrap | ✅ | Flex-Wrap für mehrzeiliges Layout |
+| Grid-Auto-Layout-Fluss | 🔲 | Figmas rasterbasiertes Auto-Layout |
+| Kombinierte Flüsse (verschachtelt) | ✅ | Verschachtelte Auto-Layout-Frames mit verschiedenen Richtungen |
+| Drag-Neuordnung in Auto Layout | ✅ | Visueller Einfügeindikator |
+| Min/Max Breite und Höhe | 🔲 | Figma unterstützt Min/Max-Einschränkungen |
+
+## Komponenten & Design-Systeme
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Komponenten erstellen | 🟡 | ⌥⌘K erstellt aus Frame/Gruppe; noch kein Komponenten-Eigenschafts-UI |
+| Komponenten-Sets | 🟡 | ⇧⌘K kombiniert Komponenten; gestrichelter violetter Rand; keine Varianten-Eigenschaftsbearbeitung |
+| Komponenteninstanzen | 🟡 | Instanz aus Kontextmenü erstellen; Live-Sync; kein Override-Bearbeitungs-UI |
+| Varianten | 🔲 | Variantenwechsel und eigenschaftsbasierte Auswahl |
+| Komponenteneigenschaften | 🔲 | Boolesche, Text-, Instanztausch-Eigenschaften |
+| Override-Propagation | ✅ | Änderungen an Hauptkomponente werden propagiert; Overrides erhalten |
+| Variablen (Farbe, Zahl, String, Boolean) | 🟡 | COLOR mit vollem UI; FLOAT/STRING/BOOLEAN definiert ohne Bearbeitungs-UI |
+| Variablensammlungen & Modi | 🟡 | Sammlungen, Modi, activeMode-Wechsel funktionieren; kein Variablen-Theming-UI |
+| Stile (Farbe, Text, Effekt, Layout) | 🔲 | Wiederverwendbare benannte Stil-Presets |
+| Bibliotheken (veröffentlichen, teilen, aktualisieren) | 🔲 | Geteilte Komponenten-/Stil-Bibliotheken |
+| Instanz ablösen | ✅ | ⌥⌘B wandelt Instanz in Frame um |
+| Zur Hauptkomponente navigieren | ✅ | Zur Quellkomponente navigieren, seitenübergreifend |
+
+## Prototyping
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Prototyp-Verbindungen | 🔲 | Geplant für Phase 6 |
+| Auslöser (Klick, Hover, Ziehen usw.) | 🔲 | Geplant für Phase 6 |
+| Aktionen (Navigieren, Overlay, Scroll usw.) | 🔲 | Geplant für Phase 6 |
+| Animationen & Übergänge | 🔲 | Geplant für Phase 6 |
+| Smart Animate | 🔲 | Übereinstimmende Ebenen automatisch animieren |
+| Overlays | 🔲 | Modale/Popover-Prototypen |
+| Scroll- & Overflow-Verhalten | 🔲 | Scrollbare Frames in Prototypen |
+| Prototyp-Flüsse | 🔲 | Benannte Startpunkte |
+| Variablen in Prototypen | 🔲 | Bedingte Logik mit Variablen |
+| Easing & Feder-Animationen | 🔲 | Benutzerdefinierte Animationskurven |
+| Prototypen präsentieren & abspielen | 🔲 | Vollbild-Prototyp-Viewer |
+
+## Import & Export
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| .fig-Datei-Import | ✅ | Vollständiger Kiwi-Codec: 194 Definitionen, ~390 Felder pro NodeChange |
+| .fig-Datei-Export | ✅ | Kiwi-Encoding + Zstd-Kompression + Miniatur-Generierung |
+| Speichern / Speichern unter | ✅ | ⌘S / ⇧⌘S; native Dialoge (Tauri), File System Access API (Chrome/Edge), Download-Fallback (Safari) |
+| Figma-Zwischenablage (Einfügen) | ✅ | Kiwi-Binär aus Figma-Zwischenablage dekodieren |
+| Figma-Zwischenablage (Kopieren) | ✅ | Kiwi-Binär kodieren, das Figma lesen kann |
+| Sketch-Datei-Import | 🔲 | .sketch-Datei-Parsing |
+| Bild/SVG-Export | 🟡 | PNG/JPG/WEBP mit Skalierung und Vorschau; SVG/PDF noch nicht |
+| Versionsverlauf | 🔲 | Vorherige Versionen durchsuchen und wiederherstellen |
+| Assets zwischen Tools kopieren | 🟡 | Figma-Zwischenablage funktioniert; kein SVG/PDF-Clipboard |
+
+## Plugin-API & Scripting
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Eval-Befehl mit Figma Plugin API | ✅ | Headless-JavaScript-Ausführung mit kompatiblem figma-Globalobjekt |
+
+## Kollaboration & Entwicklermodus
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Kommentare (Anheften, Threads, Auflösen) | 🔲 | Geplant für Phase 6 |
+| Echtzeit-Multiplayer | ✅ | P2P via Trystero + Yjs CRDT, Cursor, Folgemodus; kein Server |
+| Cursor-Chat | 🔲 | Inline-Chat-Blasen am Cursor |
+| Branching & Merging | 🔲 | Versions-Branches für Design-Dateien |
+| Entwicklermodus (Inspizieren) | 🟡 | Code-Tab zeigt JSX; keine CSS-Eigenschaften oder Handoff-Specs |
+| Code Connect | 🔲 | Design-Komponenten mit Code verknüpfen |
+| Code-Snippets | 🟡 | JSX-Export mit Hervorhebung und Kopieren; keine CSS/Swift/Kotlin-Snippets |
+| Figma für VS Code | 🔲 | Editor-Plugin-Integration |
+| MCP-Server | ✅ | @open-pencil/mcp mit stdio + HTTP-Transporten; 75 Kern-Werkzeuge + 3 Dateiverwaltung |
+| CLI-Werkzeuge | ✅ | Headless-CLI: info, tree, find, export, analyze, node, pages, variables, eval; MCP-Server |
+
+## Figma Draw
+
+| Funktion | Status | Anmerkungen |
+|----------|--------|-------------|
+| Illustrations-Werkzeuge | 🔲 | Spezialisierte Zeichenwerkzeuge von Figma Draw |
+| Muster-Transformationen | 🔲 | Sich wiederholende Muster mit Transformationen erstellen |
diff --git a/packages/docs/de/guide/tech-stack.md b/packages/docs/de/guide/tech-stack.md
index 2eabe5657..2ad81aa2f 100644
--- a/packages/docs/de/guide/tech-stack.md
+++ b/packages/docs/de/guide/tech-stack.md
@@ -10,7 +10,9 @@
| **Styling** | Tailwind CSS 4 | Utility-first, schnelle Iteration, dunkles Theme |
| **Layout** | Yoga WASM | CSS-Flexbox-Engine von Meta, kampferprobt in React Native |
| **Dateiformat** | Kiwi-Binär + Zstd | Figmas eigenes Format — kompakt, schnelles Parsen, .fig-kompatibel |
+| **Kollaboration** | Trystero + Yjs | P2P-WebRTC über MQTT-Signalisierung, CRDT-Sync, y-indexeddb-Persistenz |
| **Farbe** | culori | Farbraum-Konvertierungen (HSV, RGB, Hex) |
+| **KI/MCP** | MCP SDK + Hono | 75 Tools für KI-Coding-Werkzeuge, stdio- + HTTP-Transporte |
| **Desktop** | Tauri v2 | ~5 MB native App (vs. Electrons ~100 MB), Rust-Backend |
| **Build** | Vite 7 | Schnelles HMR, native ES-Module |
| **Testing** | Playwright + bun:test | Visuelle Regression (E2E) + schnelle Unit-Tests |
@@ -18,6 +20,24 @@
| **Formatierung** | oxfmt | Rust-basierter Formatierer |
| **Typprüfung** | typescript-go (tsgo) | Native Go-Implementierung des TypeScript-Typprüfers |
+## Wichtige Abhängigkeiten
+
+```json
+{
+ "canvaskit-wasm": "^0.40.0",
+ "vue": "^3.5.29",
+ "yoga-layout": "^3.2.1",
+ "reka-ui": "^2.8.2",
+ "tailwindcss": "^4.2.1",
+ "culori": "^4.0.2",
+ "fzstd": "^0.1.1",
+ "fflate": "^0.8.2",
+ "trystero": "^0.20.0",
+ "yjs": "^13.6.24",
+ "y-indexeddb": "^9.0.12"
+}
+```
+
## Warum nicht...
### Warum kein SVG-Rendering?
@@ -35,3 +55,9 @@ Das Projekt migrierte früh von React zu Vue 3. Vues Reaktivitätssystem und Vue
### Warum keine eigene Layout-Engine?
Yoga wird von Meta gepflegt, ist auf Milliarden von React-Native-Geräten getestet und implementiert die CSS-Flexbox-Spezifikation.
+
+## Geplante Technologien
+
+| Technologie | Zweck | Phase |
+|-----------|---------|-------|
+| CSS Grid in Yoga | Grid-basiertes Auto-Layout | Blockiert durch Upstream (facebook/yoga#1893) |
diff --git a/packages/docs/de/reference/mcp-tools.md b/packages/docs/de/reference/mcp-tools.md
index e5708d8f0..c59cb8511 100644
--- a/packages/docs/de/reference/mcp-tools.md
+++ b/packages/docs/de/reference/mcp-tools.md
@@ -24,7 +24,7 @@ Add to your MCP config (e.g. `~/.claude/settings.json` or `.cursor/mcp.json`):
}
```
-Installation:Oder aus dem Quellcode ausführen:
+Oder aus dem Quellcode ausführen:
::: code-group
```json [Bun]
@@ -73,7 +73,7 @@ Starts on port 3100 (override with `PORT` env var). Endpoints:
5. **Structure** — `reparent_node`, `group_nodes`, `clone_node`, `delete_node`
6. **Save** — `save_file` to write back to `.fig`
-## Tools (29)
+## Tools (75)
### Document
diff --git a/packages/docs/development/contributing.md b/packages/docs/development/contributing.md
index fe64506b1..998a74885 100644
--- a/packages/docs/development/contributing.md
+++ b/packages/docs/development/contributing.md
@@ -7,7 +7,9 @@ packages/
core/ @open-pencil/core — engine (zero DOM deps)
src/ Scene graph, renderer, layout, codec, kiwi, types
cli/ @open-pencil/cli — headless CLI for .fig operations
- src/commands/ info, tree, find, export
+ src/commands/ info, tree, find, export, eval, analyze
+ mcp/ @open-pencil/mcp — MCP server for AI tools
+ src/ stdio + HTTP (Hono) transports, 75 tools
src/
components/ Vue SFCs (canvas, panels, toolbar, color picker)
properties/ Property panel sections (Appearance, Fill, Stroke, etc.)
@@ -87,7 +89,10 @@ Engine source lives in `packages/core/src/`. The app's `src/engine/` and `src/ki
| `packages/core/src/kiwi/codec.ts` | Kiwi binary encoder/decoder |
| `packages/core/src/kiwi/fig-import.ts` | .fig file import logic |
| `packages/cli/src/index.ts` | CLI entry point |
-| `packages/cli/src/commands/` | CLI commands (info, tree, find, export) |
+| `packages/core/src/tools/schema.ts` | Unified tool definitions (AI, MCP, CLI) |
+| `packages/core/src/figma-api.ts` | Figma Plugin API implementation |
+| `packages/mcp/src/server.ts` | MCP server factory |
+| `packages/cli/src/commands/` | CLI commands (info, tree, find, export, eval, analyze) |
| `src/stores/editor.ts` | Global editor state |
| `src/composables/use-canvas.ts` | Canvas rendering composable |
| `src/composables/use-canvas-input.ts` | Mouse/touch input handling |
diff --git a/packages/docs/development/roadmap.md b/packages/docs/development/roadmap.md
index 5c9d3753f..576911749 100644
--- a/packages/docs/development/roadmap.md
+++ b/packages/docs/development/roadmap.md
@@ -95,43 +95,59 @@ Components, instances, overrides, variables, collections, modes, image export.
- Variable types: FLOAT, STRING, BOOLEAN editing UI
- Variable-driven theming
-### Phase 5: AI Integration & Tooling 🟡
+### Phase 5: AI Integration & Tooling ✅
-Core extraction, CLI, MCP server, design guidelines, screenshot verification loop.
+Core extraction, CLI, MCP server, AI tools, eval command.
**Delivered:**
- @open-pencil/core extracted to packages/core/ (zero DOM deps, Bun workspace)
-- @open-pencil/cli with headless .fig operations (info, tree, find, export, analyze, node, pages, variables), CanvasKit CPU rasterization, --json output
+- @open-pencil/cli with headless .fig operations (info, tree, find, export, analyze, node, pages, variables, eval), CanvasKit CPU rasterization, --json output
+- `eval` command with Figma-compatible Plugin API for headless scripting
- JSX renderer: TreeNode builders (Frame, Text, Rectangle, etc.), renderTreeNode/renderJsx, Tailwind-like shorthand props, 27 tests
- jscpd copy-paste detection (15.6% → 0.62%), kiwi-serialize.ts consolidation
- .fig roundtrip tests with LFS fixtures (material3.fig 87K nodes, nuxtui.fig 314K nodes)
- .fig import O(n²) → O(n) fix (37s → 535ms on 87K nodes), ByteBuffer optimization
-- test:coverage script
-- AI chat: OpenRouter direct (no backend), Stronghold key storage, 26 tools (create_shape, set_fill, set_effects, set_constraints, components, groups, pages, variables, eval_code, etc.), model selector, ⌘J toggle, streaming markdown, Playwright tests with mock transport
+- AI chat: OpenRouter direct (no backend), Stronghold key storage, 75 tools defined once in `schema.ts`, model selector, ⌘J toggle, streaming markdown, Playwright tests with mock transport
+- 49 additional AI/MCP tools ported from figma-use (75 total): granular set tools, node operations, variable CRUD, boolean operations, vector path tools, viewport control
+- MCP server (@open-pencil/mcp): stdio + HTTP (Hono + Streamable HTTP with sessions), 75 core tools + 3 file management tools, runs on Bun and Node.js
+- Unified tool definitions: define once in `schema.ts`, adapt for AI chat (valibot), MCP (zod), CLI (eval)
- Code panel: sceneNodeToJsx() export, Prism.js highlighting, line numbers, copy button, 14 tests
- Properties panel restructured: Design | Code | AI tabs
-- npm publishing preparation for core and cli packages
+- App menu bar for browser mode (File, Edit, View, Object, Text, Arrange)
+- Autosave: debounced 3s write after last scene change
+- Multi-selection properties panel with shared/mixed value handling
+- npm publishing with provenance for core, cli, and mcp packages
**Planned:**
-- Port remaining figma-use tools (118 total, 26 currently implemented)
- Attached mode: WebSocket to running editor for eval, create, export, screenshot
- Design guidelines system
-- AI-driven design workflow via MCP
- Screenshot verification loop
-### Phase 6: Polish + Distribution 🔲
+### Phase 6: Collaboration + Distribution 🟡
-Prototyping, comments, desktop distribution, documentation, public launch.
+Real-time collaboration, prototyping, comments, desktop distribution.
+
+**Delivered:**
+- P2P collaboration via Trystero (WebRTC) + Yjs CRDT — no server relay
+- Awareness protocol: live cursors, selections, presence with colored cursor arrows
+- Follow mode: click peer avatar to follow their viewport
+- Local persistence via y-indexeddb
+- Share link at `/share/` with secure room IDs
+- Effects rendering: drop shadow, inner shadow, shadow spread, layer blur, background blur, foreground blur
+- Per-node SkPicture cache for effects (zero re-computation for static effects)
+- Multi-file tabs: ⌘N/⌘T new tab, ⌘W close, ⌘O open in new tab
+- Apple code signing and notarization for macOS builds
+- Linux builds (x64) added to CI
+- Git LFS moved to Cloudflare R2
+- VitePress documentation site at openpencil.dev with i18n (6 languages)
+- CI/PR templates, CONTRIBUTING.md, SECURITY.md
**Planned:**
-- Prototyping (frame connections, transitions)
+- Prototyping (frame connections, transitions, animations)
- Comments (pin, threads, resolve)
-- Linux Tauri builds (macOS and Windows already covered by CI)
- PWA support
-- Documentation site (VitePress)
-- Performance optimization (Lighthouse > 90)
+- Variant switching, FLOAT/STRING/BOOLEAN variable UI, variable-driven theming
- Full Figma compatibility test suite
-- Deferred from Phase 4: variant switching, FLOAT/STRING/BOOLEAN variable UI, variable-driven theming
## Timeline
@@ -141,5 +157,5 @@ Prototyping, comments, desktop distribution, documentation, public launch.
| Phase 2: Editor UI + Layout | 3 months | ✅ Complete |
| Phase 3: File I/O + Visual Features | 2 months | ✅ Complete |
| Phase 4: Components + Variables | 2 months | ✅ Complete |
-| Phase 5: AI Integration & Tooling | 2 months | 🟡 In Progress |
-| Phase 6: Polish + Distribution | 2 months | 🔲 Planned |
+| Phase 5: AI Integration & Tooling | 2 months | ✅ Complete |
+| Phase 6: Collaboration + Distribution | 2 months | 🟡 In Progress |
diff --git a/packages/docs/es/development/contributing.md b/packages/docs/es/development/contributing.md
index 9c07b8211..a2a426770 100644
--- a/packages/docs/es/development/contributing.md
+++ b/packages/docs/es/development/contributing.md
@@ -4,38 +4,50 @@
```
packages/
- core/ @open-pencil/core — Engine
- cli/ @open-pencil/cli — Headless CLI
- mcp/ @open-pencil/mcp — MCP server
- docs/ @open-pencil/docs — VitePress
+ core/ @open-pencil/core — motor (sin deps DOM)
+ src/ Grafo de escena, renderer, layout, codec, kiwi, tipos
+ cli/ @open-pencil/cli — CLI headless para operaciones .fig
+ src/commands/ info, tree, find, export, eval, analyze
+ mcp/ @open-pencil/mcp — servidor MCP para herramientas IA
+ src/ Transportes stdio + HTTP (Hono), 75 herramientas
src/
- components/ Vue SFCs
- composables/ Canvas input, shortcuts, rendering
- stores/ Editor state
-desktop/ Tauri v2
+ components/ Vue SFCs (canvas, paneles, barra de herramientas, selector de color)
+ properties/ Secciones del panel de propiedades (Apariencia, Relleno, Trazo, etc.)
+ composables/ Entrada de canvas, atajos de teclado, hooks de renderizado
+ stores/ Estado del editor (reactividad Vue)
+ engine/ Shims de re-exportación desde @open-pencil/core
+ kiwi/ Shims de re-exportación desde @open-pencil/core
+ types.ts Tipos compartidos (re-exportados desde core)
+ constants.ts Colores UI, valores por defecto, umbrales
+desktop/ Tauri v2 (Rust + config)
tests/
- e2e/ Playwright
- engine/ bun:test
-openspec/ Specs + changes
+ e2e/ Regresión visual Playwright
+ engine/ Tests unitarios (bun:test)
+docs/ Sitio de documentación VitePress
+openspec/
+ specs/ Especificaciones de capacidades (fuente de verdad)
+ changes/ Cambios activos y archivados
```
## Entorno de desarrollo
```sh
bun install
-bun run dev # Editor: localhost:1420
-bun run docs:dev # Docs: localhost:5173
+bun run dev # Editor en localhost:1420
+bun run docs:dev # Docs en localhost:5173
```
## Estilo de código
### Herramientas
-| Tool | Command | Purpose |
-|------|---------|---------|
-| oxlint | `bun run lint` | Linting |
-| oxfmt | `bun run format` | Formatting |
-| tsgo | `bun run typecheck` | Type checking |
+| Herramienta | Comando | Propósito |
+|-------------|---------|-----------|
+| oxlint | `bun run lint` | Linting (basado en Rust, rápido) |
+| oxfmt | `bun run format` | Formateo de código |
+| tsgo | `bun run typecheck` | Verificación de tipos (checker TypeScript basado en Go) |
+
+Ejecutar todas las verificaciones:
```sh
bun run check
@@ -43,23 +55,45 @@ bun run check
### Convenciones
-- kebab-case (files), PascalCase (components/types), camelCase (functions), SCREAMING_SNAKE_CASE (constants)
-- AGENTS.md — [GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)
+- **Nombres de archivo** — kebab-case (`scene-graph.ts`, `use-canvas-input.ts`)
+- **Componentes** — PascalCase Vue SFCs (`EditorCanvas.vue`, `ScrubInput.vue`)
+- **Constantes** — SCREAMING_SNAKE_CASE
+- **Funciones/variables** — camelCase
+- **Tipos/interfaces** — PascalCase
+
+### Convenciones para agentes IA
+
+Desarrolladores y agentes IA deben leer `AGENTS.md` en la raíz del repo ([ver en GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)). Cubre renderizado, grafo de escena, componentes e instancias, layout, UI, formato de archivo, convenciones Tauri y problemas conocidos.
## Realizar cambios
-1. [OpenSpec](./openspec) specs
-2. `openspec new change "name"`
-3. `bun run check && bun run test`
-4. Pull request
+1. Consultar las [specs de openspec](/development/openspec) existentes para la capacidad que estás modificando
+2. Crear un cambio openspec si añades nuevo comportamiento: `openspec new change "mi-cambio"`
+3. Implementar el cambio
+4. Ejecutar `bun run check` y `bun run test`
+5. Enviar un pull request
## Archivos clave
-| File | Purpose |
-|------|---------|
-| `packages/core/src/scene-graph.ts` | Scene graph |
-| `packages/core/src/renderer.ts` | CanvasKit rendering |
-| `packages/core/src/layout.ts` | Yoga layout |
-| `packages/core/src/kiwi/codec.ts` | Kiwi codec |
-| `packages/cli/src/commands/` | CLI commands |
-| `src/stores/editor.ts` | Editor state |
+El código fuente del motor vive en `packages/core/src/`. Los directorios `src/engine/` y `src/kiwi/` de la app son shims de re-exportación — edita el paquete core, no los shims.
+
+| Archivo | Propósito |
+|---------|-----------|
+| `packages/core/src/scene-graph.ts` | Grafo de escena: nodos, variables, instancias, hit testing |
+| `packages/core/src/renderer.ts` | Pipeline de renderizado CanvasKit |
+| `packages/core/src/layout.ts` | Adaptador de layout Yoga |
+| `packages/core/src/undo.ts` | Gestor de deshacer/rehacer |
+| `packages/core/src/clipboard.ts` | Portapapeles compatible con Figma |
+| `packages/core/src/vector.ts` | Modelo de red vectorial |
+| `packages/core/src/render-image.ts` | Exportación de imagen offscreen (PNG/JPG/WEBP) |
+| `packages/core/src/kiwi/codec.ts` | Codificador/decodificador binario Kiwi |
+| `packages/core/src/kiwi/fig-import.ts` | Lógica de importación de archivos .fig |
+| `packages/cli/src/index.ts` | Punto de entrada del CLI |
+| `packages/core/src/tools/schema.ts` | Definiciones unificadas de herramientas (IA, MCP, CLI) |
+| `packages/core/src/figma-api.ts` | Implementación de Figma Plugin API |
+| `packages/mcp/src/server.ts` | Factory del servidor MCP |
+| `packages/cli/src/commands/` | Comandos CLI (info, tree, find, export, eval, analyze) |
+| `src/stores/editor.ts` | Estado global del editor |
+| `src/composables/use-canvas.ts` | Composable de renderizado del canvas |
+| `src/composables/use-canvas-input.ts` | Manejo de entrada ratón/touch |
+| `src/composables/use-keyboard.ts` | Manejo de atajos de teclado |
diff --git a/packages/docs/es/development/roadmap.md b/packages/docs/es/development/roadmap.md
index 1ea211a73..1b782794c 100644
--- a/packages/docs/es/development/roadmap.md
+++ b/packages/docs/es/development/roadmap.md
@@ -1,32 +1,67 @@
# Hoja de ruta
-## Fase 1 ✅
-SceneGraph, Skia rendering, shapes, selection, zoom/pan, undo/redo, snap guides.
+## Fases
-## Motor Core ✅
-Vue 3 + Reka UI panels, properties, layers, toolbar, Yoga auto-layout, inline text editing, canvas rulers.
+### Fase 1: Motor Core ✅
-## Fase 2 ✅
-.fig import/export, Kiwi codec, clipboard, pen tool, vector networks, groups, Tauri v2 desktop, sections, multi-page, hover highlight, Tier 1 rendering.
+SceneGraph, renderizado Skia, formas básicas, selección, zoom/pan, deshacer/rehacer, guías de ajuste.
-## UI Editor + Layout ✅
-Components, instances, overrides, component sets, variables (COLOR/FLOAT/STRING/BOOLEAN), collections, modes, image export, context menu, rich text formatting.
+### Fase 2: UI del Editor + Layout ✅
-## Fase 3 🟡
-@open-pencil/core, CLI (12 commands), MCP server (29+ tools), AI chat (OpenRouter), JSX renderer, code panel.
+Vue 3 + Reka UI panels, propiedades, capas, barra de herramientas, Yoga auto-layout, edición de texto inline, reglas del canvas.
-**Planned:** port remaining figma-use tools, attached mode, design guidelines, screenshot verification loop.
+### Fase 3: E/S de Archivos + Funciones Visuales ✅
-## E/S Archivos + Funciones Visuales 🔲
-Prototyping, comments, PWA, Linux Tauri builds, performance optimization, full Figma compatibility test suite.
+Importación/exportación .fig, codec Kiwi, portapapeles, herramienta de pluma, redes vectoriales, grupos, Tauri v2 desktop, secciones, multi-página, resaltado hover, renderizado Tier 1.
-## Fase 4
+### Fase 4: Componentes + Variables ✅
-| Phase | Componentes + Variables | Fase 5: Integración IA & Herramientas:Fase 6: Pulido + Distribución:Cronograma:Duración estimada:Estado |
-|-------|------|-----|
-| Fase 1 | 3 months | ✅ |
-| Motor Core | 3 months | ✅ |
-| Fase 2 | 2 months | ✅ |
-| UI Editor + Layout | 2 months | ✅ |
-| Fase 3 | 2 months | 🟡 |
-| E/S Archivos + Funciones Visuales | 2 months | 🔲 |
+Componentes, instancias, overrides, conjuntos de componentes, variables (COLOR/FLOAT/STRING/BOOLEAN), colecciones, modos, exportación de imágenes, menú contextual, formateo de texto enriquecido.
+
+### Fase 5: Integración IA & Herramientas ✅
+
+**Entregado:**
+- @open-pencil/core extraído a packages/core/ (sin dependencias DOM)
+- @open-pencil/cli con operaciones headless .fig (info, tree, find, export, analyze, eval)
+- Comando `eval` con API Plugin compatible con Figma
+- Chat IA: conexión directa OpenRouter, 75 herramientas en `schema.ts`, ⌘J
+- 49 herramientas IA/MCP adicionales portadas de figma-use (75 en total)
+- Servidor MCP (@open-pencil/mcp): stdio + HTTP, 75 herramientas core + 3 de gestión de archivos
+- Definiciones de herramientas unificadas: definir una vez en `schema.ts`, adaptar para chat IA (valibot), MCP (zod), CLI (eval)
+- Menú de aplicación para modo navegador
+- Autoguardado: escritura con debounce de 3s
+- Panel de propiedades multi-selección con valores compartidos/mixtos
+
+**Planificado:**
+- Modo adjunto: WebSocket al editor en ejecución
+- Sistema de pautas de diseño
+
+### Fase 6: Colaboración + Distribución 🟡
+
+**Entregado:**
+- Colaboración P2P vía Trystero (WebRTC) + Yjs CRDT — sin servidor relay
+- Protocolo de awareness: cursores en vivo, selecciones, presencia
+- Modo seguimiento: clic en avatar del par para seguir su viewport
+- Persistencia local vía y-indexeddb
+- Renderizado de efectos: sombra paralela, sombra interior, desenfoque de capa/fondo/primer plano
+- Pestañas multi-archivo: ⌘N/⌘T nueva pestaña, ⌘W cerrar, ⌘O abrir
+- Firma de código Apple y notarización para macOS
+- Builds Linux (x64) añadidos al CI
+- Sitio de documentación VitePress con i18n (6 idiomas)
+
+**Planificado:**
+- Prototipado (conexiones de frames, transiciones, animaciones)
+- Comentarios (pin, hilos, resolver)
+- Soporte PWA
+- Cambio de variantes, UI de variables FLOAT/STRING/BOOLEAN, theming por variables
+
+## Cronograma
+
+| Fase | Duración estimada | Estado |
+|------|------------------|--------|
+| Fase 1: Motor Core | 3 meses | ✅ Completada |
+| Fase 2: UI del Editor + Layout | 3 meses | ✅ Completada |
+| Fase 3: E/S de Archivos + Funciones Visuales | 2 meses | ✅ Completada |
+| Fase 4: Componentes + Variables | 2 meses | ✅ Completada |
+| Fase 5: Integración IA & Herramientas | 2 meses | ✅ Completada |
+| Fase 6: Colaboración + Distribución | 2 meses | 🟡 En progreso |
diff --git a/packages/docs/es/guide/architecture.md b/packages/docs/es/guide/architecture.md
index b1811748c..df6df364a 100644
--- a/packages/docs/es/guide/architecture.md
+++ b/packages/docs/es/guide/architecture.md
@@ -5,29 +5,92 @@
```
┌──────────────────────────────────────────────────────────────────┐
│ Tauri v2 Shell │
+│ │
│ ┌────────────────────────────────────────────────────────────┐ │
-│ │ Vue 3 UI Skia CanvasKit (WASM, 7MB) │ │
+│ │ Editor (Web) │ │
+│ │ │ │
+│ │ Vue 3 UI Skia CanvasKit (WASM, 7MB) │ │
+│ │ - Barra de herramientas - Renderizado vectorial │ │
+│ │ - Paneles - Modelado de texto │ │
+│ │ - Propiedades - Procesamiento de imágenes │ │
+│ │ - Capas - Efectos (desenfoque, sombra) │ │
+│ │ - Selector de color - Exportación (PNG, SVG, PDF) │ │
+│ │ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
-│ │ │ Core Engine (TS): SceneGraph, Layout, Selection │ │ │
+│ │ │ Core Engine (TS) │ │ │
+│ │ │ SceneGraph ─── Layout (Yoga) ─── Selection │ │ │
+│ │ │ │ │ │ │ │
+│ │ │ Undo/Redo ─── Constraints ─── Hit Testing │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
+│ │ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
-│ │ │ .fig import/export ── Kiwi codec │ │ │
+│ │ │ Capa de formato de archivo │ │ │
+│ │ │ .fig import/export ── Kiwi codec ── .svg (previsto) │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
-│ MCP Server (29+ tools) P2P Collaboration (Yjs CRDT) │
+│ │
+│ MCP Server (75+ tools, stdio+HTTP) P2P Collab (Trystero + Yjs) │
└──────────────────────────────────────────────────────────────────┘
```
-La interfaz sigue el layout UI3 de Figma.
+## Diseño del editor
-Renderizado: CanvasKit WASM — GPU, Skia.
+La interfaz sigue el layout UI3 de Figma — barra de herramientas abajo, navegación a la izquierda, propiedades a la derecha:
-Grafo de escena: `Map` — O(1) lookup, hit testing.
+- **Panel de navegación (izquierda)** — Árbol de capas, panel de páginas, biblioteca de assets (previsto)
+- **Canvas (centro)** — Canvas infinito con renderizado CanvasKit, zoom/pan
+- **Panel de propiedades (derecha)** — Secciones contextuales: Apariencia, Relleno, Trazo, Tipografía, Layout, Posición
+- **Barra de herramientas (abajo)** — Selección de herramienta: Seleccionar, Frame, Sección, Rectángulo, Elipse, Línea, Texto, Pluma, Mano
-Formato de archivo: Kiwi binary codec — 194 definitions. [File Format](/reference/file-format).
+## Componentes
-Deshacer/Rehacer: Inverse-command pattern.
+### Renderizado (CanvasKit WASM)
-Portapapeles: Figma-compatible, Kiwi binary.
+El mismo motor de renderizado que Figma. CanvasKit proporciona dibujo 2D acelerado por GPU con:
+- Formas vectoriales (rectángulo, elipse, ruta, línea, estrella, polígono)
+- Modelado de texto vía Paragraph API
+- Efectos (sombras, desenfoques, modos de mezcla)
+- Exportación (PNG, SVG, PDF)
-[Full details in English](/guide/architecture)
+El binario WASM de 7 MB se carga al inicio y crea una superficie GPU en el canvas HTML.
+
+### Grafo de escena
+
+`Map` plano con cadenas GUID como claves. Estructura de árbol vía referencias `parentIndex`. Proporciona búsqueda O(1), recorrido eficiente, hit testing y consultas de área rectangular para selección por marquesina.
+
+Véase [Referencia del grafo de escena](/reference/scene-graph) para los detalles internos.
+
+### Motor de layout (Yoga WASM)
+
+Yoga de Meta proporciona cálculo de layout CSS flexbox. Un adaptador delgado mapea nombres de propiedades de Figma a equivalentes de Yoga:
+
+| Propiedad Figma | Equivalente Yoga |
+|---|---|
+| `stackMode: HORIZONTAL` | `flexDirection: row` |
+| `stackMode: VERTICAL` | `flexDirection: column` |
+| `stackSpacing` | `gap` |
+| `stackPadding` | `padding` |
+| `stackJustify` | `justifyContent` |
+| `stackChildPrimaryGrow` | `flexGrow` |
+
+### Formato de archivo (Kiwi binario)
+
+Reutiliza el probado codec binario Kiwi de Figma con 194 definiciones de mensaje/enum/struct. Pipeline de importación `.fig`: parsear cabecera → descomprimir Zstd → decodificar Kiwi → NodeChange[] → grafo de escena. El pipeline de exportación invierte el proceso: grafo de escena → NodeChange[] → codificar Kiwi → comprimir Zstd → ZIP con miniatura.
+
+Véase [Referencia del formato de archivo](/reference/file-format) para más detalles.
+
+### Deshacer/Rehacer
+
+Patrón de comando inverso. Antes de aplicar cualquier cambio, se captura un snapshot de los campos afectados. El snapshot se convierte en la operación inversa. El batching agrupa cambios rápidos (como arrastre) en entradas de deshacer únicas.
+
+### Portapapeles
+
+Portapapeles bidireccional compatible con Figma. Codifica/decodifica binario Kiwi (mismo formato que archivos .fig) usando eventos nativos de copiar/pegar del navegador (síncronos, no la API asíncrona del Clipboard). El pegado gestiona escalado de rutas vectoriales, población de hijos de instancia, detección de conjuntos de componentes y aplicación de overrides.
+
+### Servidor MCP
+
+`@open-pencil/mcp` expone 75 herramientas core + 3 herramientas de gestión de archivos para herramientas de codificación IA. Dos transportes: stdio para Claude Code/Cursor/Windsurf, HTTP con Hono + Streamable HTTP para scripts y CI. Las herramientas se definen una vez en `packages/core/src/tools/schema.ts` y se adaptan para chat IA (valibot), MCP (zod) y CLI (comando eval).
+
+### Colaboración P2P
+
+Colaboración peer-to-peer en tiempo real vía Trystero (WebRTC) + Yjs CRDT. Sin servidor relay — señalización a través de brokers MQTT públicos, STUN/TURN para traversal NAT. El protocolo de awareness proporciona cursores en vivo, selecciones y presencia. Persistencia local vía y-indexeddb.
diff --git a/packages/docs/es/guide/comparison.md b/packages/docs/es/guide/comparison.md
index 111c97baf..5ce54f8f4 100644
--- a/packages/docs/es/guide/comparison.md
+++ b/packages/docs/es/guide/comparison.md
@@ -1,18 +1,262 @@
-# Comparación con Penpot
+# Open Pencil vs Penpot: Comparación de arquitectura y rendimiento
-| Metric | Open Pencil | Penpot |
-|--------|-------------|--------|
-| Total LOC | **~26,000** | **~299,000** |
-| Source files | 125 | ~2,900 |
-| Languages | TypeScript, Vue | Clojure, ClojureScript, Rust, JS, SQL, SCSS |
-| LOC ratio | **1×** | **~11×** |
-| Rendering | Skia CanvasKit (GPU, WASM) | Skia Rust/WASM (render-wasm v1) |
-| Layout | Yoga WASM (CSS flexbox) | Custom CLJS engine |
-| File format | Figma Kiwi binary (.fig) | Custom SVG + metadata |
-| Desktop | Tauri v2 (~5 MB) | No native client |
-| Backend | None (P2P) | Clojure + PostgreSQL + Redis |
-| Collaboration | P2P (Trystero + Yjs CRDT) | Client-server |
-| AI tools | 29 tools + MCP server | Plugin system |
-| CLI | ✅ 12 commands | ❌ |
+¿Por qué comparar? OpenPencil existe porque las plataformas de diseño cerradas controlan lo que es posible. Entender las diferencias arquitectónicas muestra lo que una alternativa abierta y local-first puede hacer diferente.
-[Full details in English](/guide/comparison)
+::: info Renderer WASM de Penpot
+Penpot 2.x incluye un renderer Rust/Skia WASM (`render-wasm/v1`) activable vía flags del servidor o el parámetro URL `?wasm=true`. El renderer SVG antiguo sigue siendo el predeterminado. Esta página cubre ambos.
+:::
+
+## 1. Escala y tamaño del código
+
+| Métrica | Open Pencil | Penpot |
+|---------|-------------|--------|
+| LOC total | **~26.000** | **~299.000** |
+| Archivos fuente | ~143 | ~2.900 |
+| Lenguajes | TypeScript, Vue | Clojure, ClojureScript, Rust, JS, SQL, SCSS |
+| Motor de renderizado | 1.646 LOC (TS) | 22.000 LOC (Rust/Skia WASM) |
+| Código UI | ~4.500 LOC | ~175.000 LOC (CLJS + SCSS) |
+| Backend | Ninguno (local-first) | 32.600 LOC + 151 archivos SQL |
+| Ratio LOC | **1×** | **~11×** |
+
+Open Pencil es **~11× más pequeño** — y ese es el punto. No es una simplificación; es una arquitectura fundamentalmente diferente.
+
+## 2. Arquitectura
+
+### Open Pencil: cliente monolítico
+
+```
+┌─────────────────────────────────┐
+│ Tauri (shell nativo) │
+│ ┌───────────────────────────┐ │
+│ │ Vue 3 + TypeScript │ │
+│ │ ┌─────────┐ ┌──────────┐│ │
+│ │ │ Editor │ │ Kiwi ││ │
+│ │ │ Store │ │ Codec ││ │
+│ │ └────┬─────┘ └──────────┘│ │
+│ │ │ │ │
+│ │ ┌────▼────────────────┐ │ │
+│ │ │ Scene Graph (TS) │ │ │
+│ │ │ Map │ │ │
+│ │ └────┬────────────────┘ │ │
+│ │ │ │ │
+│ │ ┌────▼────┐ ┌──────────┐│ │
+│ │ │ Skia │ │ Yoga ││ │
+│ │ │CanvasKit│ │ Layout ││ │
+│ │ │ (WASM) │ │ (WASM) ││ │
+│ │ └─────────┘ └──────────┘│ │
+│ └───────────────────────────┘ │
+└─────────────────────────────────┘
+```
+
+**Todo en un proceso.** Sin servidor, sin base de datos, sin Docker. El grafo de escena es un `Map` plano en TypeScript. El renderizado llama a Skia CanvasKit directamente desde TS. El layout es Yoga WASM llamado síncronamente.
+
+### Penpot: cliente-servidor distribuido
+
+```
+┌───────────────────────────────────────────────────────┐
+│ Docker Compose │
+│ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐ │
+│ │ Frontend │ │ Backend │ │ Exporter │ │
+│ │ ClojureScript│ │ Clojure │ │ (Chromium) │ │
+│ │ shadow-cljs │ │ JVM │ │ │ │
+│ │ ┌─────────┐ │ │ ┌────────┐ │ └──────────────┘ │
+│ │ │render- │ │ │ │Postgres│ │ │
+│ │ │wasm │ │ │ │Valkey │ │ ┌──────────────┐ │
+│ │ │(Rust→ │ │ │ │ MinIO │ │ │ MCP │ │
+│ │ │ Skia │ │ │ └────────┘ │ │ Server │ │
+│ │ │ WASM) │ │ │ │ └──────────────┘ │
+│ │ └─────────┘ │ │ │ │
+│ └──────────────┘ └─────────────┘ │
+└───────────────────────────────────────────────────────┘
+```
+
+**Mínimo 5+ servicios.** PostgreSQL para persistencia, Redis (Valkey) para pub/sub y caché, MinIO para almacenamiento de assets, un backend JVM, un exportador Node.js (Chromium headless), más el frontend ClojureScript.
+
+### Veredicto: Arquitectura
+
+La arquitectura de proceso único de Open Pencil elimina: latencia de red entre frontend y backend, overhead de serialización/deserialización en los límites de servicios, complejidad de orquestación de contenedores y overhead de consultas de base de datos.
+
+## 3. Pipeline de renderizado
+
+### Open Pencil: TS → CanvasKit WASM (directo)
+
+```typescript
+// renderer.ts — llamadas directas a CanvasKit desde TypeScript
+renderSceneToCanvas(canvas, graph, pageId) {
+ this.fillPaint.setColor(...)
+ canvas.drawRRect(rrect, this.fillPaint)
+}
+```
+
+- **1 cruce de límite:** TS → WASM (CanvasKit)
+- El grafo de escena vive en el heap JS — sin serialización para renderizar
+- 1.646 LOC de renderer total
+
+### Penpot: JS (compilado de CLJS) → Rust WASM → Skia
+
+```
+ClojureScript (compilado a JS)
+ → descomponer a primitivas + empaquetar en binario en memoria lineal WASM
+ → Rust WASM (vía Emscripten C FFI)
+ → skia-safe (bindings Rust de Skia)
+ → Skia (WebGL)
+```
+
+Cuando está deshabilitado (predeterminado), las formas se renderizan como un árbol DOM SVG. Cuando está habilitado, usa un sistema de renderizado basado en tiles con 11 superficies separadas y caché de hasta 1024 entradas.
+
+### Veredicto: Renderizado
+
+| Aspecto | Open Pencil | Penpot |
+|---------|-------------|--------|
+| Límite JS→WASM | Directo (objetos TS) | Empaquetado binario (104 bytes por forma) |
+| Modelo de renderizado | Inmediato/redibujado completo | Caché por tiles |
+| Gestión de superficies | 1 superficie | 11 superficies |
+| Overhead de memoria | Bajo (sin caché de tiles) | Alto (1024 entradas caché) |
+| Complejidad de código | 1.646 LOC | 22.000 LOC |
+| Código inseguro | Ninguno | Estado global `unsafe` |
+
+## 4. Grafo de escena y modelo de datos
+
+### Open Pencil
+
+```typescript
+// Mapa plano, búsqueda O(1)
+nodes: Map
+// 29 tipos de nodo del esquema Kiwi de Figma
+// ~390 campos por NodeChange (compatible con Figma)
+```
+
+- Interfaces TypeScript con tipos estrictos
+- GUIDs coinciden con el formato `sessionID:localID` de Figma
+- Acceso directo a propiedades — sin capas de indirección
+
+### Penpot
+
+- Datos distribuidos en `common/` (49.600 LOC de .cljc)
+- Módulos de geometría separados para flex layout, grid layout, constraints, bounds, esquinas, efectos
+- Validación de esquema en runtime (Malli)
+- Los datos deben cruzar el límite CLJS→Rust para renderizado
+
+### Veredicto: Modelo de datos
+
+Open Pencil reutiliza el esquema probado de Figma (194 definiciones Kiwi) directamente en TypeScript — cero traducción. Penpot mantiene su propio sistema de tipos a través de Clojure/ClojureScript/Rust, requiriendo sincronización manual entre los tres.
+
+## 5. Motor de layout
+
+### Open Pencil: Yoga WASM (314 LOC)
+
+```typescript
+import Yoga from 'yoga-layout'
+const root = Yoga.Node.create()
+root.setFlexDirection(FlexDirection.Row)
+root.calculateLayout()
+applyYogaLayout(graph, frame, yogaRoot)
+```
+
+314 líneas total. Síncrono, en proceso.
+
+### Penpot: Implementación dual
+
+1. **ClojureScript** (common): `flex_layout/` (6 archivos), `grid_layout/` (5+ archivos)
+2. **Rust WASM**: `flex_layout.rs` (741 LOC), `grid_layout.rs` (843 LOC)
+
+Penpot mantiene **dos motores de layout independientes** que deben producir resultados idénticos.
+
+### Veredicto: Layout
+
+Open Pencil delega en una librería probada (Yoga, usada por React Native en miles de millones de dispositivos) en 314 líneas. Penpot mantiene ~3.000+ LOC de código de layout personalizado duplicado.
+
+## 6. Formato de archivo y compatibilidad con Figma
+
+### Open Pencil
+
+- **Formato binario Kiwi nativo** — misma serialización que usa Figma internamente
+- Import directo de archivos `.fig` vía codec Kiwi extraído (2.178 LOC esquema + 551 LOC codec)
+- Soporte de pegado desde el portapapeles de Figma
+- Compatible con el protocolo multiplayer de Figma
+
+### Penpot
+
+- **Archivo ZIP** (`.penpot`) con manifiestos JSON y assets binarios
+- Sin import nativo de `.fig`
+- Tres versiones de formato con sistema de migración
+
+### Veredicto: Formato de archivo
+
+Open Pencil tiene una ventaja significativa — puede leer archivos Figma nativamente y pegar datos del portapapeles de Figma.
+
+## 7. Gestión de estado y deshacer
+
+### Open Pencil
+
+```typescript
+// 110 LOC — patrón de comando inverso
+class UndoManager {
+ apply(entry: UndoEntry) { entry.forward(); this.undoStack.push(entry) }
+ undo() { entry.inverse(); this.redoStack.push(entry) }
+}
+```
+
+110 líneas. Closures forward/inverse que capturan estado mínimo.
+
+### Penpot
+
+Gestión de estado usa Potok (librería tipo Redux para átomos ClojureScript). Undo almacena vectores de cambios inversos (máximo 50 entradas), con transacciones y auto-expiración tras 20 segundos.
+
+### Veredicto: Estado
+
+El enfoque de Open Pencil es más simple y con menos overhead.
+
+## 8. Experiencia de desarrollo
+
+| Métrica | Open Pencil | Penpot |
+|---------|-------------|--------|
+| Setup de dev | `bun install && bun dev` | Docker Compose + JVM + Node + Rust toolchain |
+| Recarga en caliente | Vite HMR (~50ms) | shadow-cljs (segundos) |
+| Verificación de tipos | TypeScript (estricto) | Runtime (esquemas Malli) |
+| Tiempo de build | <5s (Vite) | Minutos (JVM startup + CLJS compile + Rust WASM) |
+| Barrera primera contribución | Baja (TS/Vue) | Alta (Clojure + Rust + Docker) |
+| Desktop | Tauri v2 (~5MB) | N/A (solo navegador) |
+| Pool de contratación | Masivo (devs TS/Vue) | Pequeño (ClojureScript + Rust) |
+
+## 9. Características de rendimiento
+
+| Escenario | Open Pencil | Penpot |
+|-----------|-------------|--------|
+| Arranque en frío | <2s (carga WASM) | 10s+ (servidor + cliente + WASM) |
+| Latencia de operación | <1ms (en proceso) | 10-50ms (round-trip red) |
+| Frame de render | Llamada Skia directa | CLJS→JS→WASM FFI→Skia |
+| Memoria base | ~50MB (pestaña navegador) | ~300MB+ (JVM + Postgres + Valkey + navegador) |
+| Capacidad offline | Completa (local-first) | Ninguna (depende del servidor) |
+| Render 10K formas | Una pasada, sin caché | Basado en tiles con 11 superficies |
+
+## 10. Lo que Penpot hace mejor
+
+1. **Colaboración servidor** — edición multiusuario centralizada con WebSockets, cuentas y control de acceso
+2. **Exportación servidor** — servicio de export con Chromium headless
+3. **Sistema de plugins** — API completa con ejecución sandboxed
+4. **Tokens de diseño** — soporte nativo de design tokens
+5. **CSS Grid layout** — implementación propia (Open Pencil espera Yoga Grid)
+6. **Self-hosting** — despliegue Docker para equipos
+7. **Madurez** — años de uso en producción, probado a escala
+
+## 11. Scripting y extensibilidad
+
+OpenPencil incluye un [comando `eval`](/eval-command) que proporciona una API de Plugin compatible con Figma para scripting headless. Además, 75 herramientas AI disponibles vía chat integrado, servidor MCP (stdio + HTTP) y CLI. Penpot tiene sistema de plugins con ejecución sandboxed pero sin API de scripting headless ni integración MCP.
+
+## Resumen
+
+| Dimensión | Ganador | Por qué |
+|-----------|---------|---------|
+| **Simplicidad arquitectónica** | Open Pencil | Un proceso vs 5+ servicios |
+| **Rendimiento de renderizado** | Open Pencil | CanvasKit directo vs SVG DOM (default) o WASM empaquetado |
+| **Mantenibilidad del código** | Open Pencil | ~26K LOC en 1 lenguaje vs 299K en 4+ |
+| **Compatibilidad Figma** | Open Pencil | Codec Kiwi nativo vs sin soporte .fig |
+| **Onboarding de desarrolladores** | Open Pencil | TS/Vue vs Clojure/Rust/Docker |
+| **Experiencia desktop** | Open Pencil | Tauri nativo vs solo navegador |
+| **Motor de layout** | Open Pencil | Yoga (probado) vs implementación dual personalizada |
+| **Colaboración** | Empate | Penpot: servidor con control de acceso; Open Pencil: P2P vía Trystero + Yjs, zero hosting |
+| **Self-hosting** | Penpot | Listo para Docker vs solo desktop |
+| **Madurez del ecosistema** | Penpot | Años de producción vs etapa temprana |
+
+Open Pencil es arquitectónicamente más ligero — un renderer CanvasKit de proceso único en ~26K LOC de TypeScript, compatible con Figma por diseño. Penpot es una plataforma full-stack con ~299K LOC. Ambos ofrecen colaboración en tiempo real (P2P vs servidor). Penpot tiene ecosistema de plugins y exportación servidor; Open Pencil tiene scripting headless compatible con Figma, 75 herramientas AI/MCP y una app desktop nativa.
diff --git a/packages/docs/es/guide/features.md b/packages/docs/es/guide/features.md
index ebecc9a10..641c3d47c 100644
--- a/packages/docs/es/guide/features.md
+++ b/packages/docs/es/guide/features.md
@@ -2,36 +2,178 @@
## Por qué OpenPencil
-Alternativa open-source: MIT, compatible con Figma, completamente local y programable.
+Las herramientas de diseño son un problema de cadena de suministro. Cuando tu herramienta es de código cerrado, el proveedor controla lo que es posible — pueden romper tu automatización de la noche a la mañana. OpenPencil es una alternativa open-source: licencia MIT, compatible con Figma, completamente local y programable.
-## Import & export .fig
-Abre y guarda archivos Figma nativos. Schema Kiwi completo (194 definiciones). Round-trip fiel.
+## Import & export de archivos .fig de Figma
+
+Abre y guarda archivos nativos de Figma directamente. El import decodifica el esquema Kiwi completo de 194 definiciones incluyendo mensajes NodeChange con ~390 campos. El export codifica el grafo de escena de vuelta a binario Kiwi con compresión Zstd y generación de miniatura. Guardar (⌘S) y Guardar como (⇧⌘S) usan diálogos nativos del SO en la app de escritorio. El pipeline de import/export soporta fidelidad round-trip.
## Copiar y pegar con Figma
-Copiar en Figma, pegar en OpenPencil y viceversa. Mismo formato binario Kiwi.
+
+Selecciona nodos en Figma, ⌘C, cambia a OpenPencil, ⌘V — aparecen con rellenos, trazos, auto-layout, texto, radios de esquina, efectos y redes vectoriales preservados. Funciona también en la otra dirección: copia desde OpenPencil, pega en Figma.
+
+Internamente, ambas direcciones usan el mismo formato binario Kiwi que los archivos .fig. OpenPencil decodifica el esquema completo al pegar (194 definiciones, ~390 campos por NodeChange) y lo codifica al copiar. Los datos vectoriales se transportan ida y vuelta a través del formato binario `vectorNetworkBlob`. También funciona entre instancias de OpenPencil via un formato de portapapeles nativo separado.
+
+El pegado gestiona escenarios complejos: las rutas vectoriales se escalan desde `normalizedSize` de Figma a los límites reales del nodo, los hijos de instancia se pueblan desde el `symbolData` de su componente, los conjuntos de componentes se detectan promoviendo frames con `componentPropDefs` de variante, los nodos del canvas interno se omiten, y los `symbolOverrides` se aplican para texto, rellenos, visibilidad y propiedades de layout. Las fuentes referenciadas por nodos de texto pegados se cargan automáticamente.
+
+## Redes vectoriales
+
+La herramienta pluma usa el modelo de red vectorial de Figma — no rutas simples. Clic para puntos de esquina, clic+arrastrar para curvas de Bézier con asas de tangente. Soporta rutas abiertas y cerradas. Los datos vectoriales usan el mismo formato binario `vectorNetworkBlob` que Figma.
## Herramientas de forma
-Rectángulo (R), Elipse (O), Línea (L), Polígono, Estrella. Relleno, trazo, efectos.
-## Auto-layout
-Yoga WASM (flexbox). Dirección, gap, padding, alineación. ⇧A para activar.
+La barra de herramientas proporciona todas las herramientas de forma básicas de Figma: Rectángulo (R), Elipse (O), Línea (L), Polígono y Estrella. Polígono dibuja polígonos regulares (por defecto 3 lados). Estrella dibuja estrellas puntiagudas (por defecto 5 puntas) con `starInnerRadius` configurable. Todas las formas soportan relleno, trazo, resaltado al pasar el ratón y contorno de selección.
-## Edición de texto
-Edición nativa en el lienzo. Selector de fuentes virtual. Formato enriquecido (B/I/U/S).
+## Auto-Layout
+
+Yoga WASM proporciona layout CSS flexbox. Los frames soportan: dirección (horizontal, vertical, wrap), gap, padding (uniforme o por lado), justify (start, center, end, space-between), align (start, center, end, stretch) y dimensionado de hijos (fijo, rellenar, ajustar). Shift+A alterna auto-layout en un frame o envuelve los nodos seleccionados.
+
+## Edición de texto inline
+
+Edición de texto nativa en el canvas — sin overlay de textarea DOM. Doble clic en un nodo de texto para entrar en modo de edición. El canvas renderiza un cursor parpadeante, rectángulos de selección azules translúcidos y un contorno azul alrededor del nodo. Navegación con teclado con soporte de modificadores: ⌥←/→ para movimiento por palabra, ⌘←/→ para inicio/fin de línea.
+
+**Selector de fuentes** con scroll virtual, filtro de búsqueda y vista previa CSS de fuentes. En Tauri, las fuentes del sistema se enumeran vía el crate Rust `font-kit`. En el navegador, se usa la API Local Font Access cuando está disponible.
+
+## Formateo de texto enriquecido
+
+Formateo por carácter dentro de un nodo de texto. ⌘B para negrita, ⌘I para cursiva, ⌘U para subrayado, o usa los botones B/I/U/S en la sección Tipografía. Implementado vía un modelo StyleRun. El formateo de texto enriquecido se preserva durante import/export .fig.
## Deshacer/Rehacer
-⌘Z / ⇧⌘Z. Patrón inverse-command. Toda operación es reversible.
+
+Toda operación es deshacible — creación/eliminación de nodos, movimientos, redimensionamientos, cambios de propiedades, cambios de padre, cambios de layout y todas las operaciones de variables. ⌘Z deshace, ⇧⌘Z rehace.
+
+## Guías de snap
+
+Snap de bordes y centros con líneas guía rojas cuando los nodos se alinean. Consciente de la rotación — los cálculos de snap usan los límites visuales reales de nodos rotados.
+
+## Reglas del canvas
+
+Reglas en los bordes superior e izquierdo muestran escalas de coordenadas. Al seleccionar un nodo, las reglas resaltan su posición con una banda translúcida y muestran badges de coordenadas.
+
+## Selector de color y tipos de relleno
+
+Selección de color HSV con slider de tono, slider alfa, entrada hex y control de opacidad. El selector de tipo de relleno proporciona pestañas para Sólido, Gradiente (Lineal, Radial, Angular, Diamante) e Imagen.
+
+## Panel de capas
+
+Vista de árbol de la jerarquía del documento usando el componente Reka UI Tree. Expandir/colapsar frames, arrastrar para reordenar (cambia z-order), alternar visibilidad por nodo. Ambos paneles son redimensionables.
+
+## Panel de propiedades
+
+Interfaz con pestañas **Diseño** | **Código** | **IA** (reka-ui Tabs).
+
+La pestaña **Diseño** es contextual con secciones: Apariencia (opacidad, radio de esquina, visibilidad), Relleno, Trazo, Efectos, Tipografía, Layout, Posición, Exportación y Página.
+
+La pestaña **Código** muestra export JSX de la selección. La pestaña **IA** proporciona una interfaz de chat IA.
+
+## Agrupar/Desagrupar
+
+⌘G agrupa nodos seleccionados. ⇧⌘G desagrupa. Los nodos se ordenan por posición visual al agrupar.
+
+## Secciones
+
+Las secciones (S) son contenedores organizacionales de nivel superior en el canvas. Cada sección muestra una píldora de título. El color del texto se invierte automáticamente según la luminancia del fondo.
+
+## Documentos multi-página
+
+Los documentos soportan múltiples páginas como Figma. El panel de páginas permite añadir, eliminar y renombrar páginas. Cada página mantiene un estado de viewport independiente.
+
+## Resaltado al pasar
+
+Los nodos se resaltan al pasar con un contorno que sigue la geometría real — las elipses obtienen contornos elípticos, los rectángulos redondeados obtienen contornos redondeados, los vectores obtienen contornos de ruta.
+
+## Renderizado avanzado (Tier 1)
+
+El renderer CanvasKit soporta las características visuales completas de Tier 1: rellenos de gradiente (lineal, radial, angular, diamante), rellenos de imagen, efectos (sombra, desenfoque), propiedades de trazo (cap, join, dash), datos de arco, culling de viewport, reutilización de Paint y coalescencia RAF.
## Componentes e instancias
-Componentes reutilizables (⌥⌘K), conjuntos (⇧⌘K), sincronización live, overrides.
+
+Crea componentes reutilizables desde frames o selecciones (⌥⌘K). Combina componentes en un COMPONENT_SET (⇧⌘K). Crea instancias desde componentes vía menú contextual. Desacopla una instancia de vuelta a un frame con ⌥⌘B. "Ir al componente principal" navega al componente fuente.
+
+**Sincronización en vivo:** Editar un componente principal propaga cambios a todas sus instancias automáticamente. **Soporte de overrides:** Las instancias mantienen un registro de overrides que se preservan durante la sincronización. Los componentes muestran etiquetas púrpura siempre visibles con icono de diamante.
## Variables
-Tokens de diseño con colecciones y modos. Vinculación a rellenos.
+
+Tokens de diseño como variables con colecciones y modos. Diálogo con TanStack Table con columnas redimensionables. Soporta tipo COLOR con UI completa, tipos FLOAT/STRING/BOOLEAN definidos. Organiza variables en colecciones, define modos (ej: Claro/Oscuro). Vincula variables a colores de relleno. Cadenas de alias con detección de ciclos. Todas las operaciones de variables son deshacibles.
+
+## Exportación de imágenes
+
+Exporta nodos seleccionados como PNG, JPG o WEBP. Selección de escala (0,5×–4×), selector de formato, soporte multi-exportación y vista previa en vivo. Disponible vía menú contextual y ⇧⌘E.
+
+## Menú contextual
+
+Clic derecho en el canvas abre un menú contextual estilo Figma con acciones de: Portapapeles, Orden Z, Agrupación, Componentes (ítems púrpura), Visibilidad y Mover a página.
+
+## Orden Z, visibilidad y bloqueo
+
+] trae nodos al frente, [ envía al fondo. ⇧⌘H alterna visibilidad. ⇧⌘L alterna bloqueo. Mover nodos entre páginas vía submenú "Mover a página".
+
+## App web y de escritorio
+
+OpenPencil funciona en el navegador en [app.openpencil.dev](https://app.openpencil.dev) — sin instalación requerida. La app de escritorio usa Tauri v2 (~5 MB vs ~100 MB de Electron). Funciona completamente offline. Menú nativo en todas las plataformas. Herramientas de desarrollador accesibles vía ⌘⌥I.
+
+## Menú de app (navegador)
+
+En modo navegador, una barra de menú con reka-ui Menubar proporciona acceso a todas las acciones principales del editor. Seis menús: **Archivo**, **Editar**, **Ver**, **Objeto**, **Texto**, **Organizar**. Los atajos de teclado se muestran junto a cada ítem con etiquetas de modificador según la plataforma. Oculto en Tauri, que proporciona sus propios menús nativos.
+
+## Autoguardado
+
+Los archivos se guardan automáticamente 3 segundos después del último cambio de escena. Un watcher con debounce monitorea `sceneVersion`. Usa el plugin fs de Tauri en escritorio o la API File System Access en navegadores compatibles. El autoguardado está deshabilitado para documentos nuevos sin título hasta que el usuario realice un Guardar como explícito.
+
+## Colaboración P2P
+
+Colaboración peer-to-peer en tiempo real — sin servidor requerido. Comparte un enlace y edita junto. Basado en Trystero (WebRTC) para conexiones directas entre pares y Yjs (CRDT) para sincronización de documentos sin conflictos.
+
+- **Zero costes de hosting** — señalización vía brokers MQTT públicos, datos fluyen directamente entre pares
+- **Traversal NAT** — servidores Google STUN, Cloudflare STUN y Open Relay TURN
+- **Cursores en vivo** — flechas de cursor coloreadas estilo Figma con borde blanco y píldoras de nombre
+- **Presencia** — ve quién está en la sala con avatares coloreados
+- **Modo seguimiento** — clic en el avatar de un par para seguir su viewport en tiempo real
+- **Persistencia local** — y-indexeddb mantiene la sala entre recargas de página
+- **Salas seguras** — IDs generados con `crypto.getRandomValues()`
+
+## Pestañas multi-archivo
+
+Abre múltiples documentos en pestañas dentro de una sola ventana. La barra de pestañas muestra archivos abiertos con botones de cierre. Clic medio en una pestaña para cerrarla. ⌘N o ⌘T — nueva pestaña, ⌘W — cerrar pestaña actual, ⌘O — abrir archivo en nueva pestaña.
+
+## Renderizado de efectos
+
+Renderizado completo de efectos Figma vía CanvasKit: **Sombra paralela** (offset, radio de desenfoque, extensión, color), **Sombra interior**, **Desenfoque de capa** (Gaussiano), **Desenfoque de fondo** (efecto cristal/esmerilado), **Desenfoque de primer plano**. Las sombras de texto se renderizan en glifos individuales. Cache SkPicture por nodo para rendimiento.
+
+## Propiedades multi-selección
+
+Selecciona múltiples nodos y edita propiedades compartidas a la vez. Los valores compartidos se muestran normalmente, los valores diferentes muestran "Mixed". Las entradas de ancho y alto funcionan a través de la selección. Voltear H/V se aplica a todos los nodos seleccionados.
+
+## ScrubInput
+
+Todas las entradas numéricas en el panel de propiedades usan interacción de arrastre para ajustar — arrastra horizontalmente para ajustar el valor, o haz clic para escribir directamente. Soporta sufijos (°, px, %).
+
+## Builds CI/CD
+
+GitHub Actions construye apps Tauri nativas en tags de versión. La matriz cubre macOS (arm64, x64), Windows (x64, arm64) y Linux (x64). Los builds de macOS están firmados y notarizados vía certificados Apple Developer. Las notas de release se auto-rellenan desde CHANGELOG.md.
+
+## @open-pencil/core y CLI
+
+El motor está extraído en `packages/core/` (@open-pencil/core) — sin dependencias DOM. El CLI (`packages/cli/`) proporciona operaciones headless .fig: info, tree, find, export, analyze (colors, typography, spacing, clusters), node, pages, variables, eval. Todos los comandos soportan `--json`.
+
+El comando `eval` ejecuta JavaScript contra un archivo `.fig` con un objeto `figma` global compatible con Figma. Véase [Comando Eval](/eval-command) para la referencia completa.
+
+## Renderizador JSX
+
+Creación programática de diseño vía funciones TreeNode builder exportadas desde `@open-pencil/core`. Soporta props shorthand estilo Tailwind — `w`, `h`, `bg`, `rounded`, `flex`, `gap`, `p`/`px`/`py`.
## Chat IA
-29 herramientas vía OpenRouter. Servidor MCP (stdio + HTTP).
-## CLI
-info, tree, find, export, analyze, eval. Todos los comandos soportan `--json`.
+Asistente IA integrado accesible vía la pestaña IA o ⌘J. Comunica directamente con OpenRouter — sin servidor backend requerido.
-[Detalles completos en inglés](/guide/features)
+**75 herramientas** definidas en `packages/core/src/tools/schema.ts`, cubriendo: operaciones de lectura, creación, modificación, manipulación de nodos, CRUD de variables, herramientas de rutas vectoriales, control de viewport y un escape hatch `eval`. Las herramientas están conectadas al chat IA (schemas valibot), servidor MCP (schemas zod) y CLI (comando `eval`).
+
+**Servidor MCP** (`packages/mcp/`) expone todas las herramientas para herramientas de codificación IA externas. Dos transportes: stdio y HTTP con Hono. Añade 3 herramientas de gestión de archivos sobre las 75 herramientas core, para 78 en total.
+
+## Panel de código
+
+La pestaña Código muestra la representación JSX de la selección actual con resaltado de sintaxis Prism.js y botón de copia al portapapeles.
+
+## Calidad de código
+
+Detección de copia-pega vía jscpd — duplicación reducida de 15,6% a 0,62%. Pipeline de importación .fig optimizado de O(n²) a O(n).
diff --git a/packages/docs/es/guide/figma-comparison.md b/packages/docs/es/guide/figma-comparison.md
index 870585e22..98576a16b 100644
--- a/packages/docs/es/guide/figma-comparison.md
+++ b/packages/docs/es/guide/figma-comparison.md
@@ -1,9 +1,226 @@
-# Matriz de funcionalidades Figma
+# Matriz de características de Figma
-**Coverage:** 87 / 152 — 69 ✅, 18 🟡, 65 🔲. (2026-03-03)
+Comparación característica por característica de las capacidades de Figma Design con el estado de implementación actual de Open Pencil.
-✅ = Full | 🟡 = Partial | 🔲 = Not yet
+::: tip Leyenda de estado
+✅ Soportado — la característica funciona de extremo a extremo · 🟡 Parcial — el comportamiento base existe, faltan algunas sub-características · 🔲 Aún no implementado
+:::
-[Full feature matrix in English](/guide/figma-comparison)
+**Cobertura:** 88 de 152 ítems de características de Figma abordados — 70 ✅ completamente soportados, 18 🟡 parciales, 64 🔲 pendientes. Última actualización: 2026-03-04.
-[Features](/es/guide/features) · [Comparison](/es/guide/comparison)
+## Interfaz y navegación
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Barra de herramientas de diseño | ✅ | Barra inferior (estilo UI3): Seleccionar, Frame, Sección, Rectángulo, Elipse, Línea, Texto, Mano, Pluma |
+| Panel de capas (barra lateral izquierda) | ✅ | Vista de árbol con expandir/colapsar, reordenamiento por arrastre, toggle de visibilidad; ancho redimensionable |
+| Panel de páginas | ✅ | Añadir, eliminar, renombrar páginas; estado de viewport por página |
+| Panel de propiedades (barra lateral derecha) | ✅ | Secciones: Apariencia, Relleno, Trazo, Efectos, Tipografía, Layout, Posición; ancho redimensionable |
+| Zoom y pan | ✅ | Ctrl+scroll, pinch, ⌘+/⌘−/⌘0, espacio+arrastrar, ratón medio, herramienta mano (H) |
+| Reglas del canvas | ✅ | Reglas superior/izquierda con bandas de selección y badges de coordenadas |
+| Color de fondo del canvas | ✅ | Fondo por página vía panel de propiedades |
+| Guías del canvas | 🔲 | Figma soporta guías arrastrables desde las reglas |
+| Menú de acciones / paleta de comandos | 🔲 | Búsqueda de acciones rápidas de Figma |
+| Menú contextual | ✅ | Clic derecho con portapapeles, orden-z, agrupación, componente, visibilidad, bloqueo, mover-a-página |
+| Atajos de teclado | 🟡 | Atajos core + componentes + orden-z + visibilidad/bloqueo implementados; Escalar, Flecha, Lápiz, volteo, formateo de texto aún no conectados |
+| Buscar y reemplazar | 🔲 | Búsqueda/reemplazo de texto en el documento |
+| Vista de contornos de capas | 🔲 | Vista wireframe de todas las capas |
+| Miniaturas personalizadas | 🔲 | Miniatura generada en export, pero sin selector de miniatura personalizada |
+| Configuración de valores de nudge | 🔲 | Por defecto 1px/10px; Figma permite valores personalizados |
+| Menú de app (modo navegador) | ✅ | Menús Archivo, Editar, Ver, Objeto, Texto, Organizar; Tauri usa menús nativos |
+| Herramientas IA | 🟡 | 75 herramientas vía OpenRouter + servidor MCP; sin imágenes generadas por IA ni búsqueda IA aún |
+
+## Capas y formas
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Herramientas de forma (Rectángulo, Elipse, Línea, Polígono, Estrella) | ✅ | Todos los tipos de forma básicos; lados del polígono y radio interior de estrella configurables |
+| Frames | ✅ | Recorte de contenido, sistema de coordenadas independiente |
+| Grupos | ✅ | ⌘G para agrupar, ⇧⌘G para desagrupar |
+| Secciones | ✅ | Píldoras de título, auto-adopción de nodos superpuestos, texto adaptativo a luminancia |
+| Herramienta de arco (arcos, semicírculos, anillos) | ✅ | arcData con ángulo inicio/fin y radio interior |
+| Herramienta de lápiz (mano alzada) | 🔲 | Herramienta de dibujo a mano alzada de Figma |
+| Máscaras | 🔲 | Máscaras de forma para recortar capas |
+| Tipos de capa y jerarquía | ✅ | 17 tipos de nodo, Map plano + árbol padre-hijo |
+| Seleccionar capas | ✅ | Clic, shift-clic, selección por marquesina |
+| Alineación y posición | ✅ | Posición, rotación, dimensiones en el panel de propiedades |
+| Copiar y pegar objetos | ✅ | Portapapeles estándar + formato binario Kiwi de Figma |
+| Escalar capas proporcionalmente | 🟡 | Shift-redimensionar mantiene proporciones; sin herramienta Scale dedicada (K) |
+| Bloquear y desbloquear capas | ✅ | ⇧⌘L alterna bloqueo; nodos bloqueados no se pueden seleccionar/mover |
+| Alternar visibilidad de capa | ✅ | Icono de ojo en panel de capas + atajo ⇧⌘H |
+| Renombrar capas | 🟡 | Renombrado programático vía store; sin UI de renombrado inline en panel de capas aún |
+| Traer al frente / Enviar al fondo | ✅ | Atajos ] y [; también en menú contextual |
+| Mover a página | ✅ | Mover nodos entre páginas vía menú contextual |
+| Restricciones (redimensionamiento responsivo) | 🔲 | Fijar bordes/centro para comportamiento de resize del padre |
+| Selección inteligente (distribuir/alinear) | 🔲 | Espaciar y alinear uniformemente multi-selección |
+| Guías de layout (columnas, filas, grid) | 🔲 | Guías de columna/fila/grid en frames |
+| Medir distancias entre capas | 🔲 | Alt-hover para mostrar distancias |
+| Editar objetos en lote | ✅ | Panel de propiedades multi-selección: editar posición, tamaño, apariencia, relleno, trazo, efectos; valores compartidos normales, diferentes muestran "Mixed" |
+| Identificar objetos coincidentes | 🔲 | Encontrar capas similares |
+| Copiar/pegar propiedades | 🔲 | Copiar relleno/trazo/efectos entre capas |
+| Relaciones padre-hijo | ✅ | Jerarquía completa con parentIndex, re-parentamiento por arrastre |
+
+## Herramientas vectoriales
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Redes vectoriales | ✅ | Modelo compatible con Figma, no rutas simples |
+| Herramienta pluma | ✅ | Puntos de esquina, curvas bezier, rutas abiertas/cerradas |
+| Editar capas vectoriales | 🟡 | Creación funciona; edición avanzada de vértices limitada |
+| Operaciones booleanas (Unión, Sustracción, Intersección, Exclusión) | 🔲 | Combinar formas con ops booleanas |
+| Aplanar capas | 🔲 | Fusionar rutas vectoriales en una sola |
+| Convertir trazos a rutas | 🔲 | Comando Outline Stroke |
+| Convertir texto a rutas | 🔲 | Aplanar texto a contornos vectoriales |
+| Herramienta shape builder | 🔲 | Herramienta booleana interactiva |
+| Offset de ruta | 🔲 | Inset/outset de una ruta vectorial |
+| Simplificar ruta | 🔲 | Reducir cantidad de puntos vectoriales |
+
+## Texto y tipografía
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Herramienta de texto y edición inline | ✅ | Edición nativa en canvas, textarea fantasma, cursor/selección/selección de palabra, arrastre, doble/triple clic, style runs (⌘B/I/U, botón S) |
+| Renderizado de texto (Paragraph API) | ✅ | CanvasKit Paragraph para shaping, saltos de línea, métricas |
+| Carga de fuentes (fuentes del sistema) | ✅ | Inter por defecto, font-kit en Tauri con cache OnceLock, queryLocalFonts en navegador |
+| Familia y peso de fuente | ✅ | FontPicker con scroll virtual, búsqueda, vista previa CSS |
+| Tamaño de fuente y altura de línea | ✅ | Editable en sección de tipografía |
+| Alineación de texto | 🟡 | Alineación básica; Figma tiene alineación vertical y modos auto-ancho/alto |
+| Estilos de texto | 🟡 | Negrita/cursiva/subrayado/tachado por selección; sin presets de estilo reutilizables aún |
+| Modos de redimensionamiento de texto | 🔲 | Modos auto-ancho, auto-alto, tamaño-fijo de Figma |
+| Listas con viñetas y numeradas | 🔲 | Formateo de listas en texto |
+| Enlaces en texto | 🔲 | Hipervínculos dentro del contenido de texto |
+| Emojis y símbolos inteligentes | 🔲 | Renderizado de emojis y caracteres especiales |
+| Características OpenType | 🔲 | Ligaduras, alternativas estilísticas, figuras tabulares |
+| Fuentes variables | 🔲 | Ejes de fuente ajustables (peso, ancho, inclinación) |
+| Soporte texto CJK | 🔲 | Renderizado de texto chino, japonés, coreano |
+| Soporte texto RTL | 🔲 | Layout de texto de derecha a izquierda |
+| Fuentes de iconos | 🔲 | Manejo especial para glifos de fuentes de iconos |
+
+## Color, gradientes e imágenes
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Selector de color (HSV) | ✅ | Cuadrado HSV, slider de tono, slider alfa, entrada hex |
+| Rellenos sólidos | ✅ | Color hex con opacidad |
+| Gradiente lineal | ✅ | Paradas de gradiente, asas de transformación |
+| Gradiente radial | ✅ | Renderizado vía shaders CanvasKit |
+| Gradiente angular | ✅ | Soporte gradiente sweep/cónico |
+| Gradiente diamante | ✅ | Gradiente diamante de cuatro puntos |
+| Rellenos de imagen | ✅ | Decodificados de datos blob con modos de escala (fill, fit, crop, tile) |
+| Rellenos de patrón | 🔲 | Rellenos de imagen/patrón repetitivo |
+| Modos de mezcla | 🔲 | Modos de mezcla de capa y relleno (multiply, screen, overlay, etc.) |
+| Añadir imágenes y vídeos | 🟡 | Rellenos de imagen renderizados; sin import drag-and-drop ni soporte de vídeo |
+| Ajuste de propiedades de imagen | 🔲 | Exposición, contraste, saturación, etc. |
+| Recortar una imagen | 🔲 | Recorte interactivo de imágenes |
+| Herramienta cuentagotas | 🔲 | Muestrear colores del canvas |
+| Edición de color en selección mixta | 🔲 | Ajustar colores en selección heterogénea |
+| Modelos de color (RGB, HSL, HSB, Hex) | 🟡 | HSV + Hex en selector; sin toggle de modo HSL o RGB |
+
+## Efectos y propiedades
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Sombra paralela | ✅ | Offset, radio de desenfoque, color vía filtros CanvasKit |
+| Sombra interior | ✅ | Efecto de sombra inset |
+| Desenfoque de capa | ✅ | Desenfoque gaussiano en la capa |
+| Desenfoque de fondo | ✅ | Desenfocar contenido detrás de la capa |
+| Desenfoque de primer plano | ✅ | Desenfoque en primer plano |
+| Grosor de trazo | ✅ | Configurable en panel de propiedades |
+| Cap de trazo (round, square, arrow) | ✅ | NONE, ROUND, SQUARE, ARROW_LINES, ARROW_EQUILATERAL |
+| Join de trazo (miter, bevel, round) | ✅ | Los tres tipos de join |
+| Patrones de guiones | ✅ | Patrón de trazo dash-on/dash-off |
+| Radio de esquina | ✅ | Radio uniforme y por esquina con toggle independiente |
+| Suavizado de esquina (estilo iOS) | 🔲 | Redondeo continuo de esquinas de Figma |
+| Múltiples rellenos/trazos por capa | 🔲 | Figma permite apilar rellenos y trazos |
+
+## Auto Layout
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Flujo horizontal y vertical | ✅ | Motor flexbox Yoga WASM |
+| Alternar auto layout (⇧A) | ✅ | Alternar en frame o envolver selección |
+| Gap (espaciado entre hijos) | ✅ | Configurable en panel de propiedades |
+| Padding (uniforme y por lado) | ✅ | Los cuatro lados independientemente |
+| Justify content | ✅ | Start, center, end, space-between |
+| Align items | ✅ | Start, center, end, stretch |
+| Dimensionado de hijos (fijo, rellenar, ajustar) | ✅ | Modos de dimensionado por hijo |
+| Wrap | ✅ | Flex wrap para layout multi-línea |
+| Flujo auto layout grid | 🔲 | Auto layout basado en grid de Figma |
+| Flujos combinados (anidados) | ✅ | Frames auto-layout anidados con diferentes direcciones |
+| Reordenar arrastrando en auto layout | ✅ | Indicador visual de inserción |
+| Ancho/alto mínimo y máximo | 🔲 | Figma soporta restricciones min/max en hijos de auto-layout |
+
+## Componentes y sistemas de diseño
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Crear componentes | 🟡 | ⌥⌘K crea desde frame/grupo o envuelve selección; sin UI de propiedades de componente aún |
+| Conjuntos de componentes | 🟡 | ⇧⌘K combina componentes; borde punteado púrpura; sin edición de propiedades de variante |
+| Instancias de componentes | 🟡 | Crear instancia desde menú contextual con clonación de hijos y mapeo componentId; sync en vivo; sin UI de edición de overrides |
+| Variantes | 🔲 | Cambio de variante y selección por propiedades |
+| Propiedades de componente | 🔲 | Propiedades booleanas, texto, intercambio de instancia |
+| Propagación de overrides | ✅ | Cambios en componente principal se propagan; overrides preservados |
+| Variables (color, número, string, booleano) | 🟡 | COLOR con UI completa; FLOAT/STRING/BOOLEAN definidos sin UI de edición |
+| Colecciones y modos de variables | 🟡 | Colecciones, modos, cambio activeMode funcionan; sin UI de theming por variable |
+| Estilos (color, texto, efecto, layout) | 🔲 | Presets de estilo reutilizables con nombre |
+| Bibliotecas (publicar, compartir, actualizar) | 🔲 | Bibliotecas compartidas de componentes/estilos |
+| Desacoplar instancia | ✅ | ⌥⌘B convierte instancia en frame |
+| Ir al componente principal | ✅ | Navegar al componente fuente, cross-page |
+
+## Prototipado
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Conexiones de prototipo | 🔲 | Planificado para Fase 6 |
+| Triggers (clic, hover, arrastrar, etc.) | 🔲 | Planificado para Fase 6 |
+| Acciones (navegar, overlay, scroll, etc.) | 🔲 | Planificado para Fase 6 |
+| Animaciones y transiciones | 🔲 | Planificado para Fase 6 |
+| Smart animate | 🔲 | Auto-animar capas coincidentes |
+| Overlays | 🔲 | Prototipado modal/popover |
+| Comportamiento de scroll y overflow | 🔲 | Frames scrolleables en prototipos |
+| Flujos de prototipo | 🔲 | Puntos de inicio con nombre |
+| Variables en prototipos | 🔲 | Lógica condicional con variables |
+| Easing y animaciones spring | 🔲 | Curvas de animación personalizadas |
+| Presentar y reproducir prototipos | 🔲 | Visor de prototipo a pantalla completa |
+
+## Import y export
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Import de archivo .fig | ✅ | Codec Kiwi completo: 194 definiciones, ~390 campos por NodeChange |
+| Export de archivo .fig | ✅ | Codificación Kiwi + compresión Zstd + generación de miniatura |
+| Guardar / Guardar como | ✅ | ⌘S / ⇧⌘S; diálogos nativos (Tauri), File System Access API (Chrome/Edge), fallback de descarga (Safari) |
+| Portapapeles de Figma (pegar) | ✅ | Decodificar binario Kiwi del portapapeles de Figma |
+| Portapapeles de Figma (copiar) | ✅ | Codificar binario Kiwi que Figma puede leer |
+| Import de archivo Sketch | 🔲 | Parseo de archivos .sketch |
+| Export de imagen/SVG | 🟡 | PNG/JPG/WEBP con selector de escala y vista previa; SVG/PDF aún no |
+| Historial de versiones | 🔲 | Navegar y restaurar versiones anteriores |
+| Copiar assets entre herramientas | 🟡 | Portapapeles de Figma funciona; sin portapapeles SVG/PDF |
+
+## API de plugins y scripting
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Comando eval con Figma Plugin API | ✅ | Ejecución headless de JavaScript con objeto global figma compatible con la superficie de plugins de Figma |
+
+## Colaboración y modo desarrollo
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Comentarios (fijar, hilos, resolver) | 🔲 | Planificado para Fase 6 |
+| Multiplayer en tiempo real | ✅ | P2P vía Trystero + Yjs CRDT, cursores, modo seguimiento; sin servidor |
+| Chat en cursor | 🔲 | Burbujas de chat inline en el cursor |
+| Branching y merging | 🔲 | Ramas de versiones para archivos de diseño |
+| Modo desarrollo (inspeccionar) | 🟡 | Pestaña Código muestra JSX de la selección; sin propiedades CSS ni specs de handoff |
+| Code Connect | 🔲 | Vincular componentes de diseño a código |
+| Fragmentos de código | 🟡 | Export JSX con resaltado y copia; sin fragmentos CSS/Swift/Kotlin |
+| Figma for VS Code | 🔲 | Integración con plugin de editor |
+| Servidor MCP | ✅ | @open-pencil/mcp con transportes stdio + HTTP; 75 herramientas core + 3 de gestión de archivos |
+| Herramientas CLI | ✅ | CLI headless: info, tree, find, export, analyze, node, pages, variables, eval; servidor MCP |
+
+## Figma Draw
+
+| Característica | Estado | Notas |
+|---------------|--------|-------|
+| Herramientas de ilustración | 🔲 | Herramientas de dibujo especializadas de Figma Draw |
+| Transformaciones de patrón | 🔲 | Crear patrones repetitivos con transformaciones |
diff --git a/packages/docs/es/guide/tech-stack.md b/packages/docs/es/guide/tech-stack.md
index 30288d87c..a9a8cf30e 100644
--- a/packages/docs/es/guide/tech-stack.md
+++ b/packages/docs/es/guide/tech-stack.md
@@ -1,17 +1,63 @@
# Stack tecnológico
-| Layer | Technology | Why |
-|-------|-----------|-----|
-| **Rendering** | Skia CanvasKit WASM | GPU-accelerated, same as Figma |
-| **UI** | Vue 3 + VueUse | Reactive, TypeScript |
-| **Components** | Reka UI | Headless, accessible |
-| **Styling** | Tailwind CSS 4 | Utility-first |
-| **Layout** | Yoga WASM | CSS flexbox (Meta) |
-| **File Format** | Kiwi binary + Zstd | Figma .fig compatible |
-| **Desktop** | Tauri v2 | ~5 MB (vs Electron ~100 MB) |
-| **Build** | Vite 7 | Fast HMR |
-| **Testing** | Playwright + bun:test | E2E + unit |
-| **Linting** | oxlint | Rust-based |
-| **Type Checking** | typescript-go (tsgo) | Native Go |
+## Tecnologías principales
-[Full details in English](/guide/tech-stack)
+| Capa | Tecnología | Por qué |
+|------|-----------|---------|
+| **Renderizado** | Skia CanvasKit WASM | Mismo motor que Figma — rendimiento probado, acelerado por GPU, píxel-perfecto |
+| **Framework UI** | Vue 3 + VueUse | API de composición reactiva, excelente soporte TypeScript |
+| **Componentes** | Reka UI | Primitivas UI headless y accesibles (tree, slider, etc.) |
+| **Estilado** | Tailwind CSS 4 | Utility-first, iteración rápida, tema oscuro |
+| **Layout** | Yoga WASM | Motor CSS flexbox de Meta, probado en React Native |
+| **Formato de archivo** | Kiwi binario + Zstd | Formato propio de Figma — compacto, parseo rápido, compatible con .fig |
+| **Colaboración** | Trystero + Yjs | P2P WebRTC vía señalización MQTT, sync CRDT, persistencia y-indexeddb |
+| **Color** | culori | Conversiones de espacio de color (HSV, RGB, hex) |
+| **IA/MCP** | MCP SDK + Hono | 75 herramientas para codificación IA, transportes stdio + HTTP |
+| **Desktop** | Tauri v2 | ~5 MB app nativa (vs ~100 MB de Electron), backend Rust |
+| **Build** | Vite 7 | HMR rápido, módulos ES nativos |
+| **Testing** | Playwright + bun:test | Regresión visual (E2E) + tests unitarios rápidos |
+| **Linting** | oxlint | Basado en Rust, órdenes de magnitud más rápido que ESLint |
+| **Formateo** | oxfmt | Formateador basado en Rust |
+| **Verificación de tipos** | typescript-go (tsgo) | Implementación nativa en Go del verificador de tipos TypeScript |
+
+## Dependencias principales
+
+```json
+{
+ "canvaskit-wasm": "^0.40.0",
+ "vue": "^3.5.29",
+ "yoga-layout": "^3.2.1",
+ "reka-ui": "^2.8.2",
+ "tailwindcss": "^4.2.1",
+ "culori": "^4.0.2",
+ "fzstd": "^0.1.1",
+ "fflate": "^0.8.2",
+ "trystero": "^0.20.0",
+ "yjs": "^13.6.24",
+ "y-indexeddb": "^9.0.12"
+}
+```
+
+## ¿Por qué no...
+
+### ¿Por qué no renderizado SVG?
+
+SVG es lento para documentos complejos. Cada nodo es un elemento DOM — 10.000 nodos significan 10.000 elementos DOM con overhead de layout, pintado y composición. CanvasKit dibuja todo en una única superficie GPU.
+
+### ¿Por qué no Electron (como Figma desktop)?
+
+Tauri v2 usa el webview del sistema (~5 MB) en lugar de empaquetar Chromium (~100 MB). El backend Rust proporciona rendimiento nativo para E/S de archivos e integración con el sistema.
+
+### ¿Por qué no React?
+
+El proyecto migró de React a Vue 3 tempranamente. El sistema de reactividad de Vue y los composables de VueUse resultaron más ergonómicos.
+
+### ¿Por qué no un motor de layout propio?
+
+Yoga es mantenido por Meta, probado en miles de millones de dispositivos React Native e implementa la especificación CSS flexbox.
+
+## Tecnologías planificadas
+
+| Tecnología | Propósito | Fase |
+|-----------|---------|-------|
+| CSS Grid en Yoga | Auto layout basado en grid | Bloqueado por upstream (facebook/yoga#1893) |
diff --git a/packages/docs/es/reference/mcp-tools.md b/packages/docs/es/reference/mcp-tools.md
index b2d555a2f..56f5c5ea0 100644
--- a/packages/docs/es/reference/mcp-tools.md
+++ b/packages/docs/es/reference/mcp-tools.md
@@ -24,7 +24,7 @@ Add to your MCP config (e.g. `~/.claude/settings.json` or `.cursor/mcp.json`):
}
```
-Instalación:O ejecutar desde el código fuente:
+O ejecutar desde el código fuente:
::: code-group
```json [Bun]
@@ -73,7 +73,7 @@ Starts on port 3100 (override with `PORT` env var). Endpoints:
5. **Structure** — `reparent_node`, `group_nodes`, `clone_node`, `delete_node`
6. **Save** — `save_file` to write back to `.fig`
-## Tools (29)
+## Tools (75)
### Document
diff --git a/packages/docs/fr/development/contributing.md b/packages/docs/fr/development/contributing.md
index dd16eae7e..4ba645fc8 100644
--- a/packages/docs/fr/development/contributing.md
+++ b/packages/docs/fr/development/contributing.md
@@ -4,38 +4,50 @@
```
packages/
- core/ @open-pencil/core — Engine
- cli/ @open-pencil/cli — Headless CLI
- mcp/ @open-pencil/mcp — MCP server
- docs/ @open-pencil/docs — VitePress
+ core/ @open-pencil/core — moteur (zéro dépendance DOM)
+ src/ Graphe de scène, renderer, layout, codec, kiwi, types
+ cli/ @open-pencil/cli — CLI headless pour opérations .fig
+ src/commands/ info, tree, find, export, eval, analyze
+ mcp/ @open-pencil/mcp — serveur MCP pour outils IA
+ src/ Transports stdio + HTTP (Hono), 75 outils
src/
- components/ Vue SFCs
- composables/ Canvas input, shortcuts, rendering
- stores/ Editor state
-desktop/ Tauri v2
+ components/ Vue SFCs (canevas, panneaux, barre d'outils, sélecteur de couleur)
+ properties/ Sections du panneau de propriétés (Apparence, Remplissage, Contour, etc.)
+ composables/ Entrée canevas, raccourcis clavier, hooks de rendu
+ stores/ État de l'éditeur (réactivité Vue)
+ engine/ Shims de ré-exportation depuis @open-pencil/core
+ kiwi/ Shims de ré-exportation depuis @open-pencil/core
+ types.ts Types partagés (ré-exportés depuis core)
+ constants.ts Couleurs UI, défauts, seuils
+desktop/ Tauri v2 (Rust + config)
tests/
- e2e/ Playwright
- engine/ bun:test
-openspec/ Specs + changes
+ e2e/ Régression visuelle Playwright
+ engine/ Tests unitaires (bun:test)
+docs/ Site de documentation VitePress
+openspec/
+ specs/ Spécifications de capacités (source de vérité)
+ changes/ Changements actifs et archivés
```
-## Environnement de développement
+## Configuration du développement
```sh
bun install
-bun run dev # Editor: localhost:1420
-bun run docs:dev # Docs: localhost:5173
+bun run dev # Éditeur sur localhost:1420
+bun run docs:dev # Docs sur localhost:5173
```
## Style de code
### Outils
-| Tool | Command | Purpose |
-|------|---------|---------|
-| oxlint | `bun run lint` | Linting |
-| oxfmt | `bun run format` | Formatting |
-| tsgo | `bun run typecheck` | Type checking |
+| Outil | Commande | Objectif |
+|-------|----------|----------|
+| oxlint | `bun run lint` | Linting (basé sur Rust, rapide) |
+| oxfmt | `bun run format` | Formatage du code |
+| tsgo | `bun run typecheck` | Vérification de types (checker TypeScript basé sur Go) |
+
+Exécuter toutes les vérifications :
```sh
bun run check
@@ -43,23 +55,45 @@ bun run check
### Conventions
-- kebab-case (files), PascalCase (components/types), camelCase (functions), SCREAMING_SNAKE_CASE (constants)
-- AGENTS.md — [GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)
+- **Noms de fichiers** — kebab-case (`scene-graph.ts`, `use-canvas-input.ts`)
+- **Composants** — PascalCase Vue SFCs (`EditorCanvas.vue`, `ScrubInput.vue`)
+- **Constantes** — SCREAMING_SNAKE_CASE
+- **Fonctions/variables** — camelCase
+- **Types/interfaces** — PascalCase
-## Apporter des modifications
+### Conventions pour agents IA
-1. [OpenSpec](./openspec) specs
-2. `openspec new change "name"`
-3. `bun run check && bun run test`
-4. Pull request
+Les développeurs et agents IA doivent lire `AGENTS.md` à la racine du repo ([voir sur GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)). Couvre le rendu, le graphe de scène, les composants et instances, le layout, l'UI, le format de fichier, les conventions Tauri et les problèmes connus.
+
+## Apporter des changements
+
+1. Consulter les [specs openspec](/development/openspec) existantes
+2. Créer un changement openspec si vous ajoutez un nouveau comportement : `openspec new change "mon-changement"`
+3. Implémenter le changement
+4. Exécuter `bun run check` et `bun run test`
+5. Soumettre une pull request
## Fichiers clés
-| File | Purpose |
-|------|---------|
-| `packages/core/src/scene-graph.ts` | Scene graph |
-| `packages/core/src/renderer.ts` | CanvasKit rendering |
-| `packages/core/src/layout.ts` | Yoga layout |
-| `packages/core/src/kiwi/codec.ts` | Kiwi codec |
-| `packages/cli/src/commands/` | CLI commands |
-| `src/stores/editor.ts` | Editor state |
+Le code source du moteur se trouve dans `packages/core/src/`. Les répertoires `src/engine/` et `src/kiwi/` de l'app sont des shims de ré-exportation — éditez le package core, pas les shims.
+
+| Fichier | Objectif |
+|---------|----------|
+| `packages/core/src/scene-graph.ts` | Graphe de scène : nœuds, variables, instances, hit testing |
+| `packages/core/src/renderer.ts` | Pipeline de rendu CanvasKit |
+| `packages/core/src/layout.ts` | Adaptateur layout Yoga |
+| `packages/core/src/undo.ts` | Gestionnaire annuler/rétablir |
+| `packages/core/src/clipboard.ts` | Presse-papiers compatible Figma |
+| `packages/core/src/vector.ts` | Modèle de réseau vectoriel |
+| `packages/core/src/render-image.ts` | Export d'image hors-écran (PNG/JPG/WEBP) |
+| `packages/core/src/kiwi/codec.ts` | Encodeur/décodeur binaire Kiwi |
+| `packages/core/src/kiwi/fig-import.ts` | Logique d'import de fichiers .fig |
+| `packages/cli/src/index.ts` | Point d'entrée du CLI |
+| `packages/core/src/tools/schema.ts` | Définitions d'outils unifiées (IA, MCP, CLI) |
+| `packages/core/src/figma-api.ts` | Implémentation de Figma Plugin API |
+| `packages/mcp/src/server.ts` | Factory du serveur MCP |
+| `packages/cli/src/commands/` | Commandes CLI (info, tree, find, export, eval, analyze) |
+| `src/stores/editor.ts` | État global de l'éditeur |
+| `src/composables/use-canvas.ts` | Composable de rendu du canevas |
+| `src/composables/use-canvas-input.ts` | Gestion des entrées souris/touch |
+| `src/composables/use-keyboard.ts` | Gestion des raccourcis clavier |
diff --git a/packages/docs/fr/development/roadmap.md b/packages/docs/fr/development/roadmap.md
index 237bbc24e..482fc0a79 100644
--- a/packages/docs/fr/development/roadmap.md
+++ b/packages/docs/fr/development/roadmap.md
@@ -1,32 +1,67 @@
# Feuille de route
-## Phase 1 ✅
-SceneGraph, Skia rendering, shapes, selection, zoom/pan, undo/redo, snap guides.
+## Phases
-## Moteur Core ✅
-Vue 3 + Reka UI panels, properties, layers, toolbar, Yoga auto-layout, inline text editing, canvas rulers.
+### Phase 1 : Moteur Core ✅
-## Phase 2 ✅
-.fig import/export, Kiwi codec, clipboard, pen tool, vector networks, groups, Tauri v2 desktop, sections, multi-page, hover highlight, Tier 1 rendering.
+SceneGraph, rendu Skia, formes de base, sélection, zoom/pan, annuler/rétablir, guides d'alignement.
-## UI Éditeur + Layout ✅
-Components, instances, overrides, component sets, variables (COLOR/FLOAT/STRING/BOOLEAN), collections, modes, image export, context menu, rich text formatting.
+### Phase 2 : UI Éditeur + Layout ✅
-## Phase 3 🟡
-@open-pencil/core, CLI (12 commands), MCP server (29+ tools), AI chat (OpenRouter), JSX renderer, code panel.
+Vue 3 + Reka UI panels, propriétés, calques, barre d'outils, Yoga auto-layout, édition de texte en ligne, règles du canevas.
-**Planned:** port remaining figma-use tools, attached mode, design guidelines, screenshot verification loop.
+### Phase 3 : E/S Fichiers + Fonctionnalités Visuelles ✅
-## E/S Fichiers + Fonctionnalités Visuelles 🔲
-Prototyping, comments, PWA, Linux Tauri builds, performance optimization, full Figma compatibility test suite.
+Import/export .fig, codec Kiwi, presse-papiers, outil plume, réseaux vectoriels, groupes, Tauri v2 bureau, sections, multi-pages, surbrillance au survol, rendu Tier 1.
-## Phase 4
+### Phase 4 : Composants + Variables ✅
-| Phase | Composants + Variables | Phase 5: Intégration IA & Outils:Phase 6: Polissage + Distribution:Calendrier:Durée estimée:Statut |
-|-------|------|-----|
-| Phase 1 | 3 months | ✅ |
-| Moteur Core | 3 months | ✅ |
-| Phase 2 | 2 months | ✅ |
-| UI Éditeur + Layout | 2 months | ✅ |
-| Phase 3 | 2 months | 🟡 |
-| E/S Fichiers + Fonctionnalités Visuelles | 2 months | 🔲 |
+Composants, instances, surcharges, jeux de composants, variables (COLOR/FLOAT/STRING/BOOLEAN), collections, modes, export d'images, menu contextuel, formatage de texte riche.
+
+### Phase 5 : Intégration IA & Outils ✅
+
+**Livré :**
+- @open-pencil/core extrait dans packages/core/ (aucune dépendance DOM)
+- @open-pencil/cli avec opérations headless .fig (info, tree, find, export, analyze, eval)
+- Commande `eval` avec API Plugin compatible Figma
+- Chat IA : connexion directe OpenRouter, 75 outils dans `schema.ts`, ⌘J
+- 49 outils IA/MCP additionnels portés depuis figma-use (75 au total)
+- Serveur MCP (@open-pencil/mcp) : stdio + HTTP, 75 outils core + 3 gestion de fichiers
+- Définitions d'outils unifiées : définir une fois dans `schema.ts`, adapter pour chat IA (valibot), MCP (zod), CLI (eval)
+- Barre de menus pour le mode navigateur
+- Sauvegarde automatique : écriture avec debounce de 3s
+- Panneau de propriétés multi-sélection avec valeurs partagées/mixtes
+
+**Planifié :**
+- Mode attaché : WebSocket vers l'éditeur en cours d'exécution
+- Système de directives de conception
+
+### Phase 6 : Collaboration + Distribution 🟡
+
+**Livré :**
+- Collaboration P2P via Trystero (WebRTC) + Yjs CRDT — sans serveur relais
+- Protocole d'awareness : curseurs en direct, sélections, présence
+- Mode suivi : clic sur l'avatar d'un pair pour suivre son viewport
+- Persistance locale via y-indexeddb
+- Rendu des effets : ombre portée, ombre intérieure, flou de calque/arrière-plan/premier plan
+- Onglets multi-fichiers : ⌘N/⌘T nouvel onglet, ⌘W fermer, ⌘O ouvrir
+- Signature de code Apple et notarisation pour macOS
+- Builds Linux (x64) ajoutés au CI
+- Site de documentation VitePress avec i18n (6 langues)
+
+**Planifié :**
+- Prototypage (connexions de frames, transitions, animations)
+- Commentaires (pin, fils, résoudre)
+- Support PWA
+- Changement de variantes, UI variables FLOAT/STRING/BOOLEAN, theming par variables
+
+## Calendrier
+
+| Phase | Durée estimée | Statut |
+|-------|--------------|--------|
+| Phase 1 : Moteur Core | 3 mois | ✅ Terminée |
+| Phase 2 : UI Éditeur + Layout | 3 mois | ✅ Terminée |
+| Phase 3 : E/S Fichiers + Fonctionnalités Visuelles | 2 mois | ✅ Terminée |
+| Phase 4 : Composants + Variables | 2 mois | ✅ Terminée |
+| Phase 5 : Intégration IA & Outils | 2 mois | ✅ Terminée |
+| Phase 6 : Collaboration + Distribution | 2 mois | 🟡 En cours |
diff --git a/packages/docs/fr/guide/architecture.md b/packages/docs/fr/guide/architecture.md
index c21c5c64e..18697aab7 100644
--- a/packages/docs/fr/guide/architecture.md
+++ b/packages/docs/fr/guide/architecture.md
@@ -1,33 +1,96 @@
# Architecture
-## Vue d'ensemble
+## Vue d'ensemble du système
```
┌──────────────────────────────────────────────────────────────────┐
│ Tauri v2 Shell │
+│ │
│ ┌────────────────────────────────────────────────────────────┐ │
-│ │ Vue 3 UI Skia CanvasKit (WASM, 7MB) │ │
+│ │ Éditeur (Web) │ │
+│ │ │ │
+│ │ Vue 3 UI Skia CanvasKit (WASM, 7MB) │ │
+│ │ - Barre d'outils - Rendu vectoriel │ │
+│ │ - Panneaux - Mise en forme du texte │ │
+│ │ - Propriétés - Traitement d'images │ │
+│ │ - Calques - Effets (flou, ombre) │ │
+│ │ - Sélecteur de couleur - Export (PNG, SVG, PDF) │ │
+│ │ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
-│ │ │ Core Engine (TS): SceneGraph, Layout, Selection │ │ │
+│ │ │ Core Engine (TS) │ │ │
+│ │ │ SceneGraph ─── Layout (Yoga) ─── Selection │ │ │
+│ │ │ │ │ │ │ │
+│ │ │ Undo/Redo ─── Constraints ─── Hit Testing │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
+│ │ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
-│ │ │ .fig import/export ── Kiwi codec │ │ │
+│ │ │ Couche de format de fichier │ │ │
+│ │ │ .fig import/export ── Kiwi codec ── .svg (prévu) │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
-│ MCP Server (29+ tools) P2P Collaboration (Yjs CRDT) │
+│ │
+│ MCP Server (75+ tools, stdio+HTTP) P2P Collab (Trystero + Yjs) │
└──────────────────────────────────────────────────────────────────┘
```
-L'interface suit le layout UI3 de Figma.
+## Disposition de l'éditeur
-Rendu : CanvasKit WASM — GPU, Skia.
+L'interface suit le layout UI3 de Figma — barre d'outils en bas, navigation à gauche, propriétés à droite :
-Graphe de scène : `Map` — O(1) lookup, hit testing.
+- **Panneau de navigation (gauche)** — Arbre des calques, panneau des pages, bibliothèque d'assets (prévu)
+- **Canvas (centre)** — Canvas infini avec rendu CanvasKit, zoom/pan
+- **Panneau de propriétés (droite)** — Sections contextuelles : Apparence, Remplissage, Contour, Typographie, Layout, Position
+- **Barre d'outils (bas)** — Sélection d'outil : Sélectionner, Frame, Section, Rectangle, Ellipse, Ligne, Texte, Plume, Main
-Format de fichier : Kiwi binary codec — 194 definitions. [File Format](/reference/file-format).
+## Composants
-Annuler/Rétablir : Inverse-command pattern.
+### Rendu (CanvasKit WASM)
-Presse-papiers : Figma-compatible, Kiwi binary.
+Le même moteur de rendu que Figma. CanvasKit fournit un dessin 2D accéléré par GPU avec :
+- Formes vectorielles (rectangle, ellipse, chemin, ligne, étoile, polygone)
+- Mise en forme du texte via Paragraph API
+- Effets (ombres, flous, modes de fusion)
+- Export (PNG, SVG, PDF)
-[Full details in English](/guide/architecture)
+Le binaire WASM de 7 Mo se charge au démarrage et crée une surface GPU sur le canvas HTML.
+
+### Graphe de scène
+
+`Map` plat indexé par des chaînes GUID. Structure en arbre via des références `parentIndex`. Fournit une recherche O(1), un parcours efficace, du hit testing et des requêtes par zone rectangulaire pour la sélection par marquise.
+
+Voir [Référence du graphe de scène](/reference/scene-graph) pour les détails internes.
+
+### Moteur de layout (Yoga WASM)
+
+Yoga de Meta fournit le calcul de layout CSS flexbox. Un adaptateur fin mappe les noms de propriétés Figma vers les équivalents Yoga :
+
+| Propriété Figma | Équivalent Yoga |
+|---|---|
+| `stackMode: HORIZONTAL` | `flexDirection: row` |
+| `stackMode: VERTICAL` | `flexDirection: column` |
+| `stackSpacing` | `gap` |
+| `stackPadding` | `padding` |
+| `stackJustify` | `justifyContent` |
+| `stackChildPrimaryGrow` | `flexGrow` |
+
+### Format de fichier (Kiwi binaire)
+
+Réutilise le codec binaire Kiwi éprouvé de Figma avec 194 définitions de message/enum/struct. Pipeline d'importation `.fig` : analyser l'en-tête → décompresser Zstd → décoder Kiwi → NodeChange[] → graphe de scène. Le pipeline d'exportation inverse le processus : graphe de scène → NodeChange[] → encoder Kiwi → compresser Zstd → ZIP avec miniature.
+
+Voir [Référence du format de fichier](/reference/file-format) pour plus de détails.
+
+### Annuler/Rétablir
+
+Patron de commande inverse. Avant d'appliquer tout changement, les champs concernés sont capturés en snapshot. Le snapshot devient l'opération inverse. Le batching regroupe les changements rapides (comme le glissement) en entrées d'annulation uniques.
+
+### Presse-papiers
+
+Presse-papiers bidirectionnel compatible Figma. Encode/décode le binaire Kiwi (même format que les fichiers .fig) en utilisant les événements natifs copier/coller du navigateur (synchrones, pas l'API asynchrone du Clipboard). Le collage gère le redimensionnement des chemins vectoriels, le peuplement des enfants d'instances, la détection des ensembles de composants et l'application des surcharges.
+
+### Serveur MCP
+
+`@open-pencil/mcp` expose 75 outils core + 3 outils de gestion de fichiers pour les outils de codage IA. Deux transports : stdio pour Claude Code/Cursor/Windsurf, HTTP avec Hono + Streamable HTTP pour les scripts et le CI. Les outils sont définis une fois dans `packages/core/src/tools/schema.ts` et adaptés pour le chat IA (valibot), MCP (zod) et CLI (commande eval).
+
+### Collaboration P2P
+
+Collaboration peer-to-peer en temps réel via Trystero (WebRTC) + Yjs CRDT. Sans serveur relais — signalisation via des brokers MQTT publics, STUN/TURN pour le traversal NAT. Le protocole d'awareness fournit des curseurs en direct, des sélections et de la présence. Persistance locale via y-indexeddb.
diff --git a/packages/docs/fr/guide/comparison.md b/packages/docs/fr/guide/comparison.md
index cd285cdb7..5d97446a4 100644
--- a/packages/docs/fr/guide/comparison.md
+++ b/packages/docs/fr/guide/comparison.md
@@ -1,18 +1,249 @@
-# Comparaison avec Penpot
+# Open Pencil vs Penpot : Comparaison d'architecture et de performances
-| Metric | Open Pencil | Penpot |
+Pourquoi comparer ? OpenPencil existe parce que les plateformes de design fermées contrôlent ce qui est possible. Comprendre les différences architecturales montre ce qu'une alternative ouverte et local-first peut faire différemment.
+
+::: info Renderer WASM de Penpot
+Penpot 2.x inclut un renderer Rust/Skia WASM (`render-wasm/v1`) activable via les flags du serveur ou le paramètre URL `?wasm=true`. Le renderer SVG reste le défaut. Cette page couvre les deux.
+:::
+
+## 1. Échelle et taille du code
+
+| Métrique | Open Pencil | Penpot |
+|----------|-------------|--------|
+| LOC total | **~26 000** | **~299 000** |
+| Fichiers source | ~143 | ~2 900 |
+| Langages | TypeScript, Vue | Clojure, ClojureScript, Rust, JS, SQL, SCSS |
+| Moteur de rendu | 1 646 LOC (TS) | 22 000 LOC (Rust/Skia WASM) |
+| Code UI | ~4 500 LOC | ~175 000 LOC (CLJS + SCSS) |
+| Backend | Aucun (local-first) | 32 600 LOC + 151 fichiers SQL |
+| Ratio LOC | **1×** | **~11×** |
+
+Open Pencil est **~11× plus petit** — et c'est tout l'intérêt. Ce n'est pas une simplification ; c'est une architecture fondamentalement différente.
+
+## 2. Architecture
+
+### Open Pencil : Client monolithique
+
+```
+┌─────────────────────────────────┐
+│ Tauri (shell natif) │
+│ ┌───────────────────────────┐ │
+│ │ Vue 3 + TypeScript │ │
+│ │ ┌─────────┐ ┌──────────┐│ │
+│ │ │ Editor │ │ Kiwi ││ │
+│ │ │ Store │ │ Codec ││ │
+│ │ └────┬─────┘ └──────────┘│ │
+│ │ │ │ │
+│ │ ┌────▼────────────────┐ │ │
+│ │ │ Scene Graph (TS) │ │ │
+│ │ │ Map │ │ │
+│ │ └────┬────────────────┘ │ │
+│ │ │ │ │
+│ │ ┌────▼────┐ ┌──────────┐│ │
+│ │ │ Skia │ │ Yoga ││ │
+│ │ │CanvasKit│ │ Layout ││ │
+│ │ │ (WASM) │ │ (WASM) ││ │
+│ │ └─────────┘ └──────────┘│ │
+│ └───────────────────────────┘ │
+└─────────────────────────────────┘
+```
+
+**Tout dans un seul processus.** Pas de serveur, pas de base de données, pas de Docker.
+
+### Penpot : Client-serveur distribué
+
+```
+┌───────────────────────────────────────────────────────┐
+│ Docker Compose │
+│ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐ │
+│ │ Frontend │ │ Backend │ │ Exporter │ │
+│ │ ClojureScript│ │ Clojure │ │ (Chromium) │ │
+│ │ shadow-cljs │ │ JVM │ │ │ │
+│ │ ┌─────────┐ │ │ ┌────────┐ │ └──────────────┘ │
+│ │ │render- │ │ │ │Postgres│ │ │
+│ │ │wasm │ │ │ │Valkey │ │ ┌──────────────┐ │
+│ │ │(Rust→ │ │ │ │ MinIO │ │ │ MCP │ │
+│ │ │ Skia │ │ │ └────────┘ │ │ Server │ │
+│ │ │ WASM) │ │ │ │ └──────────────┘ │
+│ │ └─────────┘ │ │ │ │
+│ └──────────────┘ └─────────────┘ │
+└───────────────────────────────────────────────────────┘
+```
+
+**Minimum 5+ services.** PostgreSQL, Redis (Valkey), MinIO, un backend JVM, un exporteur Node.js (Chromium headless), plus le frontend ClojureScript.
+
+### Verdict : Architecture
+
+L'architecture monoprocessus d'Open Pencil élimine : la latence réseau, l'overhead de sérialisation aux frontières de services, la complexité d'orchestration de conteneurs et l'overhead de requêtes base de données.
+
+## 3. Pipeline de rendu
+
+### Open Pencil : TS → CanvasKit WASM (direct)
+
+```typescript
+renderSceneToCanvas(canvas, graph, pageId) {
+ this.fillPaint.setColor(...)
+ canvas.drawRRect(rrect, this.fillPaint)
+}
+```
+
+- **1 franchissement de frontière :** TS → WASM (CanvasKit)
+- Le graphe de scène vit dans le heap JS — pas de sérialisation pour le rendu
+- 1 646 LOC de renderer au total
+
+### Penpot : JS (compilé depuis CLJS) → Rust WASM → Skia
+
+```
+ClojureScript (compilé en JS)
+ → décomposer en primitives + empaqueter en binaire en mémoire linéaire WASM
+ → Rust WASM (via Emscripten C FFI)
+ → skia-safe (bindings Rust Skia)
+ → Skia (WebGL)
+```
+
+Quand désactivé (défaut), les formes sont rendues comme un arbre DOM SVG. Quand activé, système de rendu par tuiles avec 11 surfaces et cache de 1024 entrées.
+
+### Verdict : Rendu
+
+| Aspect | Open Pencil | Penpot |
|--------|-------------|--------|
-| Total LOC | **~26,000** | **~299,000** |
-| Source files | 125 | ~2,900 |
-| Languages | TypeScript, Vue | Clojure, ClojureScript, Rust, JS, SQL, SCSS |
-| LOC ratio | **1×** | **~11×** |
-| Rendering | Skia CanvasKit (GPU, WASM) | Skia Rust/WASM (render-wasm v1) |
-| Layout | Yoga WASM (CSS flexbox) | Custom CLJS engine |
-| File format | Figma Kiwi binary (.fig) | Custom SVG + metadata |
-| Desktop | Tauri v2 (~5 MB) | No native client |
-| Backend | None (P2P) | Clojure + PostgreSQL + Redis |
-| Collaboration | P2P (Trystero + Yjs CRDT) | Client-server |
-| AI tools | 29 tools + MCP server | Plugin system |
-| CLI | ✅ 12 commands | ❌ |
+| Frontière JS→WASM | Direct (objets TS) | Empaquetage binaire (104 octets par forme) |
+| Modèle de rendu | Immédiat/redessin complet | Cache par tuiles |
+| Gestion des surfaces | 1 surface | 11 surfaces |
+| Overhead mémoire | Faible (pas de cache tuiles) | Élevé (1024 entrées cache) |
+| Complexité du code | 1 646 LOC | 22 000 LOC |
+| Code unsafe | Aucun | État global `unsafe` |
-[Full details in English](/guide/comparison)
+## 4. Graphe de scène et modèle de données
+
+### Open Pencil
+
+```typescript
+nodes: Map
+// 29 types de nœuds du schéma Kiwi de Figma
+// ~390 champs par NodeChange (compatible Figma)
+```
+
+- Interfaces TypeScript avec types stricts
+- GUIDs au format `sessionID:localID` de Figma
+
+### Penpot
+
+- Données réparties dans `common/` (49 600 LOC de .cljc)
+- Validation de schéma au runtime (Malli)
+- Les données doivent traverser la frontière CLJS→Rust pour le rendu
+
+### Verdict : Modèle de données
+
+Open Pencil réutilise le schéma éprouvé de Figma directement en TypeScript — zéro traduction. Penpot maintient son propre système de types à travers trois langages.
+
+## 5. Moteur de layout
+
+### Open Pencil : Yoga WASM (314 LOC)
+
+```typescript
+import Yoga from 'yoga-layout'
+const root = Yoga.Node.create()
+root.setFlexDirection(FlexDirection.Row)
+root.calculateLayout()
+```
+
+314 lignes au total. Synchrone, dans le processus.
+
+### Penpot : Double implémentation
+
+Penpot maintient **deux moteurs de layout indépendants** (CLJS et Rust) qui doivent produire des résultats identiques. ~3 000+ LOC de code layout personnalisé dupliqué.
+
+### Verdict : Layout
+
+Open Pencil délègue à Yoga (utilisé par React Native sur des milliards d'appareils) en 314 lignes.
+
+## 6. Format de fichier et compatibilité Figma
+
+### Open Pencil
+
+- **Format binaire Kiwi natif** — même sérialisation que Figma
+- Import direct `.fig`, collage depuis le presse-papiers Figma
+- Compatible avec le protocole multiplayer de Figma
+
+### Penpot
+
+- **Archive ZIP** (`.penpot`) avec manifestes JSON et assets binaires
+- Pas d'import natif `.fig`
+- Trois versions de format avec système de migration
+
+### Verdict : Format de fichier
+
+Open Pencil a un avantage significatif — il peut lire les fichiers Figma nativement et coller les données du presse-papiers Figma.
+
+## 7. Gestion d'état et annulation
+
+### Open Pencil
+
+```typescript
+// 110 LOC — patron de commande inverse
+class UndoManager {
+ apply(entry) { entry.forward(); this.undoStack.push(entry) }
+ undo() { entry.inverse(); this.redoStack.push(entry) }
+}
+```
+
+110 lignes. Closures forward/inverse avec état minimal.
+
+### Penpot
+
+Gestion d'état via Potok (bibliothèque Redux-like pour atomes ClojureScript). Undo stocke des vecteurs de changements inverses (max 50 entrées), avec auto-expiration après 20 secondes.
+
+## 8. Expérience développeur
+
+| Métrique | Open Pencil | Penpot |
+|----------|-------------|--------|
+| Setup dev | `bun install && bun dev` | Docker Compose + JVM + Node + Rust |
+| Rechargement à chaud | Vite HMR (~50ms) | shadow-cljs (secondes) |
+| Vérification de types | TypeScript (strict) | Runtime (schémas Malli) |
+| Temps de build | <5s (Vite) | Minutes (JVM + CLJS + Rust WASM) |
+| Barrière première contribution | Basse (TS/Vue) | Haute (Clojure + Rust + Docker) |
+| Desktop | Tauri v2 (~5Mo) | N/A (navigateur uniquement) |
+| Bassin de recrutement | Massif (devs TS/Vue) | Petit (ClojureScript + Rust) |
+
+## 9. Caractéristiques de performance
+
+| Scénario | Open Pencil | Penpot |
+|----------|-------------|--------|
+| Démarrage à froid | <2s (chargement WASM) | 10s+ (serveur + client + WASM) |
+| Latence d'opération | <1ms (dans le processus) | 10-50ms (aller-retour réseau) |
+| Frame de rendu | Appel Skia direct | CLJS→JS→WASM FFI→Skia |
+| Mémoire de base | ~50Mo (onglet navigateur) | ~300Mo+ (JVM + Postgres + Valkey + navigateur) |
+| Capacité hors ligne | Complète (local-first) | Aucune (dépend du serveur) |
+| Rendu 10K formes | Une passe, sans cache | Par tuiles avec 11 surfaces |
+
+## 10. Ce que Penpot fait mieux
+
+1. **Collaboration serveur** — édition multi-utilisateurs centralisée avec WebSockets, comptes et contrôle d'accès
+2. **Export serveur** — service d'export Chromium headless
+3. **Système de plugins** — API complète avec exécution sandboxée
+4. **Tokens de design** — support natif des design tokens
+5. **CSS Grid layout** — implémentation personnalisée (Open Pencil attend Yoga Grid)
+6. **Self-hosting** — déploiement Docker pour les équipes
+7. **Maturité** — années d'utilisation en production
+
+## 11. Scripting et extensibilité
+
+OpenPencil inclut une [commande `eval`](/eval-command) offrant une API Plugin compatible Figma pour le scripting headless. De plus, 75 outils IA sont disponibles via le chat intégré, le serveur MCP (stdio + HTTP) et le CLI. Penpot a un système de plugins avec exécution sandboxée mais pas d'API de scripting headless ni d'intégration MCP.
+
+## Résumé
+
+| Dimension | Gagnant | Pourquoi |
+|-----------|---------|----------|
+| **Simplicité architecturale** | Open Pencil | Un processus vs 5+ services |
+| **Performance de rendu** | Open Pencil | CanvasKit direct vs SVG DOM (défaut) ou WASM empaqueté |
+| **Maintenabilité du code** | Open Pencil | ~26K LOC en 1 langage vs 299K en 4+ |
+| **Compatibilité Figma** | Open Pencil | Codec Kiwi natif vs pas de support .fig |
+| **Onboarding développeur** | Open Pencil | TS/Vue vs Clojure/Rust/Docker |
+| **Expérience desktop** | Open Pencil | Tauri natif vs navigateur uniquement |
+| **Moteur de layout** | Open Pencil | Yoga (éprouvé) vs double implémentation |
+| **Collaboration** | Égalité | Penpot : serveur avec contrôle d'accès ; Open Pencil : P2P via Trystero + Yjs |
+| **Self-hosting** | Penpot | Prêt Docker vs desktop uniquement |
+| **Maturité écosystème** | Penpot | Années de production vs stade précoce |
+
+Open Pencil est architecturalement plus léger — un renderer CanvasKit monoprocessus en ~26K LOC TypeScript, compatible Figma par conception. Penpot est une plateforme full-stack avec ~299K LOC. Open Pencil a le scripting headless, 75 outils AI/MCP et une app desktop native.
diff --git a/packages/docs/fr/guide/features.md b/packages/docs/fr/guide/features.md
index 3ba5b4f25..76c9aefa3 100644
--- a/packages/docs/fr/guide/features.md
+++ b/packages/docs/fr/guide/features.md
@@ -2,36 +2,162 @@
## Pourquoi OpenPencil
-Alternative open-source aux outils de design : MIT, compatible Figma, entièrement local et programmable.
+Les outils de design sont un problème de chaîne d'approvisionnement. Quand votre outil est propriétaire, l'éditeur contrôle ce qui est possible — il peut casser votre automatisation du jour au lendemain. OpenPencil est une alternative open-source : licence MIT, compatible Figma, entièrement local et programmable.
-## Import & export .fig
-Ouvre et enregistre les fichiers Figma natifs. Schema Kiwi complet (194 définitions). Round-trip fidèle.
+## Import & export de fichiers .fig Figma
+
+Ouvrez et enregistrez les fichiers natifs Figma directement. L'import décode le schéma Kiwi complet à 194 définitions incluant les messages NodeChange avec ~390 champs. L'export encode le graphe de scène en binaire Kiwi avec compression Zstd et génération de miniature. Enregistrer (⌘S) et Enregistrer sous (⇧⌘S) utilisent les dialogues natifs de l'OS sur l'app bureau.
## Copier-coller avec Figma
-Copier dans Figma, coller dans OpenPencil et vice versa. Format binaire Kiwi identique.
+
+Sélectionnez des nœuds dans Figma, ⌘C, passez à OpenPencil, ⌘V — ils apparaissent avec remplissages, contours, auto-layout, texte, rayons de coins, effets et réseaux vectoriels préservés. Fonctionne aussi dans l'autre sens.
+
+Le collage gère les scénarios complexes : les chemins vectoriels sont redimensionnés depuis la `normalizedSize` de Figma vers les limites réelles du nœud, les enfants d'instance sont peuplés depuis le `symbolData` de leur composant, les ensembles de composants sont détectés et les `symbolOverrides` sont appliqués. Les polices sont chargées automatiquement.
+
+## Réseaux vectoriels
+
+L'outil plume utilise le modèle de réseau vectoriel de Figma — pas de chemins simples. Clic pour les points d'angle, clic+glisser pour les courbes de Bézier. Chemins ouverts et fermés supportés.
## Outils de forme
-Rectangle (R), Ellipse (O), Ligne (L), Polygone, Étoile. Remplissage, contour, effets.
-## Mise en page auto
-Yoga WASM (flexbox). Direction, gap, padding, alignement. ⇧A pour activer.
+La barre d'outils fournit tous les outils de forme de base de Figma : Rectangle (R), Ellipse (O), Ligne (L), Polygone et Étoile. Toutes les formes supportent remplissage, contour, surbrillance au survol et contour de sélection.
-## Édition de texte
-Édition native sur le canevas. Sélecteur de polices virtuel. Formatage riche (B/I/U/S).
+## Auto-Layout
+
+Yoga WASM fournit le layout CSS flexbox. Les frames supportent : direction, gap, padding, justify, align et dimensionnement des enfants. Shift+A active/désactive l'auto-layout.
+
+## Édition de texte en ligne
+
+Édition de texte native sur le canevas. Double-clic sur un nœud texte pour entrer en mode édition. **Sélecteur de polices** avec défilement virtuel, filtre de recherche et aperçu CSS. Dans Tauri, les polices système sont énumérées via le crate Rust `font-kit`.
+
+## Formatage de texte riche
+
+Formatage par caractère : ⌘B gras, ⌘I italique, ⌘U souligné, ou boutons B/I/U/S. Implémenté via un modèle StyleRun. Préservé lors de l'import/export .fig.
## Annuler/Rétablir
-⌘Z / ⇧⌘Z. Pattern inverse-command. Toute opération est annulable.
+
+Toute opération est annulable. Patron de commande inverse. ⌘Z annule, ⇧⌘Z rétablit.
+
+## Guides d'alignement
+
+Accrochage aux bords et centres avec lignes guides rouges. Conscient de la rotation.
+
+## Règles du canevas
+
+Règles en haut et à gauche montrant les échelles de coordonnées avec badges de coordonnées lors de la sélection.
+
+## Sélecteur de couleur et types de remplissage
+
+Sélection HSV avec curseur de teinte, curseur alpha, entrée hex et contrôle d'opacité. Types : Solide, Dégradé (Linéaire, Radial, Angulaire, Diamant) et Image.
+
+## Panneau des calques
+
+Vue en arbre de la hiérarchie du document avec le composant Reka UI Tree. Panneaux redimensionnables.
+
+## Panneau de propriétés
+
+Interface à onglets **Design** | **Code** | **IA**. L'onglet Design montre des sections contextuelles : Apparence, Remplissage, Contour, Effets, Typographie, Layout, Position, Export et Page.
+
+## Grouper/Dégrouper
+
+⌘G groupe. ⇧⌘G dégroupe. Les nœuds sont triés par position visuelle.
+
+## Sections
+
+Les sections (S) sont des conteneurs organisationnels de niveau supérieur sur le canevas avec des pilules de titre et inversion automatique de la couleur du texte.
+
+## Documents multi-pages
+
+Les documents supportent plusieurs pages. Chaque page maintient un état de viewport indépendant.
+
+## Surbrillance au survol
+
+Les nœuds se mettent en surbrillance avec un contour qui suit la géométrie réelle.
+
+## Rendu avancé (Tier 1)
+
+Le renderer CanvasKit supporte les fonctionnalités visuelles Tier 1 complètes : dégradés, remplissages d'images, effets, propriétés de contour, données d'arc, culling de viewport, réutilisation de Paint et coalescence RAF.
## Composants et instances
-Composants réutilisables (⌥⌘K), jeux (⇧⌘K), sync live, surcharges.
+
+Composants réutilisables (⌥⌘K), ensembles (⇧⌘K), instances via menu contextuel, détacher (⌥⌘B). **Sync en direct** et **support des surcharges**. Étiquettes violettes avec icône diamant.
## Variables
-Jetons de design avec collections et modes. Liaison aux remplissages.
+
+Jetons de design avec collections et modes. Dialogue TanStack Table. Supporte COLOR avec UI complète, FLOAT/STRING/BOOLEAN définis. Toutes les opérations sont annulables.
+
+## Export d'images
+
+PNG, JPG, WEBP avec échelle 0,5×–4×, aperçu en direct et ⇧⌘E.
+
+## Menu contextuel
+
+Clic droit pour : Presse-papiers, Ordre Z, Groupement, Composants (items violets), Visibilité, Déplacer vers page.
+
+## Ordre Z, visibilité et verrouillage
+
+] amène au premier plan, [ envoie en arrière. ⇧⌘H visibilité. ⇧⌘L verrouillage.
+
+## App web et bureau
+
+OpenPencil fonctionne dans le navigateur sur [app.openpencil.dev](https://app.openpencil.dev). L'app bureau utilise Tauri v2 (~5 Mo). Fonctionne entièrement hors ligne.
+
+## Menu de l'app (navigateur)
+
+Barre de menus avec reka-ui : **Fichier**, **Édition**, **Affichage**, **Objet**, **Texte**, **Disposition**. Raccourcis clavier adaptés à la plateforme. Caché dans Tauri.
+
+## Sauvegarde automatique
+
+Fichiers sauvegardés 3 secondes après le dernier changement. Debounce sur `sceneVersion`. Désactivé pour les nouveaux documents sans titre.
+
+## Collaboration P2P
+
+Collaboration peer-to-peer en temps réel — aucun serveur requis. Basé sur Trystero (WebRTC) + Yjs (CRDT).
+
+- **Zéro coût d'hébergement** — signalisation via brokers MQTT publics
+- **Traversal NAT** — serveurs Google STUN, Cloudflare STUN et Open Relay TURN
+- **Curseurs en direct** — flèches colorées style Figma avec pilules de nom
+- **Présence** — avatars colorés
+- **Mode suivi** — cliquez sur l'avatar d'un pair pour suivre son viewport
+- **Persistance locale** — y-indexeddb maintient la salle entre les rechargements
+- **Salles sécurisées** — IDs via `crypto.getRandomValues()`
+
+## Onglets multi-fichiers
+
+Ouvrez plusieurs documents en onglets. ⌘N/⌘T nouvel onglet, ⌘W fermer, ⌘O ouvrir dans un nouvel onglet. Chaque onglet maintient son propre état de document.
+
+## Rendu des effets
+
+Rendu complet des effets Figma : **Ombre portée**, **Ombre intérieure**, **Flou de calque** (Gaussien), **Flou d'arrière-plan** (effet verre/givre), **Flou de premier plan**. Cache SkPicture par nœud pour la performance.
+
+## Propriétés multi-sélection
+
+Sélectionnez plusieurs nœuds et éditez les propriétés partagées. Valeurs communes affichées normalement, valeurs différentes montrent « Mixed ». Retournement H/V s'applique à tous les nœuds.
+
+## ScrubInput
+
+Toutes les entrées numériques utilisent une interaction glisser-pour-ajuster. Supporte les suffixes (°, px, %).
+
+## Builds CI/CD
+
+GitHub Actions construit les apps Tauri sur les tags de version. macOS signé et notarisé. Notes de release auto-remplies depuis CHANGELOG.md.
+
+## @open-pencil/core et CLI
+
+Le moteur est extrait dans `packages/core/`. Le CLI fournit : info, tree, find, export, analyze, node, pages, variables, eval. Tous supportent `--json`. Le commande `eval` exécute JavaScript avec l'API Plugin Figma. Voir [Commande Eval](/eval-command).
+
+## Rendereur JSX
+
+Création programmable via TreeNode builders. Props shorthand style Tailwind.
## Chat IA
-29 outils via OpenRouter. Serveur MCP (stdio + HTTP).
-## CLI
-info, tree, find, export, analyze, eval. Toutes les commandes supportent `--json`.
+Assistant IA intégré via ⌘J. **75 outils** dans `schema.ts` couvrant lecture, création, modification, manipulation de nœuds, CRUD variables, outils vectoriels, contrôle viewport et `eval`. **Serveur MCP** expose 78 outils au total (75 core + 3 gestion fichiers) pour les outils de codage IA externes.
-[Détails complets en anglais](/guide/features)
+## Panneau de code
+
+L'onglet Code montre le JSX de la sélection avec coloration syntaxique Prism.js et copie.
+
+## Qualité de code
+
+Détection de copier-coller via jscpd — duplication réduite de 15,6% à 0,62%. Pipeline d'import optimisé de O(n²) à O(n).
diff --git a/packages/docs/fr/guide/figma-comparison.md b/packages/docs/fr/guide/figma-comparison.md
index 828df95c1..9dd89aa5c 100644
--- a/packages/docs/fr/guide/figma-comparison.md
+++ b/packages/docs/fr/guide/figma-comparison.md
@@ -1,9 +1,226 @@
-# Matrice des fonctionnalités Figma
+# Matrice de fonctionnalités Figma
-**Coverage:** 87 / 152 — 69 ✅, 18 🟡, 65 🔲. (2026-03-03)
+Comparaison fonctionnalité par fonctionnalité des capacités de Figma Design avec l'état d'implémentation actuel d'Open Pencil.
-✅ = Full | 🟡 = Partial | 🔲 = Not yet
+::: tip Légende des statuts
+✅ Supporté — la fonctionnalité est complète · 🟡 Partiel — le comportement de base existe, certaines sous-fonctionnalités manquent · 🔲 Pas encore implémenté
+:::
-[Full feature matrix in English](/guide/figma-comparison)
+**Couverture :** 88 des 152 éléments Figma traités — 70 ✅ entièrement supportés, 18 🟡 partiels, 64 🔲 en attente. Dernière mise à jour : 2026-03-04.
-[Features](/fr/guide/features) · [Comparison](/fr/guide/comparison)
+## Interface et navigation
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Barre d'outils de design | ✅ | Barre inférieure (style UI3) : Sélection, Frame, Section, Rectangle, Ellipse, Ligne, Texte, Main, Plume |
+| Panneau des calques (barre latérale gauche) | ✅ | Vue en arbre avec expansion/réduction, réordonnancement par glissement, toggle de visibilité ; largeur redimensionnable |
+| Panneau des pages | ✅ | Ajouter, supprimer, renommer des pages ; état viewport par page |
+| Panneau de propriétés (barre latérale droite) | ✅ | Sections : Apparence, Remplissage, Contour, Effets, Typographie, Layout, Position ; largeur redimensionnable |
+| Zoom et défilement | ✅ | Ctrl+scroll, pinch, ⌘+/⌘−/⌘0, espace+glisser, souris milieu, outil main (H) |
+| Règles du canevas | ✅ | Règles haut/gauche avec bandes de sélection et badges de coordonnées |
+| Couleur de fond du canevas | ✅ | Fond par page via le panneau de propriétés |
+| Guides du canevas | 🔲 | Figma supporte des guides glissables depuis les règles |
+| Menu d'actions / palette de commandes | 🔲 | Recherche d'actions rapides de Figma |
+| Menu contextuel | ✅ | Clic droit avec presse-papiers, ordre-z, groupement, composant, visibilité, verrouillage, déplacer-vers-page |
+| Raccourcis clavier | 🟡 | Raccourcis de base + composants + ordre-z + visibilité/verrouillage implémentés ; Échelle, Flèche, Crayon, retournement, formatage texte pas encore câblés |
+| Rechercher et remplacer | 🔲 | Recherche/remplacement de texte dans le document |
+| Vue des contours de calques | 🔲 | Vue filaire de tous les calques |
+| Miniatures personnalisées | 🔲 | Miniature générée à l'export, mais pas de sélecteur personnalisé |
+| Réglages de valeur de nudge | 🔲 | Défaut 1px/10px ; Figma permet des valeurs personnalisées |
+| Menu de l'app (mode navigateur) | ✅ | Menus Fichier, Édition, Affichage, Objet, Texte, Disposition ; Tauri utilise les menus natifs |
+| Outils IA | 🟡 | 75 outils via OpenRouter + serveur MCP ; pas d'images générées par IA ni de recherche IA encore |
+
+## Calques et formes
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Outils de forme (Rectangle, Ellipse, Ligne, Polygone, Étoile) | ✅ | Tous les types de forme de base ; côtés du polygone et rayon intérieur de l'étoile configurables |
+| Frames | ✅ | Découpe du contenu, système de coordonnées indépendant |
+| Groupes | ✅ | ⌘G pour grouper, ⇧⌘G pour dégrouper |
+| Sections | ✅ | Pilules de titre, auto-adoption des nœuds superposés, texte adaptatif à la luminance |
+| Outil arc (arcs, demi-cercles, anneaux) | ✅ | arcData avec angle début/fin et rayon intérieur |
+| Outil crayon (main levée) | 🔲 | Outil de dessin à main levée de Figma |
+| Masques | 🔲 | Masques de forme pour découper les calques |
+| Types de calques et hiérarchie | ✅ | 17 types de nœuds, Map plat + arbre parent-enfant |
+| Sélectionner des calques | ✅ | Clic, shift-clic, sélection par marquise |
+| Alignement et position | ✅ | Position, rotation, dimensions dans le panneau |
+| Copier et coller des objets | ✅ | Presse-papiers standard + format binaire Kiwi de Figma |
+| Mettre à l'échelle proportionnellement | 🟡 | Shift-redimensionner contraint les proportions ; pas d'outil Scale dédié (K) |
+| Verrouiller et déverrouiller des calques | ✅ | ⇧⌘L toggle le verrouillage |
+| Basculer la visibilité | ✅ | Icône œil dans le panneau + raccourci ⇧⌘H |
+| Renommer des calques | 🟡 | Renommage programmatique via store ; pas d'UI inline encore |
+| Mettre au premier plan / Envoyer en arrière | ✅ | Raccourcis ] et [ ; aussi dans le menu contextuel |
+| Déplacer vers une page | ✅ | Déplacer les nœuds entre pages via menu contextuel |
+| Contraintes (redimensionnement réactif) | 🔲 | Épingler bords/centre pour le comportement de resize parent |
+| Sélection intelligente (distribuer/aligner) | 🔲 | Espacer et aligner uniformément |
+| Guides de layout (colonnes, lignes, grille) | 🔲 | Guides colonne/ligne/grille sur les frames |
+| Mesurer les distances entre calques | 🔲 | Alt-survol pour afficher les distances |
+| Éditer des objets en lot | ✅ | Panneau multi-sélection : valeurs partagées affichées normalement, valeurs différentes affichent « Mixed » |
+| Identifier les objets similaires | 🔲 | Trouver des calques similaires |
+| Copier/coller des propriétés | 🔲 | Copier remplissage/contour/effets entre calques |
+| Relations parent-enfant | ✅ | Hiérarchie complète avec parentIndex, re-parentage par glissement |
+
+## Outils vectoriels
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Réseaux vectoriels | ✅ | Modèle compatible Figma, pas de chemins simples |
+| Outil plume | ✅ | Points d'angle, courbes de Bézier, chemins ouverts/fermés |
+| Éditer des calques vectoriels | 🟡 | Création fonctionne ; édition avancée de sommets limitée |
+| Opérations booléennes (Union, Soustraction, Intersection, Exclusion) | 🔲 | Combiner des formes avec des opérations booléennes |
+| Aplatir des calques | 🔲 | Fusionner les chemins vectoriels |
+| Convertir les contours en chemins | 🔲 | Commande Outline Stroke |
+| Convertir le texte en chemins | 🔲 | Aplatir le texte en contours vectoriels |
+| Outil shape builder | 🔲 | Outil booléen interactif |
+| Décalage de chemin | 🔲 | Inset/outset d'un chemin vectoriel |
+| Simplifier le chemin | 🔲 | Réduire le nombre de points vectoriels |
+
+## Texte et typographie
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Outil texte et édition en ligne | ✅ | Édition native sur canevas, textarea phantom, style runs (⌘B/I/U, bouton S) |
+| Rendu de texte (Paragraph API) | ✅ | CanvasKit Paragraph pour le façonnage, les sauts de ligne, les métriques |
+| Chargement de polices (polices système) | ✅ | Inter par défaut, font-kit dans Tauri avec cache OnceLock, queryLocalFonts dans le navigateur |
+| Famille et graisse de police | ✅ | FontPicker avec défilement virtuel, recherche, aperçu CSS |
+| Taille de police et interligne | ✅ | Éditable dans la section typographie |
+| Alignement du texte | 🟡 | Alignement de base ; Figma a l'alignement vertical et les modes auto-largeur/hauteur |
+| Styles de texte | 🟡 | Gras/italique/souligné/barré par sélection ; pas de presets réutilisables encore |
+| Modes de redimensionnement du texte | 🔲 | Modes auto-largeur, auto-hauteur, taille-fixe de Figma |
+| Listes à puces et numérotées | 🔲 | Formatage de listes dans le texte |
+| Liens dans le texte | 🔲 | Hyperliens dans le contenu texte |
+| Emojis et symboles intelligents | 🔲 | Rendu d'émojis et caractères spéciaux |
+| Fonctionnalités OpenType | 🔲 | Ligatures, alternatives stylistiques, chiffres tabulaires |
+| Polices variables | 🔲 | Axes de police ajustables (graisse, largeur, inclinaison) |
+| Support texte CJK | 🔲 | Rendu du texte chinois, japonais, coréen |
+| Support texte RTL | 🔲 | Mise en page de texte de droite à gauche |
+| Polices d'icônes | 🔲 | Gestion spéciale des glyphes de polices d'icônes |
+
+## Couleur, dégradés et images
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Sélecteur de couleur (HSV) | ✅ | Carré HSV, curseur de teinte, curseur alpha, entrée hex |
+| Remplissages solides | ✅ | Couleur hex avec opacité |
+| Dégradé linéaire | ✅ | Arrêts de dégradé, poignées de transformation |
+| Dégradé radial | ✅ | Rendu via shaders CanvasKit |
+| Dégradé angulaire | ✅ | Support dégradé sweep/conique |
+| Dégradé diamant | ✅ | Dégradé diamant à quatre points |
+| Remplissages d'image | ✅ | Décodés à partir de données blob avec modes d'échelle (fill, fit, crop, tile) |
+| Remplissages de motif | 🔲 | Remplissages d'image/motif répétitif |
+| Modes de fusion | 🔲 | Modes de fusion de calque et remplissage (multiply, screen, overlay, etc.) |
+| Ajouter des images et vidéos | 🟡 | Remplissages d'image rendus ; pas d'import drag-and-drop ni support vidéo |
+| Ajustement des propriétés d'image | 🔲 | Exposition, contraste, saturation, etc. |
+| Recadrer une image | 🔲 | Recadrage interactif d'images |
+| Outil pipette | 🔲 | Échantillonner des couleurs du canevas |
+| Édition de couleur en sélection mixte | 🔲 | Ajuster les couleurs dans une sélection hétérogène |
+| Modèles de couleur (RGB, HSL, HSB, Hex) | 🟡 | HSV + Hex dans le sélecteur ; pas de bascule mode HSL ou RGB |
+
+## Effets et propriétés
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Ombre portée | ✅ | Décalage, rayon de flou, couleur via filtres CanvasKit |
+| Ombre intérieure | ✅ | Effet d'ombre inset |
+| Flou de calque | ✅ | Flou gaussien sur le calque |
+| Flou d'arrière-plan | ✅ | Flouter le contenu derrière le calque |
+| Flou de premier plan | ✅ | Flou au premier plan |
+| Épaisseur du contour | ✅ | Configurable dans le panneau de propriétés |
+| Extrémité du contour (round, square, arrow) | ✅ | NONE, ROUND, SQUARE, ARROW_LINES, ARROW_EQUILATERAL |
+| Jointure du contour (miter, bevel, round) | ✅ | Les trois types de jointure |
+| Motifs de tirets | ✅ | Motif de contour dash-on/dash-off |
+| Rayon de coin | ✅ | Rayon uniforme et par coin avec toggle indépendant |
+| Lissage de coin (style iOS) | 🔲 | Arrondi continu des coins de Figma |
+| Remplissages/contours multiples par calque | 🔲 | Figma permet d'empiler remplissages et contours |
+
+## Auto Layout
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Flux horizontal et vertical | ✅ | Moteur flexbox Yoga WASM |
+| Basculer auto layout (⇧A) | ✅ | Basculer sur un frame ou envelopper la sélection |
+| Gap (espacement entre enfants) | ✅ | Configurable dans le panneau de propriétés |
+| Padding (uniforme et par côté) | ✅ | Les quatre côtés indépendamment |
+| Justify content | ✅ | Start, center, end, space-between |
+| Align items | ✅ | Start, center, end, stretch |
+| Dimensionnement des enfants (fixe, remplir, ajuster) | ✅ | Modes de dimensionnement par enfant |
+| Wrap | ✅ | Flex wrap pour layout multi-ligne |
+| Flux auto layout en grille | 🔲 | Auto layout basé sur grille de Figma |
+| Flux combinés (imbriqués) | ✅ | Frames auto-layout imbriqués avec directions différentes |
+| Réordonnancer par glissement dans auto layout | ✅ | Indicateur visuel d'insertion |
+| Largeur/hauteur min et max | 🔲 | Figma supporte les contraintes min/max |
+
+## Composants et systèmes de design
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Créer des composants | 🟡 | ⌥⌘K crée depuis frame/groupe ; pas d'UI de propriétés de composant encore |
+| Ensembles de composants | 🟡 | ⇧⌘K combine des composants ; bordure pointillée violette ; pas d'édition de propriétés de variante |
+| Instances de composants | 🟡 | Créer instance depuis menu contextuel ; sync en direct ; pas d'UI d'édition de surcharges |
+| Variantes | 🔲 | Changement de variante et sélection par propriétés |
+| Propriétés de composant | 🔲 | Propriétés booléennes, texte, échange d'instance |
+| Propagation des surcharges | ✅ | Changements du composant principal propagés ; surcharges préservées |
+| Variables (couleur, nombre, chaîne, booléen) | 🟡 | COLOR avec UI complète ; FLOAT/STRING/BOOLEAN définis sans UI d'édition |
+| Collections et modes de variables | 🟡 | Collections, modes, changement activeMode fonctionnent ; pas d'UI de thématisation |
+| Styles (couleur, texte, effet, layout) | 🔲 | Presets de style réutilisables nommés |
+| Bibliothèques (publier, partager, mettre à jour) | 🔲 | Bibliothèques partagées de composants/styles |
+| Détacher une instance | ✅ | ⌥⌘B convertit une instance en frame |
+| Aller au composant principal | ✅ | Naviguer vers le composant source, cross-page |
+
+## Prototypage
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Connexions de prototype | 🔲 | Prévu pour la Phase 6 |
+| Déclencheurs (clic, survol, glisser, etc.) | 🔲 | Prévu pour la Phase 6 |
+| Actions (naviguer, overlay, scroll, etc.) | 🔲 | Prévu pour la Phase 6 |
+| Animations et transitions | 🔲 | Prévu pour la Phase 6 |
+| Smart animate | 🔲 | Auto-animer les calques correspondants |
+| Overlays | 🔲 | Prototypage modal/popover |
+| Comportement de scroll et overflow | 🔲 | Frames scrollables dans les prototypes |
+| Flux de prototype | 🔲 | Points de départ nommés |
+| Variables dans les prototypes | 🔲 | Logique conditionnelle avec variables |
+| Easing et animations spring | 🔲 | Courbes d'animation personnalisées |
+| Présenter et jouer les prototypes | 🔲 | Visionneuse de prototype plein écran |
+
+## Import et export
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Import de fichier .fig | ✅ | Codec Kiwi complet : 194 définitions, ~390 champs par NodeChange |
+| Export de fichier .fig | ✅ | Encodage Kiwi + compression Zstd + génération de miniature |
+| Enregistrer / Enregistrer sous | ✅ | ⌘S / ⇧⌘S ; dialogues natifs (Tauri), File System Access API (Chrome/Edge), téléchargement (Safari) |
+| Presse-papiers Figma (coller) | ✅ | Décoder binaire Kiwi du presse-papiers Figma |
+| Presse-papiers Figma (copier) | ✅ | Encoder binaire Kiwi lisible par Figma |
+| Import de fichier Sketch | 🔲 | Analyse de fichiers .sketch |
+| Export image/SVG | 🟡 | PNG/JPG/WEBP avec sélecteur d'échelle et aperçu ; SVG/PDF pas encore |
+| Historique des versions | 🔲 | Parcourir et restaurer les versions précédentes |
+| Copier des assets entre outils | 🟡 | Presse-papiers Figma fonctionne ; pas de presse-papiers SVG/PDF |
+
+## API de plugins et scripting
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Commande eval avec Figma Plugin API | ✅ | Exécution headless de JavaScript avec objet global figma compatible |
+
+## Collaboration et mode développeur
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Commentaires (épingler, fils, résoudre) | 🔲 | Prévu pour la Phase 6 |
+| Multijoueur en temps réel | ✅ | P2P via Trystero + Yjs CRDT, curseurs, mode suivi ; sans serveur |
+| Chat au curseur | 🔲 | Bulles de chat inline au curseur |
+| Branching et merging | 🔲 | Branches de version pour fichiers de design |
+| Mode développeur (inspecter) | 🟡 | Onglet Code montre JSX ; pas de propriétés CSS ni specs de handoff |
+| Code Connect | 🔲 | Lier composants de design au code |
+| Extraits de code | 🟡 | Export JSX avec coloration et copie ; pas d'extraits CSS/Swift/Kotlin |
+| Figma for VS Code | 🔲 | Intégration plugin éditeur |
+| Serveur MCP | ✅ | @open-pencil/mcp avec transports stdio + HTTP ; 75 outils core + 3 gestion de fichiers |
+| Outils CLI | ✅ | CLI headless : info, tree, find, export, analyze, node, pages, variables, eval ; serveur MCP |
+
+## Figma Draw
+
+| Fonctionnalité | Statut | Notes |
+|---------------|--------|-------|
+| Outils d'illustration | 🔲 | Outils de dessin spécialisés de Figma Draw |
+| Transformations de motif | 🔲 | Créer des motifs répétitifs avec des transformations |
diff --git a/packages/docs/fr/guide/tech-stack.md b/packages/docs/fr/guide/tech-stack.md
index bbe3f4e7a..cbced2e70 100644
--- a/packages/docs/fr/guide/tech-stack.md
+++ b/packages/docs/fr/guide/tech-stack.md
@@ -1,17 +1,63 @@
# Stack technique
-| Layer | Technology | Why |
-|-------|-----------|-----|
-| **Rendering** | Skia CanvasKit WASM | GPU-accelerated, same as Figma |
-| **UI** | Vue 3 + VueUse | Reactive, TypeScript |
-| **Components** | Reka UI | Headless, accessible |
-| **Styling** | Tailwind CSS 4 | Utility-first |
-| **Layout** | Yoga WASM | CSS flexbox (Meta) |
-| **File Format** | Kiwi binary + Zstd | Figma .fig compatible |
-| **Desktop** | Tauri v2 | ~5 MB (vs Electron ~100 MB) |
-| **Build** | Vite 7 | Fast HMR |
-| **Testing** | Playwright + bun:test | E2E + unit |
-| **Linting** | oxlint | Rust-based |
-| **Type Checking** | typescript-go (tsgo) | Native Go |
+## Technologies principales
-[Full details in English](/guide/tech-stack)
+| Couche | Technologie | Pourquoi |
+|--------|-----------|----------|
+| **Rendu** | Skia CanvasKit WASM | Même moteur que Figma — performances éprouvées, accéléré GPU, pixel-parfait |
+| **Framework UI** | Vue 3 + VueUse | API de composition réactive, excellent support TypeScript |
+| **Composants** | Reka UI | Primitives UI headless et accessibles (tree, slider, etc.) |
+| **Stylisation** | Tailwind CSS 4 | Utility-first, itération rapide, thème sombre |
+| **Layout** | Yoga WASM | Moteur CSS flexbox de Meta, éprouvé dans React Native |
+| **Format de fichier** | Kiwi binaire + Zstd | Format propre de Figma — compact, parsing rapide, compatible .fig |
+| **Collaboration** | Trystero + Yjs | P2P WebRTC via signalisation MQTT, sync CRDT, persistance y-indexeddb |
+| **Couleur** | culori | Conversions d'espaces colorimétriques (HSV, RGB, hex) |
+| **IA/MCP** | MCP SDK + Hono | 75 outils pour le codage IA, transports stdio + HTTP |
+| **Desktop** | Tauri v2 | ~5 Mo app native (vs ~100 Mo d'Electron), backend Rust |
+| **Build** | Vite 7 | HMR rapide, modules ES natifs |
+| **Test** | Playwright + bun:test | Régression visuelle (E2E) + tests unitaires rapides |
+| **Linting** | oxlint | Basé sur Rust, ordres de grandeur plus rapide qu'ESLint |
+| **Formatage** | oxfmt | Formateur basé sur Rust |
+| **Vérification de types** | typescript-go (tsgo) | Implémentation native en Go du vérificateur de types TypeScript |
+
+## Dépendances principales
+
+```json
+{
+ "canvaskit-wasm": "^0.40.0",
+ "vue": "^3.5.29",
+ "yoga-layout": "^3.2.1",
+ "reka-ui": "^2.8.2",
+ "tailwindcss": "^4.2.1",
+ "culori": "^4.0.2",
+ "fzstd": "^0.1.1",
+ "fflate": "^0.8.2",
+ "trystero": "^0.20.0",
+ "yjs": "^13.6.24",
+ "y-indexeddb": "^9.0.12"
+}
+```
+
+## Pourquoi pas...
+
+### Pourquoi pas le rendu SVG ?
+
+SVG est lent pour les documents complexes. Chaque nœud est un élément DOM — 10 000 nœuds signifient 10 000 éléments DOM avec overhead de layout, peinture et composition. CanvasKit dessine tout sur une seule surface GPU.
+
+### Pourquoi pas Electron (comme Figma desktop) ?
+
+Tauri v2 utilise le webview système (~5 Mo) au lieu d'embarquer Chromium (~100 Mo). Le backend Rust fournit des performances natives pour les E/S fichier et l'intégration système.
+
+### Pourquoi pas React ?
+
+Le projet a migré de React vers Vue 3 très tôt. Le système de réactivité de Vue et les composables VueUse se sont avérés plus ergonomiques.
+
+### Pourquoi pas un moteur de layout personnalisé ?
+
+Yoga est maintenu par Meta, éprouvé sur des milliards d'appareils React Native et implémente la spécification CSS flexbox.
+
+## Technologies planifiées
+
+| Technologie | Objectif | Phase |
+|-----------|---------|-------|
+| CSS Grid dans Yoga | Auto layout basé sur une grille | Bloqué en amont (facebook/yoga#1893) |
diff --git a/packages/docs/fr/reference/mcp-tools.md b/packages/docs/fr/reference/mcp-tools.md
index a79eccb76..f81a9cd2e 100644
--- a/packages/docs/fr/reference/mcp-tools.md
+++ b/packages/docs/fr/reference/mcp-tools.md
@@ -24,7 +24,7 @@ Add to your MCP config (e.g. `~/.claude/settings.json` or `.cursor/mcp.json`):
}
```
-Installation:Ou exécuter depuis les sources :
+Ou exécuter depuis les sources :
::: code-group
```json [Bun]
@@ -73,7 +73,7 @@ Starts on port 3100 (override with `PORT` env var). Endpoints:
5. **Structure** — `reparent_node`, `group_nodes`, `clone_node`, `delete_node`
6. **Save** — `save_file` to write back to `.fig`
-## Tools (29)
+## Tools (75)
### Document
diff --git a/packages/docs/guide/architecture.md b/packages/docs/guide/architecture.md
index f17a651e1..b6b90bd77 100644
--- a/packages/docs/guide/architecture.md
+++ b/packages/docs/guide/architecture.md
@@ -29,7 +29,7 @@
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
-│ MCP Server (planned, 117 tools) Collaboration (planned, CRDT) │
+│ MCP Server (75+ tools, stdio+HTTP) P2P Collab (Trystero + Yjs) │
└──────────────────────────────────────────────────────────────────┘
```
@@ -85,4 +85,12 @@ Inverse-command pattern. Before applying any change, affected fields are snapsho
### Clipboard
-Figma-compatible bidirectional clipboard. Encodes/decodes Kiwi binary (same format as .fig files) using native browser copy/paste events (synchronous, not async Clipboard API).
+Figma-compatible bidirectional clipboard. Encodes/decodes Kiwi binary (same format as .fig files) using native browser copy/paste events (synchronous, not async Clipboard API). Paste handles vector path scaling, instance child population from components, component set detection, and override application.
+
+### MCP Server
+
+`@open-pencil/mcp` exposes 75 core tools + 3 file management tools for AI coding tools. Two transports: stdio for Claude Code/Cursor/Windsurf, HTTP with Hono + Streamable HTTP for scripts and CI. Tools are defined once in `packages/core/src/tools/schema.ts` and adapted for AI chat (valibot), MCP (zod), and CLI (eval command).
+
+### P2P Collaboration
+
+Real-time peer-to-peer collaboration via Trystero (WebRTC) + Yjs CRDT. No server relay — signaling over MQTT public brokers, STUN/TURN for NAT traversal. Awareness protocol provides live cursors, selections, and presence. Local persistence via y-indexeddb.
diff --git a/packages/docs/guide/comparison.md b/packages/docs/guide/comparison.md
index 5ec2673b1..f965eba9c 100644
--- a/packages/docs/guide/comparison.md
+++ b/packages/docs/guide/comparison.md
@@ -11,7 +11,7 @@ Penpot 2.x includes a Rust/Skia WASM renderer (`render-wasm/v1`) that can be ena
| Metric | Open Pencil | Penpot |
|--------|-------------|--------|
| Total LOC | **~26,000** | **~299,000** |
-| Source files | 125 | ~2,900 |
+| Source files | ~143 | ~2,900 |
| Languages | TypeScript, Vue | Clojure, ClojureScript, Rust, JS, SQL, SCSS |
| Rendering engine | 1,646 LOC (TS) | 22,000 LOC (Rust/Skia WASM) |
| UI code | ~4,500 LOC | ~175,000 LOC (CLJS + SCSS) |
@@ -262,7 +262,7 @@ Open Pencil's approach is simpler and lower overhead. Penpot's approach is more
## 10. What Penpot Does Better
-1. **Real-time collaboration** — production-ready multi-user editing with WebSockets
+1. **Server-side collaboration** — centralized multi-user editing with WebSockets, user accounts, and access control (Open Pencil uses P2P via Trystero + Yjs — no server, but also no access control or persistence beyond the session)
2. **Server-side export** — headless Chromium export service for SVG/PNG/PDF rendering
3. **Plugin system** — full plugin API with sandboxed execution
4. **Design tokens** — native design token support
@@ -272,7 +272,7 @@ Open Pencil's approach is simpler and lower overhead. Penpot's approach is more
## 11. Scripting & Extensibility
-OpenPencil ships with an [`eval` command](/eval-command) that provides a Figma-compatible Plugin API for headless scripting — batch operations, automated testing, and AI-driven modifications all run without the GUI. Penpot has no plugin system or scripting API; extending it requires forking the Clojure backend.
+OpenPencil ships with an [`eval` command](/eval-command) that provides a Figma-compatible Plugin API for headless scripting — batch operations, automated testing, and AI-driven modifications all run without the GUI. On top of that, 75 AI tools are available via built-in chat, MCP server (stdio + HTTP), and the CLI. Penpot has a plugin system with sandboxed execution but no headless scripting API or MCP integration.
## Summary
@@ -280,13 +280,13 @@ OpenPencil ships with an [`eval` command](/eval-command) that provides a Figma-c
|-----------|--------|-----|
| **Architecture simplicity** | Open Pencil | Single process vs 5+ services |
| **Rendering performance** | Open Pencil | Direct CanvasKit vs SVG DOM (default) or binary-packed WASM |
-| **Code maintainability** | Open Pencil | 14.5K LOC in 1 language vs 299K in 4+ languages |
+| **Code maintainability** | Open Pencil | ~26K LOC in 1 language vs 299K in 4+ languages |
| **Figma compatibility** | Open Pencil | Native Kiwi codec vs no .fig support |
| **Developer onboarding** | Open Pencil | TS/Vue vs Clojure/Rust/Docker |
| **Desktop experience** | Open Pencil | Tauri native vs browser-only |
| **Layout engine** | Open Pencil | Yoga (proven) vs custom dual implementation |
-| **Collaboration** | Penpot | Production multi-user vs planned (Yjs) |
+| **Collaboration** | Tie | Penpot: server-based with access control; Open Pencil: P2P via Trystero + Yjs, zero hosting |
| **Self-hosting** | Penpot | Docker-ready vs desktop-only |
| **Ecosystem maturity** | Penpot | Years of production vs early stage |
-Open Pencil is architecturally leaner — a single-process CanvasKit renderer in ~26K LOC of TypeScript, Figma-compatible by design. Penpot is a full-stack platform with ~299K LOC across Clojure, ClojureScript, Rust, and SCSS, plus a Docker service fleet. The tradeoff is that Penpot already has production collaboration, a plugin ecosystem, and server-side export, while Open Pencil is still building toward those.
+Open Pencil is architecturally leaner — a single-process CanvasKit renderer in ~26K LOC of TypeScript, Figma-compatible by design. Penpot is a full-stack platform with ~299K LOC across Clojure, ClojureScript, Rust, and SCSS, plus a Docker service fleet. Both now offer real-time collaboration (different architectures: P2P vs server). Penpot has a plugin ecosystem and server-side export; Open Pencil has Figma-compatible headless scripting, 75 AI/MCP tools, and a native desktop app.
diff --git a/packages/docs/guide/features.md b/packages/docs/guide/features.md
index e7d7bcae0..a24bbf79b 100644
--- a/packages/docs/guide/features.md
+++ b/packages/docs/guide/features.md
@@ -14,6 +14,8 @@ Select nodes in Figma, ⌘C, switch to OpenPencil,
Under the hood, both directions use the same Kiwi binary format as .fig files — Figma base64-encodes it into HTML on the clipboard. OpenPencil decodes the full schema on paste (194 definitions, ~390 fields per NodeChange) and encodes it on copy. Vector data round-trips through the `vectorNetworkBlob` binary format. Also works between OpenPencil instances via a separate native clipboard format.
+Paste handles complex scenarios: vector paths are scaled from Figma's `normalizedSize` to actual node bounds, instance children are populated from their component's `symbolData`, component sets are detected by promoting frames with variant `componentPropDefs`, internal canvas nodes are skipped, and `symbolOverrides` are applied for text, fills, visibility, and layout properties. Fonts referenced by pasted text nodes are automatically loaded.
+
## Vector Networks
The pen tool uses Figma's vector network model — not simple paths. Click to place corner points, click+drag for bezier curves with tangent handles. Supports open and closed paths. Vector data uses the same `vectorNetworkBlob` binary format as Figma.
@@ -173,13 +175,61 @@ In browser mode, a menu bar built with reka-ui Menubar provides access to all ma
Files are automatically saved 3 seconds after the last scene change. A debounced watcher monitors `sceneVersion` — multiple rapid edits only trigger a single write after activity settles. Uses the Tauri fs plugin on desktop or the File System Access API in supported browsers. Autosave is disabled for new untitled documents until the user performs an explicit Save As. Errors are handled silently — the user can always trigger a manual save with ⌘S.
+## P2P Collaboration
+
+Real-time peer-to-peer collaboration — no server required. Share a link and edit together. Built on Trystero (WebRTC) for direct peer connections and Yjs (CRDT) for conflict-free document sync.
+
+- **Zero hosting cost** — signaling via MQTT public brokers, data flows directly between peers
+- **NAT traversal** — Google STUN, Cloudflare STUN, and Open Relay TURN servers
+- **Live cursors** — Figma-style colored cursor arrows with white border and name pills, rendered in screen space
+- **Presence** — see who's in the room with colored avatars
+- **Follow mode** — click a peer's avatar to follow their viewport in real time, click again to stop
+- **Local persistence** — y-indexeddb keeps the room alive across page refreshes
+- **Secure rooms** — IDs generated with `crypto.getRandomValues()`, shared via `/share/` URL
+
+Stale cursors are cleaned up automatically when a peer disconnects.
+
+## Multi-File Tabs
+
+Open multiple documents in tabs within a single window. Tab bar shows open files with close buttons. Middle-click a tab to close it.
+
+- ⌘N or ⌘T — new tab
+- ⌘W — close current tab
+- ⌘O — open file in new tab
+- + button in tab bar — new tab
+
+Each tab maintains its own document state, undo history, and viewport.
+
+## Effects Rendering
+
+Full rendering of Figma effects via CanvasKit:
+
+- **Drop shadow** — offset, blur radius, spread, color; draws behind opaque content using `MaskFilter` direct draw (no `saveLayer` overhead)
+- **Inner shadow** — inset shadow with offset, blur, and color
+- **Layer blur** — Gaussian blur on the entire layer
+- **Background blur** — blur content behind the layer (glass/frosted effect)
+- **Foreground blur** — blur in the foreground
+
+Text shadows render on individual glyphs instead of the bounding box. Each effect has an independent visibility toggle. Per-node `SkPicture` caching means unchanged shadow/blur nodes replay from cache on scene redraws — zero re-computation for static effects.
+
+## Multi-Selection Properties
+
+Select multiple nodes and edit shared properties at once. The properties panel adapts:
+
+- Shared values display normally in all sections (position, size, appearance, fill, stroke, effects)
+- Differing values show "Mixed"
+- Width and height inputs work across the selection
+- Flip horizontal/vertical applies to all selected nodes
+
+Single-node alignment aligns to parent frame bounds. Multi-selection uses the selection bounding box.
+
## ScrubInput
All numeric inputs in the properties panel use a drag-to-scrub interaction — drag horizontally to adjust the value, or click to type directly. Supports suffix display (°, px, %).
## CI/CD Builds
-GitHub Actions workflow builds native Tauri desktop apps on version tags. The build matrix covers Windows (x64, arm64) and macOS (x64, arm64). Builds use `tauri-apps/tauri-action` and produce draft GitHub releases with platform-specific binaries.
+GitHub Actions workflow builds native Tauri desktop apps on version tags. The build matrix covers macOS (arm64, x64), Windows (x64, arm64), and Linux (x64). Builds use `tauri-apps/tauri-action` and produce draft GitHub releases with platform-specific binaries. macOS builds are code-signed and notarized via Apple Developer certificates. Release notes are auto-populated from CHANGELOG.md.
## @open-pencil/core & CLI
@@ -220,9 +270,9 @@ Built-in AI assistant accessible via the AI tab in the properties panel or
**Model selector** with curated models: Claude, Gemini, GPT, DeepSeek, Qwen, Kimi, Llama — stored in `@open-pencil/core` constants with benchmark-ranked tags. Responses stream as markdown (vue-stream-markdown).
-**29 tools** defined in `packages/core/src/tools/schema.ts`: read tools (`get_selection`, `get_page_tree`, `get_node`, `find_nodes`, `list_pages`, `list_variables`, `list_collections`), create tools (`create_shape`, `render`, `create_component`, `create_instance`), modify tools (`set_fill`, `set_stroke`, `set_effects`, `update_node`, `set_layout`, `set_constraints`, `rename_node`, `reparent_node`, `clone_node`, `delete_node`), organize tools (`select_nodes`, `group_nodes`, `ungroup_node`, `switch_page`), and `eval` escape hatch. Tools are wired to AI chat (valibot schemas), MCP server (zod schemas), and CLI (`eval` command). Tool calls display as collapsible timeline entries in the chat (reka-ui Collapsible).
+**75 tools** defined in `packages/core/src/tools/schema.ts`, covering: read operations (selection, page tree, node details, search), create operations (shapes, frames, vectors, slices, pages, components, instances), modify operations (fill, stroke, effects, layout, constraints, text, font, opacity, rotation, radius, visibility, blend mode, lock), node manipulation (move, resize, reparent, clone, delete, flatten, boolean operations), variable CRUD (get, find, create, set, delete, bind, collections), vector path tools (get, set, scale, flip, move), viewport control, and an `eval` escape hatch. Tools are wired to AI chat (valibot schemas), MCP server (zod schemas), and CLI (`eval` command). Tool calls display as collapsible timeline entries in the chat (reka-ui Collapsible).
-**MCP server** (`packages/mcp/`) exposes all tools for external AI coding tools. Two transports: stdio for Claude Code/Cursor/Windsurf (`openpencil-mcp`), HTTP with Hono + Streamable HTTP for scripts and CI (`openpencil-mcp-http`). Adds 3 file management tools (`open_file`, `save_file`, `new_document`) on top of the 26 core tools. Runs on Bun and Node.js. See [MCP Tools reference](/reference/mcp-tools).
+**MCP server** (`packages/mcp/`) exposes all tools for external AI coding tools. Two transports: stdio for Claude Code/Cursor/Windsurf (`openpencil-mcp`), HTTP with Hono + Streamable HTTP for scripts and CI (`openpencil-mcp-http`). Adds 3 file management tools (`open_file`, `save_file`, `new_document`) on top of the 75 core tools, for 78 total. Runs on Bun and Node.js. See [MCP Tools reference](/reference/mcp-tools).
Tested with Playwright using mock transport for CI (chat), bun:test for tool execution (MCP).
diff --git a/packages/docs/guide/figma-comparison.md b/packages/docs/guide/figma-comparison.md
index 990713a40..d41ab0e8d 100644
--- a/packages/docs/guide/figma-comparison.md
+++ b/packages/docs/guide/figma-comparison.md
@@ -6,7 +6,7 @@ Feature-by-feature comparison of Figma Design capabilities with Open Pencil's cu
✅ Supported — feature works end-to-end · 🟡 Partial — core behavior exists, some sub-features missing · 🔲 Not yet implemented
:::
-**Coverage:** 87 of 152 Figma feature items addressed — 69 ✅ fully supported, 18 🟡 partial, 65 🔲 not yet. Last updated: 2026-03-03.
+**Coverage:** 88 of 152 Figma feature items addressed — 70 ✅ fully supported, 18 🟡 partial, 64 🔲 not yet. Last updated: 2026-03-04.
## Interface & Navigation
@@ -28,7 +28,7 @@ Feature-by-feature comparison of Figma Design capabilities with Open Pencil's cu
| Custom file thumbnails | 🔲 | Thumbnail generated on export, but no custom thumbnail picker |
| Nudge value settings | 🔲 | Default 1px/10px; Figma allows custom small/big nudge values |
| App menu (browser mode) | ✅ | File, Edit, View, Object, Text, Arrange menus; Tauri uses native menus |
-| AI tools | 🟡 | 29 tools via OpenRouter + MCP server; no AI-generated images or AI-powered search yet |
+| AI tools | 🟡 | 75 tools via OpenRouter + MCP server; no AI-generated images or AI-powered search yet |
## Layers & Shapes
@@ -55,7 +55,7 @@ Feature-by-feature comparison of Figma Design capabilities with Open Pencil's cu
| Smart selection (distribute/align) | 🔲 | Evenly space and align multi-selection |
| Layout guides (columns, rows, grid) | 🔲 | Column/row/grid overlay guides on frames |
| Measure distances between layers | 🔲 | Alt-hover to show distances |
-| Edit objects in bulk | 🔲 | Batch property editing |
+| Edit objects in bulk | ✅ | Multi-selection properties panel: edit position, size, appearance, fill, stroke, effects across multiple nodes; shared values display normally, differing values show "Mixed" |
| Identify matching objects | 🔲 | Find similar layers |
| Copy/paste properties | 🔲 | Copy fill/stroke/effects between layers |
| Parent-child relationships | ✅ | Full hierarchy with parentIndex, reparenting via drag |
@@ -215,7 +215,7 @@ Feature-by-feature comparison of Figma Design capabilities with Open Pencil's cu
| Code Connect | 🔲 | Link design components to code |
| Code snippets | 🟡 | JSX export with syntax highlighting and copy; no CSS/Swift/Kotlin snippets |
| Figma for VS Code | 🔲 | Editor plugin integration |
-| MCP server | ✅ | @open-pencil/mcp with stdio + HTTP transports; 29 core tools + 3 file management tools |
+| MCP server | ✅ | @open-pencil/mcp with stdio + HTTP transports; 75 core tools + 3 file management tools |
| CLI tools | ✅ | Headless CLI: info, tree, find, export, analyze, node, pages, variables, eval; MCP server with stdio + HTTP |
## Figma Draw
diff --git a/packages/docs/guide/tech-stack.md b/packages/docs/guide/tech-stack.md
index d0c619d3e..7537477d5 100644
--- a/packages/docs/guide/tech-stack.md
+++ b/packages/docs/guide/tech-stack.md
@@ -10,7 +10,9 @@
| **Styling** | Tailwind CSS 4 | Utility-first, fast iteration, dark theme |
| **Layout** | Yoga WASM | CSS flexbox engine from Meta, battle-tested in React Native |
| **File Format** | Kiwi binary + Zstd | Figma's own format — compact, fast parsing, .fig compatible |
+| **Collaboration** | Trystero + Yjs | P2P WebRTC via MQTT signaling, CRDT sync, y-indexeddb persistence |
| **Color** | culori | Color space conversions (HSV, RGB, hex) |
+| **AI/MCP** | MCP SDK + Hono | 75 tools for AI coding tools, stdio + HTTP transports |
| **Desktop** | Tauri v2 | ~5MB native app (vs Electron's ~100MB), Rust backend |
| **Build** | Vite 7 | Fast HMR, native ES modules |
| **Testing** | Playwright + bun:test | Visual regression (E2E) + fast unit tests |
@@ -29,7 +31,10 @@
"tailwindcss": "^4.2.1",
"culori": "^4.0.2",
"fzstd": "^0.1.1",
- "fflate": "^0.8.2"
+ "fflate": "^0.8.2",
+ "trystero": "^0.20.0",
+ "yjs": "^13.6.24",
+ "y-indexeddb": "^9.0.12"
}
```
@@ -55,5 +60,4 @@ Yoga is maintained by Meta, battle-tested across billions of React Native device
| Technology | Purpose | Phase |
|-----------|---------|-------|
-| Yjs (CRDT) | Real-time collaboration | Phase 6 |
-| MCP Server | AI agent integration (117 tools) | Phase 5 |
+| CSS Grid in Yoga | Grid-based auto layout | Blocked on upstream (facebook/yoga#1893) |
diff --git a/packages/docs/it/development/contributing.md b/packages/docs/it/development/contributing.md
index 371bc27dc..94db5c69f 100644
--- a/packages/docs/it/development/contributing.md
+++ b/packages/docs/it/development/contributing.md
@@ -4,38 +4,50 @@
```
packages/
- core/ @open-pencil/core — Engine
- cli/ @open-pencil/cli — Headless CLI
- mcp/ @open-pencil/mcp — MCP server
- docs/ @open-pencil/docs — VitePress
+ core/ @open-pencil/core — motore (zero dipendenze DOM)
+ src/ Grafo scena, renderer, layout, codec, kiwi, tipi
+ cli/ @open-pencil/cli — CLI headless per operazioni .fig
+ src/commands/ info, tree, find, export, eval, analyze
+ mcp/ @open-pencil/mcp — server MCP per strumenti IA
+ src/ Trasporti stdio + HTTP (Hono), 75 strumenti
src/
- components/ Vue SFCs
- composables/ Canvas input, shortcuts, rendering
- stores/ Editor state
-desktop/ Tauri v2
+ components/ Vue SFCs (canvas, pannelli, barra strumenti, selettore colore)
+ properties/ Sezioni pannello proprietà (Aspetto, Riempimento, Contorno, ecc.)
+ composables/ Input canvas, scorciatoie tastiera, hook di rendering
+ stores/ Stato editor (reattività Vue)
+ engine/ Shim di ri-esportazione da @open-pencil/core
+ kiwi/ Shim di ri-esportazione da @open-pencil/core
+ types.ts Tipi condivisi (ri-esportati da core)
+ constants.ts Colori UI, default, soglie
+desktop/ Tauri v2 (Rust + config)
tests/
- e2e/ Playwright
- engine/ bun:test
-openspec/ Specs + changes
+ e2e/ Regressione visiva Playwright
+ engine/ Test unitari (bun:test)
+docs/ Sito documentazione VitePress
+openspec/
+ specs/ Specifiche di capacità (fonte di verità)
+ changes/ Cambiamenti attivi e archiviati
```
-## Ambiente di sviluppo
+## Configurazione sviluppo
```sh
bun install
-bun run dev # Editor: localhost:1420
-bun run docs:dev # Docs: localhost:5173
+bun run dev # Editor su localhost:1420
+bun run docs:dev # Docs su localhost:5173
```
-## Stile del codice
+## Stile di codice
### Strumenti
-| Tool | Command | Purpose |
-|------|---------|---------|
-| oxlint | `bun run lint` | Linting |
-| oxfmt | `bun run format` | Formatting |
-| tsgo | `bun run typecheck` | Type checking |
+| Strumento | Comando | Scopo |
+|-----------|---------|-------|
+| oxlint | `bun run lint` | Linting (basato su Rust, veloce) |
+| oxfmt | `bun run format` | Formattazione codice |
+| tsgo | `bun run typecheck` | Verifica tipi (checker TypeScript basato su Go) |
+
+Eseguire tutte le verifiche:
```sh
bun run check
@@ -43,23 +55,45 @@ bun run check
### Convenzioni
-- kebab-case (files), PascalCase (components/types), camelCase (functions), SCREAMING_SNAKE_CASE (constants)
-- AGENTS.md — [GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)
+- **Nomi file** — kebab-case (`scene-graph.ts`, `use-canvas-input.ts`)
+- **Componenti** — PascalCase Vue SFCs (`EditorCanvas.vue`, `ScrubInput.vue`)
+- **Costanti** — SCREAMING_SNAKE_CASE
+- **Funzioni/variabili** — camelCase
+- **Tipi/interfacce** — PascalCase
+
+### Convenzioni per agenti IA
+
+Sviluppatori e agenti IA dovrebbero leggere `AGENTS.md` nella root del repo ([vedi su GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)). Copre rendering, grafo scena, componenti e istanze, layout, UI, formato file, convenzioni Tauri e problemi noti.
## Apportare modifiche
-1. [OpenSpec](./openspec) specs
-2. `openspec new change "name"`
-3. `bun run check && bun run test`
-4. Pull request
+1. Consultare le [spec openspec](/development/openspec) esistenti
+2. Creare un cambiamento openspec se si aggiunge un nuovo comportamento: `openspec new change "mio-cambiamento"`
+3. Implementare il cambiamento
+4. Eseguire `bun run check` e `bun run test`
+5. Inviare una pull request
-## File principali
+## File chiave
-| File | Purpose |
-|------|---------|
-| `packages/core/src/scene-graph.ts` | Scene graph |
-| `packages/core/src/renderer.ts` | CanvasKit rendering |
-| `packages/core/src/layout.ts` | Yoga layout |
-| `packages/core/src/kiwi/codec.ts` | Kiwi codec |
-| `packages/cli/src/commands/` | CLI commands |
-| `src/stores/editor.ts` | Editor state |
+Il codice sorgente del motore si trova in `packages/core/src/`. I directory `src/engine/` e `src/kiwi/` dell'app sono shim di ri-esportazione — modificare il pacchetto core, non gli shim.
+
+| File | Scopo |
+|------|-------|
+| `packages/core/src/scene-graph.ts` | Grafo scena: nodi, variabili, istanze, hit testing |
+| `packages/core/src/renderer.ts` | Pipeline di rendering CanvasKit |
+| `packages/core/src/layout.ts` | Adattatore layout Yoga |
+| `packages/core/src/undo.ts` | Gestore annulla/ripristina |
+| `packages/core/src/clipboard.ts` | Appunti compatibili con Figma |
+| `packages/core/src/vector.ts` | Modello rete vettoriale |
+| `packages/core/src/render-image.ts` | Export immagine offscreen (PNG/JPG/WEBP) |
+| `packages/core/src/kiwi/codec.ts` | Encoder/decoder binario Kiwi |
+| `packages/core/src/kiwi/fig-import.ts` | Logica import file .fig |
+| `packages/cli/src/index.ts` | Punto di ingresso CLI |
+| `packages/core/src/tools/schema.ts` | Definizioni strumenti unificate (IA, MCP, CLI) |
+| `packages/core/src/figma-api.ts` | Implementazione Figma Plugin API |
+| `packages/mcp/src/server.ts` | Factory del server MCP |
+| `packages/cli/src/commands/` | Comandi CLI (info, tree, find, export, eval, analyze) |
+| `src/stores/editor.ts` | Stato globale dell'editor |
+| `src/composables/use-canvas.ts` | Composable rendering canvas |
+| `src/composables/use-canvas-input.ts` | Gestione input mouse/touch |
+| `src/composables/use-keyboard.ts` | Gestione scorciatoie tastiera |
diff --git a/packages/docs/it/development/roadmap.md b/packages/docs/it/development/roadmap.md
index caa7f3cfc..dcaee5cba 100644
--- a/packages/docs/it/development/roadmap.md
+++ b/packages/docs/it/development/roadmap.md
@@ -1,32 +1,67 @@
# Roadmap
-## Fase 1 ✅
-SceneGraph, Skia rendering, shapes, selection, zoom/pan, undo/redo, snap guides.
+## Fasi
-## Motore Core ✅
-Vue 3 + Reka UI panels, properties, layers, toolbar, Yoga auto-layout, inline text editing, canvas rulers.
+### Fase 1: Motore Core ✅
-## Fase 2 ✅
-.fig import/export, Kiwi codec, clipboard, pen tool, vector networks, groups, Tauri v2 desktop, sections, multi-page, hover highlight, Tier 1 rendering.
+SceneGraph, rendering Skia, forme base, selezione, zoom/pan, annulla/ripristina, guide di snap.
-## UI Editor + Layout ✅
-Components, instances, overrides, component sets, variables (COLOR/FLOAT/STRING/BOOLEAN), collections, modes, image export, context menu, rich text formatting.
+### Fase 2: UI Editor + Layout ✅
-## Fase 3 🟡
-@open-pencil/core, CLI (12 commands), MCP server (29+ tools), AI chat (OpenRouter), JSX renderer, code panel.
+Vue 3 + Reka UI panels, proprietà, livelli, barra strumenti, Yoga auto-layout, editing testo inline, righelli canvas.
-**Planned:** port remaining figma-use tools, attached mode, design guidelines, screenshot verification loop.
+### Fase 3: File I/O + Feature Visive ✅
-## File I/O + Feature Visive 🔲
-Prototyping, comments, PWA, Linux Tauri builds, performance optimization, full Figma compatibility test suite.
+Import/export .fig, codec Kiwi, appunti, strumento penna, reti vettoriali, gruppi, Tauri v2 desktop, sezioni, multi-pagina, evidenziazione hover, rendering Tier 1.
-## Fase 4
+### Fase 4: Componenti + Variabili ✅
-| Phase | Componenti + Variabili | Fase 5: Integrazione IA & Strumenti:Fase 6: Rifinitura + Distribuzione:Tempistica:Durata stimata:Stato |
-|-------|------|-----|
-| Fase 1 | 3 months | ✅ |
-| Motore Core | 3 months | ✅ |
-| Fase 2 | 2 months | ✅ |
-| UI Editor + Layout | 2 months | ✅ |
-| Fase 3 | 2 months | 🟡 |
-| File I/O + Feature Visive | 2 months | 🔲 |
+Componenti, istanze, override, set di componenti, variabili (COLOR/FLOAT/STRING/BOOLEAN), collezioni, modalità, export immagini, menu contestuale, formattazione testo ricco.
+
+### Fase 5: Integrazione IA & Strumenti ✅
+
+**Consegnato:**
+- @open-pencil/core estratto in packages/core/ (nessuna dipendenza DOM)
+- @open-pencil/cli con operazioni headless .fig (info, tree, find, export, analyze, eval)
+- Comando `eval` con API Plugin compatibile Figma
+- Chat IA: connessione diretta OpenRouter, 75 strumenti in `schema.ts`, ⌘J
+- 49 strumenti IA/MCP aggiuntivi portati da figma-use (75 in totale)
+- Server MCP (@open-pencil/mcp): stdio + HTTP, 75 strumenti core + 3 gestione file
+- Definizioni strumenti unificate: definire una volta in `schema.ts`, adattare per chat IA (valibot), MCP (zod), CLI (eval)
+- Barra dei menu per modalità browser
+- Salvataggio automatico: scrittura con debounce di 3s
+- Pannello proprietà multi-selezione con valori condivisi/misti
+
+**Pianificato:**
+- Modalità attached: WebSocket verso l'editor in esecuzione
+- Sistema di linee guida di design
+
+### Fase 6: Collaborazione + Distribuzione 🟡
+
+**Consegnato:**
+- Collaborazione P2P via Trystero (WebRTC) + Yjs CRDT — senza server relay
+- Protocollo awareness: cursori in tempo reale, selezioni, presenza
+- Modalità segui: clic sull'avatar di un peer per seguire il suo viewport
+- Persistenza locale via y-indexeddb
+- Rendering effetti: ombra portata, ombra interna, sfocatura livello/sfondo/primo piano
+- Schede multi-file: ⌘N/⌘T nuova scheda, ⌘W chiudi, ⌘O apri
+- Firma codice Apple e notarizzazione per macOS
+- Build Linux (x64) aggiunti al CI
+- Sito documentazione VitePress con i18n (6 lingue)
+
+**Pianificato:**
+- Prototipazione (connessioni frame, transizioni, animazioni)
+- Commenti (pin, thread, risolvere)
+- Supporto PWA
+- Cambio varianti, UI variabili FLOAT/STRING/BOOLEAN, theming tramite variabili
+
+## Tempistica
+
+| Fase | Durata stimata | Stato |
+|------|---------------|--------|
+| Fase 1: Motore Core | 3 mesi | ✅ Completata |
+| Fase 2: UI Editor + Layout | 3 mesi | ✅ Completata |
+| Fase 3: File I/O + Feature Visive | 2 mesi | ✅ Completata |
+| Fase 4: Componenti + Variabili | 2 mesi | ✅ Completata |
+| Fase 5: Integrazione IA & Strumenti | 2 mesi | ✅ Completata |
+| Fase 6: Collaborazione + Distribuzione | 2 mesi | 🟡 In corso |
diff --git a/packages/docs/it/guide/architecture.md b/packages/docs/it/guide/architecture.md
index a8dfdeaa0..b749ff50f 100644
--- a/packages/docs/it/guide/architecture.md
+++ b/packages/docs/it/guide/architecture.md
@@ -5,29 +5,92 @@
```
┌──────────────────────────────────────────────────────────────────┐
│ Tauri v2 Shell │
+│ │
│ ┌────────────────────────────────────────────────────────────┐ │
-│ │ Vue 3 UI Skia CanvasKit (WASM, 7MB) │ │
+│ │ Editor (Web) │ │
+│ │ │ │
+│ │ Vue 3 UI Skia CanvasKit (WASM, 7MB) │ │
+│ │ - Barra strumenti - Rendering vettoriale │ │
+│ │ - Pannelli - Composizione testo │ │
+│ │ - Proprietà - Elaborazione immagini │ │
+│ │ - Livelli - Effetti (sfocatura, ombra) │ │
+│ │ - Selettore colore - Esportazione (PNG, SVG, PDF)│ │
+│ │ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
-│ │ │ Core Engine (TS): SceneGraph, Layout, Selection │ │ │
+│ │ │ Core Engine (TS) │ │ │
+│ │ │ SceneGraph ─── Layout (Yoga) ─── Selection │ │ │
+│ │ │ │ │ │ │ │
+│ │ │ Undo/Redo ─── Constraints ─── Hit Testing │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
+│ │ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
-│ │ │ .fig import/export ── Kiwi codec │ │ │
+│ │ │ Livello formato file │ │ │
+│ │ │ .fig import/export ── Kiwi codec ── .svg (previsto) │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
-│ MCP Server (29+ tools) P2P Collaboration (Yjs CRDT) │
+│ │
+│ MCP Server (75+ tools, stdio+HTTP) P2P Collab (Trystero + Yjs) │
└──────────────────────────────────────────────────────────────────┘
```
-UI segue il layout UI3 di Figma.
+## Layout dell'editor
-Rendering: CanvasKit WASM — GPU, Skia.
+L'interfaccia segue il layout UI3 di Figma — barra strumenti in basso, navigazione a sinistra, proprietà a destra:
-Grafo della scena: `Map` — O(1) lookup, hit testing.
+- **Pannello di navigazione (sinistra)** — Albero dei livelli, pannello pagine, libreria asset (previsto)
+- **Canvas (centro)** — Canvas infinito con rendering CanvasKit, zoom/pan
+- **Pannello proprietà (destra)** — Sezioni contestuali: Aspetto, Riempimento, Contorno, Tipografia, Layout, Posizione
+- **Barra strumenti (basso)** — Selezione strumento: Seleziona, Frame, Sezione, Rettangolo, Ellisse, Linea, Testo, Penna, Mano
-Formato file: Kiwi binary codec — 194 definitions. [File Format](/reference/file-format).
+## Componenti
-Annulla/Ripristina: Inverse-command pattern.
+### Rendering (CanvasKit WASM)
-Appunti: Figma-compatible, Kiwi binary.
+Lo stesso motore di rendering di Figma. CanvasKit fornisce disegno 2D accelerato via GPU con:
+- Forme vettoriali (rettangolo, ellisse, percorso, linea, stella, poligono)
+- Composizione testo via Paragraph API
+- Effetti (ombre, sfocature, modalità di fusione)
+- Esportazione (PNG, SVG, PDF)
-[Full details in English](/guide/architecture)
+Il binario WASM da 7 MB viene caricato all'avvio e crea una superficie GPU sul canvas HTML.
+
+### Grafo della scena
+
+`Map` piatto indicizzato per stringhe GUID. Struttura ad albero tramite riferimenti `parentIndex`. Fornisce ricerca O(1), attraversamento efficiente, hit testing e query per area rettangolare per la selezione a marquee.
+
+Vedi [Riferimento del grafo della scena](/reference/scene-graph) per i dettagli interni.
+
+### Motore di layout (Yoga WASM)
+
+Yoga di Meta fornisce il calcolo del layout CSS flexbox. Un sottile adattatore mappa i nomi delle proprietà Figma agli equivalenti Yoga:
+
+| Proprietà Figma | Equivalente Yoga |
+|---|---|
+| `stackMode: HORIZONTAL` | `flexDirection: row` |
+| `stackMode: VERTICAL` | `flexDirection: column` |
+| `stackSpacing` | `gap` |
+| `stackPadding` | `padding` |
+| `stackJustify` | `justifyContent` |
+| `stackChildPrimaryGrow` | `flexGrow` |
+
+### Formato file (Kiwi binario)
+
+Riutilizza il collaudato codec binario Kiwi di Figma con 194 definizioni di messaggio/enum/struct. Pipeline di importazione `.fig`: analizzare header → decomprimere Zstd → decodificare Kiwi → NodeChange[] → grafo della scena. Il pipeline di esportazione inverte il processo: grafo della scena → NodeChange[] → codificare Kiwi → comprimere Zstd → ZIP con miniatura.
+
+Vedi [Riferimento del formato file](/reference/file-format) per maggiori dettagli.
+
+### Annulla/Ripristina
+
+Pattern di comando inverso. Prima di applicare qualsiasi modifica, i campi interessati vengono catturati in uno snapshot. Lo snapshot diventa l'operazione inversa. Il batching raggruppa le modifiche rapide (come il trascinamento) in singole voci di annullamento.
+
+### Appunti
+
+Appunti bidirezionali compatibili con Figma. Codifica/decodifica binario Kiwi (stesso formato dei file .fig) usando gli eventi nativi copia/incolla del browser (sincroni, non l'API asincrona degli Appunti). L'incolla gestisce il ridimensionamento dei percorsi vettoriali, la popolazione dei figli delle istanze, il rilevamento dei set di componenti e l'applicazione degli override.
+
+### Server MCP
+
+`@open-pencil/mcp` espone 75 strumenti core + 3 strumenti di gestione file per strumenti di codifica IA. Due trasporti: stdio per Claude Code/Cursor/Windsurf, HTTP con Hono + Streamable HTTP per script e CI. Gli strumenti sono definiti una volta in `packages/core/src/tools/schema.ts` e adattati per chat IA (valibot), MCP (zod) e CLI (comando eval).
+
+### Collaborazione P2P
+
+Collaborazione peer-to-peer in tempo reale via Trystero (WebRTC) + Yjs CRDT. Senza server relay — segnalazione tramite broker MQTT pubblici, STUN/TURN per il traversal NAT. Il protocollo awareness fornisce cursori in tempo reale, selezioni e presenza. Persistenza locale tramite y-indexeddb.
diff --git a/packages/docs/it/guide/comparison.md b/packages/docs/it/guide/comparison.md
index 369225303..99112e215 100644
--- a/packages/docs/it/guide/comparison.md
+++ b/packages/docs/it/guide/comparison.md
@@ -1,18 +1,235 @@
-# Confronto con Penpot
+# Open Pencil vs Penpot: Confronto architettura e prestazioni
-| Metric | Open Pencil | Penpot |
-|--------|-------------|--------|
-| Total LOC | **~26,000** | **~299,000** |
-| Source files | 125 | ~2,900 |
-| Languages | TypeScript, Vue | Clojure, ClojureScript, Rust, JS, SQL, SCSS |
-| LOC ratio | **1×** | **~11×** |
-| Rendering | Skia CanvasKit (GPU, WASM) | Skia Rust/WASM (render-wasm v1) |
-| Layout | Yoga WASM (CSS flexbox) | Custom CLJS engine |
-| File format | Figma Kiwi binary (.fig) | Custom SVG + metadata |
-| Desktop | Tauri v2 (~5 MB) | No native client |
-| Backend | None (P2P) | Clojure + PostgreSQL + Redis |
-| Collaboration | P2P (Trystero + Yjs CRDT) | Client-server |
-| AI tools | 29 tools + MCP server | Plugin system |
-| CLI | ✅ 12 commands | ❌ |
+Perché confrontare? OpenPencil esiste perché le piattaforme di design chiuse controllano ciò che è possibile. Comprendere le differenze architetturali mostra cosa un'alternativa aperta e local-first può fare diversamente.
-[Full details in English](/guide/comparison)
+::: info Renderer WASM di Penpot
+Penpot 2.x include un renderer Rust/Skia WASM (`render-wasm/v1`) attivabile tramite flag del server o il parametro URL `?wasm=true`. Il renderer SVG rimane il default. Questa pagina copre entrambi.
+:::
+
+## 1. Scala e dimensione del codice
+
+| Metrica | Open Pencil | Penpot |
+|---------|-------------|--------|
+| LOC totali | **~26.000** | **~299.000** |
+| File sorgente | ~143 | ~2.900 |
+| Linguaggi | TypeScript, Vue | Clojure, ClojureScript, Rust, JS, SQL, SCSS |
+| Motore di rendering | 1.646 LOC (TS) | 22.000 LOC (Rust/Skia WASM) |
+| Codice UI | ~4.500 LOC | ~175.000 LOC (CLJS + SCSS) |
+| Backend | Nessuno (local-first) | 32.600 LOC + 151 file SQL |
+| Rapporto LOC | **1×** | **~11×** |
+
+Open Pencil è **~11× più piccolo** — e questo è il punto. Non è una semplificazione; è un'architettura fondamentalmente diversa.
+
+## 2. Architettura
+
+### Open Pencil: Client monolitico
+
+```
+┌─────────────────────────────────┐
+│ Tauri (shell nativo) │
+│ ┌───────────────────────────┐ │
+│ │ Vue 3 + TypeScript │ │
+│ │ ┌─────────┐ ┌──────────┐│ │
+│ │ │ Editor │ │ Kiwi ││ │
+│ │ │ Store │ │ Codec ││ │
+│ │ └────┬─────┘ └──────────┘│ │
+│ │ │ │ │
+│ │ ┌────▼────────────────┐ │ │
+│ │ │ Scene Graph (TS) │ │ │
+│ │ │ Map │ │ │
+│ │ └────┬────────────────┘ │ │
+│ │ │ │ │
+│ │ ┌────▼────┐ ┌──────────┐│ │
+│ │ │ Skia │ │ Yoga ││ │
+│ │ │CanvasKit│ │ Layout ││ │
+│ │ │ (WASM) │ │ (WASM) ││ │
+│ │ └─────────┘ └──────────┘│ │
+│ └───────────────────────────┘ │
+└─────────────────────────────────┘
+```
+
+**Tutto in un unico processo.** Nessun server, nessun database, nessun Docker.
+
+### Penpot: Client-server distribuito
+
+```
+┌───────────────────────────────────────────────────────┐
+│ Docker Compose │
+│ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐ │
+│ │ Frontend │ │ Backend │ │ Exporter │ │
+│ │ ClojureScript│ │ Clojure │ │ (Chromium) │ │
+│ │ shadow-cljs │ │ JVM │ │ │ │
+│ │ ┌─────────┐ │ │ ┌────────┐ │ └──────────────┘ │
+│ │ │render- │ │ │ │Postgres│ │ │
+│ │ │wasm │ │ │ │Valkey │ │ ┌──────────────┐ │
+│ │ │(Rust→ │ │ │ │ MinIO │ │ │ MCP │ │
+│ │ │ Skia │ │ │ └────────┘ │ │ Server │ │
+│ │ │ WASM) │ │ │ │ └──────────────┘ │
+│ │ └─────────┘ │ │ │ │
+│ └──────────────┘ └─────────────┘ │
+└───────────────────────────────────────────────────────┘
+```
+
+**Minimo 5+ servizi.** PostgreSQL, Redis (Valkey), MinIO, backend JVM, esportatore Node.js (Chromium headless), più il frontend ClojureScript.
+
+### Verdetto: Architettura
+
+L'architettura monoprocesso di Open Pencil elimina: latenza di rete, overhead di serializzazione, complessità di orchestrazione container e overhead di query database.
+
+## 3. Pipeline di rendering
+
+### Open Pencil: TS → CanvasKit WASM (diretto)
+
+```typescript
+renderSceneToCanvas(canvas, graph, pageId) {
+ this.fillPaint.setColor(...)
+ canvas.drawRRect(rrect, this.fillPaint)
+}
+```
+
+- **1 attraversamento:** TS → WASM (CanvasKit)
+- 1.646 LOC di renderer totale
+
+### Penpot: JS (compilato da CLJS) → Rust WASM → Skia
+
+```
+ClojureScript (compilato in JS)
+ → scomporre in primitive + impacchettare in binario nella memoria lineare WASM
+ → Rust WASM (via Emscripten C FFI)
+ → skia-safe (binding Rust Skia)
+ → Skia (WebGL)
+```
+
+Quando disabilitato (default), rendering come albero DOM SVG. Quando abilitato, sistema di rendering a tile con 11 superfici.
+
+### Verdetto: Rendering
+
+| Aspetto | Open Pencil | Penpot |
+|---------|-------------|--------|
+| Confine JS→WASM | Diretto (oggetti TS) | Impacchettamento binario (104 byte per forma) |
+| Modello di rendering | Immediato/ridisegno completo | Cache a tile |
+| Gestione superfici | 1 superficie | 11 superfici |
+| Overhead memoria | Basso | Alto (1024 voci cache) |
+| Complessità codice | 1.646 LOC | 22.000 LOC |
+| Codice unsafe | Nessuno | Stato globale `unsafe` |
+
+## 4. Grafo della scena e modello dati
+
+### Open Pencil
+
+```typescript
+nodes: Map
+// 29 tipi di nodo dallo schema Kiwi di Figma
+// ~390 campi per NodeChange (compatibile Figma)
+```
+
+### Penpot
+
+- Dati distribuiti in `common/` (49.600 LOC di .cljc)
+- Validazione schema a runtime (Malli)
+
+### Verdetto: Modello dati
+
+Open Pencil riutilizza lo schema provato di Figma (194 definizioni Kiwi) direttamente in TypeScript. Penpot mantiene un proprio sistema di tipi attraverso tre linguaggi.
+
+## 5. Motore di layout
+
+### Open Pencil: Yoga WASM (314 LOC)
+
+```typescript
+import Yoga from 'yoga-layout'
+const root = Yoga.Node.create()
+root.setFlexDirection(FlexDirection.Row)
+root.calculateLayout()
+```
+
+314 righe. Sincrono, in-process.
+
+### Penpot: Doppia implementazione
+
+Penpot mantiene **due motori di layout indipendenti** (CLJS e Rust) che devono produrre risultati identici. ~3.000+ LOC duplicati.
+
+## 6. Formato file e compatibilità Figma
+
+### Open Pencil
+
+- **Formato binario Kiwi nativo** — stessa serializzazione di Figma
+- Import diretto `.fig`, incolla dagli appunti di Figma
+- Compatibile con il protocollo multiplayer di Figma
+
+### Penpot
+
+- **Archivio ZIP** (`.penpot`) con manifesti JSON e asset binari
+- Nessun import nativo `.fig`
+
+### Verdetto: Formato file
+
+Open Pencil ha un vantaggio significativo — può leggere file Figma nativamente e incollare dati dagli appunti di Figma.
+
+## 7. Gestione stato e annullamento
+
+### Open Pencil
+
+```typescript
+// 110 LOC — pattern di comando inverso
+class UndoManager {
+ apply(entry) { entry.forward(); this.undoStack.push(entry) }
+ undo() { entry.inverse(); this.redoStack.push(entry) }
+}
+```
+
+### Penpot
+
+Gestione stato via Potok. Undo con vettori di cambiamenti inversi (max 50 voci), auto-scadenza dopo 20 secondi.
+
+## 8. Esperienza sviluppatore
+
+| Metrica | Open Pencil | Penpot |
+|---------|-------------|--------|
+| Setup dev | `bun install && bun dev` | Docker Compose + JVM + Node + Rust |
+| Hot reload | Vite HMR (~50ms) | shadow-cljs (secondi) |
+| Type checking | TypeScript (strict) | Runtime (schemi Malli) |
+| Tempo build | <5s (Vite) | Minuti (JVM + CLJS + Rust WASM) |
+| Barriera prima contribuzione | Bassa (TS/Vue) | Alta (Clojure + Rust + Docker) |
+| Desktop | Tauri v2 (~5MB) | N/A (solo browser) |
+
+## 9. Caratteristiche di prestazione
+
+| Scenario | Open Pencil | Penpot |
+|----------|-------------|--------|
+| Avvio a freddo | <2s (caricamento WASM) | 10s+ (server + client + WASM) |
+| Latenza operazione | <1ms (in-process) | 10-50ms (round-trip rete) |
+| Frame di render | Chiamata Skia diretta | CLJS→JS→WASM FFI→Skia |
+| Memoria base | ~50MB (tab browser) | ~300MB+ (JVM + Postgres + Valkey + browser) |
+| Capacità offline | Completa (local-first) | Nessuna (dipende dal server) |
+
+## 10. Cosa fa meglio Penpot
+
+1. **Collaborazione server** — editing multi-utente centralizzato con WebSockets, account e controllo accessi
+2. **Export server** — servizio export Chromium headless
+3. **Sistema plugin** — API completa con esecuzione sandboxed
+4. **Token di design** — supporto nativo design token
+5. **CSS Grid layout** — implementazione propria (Open Pencil attende Yoga Grid)
+6. **Self-hosting** — deployment Docker per team
+7. **Maturità** — anni di uso in produzione
+
+## 11. Scripting ed estensibilità
+
+OpenPencil include un [comando `eval`](/eval-command) che fornisce un'API Plugin compatibile Figma per scripting headless. Inoltre, 75 strumenti AI disponibili via chat integrata, server MCP (stdio + HTTP) e CLI. Penpot ha un sistema plugin con esecuzione sandboxed ma senza API di scripting headless né integrazione MCP.
+
+## Riepilogo
+
+| Dimensione | Vincitore | Perché |
+|-----------|---------|--------|
+| **Semplicità architetturale** | Open Pencil | Un processo vs 5+ servizi |
+| **Prestazioni di rendering** | Open Pencil | CanvasKit diretto vs SVG DOM (default) o WASM impacchettato |
+| **Manutenibilità codice** | Open Pencil | ~26K LOC in 1 linguaggio vs 299K in 4+ |
+| **Compatibilità Figma** | Open Pencil | Codec Kiwi nativo vs nessun supporto .fig |
+| **Onboarding sviluppatori** | Open Pencil | TS/Vue vs Clojure/Rust/Docker |
+| **Esperienza desktop** | Open Pencil | Tauri nativo vs solo browser |
+| **Motore di layout** | Open Pencil | Yoga (provato) vs doppia implementazione |
+| **Collaborazione** | Pareggio | Penpot: server con controllo accessi; Open Pencil: P2P via Trystero + Yjs |
+| **Self-hosting** | Penpot | Docker-ready vs solo desktop |
+| **Maturità ecosistema** | Penpot | Anni di produzione vs stadio iniziale |
+
+Open Pencil è architetturalmente più snello — un renderer CanvasKit monoprocesso in ~26K LOC TypeScript, compatibile Figma per design. Penpot è una piattaforma full-stack con ~299K LOC. Open Pencil ha scripting headless, 75 strumenti AI/MCP e app desktop nativa.
diff --git a/packages/docs/it/guide/features.md b/packages/docs/it/guide/features.md
index a1e435627..267c1a436 100644
--- a/packages/docs/it/guide/features.md
+++ b/packages/docs/it/guide/features.md
@@ -2,39 +2,41 @@
## Perché OpenPencil
-I tool di design sono un problema di catena di fornitura. Quando il tuo strumento è proprietario, il fornitore controlla cosa è possibile. OpenPencil è un'alternativa open-source: licenza MIT, compatibile con Figma, completamente locale e programmabile.
+Gli strumenti di design sono un problema di catena di fornitura. Quando il tuo strumento è proprietario, il fornitore controlla ciò che è possibile. OpenPencil è un'alternativa open-source: licenza MIT, compatibile con Figma, completamente locale e programmabile.
## Import & export file .fig di Figma
-Apri e salva file nativi di Figma direttamente. L'import decodifica lo schema completo Kiwi a 194 definizioni. L'export codifica il grafo della scena in formato binario Kiwi con compressione Zstd e generazione thumbnail.
+Apri e salva file nativi Figma direttamente. L'import decodifica lo schema Kiwi completo a 194 definizioni inclusi i messaggi NodeChange con ~390 campi. L'export codifica il grafo della scena in binario Kiwi con compressione Zstd e generazione thumbnail. Salva (⌘S) e Salva con nome (⇧⌘S) usano dialoghi nativi dell'OS.
## Copia e incolla con Figma
-Seleziona nodi in Figma, ⌘C, passa a OpenPencil, ⌘V — appaiono con riempimenti, contorni, auto-layout, testo, raggi degli angoli, effetti e reti vettoriali. Funziona anche al contrario.
+Seleziona nodi in Figma, ⌘C, passa a OpenPencil, ⌘V — appaiono con riempimenti, contorni, auto-layout, testo, raggi degli angoli, effetti e reti vettoriali preservati. Funziona anche al contrario.
+
+L'incolla gestisce scenari complessi: i percorsi vettoriali vengono ridimensionati dalla `normalizedSize` di Figma, i figli delle istanze vengono popolati dal `symbolData` del componente, i set di componenti vengono rilevati e i `symbolOverrides` vengono applicati. I font vengono caricati automaticamente.
## Reti vettoriali
-Lo strumento penna usa il modello di rete vettoriale di Figma. Click per punti angolari, click+trascinamento per curve di Bézier.
+Lo strumento penna usa il modello di rete vettoriale di Figma — non percorsi semplici. Click per punti angolari, click+trascinamento per curve di Bézier. Percorsi aperti e chiusi supportati.
## Strumenti forma
-Rettangolo (R), Ellisse (O), Linea (L), Poligono e Stella. Tutti supportano riempimento, contorno ed effetti.
+La barra strumenti fornisce tutti gli strumenti forma base di Figma: Rettangolo (R), Ellisse (O), Linea (L), Poligono e Stella. Tutti supportano riempimento, contorno, evidenziazione al passaggio e contorno di selezione.
-## Auto-layout
+## Auto-Layout
-Yoga WASM fornisce il layout CSS flexbox. Direzione, gap, padding, allineamento e dimensionamento figli. Shift+A attiva/disattiva l'auto-layout.
+Yoga WASM fornisce il layout CSS flexbox. I frame supportano: direzione, gap, padding, justify, align e dimensionamento figli. Shift+A attiva/disattiva l'auto-layout.
## Modifica testo inline
-Modifica testo nativa nel canvas. Doppio click su un nodo testo per entrare in modalità modifica. Selettore font con scroll virtuale e ricerca.
+Modifica testo nativa nel canvas. Doppio click su un nodo testo per entrare in modalità modifica. **Selettore font** con scroll virtuale, filtro di ricerca e anteprima CSS. In Tauri, i font di sistema sono enumerati via il crate Rust `font-kit`.
-## Formattazione rich text
+## Formattazione testo ricco
-Formattazione per carattere: ⌘B grassetto, ⌘I corsivo, ⌘U sottolineato. Preservata nell'import/export .fig.
+Formattazione per carattere: ⌘B grassetto, ⌘I corsivo, ⌘U sottolineato, o pulsanti B/I/U/S. Implementato via modello StyleRun. Preservato nell'import/export .fig.
## Annulla/Ripristina
-Ogni operazione è annullabile. Pattern inverse-command. ⌘Z annulla, ⇧⌘Z ripristina.
+Ogni operazione è annullabile. Pattern di comando inverso. ⌘Z annulla, ⇧⌘Z ripristina.
## Guide di snap
@@ -42,52 +44,120 @@ Snap ai bordi e al centro con linee guida rosse. Consapevole della rotazione.
## Righelli canvas
-Righelli in alto e a sinistra mostrano le scale delle coordinate.
+Righelli in alto e a sinistra mostrano scale di coordinate con badge di coordinate alla selezione.
## Selettore colore e tipi di riempimento
-Selezione HSV con cursore tonalità, cursore alfa, input hex. Tipi: colore solido, gradiente, immagine.
+Selezione HSV con slider di tonalità, slider alfa, input hex e controllo opacità. Tipi: Solido, Gradiente (Lineare, Radiale, Angolare, Diamante) e Immagine.
## Pannello livelli
-Vista ad albero della gerarchia del documento. Espandi/comprimi, trascina per riordinare, attiva/disattiva visibilità.
+Vista ad albero della gerarchia del documento. Pannelli ridimensionabili.
## Pannello proprietà
-Tab **Design** | **Codice** | **IA**. Design mostra sezioni contestuali.
+Interfaccia a tab **Design** | **Codice** | **IA**. Il tab Design mostra sezioni contestuali: Aspetto, Riempimento, Contorno, Effetti, Tipografia, Layout, Posizione, Esportazione e Pagina.
+
+## Raggruppa/Separa
+
+⌘G raggruppa. ⇧⌘G separa. I nodi vengono ordinati per posizione visiva.
+
+## Sezioni
+
+Le sezioni (S) sono contenitori organizzativi di livello superiore sul canvas con pillole di titolo e inversione automatica del colore del testo.
+
+## Documenti multi-pagina
+
+I documenti supportano più pagine. Ogni pagina mantiene uno stato viewport indipendente.
+
+## Evidenziazione al passaggio
+
+I nodi si evidenziano con un contorno che segue la geometria reale.
+
+## Rendering avanzato (Tier 1)
+
+Il renderer CanvasKit supporta le caratteristiche visive Tier 1 complete: riempimenti gradiente, riempimenti immagine, effetti, proprietà contorno, dati arco, culling viewport, riuso Paint e coalescenza RAF.
## Componenti e istanze
-Componenti riutilizzabili con sincronizzazione live, override e set di componenti.
+Componenti riutilizzabili (⌥⌘K), set (⇧⌘K), istanze via menu contestuale, stacca (⌥⌘B). **Sync in tempo reale** e **supporto override**. Etichette viola con icona diamante.
## Variabili
-Token di design come variabili con collezioni e modalità. Supporto colore, float, stringa, booleano.
+Token di design con collezioni e modalità. Dialogo TanStack Table. Supporta COLOR con UI completa, FLOAT/STRING/BOOLEAN definiti. Tutte le operazioni sono annullabili.
-## Export immagini
+## Esportazione immagini
-PNG, JPG, WEBP con scala da 0,5× a 4× e anteprima live.
+PNG, JPG, WEBP con scala 0,5×–4×, anteprima live e ⇧⌘E.
## Menu contestuale
-Click destro per azioni su appunti, ordine Z, raggruppamento, componenti e visibilità.
+Click destro per: Appunti, Ordine Z, Raggruppamento, Componenti (voci viola), Visibilità, Sposta a pagina.
+
+## Ordine Z, visibilità e blocco
+
+] porta in primo piano, [ invia in fondo. ⇧⌘H visibilità. ⇧⌘L blocco.
## App web e desktop
-Browser su [app.openpencil.dev](https://app.openpencil.dev). Desktop con Tauri v2 (~5 MB).
+OpenPencil funziona nel browser su [app.openpencil.dev](https://app.openpencil.dev). L'app desktop usa Tauri v2 (~5 MB). Funziona completamente offline.
## Menu app (browser)
-Barra dei menu con reka-ui: File, Modifica, Visualizza, Oggetto, Testo, Disponi.
+Barra dei menu con reka-ui: **File**, **Modifica**, **Visualizza**, **Oggetto**, **Testo**, **Disponi**. Scorciatoie adattate alla piattaforma. Nascosto in Tauri.
## Salvataggio automatico
-File salvati automaticamente 3 secondi dopo l'ultima modifica.
+File salvati 3 secondi dopo l'ultima modifica. Debounce su `sceneVersion`. Disabilitato per documenti nuovi senza titolo.
-## Chat IA
+## Collaborazione P2P
-Assistente IA integrato con 29 strumenti. Server MCP per strumenti di coding IA esterni.
+Collaborazione peer-to-peer in tempo reale — nessun server richiesto. Basato su Trystero (WebRTC) + Yjs (CRDT).
+
+- **Zero costi di hosting** — segnalazione via broker MQTT pubblici
+- **Traversal NAT** — server Google STUN, Cloudflare STUN e Open Relay TURN
+- **Cursori in tempo reale** — frecce colorate stile Figma con pillole di nome
+- **Presenza** — avatar colorati
+- **Modalità segui** — clicca sull'avatar di un peer per seguire il suo viewport
+- **Persistenza locale** — y-indexeddb mantiene la stanza tra i ricaricamenti
+- **Stanze sicure** — ID via `crypto.getRandomValues()`
+
+## Schede multi-file
+
+Apri più documenti in schede. ⌘N/⌘T nuova scheda, ⌘W chiudi, ⌘O apri in nuova scheda. Ogni scheda mantiene il proprio stato documento.
+
+## Rendering effetti
+
+Rendering completo degli effetti Figma: **Ombra portata**, **Ombra interna**, **Sfocatura livello** (Gaussiana), **Sfocatura sfondo** (effetto vetro/satinato), **Sfocatura primo piano**. Cache SkPicture per nodo per le prestazioni.
+
+## Proprietà multi-selezione
+
+Seleziona più nodi e modifica le proprietà condivise. Valori comuni visualizzati normalmente, valori diversi mostrano "Mixed". Capovolgi H/V si applica a tutti i nodi.
+
+## ScrubInput
+
+Tutte le entrate numeriche usano interazione trascina-per-regolare. Supporta suffissi (°, px, %).
+
+## Build CI/CD
+
+GitHub Actions costruisce app Tauri sui tag di versione. macOS firmato e notarizzato. Note di release auto-popolate dal CHANGELOG.md.
## @open-pencil/core e CLI
-CLI headless: info, tree, find, export, analyze, eval. Tutti i comandi supportano `--json`.
+Il motore è estratto in `packages/core/`. Il CLI fornisce: info, tree, find, export, analyze, node, pages, variables, eval. Tutti supportano `--json`. Il comando `eval` esegue JavaScript con API Plugin Figma. Vedi [Comando Eval](/eval-command).
+
+## Renderer JSX
+
+Creazione programmabile via TreeNode builder. Props shorthand stile Tailwind.
+
+## Chat IA
+
+Assistente IA integrato via ⌘J. **75 strumenti** in `schema.ts` che coprono lettura, creazione, modifica, manipolazione nodi, CRUD variabili, strumenti vettoriali, controllo viewport e `eval`. **Server MCP** espone 78 strumenti totali (75 core + 3 gestione file) per strumenti di codifica IA esterni.
+
+## Pannello codice
+
+Il tab Codice mostra il JSX della selezione con evidenziazione sintassi Prism.js e copia.
+
+## Qualità del codice
+
+Rilevamento copia-incolla via jscpd — duplicazione ridotta dal 15,6% allo 0,62%. Pipeline di importazione ottimizzato da O(n²) a O(n).
diff --git a/packages/docs/it/guide/figma-comparison.md b/packages/docs/it/guide/figma-comparison.md
index dbf7a5fcd..6a376cb54 100644
--- a/packages/docs/it/guide/figma-comparison.md
+++ b/packages/docs/it/guide/figma-comparison.md
@@ -1,9 +1,226 @@
# Matrice funzionalità Figma
-**Coverage:** 87 / 152 — 69 ✅, 18 🟡, 65 🔲. (2026-03-03)
+Confronto funzionalità per funzionalità delle capacità di Figma Design con lo stato di implementazione attuale di Open Pencil.
-✅ = Full | 🟡 = Partial | 🔲 = Not yet
+::: tip Legenda stati
+✅ Supportato — la funzionalità è completa · 🟡 Parziale — il comportamento di base esiste, mancano alcune sotto-funzionalità · 🔲 Non ancora implementato
+:::
-[Full feature matrix in English](/guide/figma-comparison)
+**Copertura:** 88 dei 152 elementi Figma affrontati — 70 ✅ completamente supportati, 18 🟡 parziali, 64 🔲 in sospeso. Ultimo aggiornamento: 2026-03-04.
-[Features](/it/guide/features) · [Comparison](/it/guide/comparison)
+## Interfaccia e navigazione
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Barra strumenti di design | ✅ | Barra inferiore (stile UI3): Selezione, Frame, Sezione, Rettangolo, Ellisse, Linea, Testo, Mano, Penna |
+| Pannello livelli (barra laterale sinistra) | ✅ | Vista ad albero con espansione/compressione, riordinamento per trascinamento, toggle visibilità; larghezza ridimensionabile |
+| Pannello pagine | ✅ | Aggiungere, eliminare, rinominare pagine; stato viewport per pagina |
+| Pannello proprietà (barra laterale destra) | ✅ | Sezioni: Aspetto, Riempimento, Contorno, Effetti, Tipografia, Layout, Posizione; larghezza ridimensionabile |
+| Zoom e panoramica | ✅ | Ctrl+scroll, pinch, ⌘+/⌘−/⌘0, spazio+trascinamento, mouse centrale, strumento mano (H) |
+| Righelli canvas | ✅ | Righelli superiore/sinistro con bande di selezione e badge di coordinate |
+| Colore di sfondo del canvas | ✅ | Sfondo per pagina tramite pannello proprietà |
+| Guide del canvas | 🔲 | Figma supporta guide trascinabili dai righelli |
+| Menu azioni / palette comandi | 🔲 | Ricerca azioni rapide di Figma |
+| Menu contestuale | ✅ | Clic destro con appunti, ordine-z, raggruppamento, componente, visibilità, blocco, sposta-a-pagina |
+| Scorciatoie tastiera | 🟡 | Scorciatoie base + componenti + ordine-z + visibilità/blocco implementate; Scala, Freccia, Matita, ribaltamento, formattazione testo non ancora collegati |
+| Cerca e sostituisci | 🔲 | Ricerca/sostituzione testo nel documento |
+| Vista contorni livelli | 🔲 | Vista wireframe di tutti i livelli |
+| Miniature personalizzate | 🔲 | Miniatura generata all'export, ma nessun selettore personalizzato |
+| Impostazioni valore nudge | 🔲 | Default 1px/10px; Figma consente valori personalizzati |
+| Menu app (modalità browser) | ✅ | Menu File, Modifica, Visualizza, Oggetto, Testo, Disponi; Tauri usa menu nativi |
+| Strumenti IA | 🟡 | 75 strumenti via OpenRouter + server MCP; nessuna immagine generata da IA o ricerca IA ancora |
+
+## Livelli e forme
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Strumenti forma (Rettangolo, Ellisse, Linea, Poligono, Stella) | ✅ | Tutti i tipi di forma base; lati poligono e raggio interno stella configurabili |
+| Frame | ✅ | Ritaglio contenuto, sistema di coordinate indipendente |
+| Gruppi | ✅ | ⌘G per raggruppare, ⇧⌘G per separare |
+| Sezioni | ✅ | Pillole titolo, auto-adozione nodi sovrapposti, testo adattivo alla luminanza |
+| Strumento arco (archi, semicerchi, anelli) | ✅ | arcData con angolo inizio/fine e raggio interno |
+| Strumento matita (mano libera) | 🔲 | Strumento di disegno a mano libera di Figma |
+| Maschere | 🔲 | Maschere di forma per ritagliare livelli |
+| Tipi di livello e gerarchia | ✅ | 17 tipi di nodo, Map piatta + albero genitore-figlio |
+| Selezionare livelli | ✅ | Clic, shift-clic, selezione a marquee |
+| Allineamento e posizione | ✅ | Posizione, rotazione, dimensioni nel pannello |
+| Copiare e incollare oggetti | ✅ | Appunti standard + formato binario Kiwi di Figma |
+| Scalare livelli proporzionalmente | 🟡 | Shift-ridimensiona mantiene proporzioni; nessuno strumento Scale dedicato (K) |
+| Bloccare e sbloccare livelli | ✅ | ⇧⌘L alterna blocco |
+| Toggle visibilità livello | ✅ | Icona occhio nel pannello + scorciatoia ⇧⌘H |
+| Rinominare livelli | 🟡 | Rinomina programmata via store; nessuna UI inline ancora |
+| Porta in primo piano / Invia in fondo | ✅ | Scorciatoie ] e [; anche nel menu contestuale |
+| Sposta a pagina | ✅ | Spostare nodi tra pagine tramite menu contestuale |
+| Vincoli (ridimensionamento responsivo) | 🔲 | Fissare bordi/centro per comportamento resize genitore |
+| Selezione intelligente (distribuire/allineare) | 🔲 | Spaziare e allineare uniformemente |
+| Guide di layout (colonne, righe, griglia) | 🔲 | Guide colonna/riga/griglia sui frame |
+| Misurare distanze tra livelli | 🔲 | Alt-hover per mostrare distanze |
+| Modificare oggetti in blocco | ✅ | Pannello multi-selezione: valori condivisi normali, valori diversi mostrano "Mixed" |
+| Identificare oggetti corrispondenti | 🔲 | Trovare livelli simili |
+| Copiare/incollare proprietà | 🔲 | Copiare riempimento/contorno/effetti tra livelli |
+| Relazioni genitore-figlio | ✅ | Gerarchia completa con parentIndex, ri-parentamento per trascinamento |
+
+## Strumenti vettoriali
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Reti vettoriali | ✅ | Modello compatibile Figma, non percorsi semplici |
+| Strumento penna | ✅ | Punti angolari, curve di Bézier, percorsi aperti/chiusi |
+| Modificare livelli vettoriali | 🟡 | Creazione funziona; modifica avanzata vertici limitata |
+| Operazioni booleane (Unione, Sottrazione, Intersezione, Esclusione) | 🔲 | Combinare forme con operazioni booleane |
+| Appiattire livelli | 🔲 | Unire percorsi vettoriali |
+| Convertire contorni in percorsi | 🔲 | Comando Outline Stroke |
+| Convertire testo in percorsi | 🔲 | Appiattire testo in contorni vettoriali |
+| Strumento shape builder | 🔲 | Strumento booleano interattivo |
+| Offset percorso | 🔲 | Inset/outset di un percorso vettoriale |
+| Semplificare percorso | 🔲 | Ridurre numero punti vettoriali |
+
+## Testo e tipografia
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Strumento testo e modifica inline | ✅ | Modifica nativa sul canvas, textarea phantom, style run (⌘B/I/U, pulsante S) |
+| Rendering testo (Paragraph API) | ✅ | CanvasKit Paragraph per shaping, interruzione riga, metriche |
+| Caricamento font (font di sistema) | ✅ | Inter default, font-kit in Tauri con cache OnceLock, queryLocalFonts nel browser |
+| Famiglia e peso font | ✅ | FontPicker con scroll virtuale, ricerca, anteprima CSS |
+| Dimensione font e altezza riga | ✅ | Modificabile nella sezione tipografia |
+| Allineamento testo | 🟡 | Allineamento base; Figma ha allineamento verticale e modi auto-larghezza/altezza |
+| Stili di testo | 🟡 | Grassetto/corsivo/sottolineato/barrato per selezione; nessun preset riutilizzabile ancora |
+| Modi ridimensionamento testo | 🔲 | Modi auto-larghezza, auto-altezza, dimensione-fissa di Figma |
+| Liste puntate e numerate | 🔲 | Formattazione liste nel testo |
+| Link nel testo | 🔲 | Iperlink nel contenuto testo |
+| Emoji e simboli intelligenti | 🔲 | Rendering emoji e caratteri speciali |
+| Funzionalità OpenType | 🔲 | Legature, alternative stilistiche, cifre tabulari |
+| Font variabili | 🔲 | Assi font regolabili (peso, larghezza, inclinazione) |
+| Supporto testo CJK | 🔲 | Rendering testo cinese, giapponese, coreano |
+| Supporto testo RTL | 🔲 | Layout testo da destra a sinistra |
+| Font icone | 🔲 | Gestione speciale per glifi font icone |
+
+## Colore, gradienti e immagini
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Selettore colore (HSV) | ✅ | Quadrato HSV, slider tonalità, slider alfa, input hex |
+| Riempimenti solidi | ✅ | Colore hex con opacità |
+| Gradiente lineare | ✅ | Stop gradiente, maniglie di trasformazione |
+| Gradiente radiale | ✅ | Rendering via shader CanvasKit |
+| Gradiente angolare | ✅ | Supporto gradiente sweep/conico |
+| Gradiente diamante | ✅ | Gradiente diamante a quattro punti |
+| Riempimenti immagine | ✅ | Decodificati da dati blob con modi scala (fill, fit, crop, tile) |
+| Riempimenti pattern | 🔲 | Riempimenti immagine/pattern ripetitivi |
+| Modi fusione | 🔲 | Modi fusione livello e riempimento (multiply, screen, overlay, ecc.) |
+| Aggiungere immagini e video | 🟡 | Riempimenti immagine renderizzati; nessun import drag-and-drop né supporto video |
+| Regolazione proprietà immagine | 🔲 | Esposizione, contrasto, saturazione, ecc. |
+| Ritagliare un'immagine | 🔲 | Ritaglio interattivo immagini |
+| Strumento contagocce | 🔲 | Campionare colori dal canvas |
+| Modifica colore in selezione mista | 🔲 | Regolare colori in selezione eterogenea |
+| Modelli colore (RGB, HSL, HSB, Hex) | 🟡 | HSV + Hex nel selettore; nessun toggle modo HSL o RGB |
+
+## Effetti e proprietà
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Ombra portata | ✅ | Offset, raggio sfocatura, colore via filtri CanvasKit |
+| Ombra interna | ✅ | Effetto ombra inset |
+| Sfocatura livello | ✅ | Sfocatura gaussiana sul livello |
+| Sfocatura sfondo | ✅ | Sfocare contenuto dietro il livello |
+| Sfocatura primo piano | ✅ | Sfocatura in primo piano |
+| Spessore contorno | ✅ | Configurabile nel pannello proprietà |
+| Estremità contorno (round, square, arrow) | ✅ | NONE, ROUND, SQUARE, ARROW_LINES, ARROW_EQUILATERAL |
+| Giunzione contorno (miter, bevel, round) | ✅ | Tutti e tre i tipi di giunzione |
+| Pattern tratteggio | ✅ | Pattern contorno dash-on/dash-off |
+| Raggio angolo | ✅ | Raggio uniforme e per angolo con toggle indipendente |
+| Smussatura angolo (stile iOS) | 🔲 | Arrotondamento continuo degli angoli di Figma |
+| Riempimenti/contorni multipli per livello | 🔲 | Figma consente di impilare riempimenti e contorni |
+
+## Auto Layout
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Flusso orizzontale e verticale | ✅ | Motore flexbox Yoga WASM |
+| Toggle auto layout (⇧A) | ✅ | Toggle su frame o avvolgi selezione |
+| Gap (spaziatura tra figli) | ✅ | Configurabile nel pannello proprietà |
+| Padding (uniforme e per lato) | ✅ | Tutti e quattro i lati indipendentemente |
+| Justify content | ✅ | Start, center, end, space-between |
+| Align items | ✅ | Start, center, end, stretch |
+| Dimensionamento figli (fisso, riempimento, adatta) | ✅ | Modi dimensionamento per figlio |
+| Wrap | ✅ | Flex wrap per layout multi-riga |
+| Flusso auto layout griglia | 🔲 | Auto layout basato su griglia di Figma |
+| Flussi combinati (annidati) | ✅ | Frame auto-layout annidati con direzioni diverse |
+| Riordinare trascinando in auto layout | ✅ | Indicatore visivo di inserimento |
+| Larghezza/altezza min e max | 🔲 | Figma supporta vincoli min/max |
+
+## Componenti e sistemi di design
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Creare componenti | 🟡 | ⌥⌘K crea da frame/gruppo; nessuna UI proprietà componente ancora |
+| Set di componenti | 🟡 | ⇧⌘K combina componenti; bordo tratteggiato viola; nessuna modifica proprietà variante |
+| Istanze di componenti | 🟡 | Creare istanza dal menu contestuale; sync in tempo reale; nessuna UI modifica override |
+| Varianti | 🔲 | Cambio variante e selezione per proprietà |
+| Proprietà componente | 🔲 | Proprietà booleane, testo, scambio istanza |
+| Propagazione override | ✅ | Modifiche al componente principale propagate; override preservati |
+| Variabili (colore, numero, stringa, booleano) | 🟡 | COLOR con UI completa; FLOAT/STRING/BOOLEAN definiti senza UI di modifica |
+| Collezioni e modi variabili | 🟡 | Collezioni, modi, cambio activeMode funzionano; nessuna UI tematizzazione |
+| Stili (colore, testo, effetto, layout) | 🔲 | Preset stile riutilizzabili nominati |
+| Librerie (pubblicare, condividere, aggiornare) | 🔲 | Librerie condivise componenti/stili |
+| Staccare istanza | ✅ | ⌥⌘B converte istanza in frame |
+| Vai al componente principale | ✅ | Navigare al componente sorgente, cross-page |
+
+## Prototipazione
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Connessioni prototipo | 🔲 | Pianificato per Fase 6 |
+| Trigger (clic, hover, trascinamento, ecc.) | 🔲 | Pianificato per Fase 6 |
+| Azioni (navigare, overlay, scroll, ecc.) | 🔲 | Pianificato per Fase 6 |
+| Animazioni e transizioni | 🔲 | Pianificato per Fase 6 |
+| Smart animate | 🔲 | Auto-animare livelli corrispondenti |
+| Overlay | 🔲 | Prototipazione modale/popover |
+| Comportamento scroll e overflow | 🔲 | Frame scrollabili nei prototipi |
+| Flussi prototipo | 🔲 | Punti di partenza nominati |
+| Variabili nei prototipi | 🔲 | Logica condizionale con variabili |
+| Easing e animazioni spring | 🔲 | Curve di animazione personalizzate |
+| Presentare e riprodurre prototipi | 🔲 | Visualizzatore prototipo a schermo intero |
+
+## Import e export
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Import file .fig | ✅ | Codec Kiwi completo: 194 definizioni, ~390 campi per NodeChange |
+| Export file .fig | ✅ | Codifica Kiwi + compressione Zstd + generazione miniatura |
+| Salva / Salva con nome | ✅ | ⌘S / ⇧⌘S; dialoghi nativi (Tauri), File System Access API (Chrome/Edge), download fallback (Safari) |
+| Appunti Figma (incolla) | ✅ | Decodificare binario Kiwi dagli appunti Figma |
+| Appunti Figma (copia) | ✅ | Codificare binario Kiwi leggibile da Figma |
+| Import file Sketch | 🔲 | Parsing file .sketch |
+| Export immagine/SVG | 🟡 | PNG/JPG/WEBP con selettore scala e anteprima; SVG/PDF non ancora |
+| Cronologia versioni | 🔲 | Sfogliare e ripristinare versioni precedenti |
+| Copiare asset tra strumenti | 🟡 | Appunti Figma funzionano; nessun appunti SVG/PDF |
+
+## API plugin e scripting
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Comando eval con Figma Plugin API | ✅ | Esecuzione headless JavaScript con oggetto globale figma compatibile |
+
+## Collaborazione e modalità sviluppatore
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Commenti (fissare, thread, risolvere) | 🔲 | Pianificato per Fase 6 |
+| Multiplayer in tempo reale | ✅ | P2P via Trystero + Yjs CRDT, cursori, modalità segui; senza server |
+| Chat al cursore | 🔲 | Bolle chat inline al cursore |
+| Branching e merging | 🔲 | Branch di versione per file di design |
+| Modalità sviluppatore (ispezione) | 🟡 | Tab Codice mostra JSX; nessuna proprietà CSS né spec di handoff |
+| Code Connect | 🔲 | Collegare componenti design al codice |
+| Frammenti di codice | 🟡 | Export JSX con evidenziazione e copia; nessun frammento CSS/Swift/Kotlin |
+| Figma for VS Code | 🔲 | Integrazione plugin editor |
+| Server MCP | ✅ | @open-pencil/mcp con trasporti stdio + HTTP; 75 strumenti core + 3 gestione file |
+| Strumenti CLI | ✅ | CLI headless: info, tree, find, export, analyze, node, pages, variables, eval; server MCP |
+
+## Figma Draw
+
+| Funzionalità | Stato | Note |
+|-------------|-------|------|
+| Strumenti illustrazione | 🔲 | Strumenti di disegno specializzati di Figma Draw |
+| Trasformazioni pattern | 🔲 | Creare pattern ripetitivi con trasformazioni |
diff --git a/packages/docs/it/guide/tech-stack.md b/packages/docs/it/guide/tech-stack.md
index 179a5dfa7..d58fe021e 100644
--- a/packages/docs/it/guide/tech-stack.md
+++ b/packages/docs/it/guide/tech-stack.md
@@ -1,17 +1,63 @@
# Stack tecnologico
-| Layer | Technology | Why |
-|-------|-----------|-----|
-| **Rendering** | Skia CanvasKit WASM | GPU-accelerated, same as Figma |
-| **UI** | Vue 3 + VueUse | Reactive, TypeScript |
-| **Components** | Reka UI | Headless, accessible |
-| **Styling** | Tailwind CSS 4 | Utility-first |
-| **Layout** | Yoga WASM | CSS flexbox (Meta) |
-| **File Format** | Kiwi binary + Zstd | Figma .fig compatible |
-| **Desktop** | Tauri v2 | ~5 MB (vs Electron ~100 MB) |
-| **Build** | Vite 7 | Fast HMR |
-| **Testing** | Playwright + bun:test | E2E + unit |
-| **Linting** | oxlint | Rust-based |
-| **Type Checking** | typescript-go (tsgo) | Native Go |
+## Tecnologie principali
-[Full details in English](/guide/tech-stack)
+| Livello | Tecnologia | Perché |
+|---------|-----------|--------|
+| **Rendering** | Skia CanvasKit WASM | Stesso motore di Figma — prestazioni provate, accelerato GPU, pixel-perfetto |
+| **Framework UI** | Vue 3 + VueUse | API di composizione reattiva, eccellente supporto TypeScript |
+| **Componenti** | Reka UI | Primitivi UI headless e accessibili (tree, slider, ecc.) |
+| **Stile** | Tailwind CSS 4 | Utility-first, iterazione rapida, tema scuro |
+| **Layout** | Yoga WASM | Motore CSS flexbox di Meta, collaudato in React Native |
+| **Formato file** | Kiwi binario + Zstd | Formato proprio di Figma — compatto, parsing veloce, compatibile .fig |
+| **Collaborazione** | Trystero + Yjs | P2P WebRTC via segnalazione MQTT, sync CRDT, persistenza y-indexeddb |
+| **Colore** | culori | Conversioni spazio colore (HSV, RGB, hex) |
+| **IA/MCP** | MCP SDK + Hono | 75 strumenti per il coding IA, trasporti stdio + HTTP |
+| **Desktop** | Tauri v2 | ~5 MB app nativa (vs ~100 MB di Electron), backend Rust |
+| **Build** | Vite 7 | HMR veloce, moduli ES nativi |
+| **Test** | Playwright + bun:test | Regressione visiva (E2E) + test unitari veloci |
+| **Linting** | oxlint | Basato su Rust, ordini di grandezza più veloce di ESLint |
+| **Formattazione** | oxfmt | Formattatore basato su Rust |
+| **Verifica tipi** | typescript-go (tsgo) | Implementazione nativa in Go del type checker TypeScript |
+
+## Dipendenze principali
+
+```json
+{
+ "canvaskit-wasm": "^0.40.0",
+ "vue": "^3.5.29",
+ "yoga-layout": "^3.2.1",
+ "reka-ui": "^2.8.2",
+ "tailwindcss": "^4.2.1",
+ "culori": "^4.0.2",
+ "fzstd": "^0.1.1",
+ "fflate": "^0.8.2",
+ "trystero": "^0.20.0",
+ "yjs": "^13.6.24",
+ "y-indexeddb": "^9.0.12"
+}
+```
+
+## Perché non...
+
+### Perché non il rendering SVG?
+
+SVG è lento per documenti complessi. Ogni nodo è un elemento DOM — 10.000 nodi significano 10.000 elementi DOM con overhead di layout, disegno e composizione. CanvasKit disegna tutto su una singola superficie GPU.
+
+### Perché non Electron (come Figma desktop)?
+
+Tauri v2 usa il webview di sistema (~5 MB) invece di incorporare Chromium (~100 MB). Il backend Rust fornisce prestazioni native per I/O file e integrazione di sistema.
+
+### Perché non React?
+
+Il progetto è migrato da React a Vue 3 nelle fasi iniziali. Il sistema di reattività di Vue e i composables VueUse si sono rivelati più ergonomici.
+
+### Perché non un motore di layout personalizzato?
+
+Yoga è mantenuto da Meta, collaudato su miliardi di dispositivi React Native e implementa la specifica CSS flexbox.
+
+## Tecnologie pianificate
+
+| Tecnologia | Scopo | Fase |
+|-----------|---------|-------|
+| CSS Grid in Yoga | Auto layout basato su griglia | Bloccato da upstream (facebook/yoga#1893) |
diff --git a/packages/docs/it/reference/mcp-tools.md b/packages/docs/it/reference/mcp-tools.md
index 13cb35701..bc246fa42 100644
--- a/packages/docs/it/reference/mcp-tools.md
+++ b/packages/docs/it/reference/mcp-tools.md
@@ -24,7 +24,7 @@ Add to your MCP config (e.g. `~/.claude/settings.json` or `.cursor/mcp.json`):
}
```
-Installazione:O eseguire dal codice sorgente:
+O eseguire dal codice sorgente:
::: code-group
```json [Bun]
@@ -73,7 +73,7 @@ Starts on port 3100 (override with `PORT` env var). Endpoints:
5. **Structure** — `reparent_node`, `group_nodes`, `clone_node`, `delete_node`
6. **Save** — `save_file` to write back to `.fig`
-## Tools (29)
+## Tools (75)
### Document
diff --git a/packages/docs/pl/development/contributing.md b/packages/docs/pl/development/contributing.md
index 43a9b981d..e25b2826c 100644
--- a/packages/docs/pl/development/contributing.md
+++ b/packages/docs/pl/development/contributing.md
@@ -1,41 +1,53 @@
-# Współpraca
+# Współtworzenie
## Struktura projektu
```
packages/
- core/ @open-pencil/core — Engine
- cli/ @open-pencil/cli — Headless CLI
- mcp/ @open-pencil/mcp — MCP server
- docs/ @open-pencil/docs — VitePress
+ core/ @open-pencil/core — silnik (zero zależności DOM)
+ src/ Graf sceny, renderer, layout, kodek, kiwi, typy
+ cli/ @open-pencil/cli — headless CLI do operacji .fig
+ src/commands/ info, tree, find, export, eval, analyze
+ mcp/ @open-pencil/mcp — serwer MCP dla narzędzi AI
+ src/ Transporty stdio + HTTP (Hono), 75 narzędzi
src/
- components/ Vue SFCs
- composables/ Canvas input, shortcuts, rendering
- stores/ Editor state
-desktop/ Tauri v2
+ components/ Vue SFCs (canvas, panele, pasek narzędzi, wybieracz kolorów)
+ properties/ Sekcje panelu właściwości (Wygląd, Wypełnienie, Obrys, itp.)
+ composables/ Wejście canvasu, skróty klawiszowe, hooki renderowania
+ stores/ Stan edytora (reaktywność Vue)
+ engine/ Shimy re-eksportu z @open-pencil/core
+ kiwi/ Shimy re-eksportu z @open-pencil/core
+ types.ts Współdzielone typy (re-eksportowane z core)
+ constants.ts Kolory UI, wartości domyślne, progi
+desktop/ Tauri v2 (Rust + config)
tests/
- e2e/ Playwright
- engine/ bun:test
-openspec/ Specs + changes
+ e2e/ Regresja wizualna Playwright
+ engine/ Testy jednostkowe (bun:test)
+docs/ Strona dokumentacji VitePress
+openspec/
+ specs/ Specyfikacje możliwości (źródło prawdy)
+ changes/ Aktywne i zarchiwizowane zmiany
```
-## Środowisko deweloperskie
+## Konfiguracja deweloperska
```sh
bun install
-bun run dev # Editor: localhost:1420
-bun run docs:dev # Docs: localhost:5173
+bun run dev # Edytor na localhost:1420
+bun run docs:dev # Dokumentacja na localhost:5173
```
## Styl kodu
### Narzędzia
-| Tool | Command | Purpose |
-|------|---------|---------|
-| oxlint | `bun run lint` | Linting |
-| oxfmt | `bun run format` | Formatting |
-| tsgo | `bun run typecheck` | Type checking |
+| Narzędzie | Polecenie | Cel |
+|-----------|-----------|-----|
+| oxlint | `bun run lint` | Linting (oparty na Rust, szybki) |
+| oxfmt | `bun run format` | Formatowanie kodu |
+| tsgo | `bun run typecheck` | Sprawdzanie typów (checker TypeScript oparty na Go) |
+
+Uruchom wszystkie sprawdzenia:
```sh
bun run check
@@ -43,23 +55,45 @@ bun run check
### Konwencje
-- kebab-case (files), PascalCase (components/types), camelCase (functions), SCREAMING_SNAKE_CASE (constants)
-- AGENTS.md — [GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)
+- **Nazwy plików** — kebab-case (`scene-graph.ts`, `use-canvas-input.ts`)
+- **Komponenty** — PascalCase Vue SFCs (`EditorCanvas.vue`, `ScrubInput.vue`)
+- **Stałe** — SCREAMING_SNAKE_CASE
+- **Funkcje/zmienne** — camelCase
+- **Typy/interfejsy** — PascalCase
+
+### Konwencje dla agentów AI
+
+Deweloperzy i agenci AI powinni przeczytać `AGENTS.md` w katalogu głównym repo ([zobacz na GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)). Obejmuje renderowanie, graf sceny, komponenty i instancje, layout, UI, format pliku, konwencje Tauri i znane problemy.
## Wprowadzanie zmian
-1. [OpenSpec](./openspec) specs
-2. `openspec new change "name"`
-3. `bun run check && bun run test`
-4. Pull request
+1. Sprawdzić istniejące [specyfikacje openspec](/development/openspec)
+2. Utworzyć zmianę openspec jeśli dodajesz nowe zachowanie: `openspec new change "moja-zmiana"`
+3. Zaimplementować zmianę
+4. Uruchomić `bun run check` i `bun run test`
+5. Wysłać pull request
## Kluczowe pliki
-| File | Purpose |
-|------|---------|
-| `packages/core/src/scene-graph.ts` | Scene graph |
-| `packages/core/src/renderer.ts` | CanvasKit rendering |
-| `packages/core/src/layout.ts` | Yoga layout |
-| `packages/core/src/kiwi/codec.ts` | Kiwi codec |
-| `packages/cli/src/commands/` | CLI commands |
-| `src/stores/editor.ts` | Editor state |
+Kod źródłowy silnika znajduje się w `packages/core/src/`. Katalogi `src/engine/` i `src/kiwi/` aplikacji to shimy re-eksportu — edytuj pakiet core, nie shimy.
+
+| Plik | Cel |
+|------|-----|
+| `packages/core/src/scene-graph.ts` | Graf sceny: węzły, zmienne, instancje, hit testing |
+| `packages/core/src/renderer.ts` | Pipeline renderowania CanvasKit |
+| `packages/core/src/layout.ts` | Adapter layoutu Yoga |
+| `packages/core/src/undo.ts` | Menedżer cofnij/ponów |
+| `packages/core/src/clipboard.ts` | Schowek kompatybilny z Figmą |
+| `packages/core/src/vector.ts` | Model sieci wektorowej |
+| `packages/core/src/render-image.ts` | Eksport obrazu offscreen (PNG/JPG/WEBP) |
+| `packages/core/src/kiwi/codec.ts` | Koder/dekoder binarny Kiwi |
+| `packages/core/src/kiwi/fig-import.ts` | Logika importu plików .fig |
+| `packages/cli/src/index.ts` | Punkt wejścia CLI |
+| `packages/core/src/tools/schema.ts` | Ujednolicone definicje narzędzi (AI, MCP, CLI) |
+| `packages/core/src/figma-api.ts` | Implementacja Figma Plugin API |
+| `packages/mcp/src/server.ts` | Fabryka serwera MCP |
+| `packages/cli/src/commands/` | Polecenia CLI (info, tree, find, export, eval, analyze) |
+| `src/stores/editor.ts` | Globalny stan edytora |
+| `src/composables/use-canvas.ts` | Composable renderowania canvasu |
+| `src/composables/use-canvas-input.ts` | Obsługa wejścia mysz/dotyk |
+| `src/composables/use-keyboard.ts` | Obsługa skrótów klawiszowych |
diff --git a/packages/docs/pl/development/roadmap.md b/packages/docs/pl/development/roadmap.md
index 68d8b612c..d97a99675 100644
--- a/packages/docs/pl/development/roadmap.md
+++ b/packages/docs/pl/development/roadmap.md
@@ -1,32 +1,67 @@
# Plan rozwoju
-## Faza 1 ✅
-SceneGraph, Skia rendering, shapes, selection, zoom/pan, undo/redo, snap guides.
+## Fazy
-## Silnik Core ✅
-Vue 3 + Reka UI panels, properties, layers, toolbar, Yoga auto-layout, inline text editing, canvas rulers.
+### Faza 1: Silnik Core ✅
-## Faza 2 ✅
-.fig import/export, Kiwi codec, clipboard, pen tool, vector networks, groups, Tauri v2 desktop, sections, multi-page, hover highlight, Tier 1 rendering.
+SceneGraph, renderowanie Skia, podstawowe kształty, selekcja, zoom/pan, cofnij/ponów, linie wyrównania.
-## UI Edytora + Layout ✅
-Components, instances, overrides, component sets, variables (COLOR/FLOAT/STRING/BOOLEAN), collections, modes, image export, context menu, rich text formatting.
+### Faza 2: UI Edytora + Layout ✅
-## Faza 3 🟡
-@open-pencil/core, CLI (12 commands), MCP server (29+ tools), AI chat (OpenRouter), JSX renderer, code panel.
+Vue 3 + Reka UI panele, właściwości, warstwy, pasek narzędzi, Yoga auto-layout, edycja tekstu inline, linijki canvas.
-**Planned:** port remaining figma-use tools, attached mode, design guidelines, screenshot verification loop.
+### Faza 3: I/O Plików + Funkcje Wizualne ✅
-## I/O Plików + Funkcje Wizualne 🔲
-Prototyping, comments, PWA, Linux Tauri builds, performance optimization, full Figma compatibility test suite.
+Import/eksport .fig, kodek Kiwi, schowek, narzędzie pióra, sieci wektorowe, grupy, Tauri v2 desktop, sekcje, wiele stron, podświetlenie hover, renderowanie Tier 1.
-## Faza 4
+### Faza 4: Komponenty + Zmienne ✅
-| Phase | Komponenty + Zmienne | Faza 5: Integracja AI i Narzędzia:Faza 6: Dopracowanie + Dystrybucja:Harmonogram:Szacowany czas:Status |
-|-------|------|-----|
-| Faza 1 | 3 months | ✅ |
-| Silnik Core | 3 months | ✅ |
-| Faza 2 | 2 months | ✅ |
-| UI Edytora + Layout | 2 months | ✅ |
-| Faza 3 | 2 months | 🟡 |
-| I/O Plików + Funkcje Wizualne | 2 months | 🔲 |
+Komponenty, instancje, nadpisania, zestawy komponentów, zmienne (COLOR/FLOAT/STRING/BOOLEAN), kolekcje, tryby, eksport obrazów, menu kontekstowe, formatowanie tekstu bogatego.
+
+### Faza 5: Integracja AI i Narzędzia ✅
+
+**Dostarczone:**
+- @open-pencil/core wyodrębniony do packages/core/ (zero zależności DOM)
+- @open-pencil/cli z headless operacjami .fig (info, tree, find, export, analyze, eval)
+- Polecenie `eval` z API Plugin kompatybilnym z Figmą
+- Chat AI: bezpośrednie połączenie OpenRouter, 75 narzędzi w `schema.ts`, ⌘J
+- 49 dodatkowych narzędzi AI/MCP przeniesionych z figma-use (75 łącznie)
+- Serwer MCP (@open-pencil/mcp): stdio + HTTP, 75 narzędzi core + 3 zarządzanie plikami
+- Ujednolicone definicje narzędzi: zdefiniuj raz w `schema.ts`, adaptuj dla chatu AI (valibot), MCP (zod), CLI (eval)
+- Pasek menu dla trybu przeglądarki
+- Autozapis: zapis z debounce 3s
+- Panel właściwości multi-selekcji z wartościami wspólnymi/mieszanymi
+
+**Planowane:**
+- Tryb attached: WebSocket do działającego edytora
+- System wytycznych projektowych
+
+### Faza 6: Współpraca + Dystrybucja 🟡
+
+**Dostarczone:**
+- Współpraca P2P przez Trystero (WebRTC) + Yjs CRDT — bez serwera relay
+- Protokół awareness: kursory na żywo, selekcje, obecność
+- Tryb śledzenia: klik na avatar peera aby śledzić viewport
+- Lokalna persystencja przez y-indexeddb
+- Renderowanie efektów: cień rzucany, cień wewnętrzny, rozmycie warstwy/tła/pierwszego planu
+- Karty multi-plikowe: ⌘N/⌘T nowa karta, ⌘W zamknij, ⌘O otwórz
+- Podpisywanie kodu Apple i notaryzacja dla macOS
+- Buildy Linux (x64) dodane do CI
+- Strona dokumentacji VitePress z i18n (6 języków)
+
+**Planowane:**
+- Prototypowanie (połączenia ramek, przejścia, animacje)
+- Komentarze (pin, wątki, rozwiązywanie)
+- Wsparcie PWA
+- Przełączanie wariantów, UI zmiennych FLOAT/STRING/BOOLEAN, theming przez zmienne
+
+## Harmonogram
+
+| Faza | Szacowany czas | Status |
+|------|---------------|--------|
+| Faza 1: Silnik Core | 3 miesiące | ✅ Ukończona |
+| Faza 2: UI Edytora + Layout | 3 miesiące | ✅ Ukończona |
+| Faza 3: I/O Plików + Funkcje Wizualne | 2 miesiące | ✅ Ukończona |
+| Faza 4: Komponenty + Zmienne | 2 miesiące | ✅ Ukończona |
+| Faza 5: Integracja AI i Narzędzia | 2 miesiące | ✅ Ukończona |
+| Faza 6: Współpraca + Dystrybucja | 2 miesiące | 🟡 W toku |
diff --git a/packages/docs/pl/guide/architecture.md b/packages/docs/pl/guide/architecture.md
index fb79bdda3..881d77778 100644
--- a/packages/docs/pl/guide/architecture.md
+++ b/packages/docs/pl/guide/architecture.md
@@ -5,29 +5,92 @@
```
┌──────────────────────────────────────────────────────────────────┐
│ Tauri v2 Shell │
+│ │
│ ┌────────────────────────────────────────────────────────────┐ │
-│ │ Vue 3 UI Skia CanvasKit (WASM, 7MB) │ │
+│ │ Edytor (Web) │ │
+│ │ │ │
+│ │ Vue 3 UI Skia CanvasKit (WASM, 7MB) │ │
+│ │ - Pasek narzędzi - Renderowanie wektorowe │ │
+│ │ - Panele - Kształtowanie tekstu │ │
+│ │ - Właściwości - Przetwarzanie obrazów │ │
+│ │ - Warstwy - Efekty (rozmycie, cień) │ │
+│ │ - Selektor kolorów - Eksport (PNG, SVG, PDF) │ │
+│ │ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
-│ │ │ Core Engine (TS): SceneGraph, Layout, Selection │ │ │
+│ │ │ Core Engine (TS) │ │ │
+│ │ │ SceneGraph ─── Layout (Yoga) ─── Selection │ │ │
+│ │ │ │ │ │ │ │
+│ │ │ Undo/Redo ─── Constraints ─── Hit Testing │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
+│ │ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
-│ │ │ .fig import/export ── Kiwi codec │ │ │
+│ │ │ Warstwa formatu pliku │ │ │
+│ │ │ .fig import/export ── Kiwi codec ── .svg (planowane)│ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
-│ MCP Server (29+ tools) P2P Collaboration (Yjs CRDT) │
+│ │
+│ MCP Server (75+ tools, stdio+HTTP) P2P Collab (Trystero + Yjs) │
└──────────────────────────────────────────────────────────────────┘
```
-Interfejs podąża za layoutem UI3 Figmy.
+## Układ edytora
-Renderowanie: CanvasKit WASM — GPU, Skia.
+Interfejs podąża za layoutem UI3 Figmy — pasek narzędzi na dole, nawigacja po lewej, właściwości po prawej:
-Graf sceny: `Map` — O(1) lookup, hit testing.
+- **Panel nawigacji (lewy)** — Drzewo warstw, panel stron, biblioteka zasobów (planowane)
+- **Canvas (środek)** — Nieskończony canvas z renderowaniem CanvasKit, zoom/pan
+- **Panel właściwości (prawy)** — Kontekstowe sekcje: Wygląd, Wypełnienie, Obrys, Typografia, Layout, Pozycja
+- **Pasek narzędzi (dół)** — Wybór narzędzia: Zaznacz, Frame, Sekcja, Prostokąt, Elipsa, Linia, Tekst, Pióro, Ręka
-Format pliku: Kiwi binary codec — 194 definitions. [File Format](/reference/file-format).
+## Komponenty
-Cofnij/Ponów: Inverse-command pattern.
+### Renderowanie (CanvasKit WASM)
-Schowek: Figma-compatible, Kiwi binary.
+Ten sam silnik renderowania co Figma. CanvasKit zapewnia rysowanie 2D z akceleracją GPU:
+- Kształty wektorowe (prostokąt, elipsa, ścieżka, linia, gwiazda, wielokąt)
+- Kształtowanie tekstu przez Paragraph API
+- Efekty (cienie, rozmycia, tryby mieszania)
+- Eksport (PNG, SVG, PDF)
-[Full details in English](/guide/architecture)
+Binarny plik WASM o wielkości 7 MB ładuje się przy starcie i tworzy powierzchnię GPU na canvasie HTML.
+
+### Graf sceny
+
+Płaska `Map` indeksowana ciągami GUID. Struktura drzewa poprzez referencje `parentIndex`. Zapewnia wyszukiwanie O(1), wydajne przechodzenie, hit testing i zapytania obszarowe dla selekcji markerowej.
+
+Zobacz [Referencja grafu sceny](/reference/scene-graph) dla szczegółów wewnętrznych.
+
+### Silnik layoutu (Yoga WASM)
+
+Yoga od Mety zapewnia obliczanie layoutu CSS flexbox. Cienki adapter mapuje nazwy właściwości Figmy na odpowiedniki Yoga:
+
+| Właściwość Figma | Odpowiednik Yoga |
+|---|---|
+| `stackMode: HORIZONTAL` | `flexDirection: row` |
+| `stackMode: VERTICAL` | `flexDirection: column` |
+| `stackSpacing` | `gap` |
+| `stackPadding` | `padding` |
+| `stackJustify` | `justifyContent` |
+| `stackChildPrimaryGrow` | `flexGrow` |
+
+### Format pliku (Kiwi binarny)
+
+Wykorzystuje sprawdzony binarny kodek Kiwi Figmy z 194 definicjami wiadomości/enum/struct. Pipeline importu `.fig`: parsowanie nagłówka → dekompresja Zstd → dekodowanie Kiwi → NodeChange[] → graf sceny. Pipeline eksportu odwraca proces: graf sceny → NodeChange[] → kodowanie Kiwi → kompresja Zstd → ZIP z miniaturą.
+
+Zobacz [Referencja formatu pliku](/reference/file-format) dla szczegółów.
+
+### Cofnij/Ponów
+
+Wzorzec komendy odwrotnej. Przed zastosowaniem jakiejkolwiek zmiany, dotknięte pola są zrzucane do snapshotu. Snapshot staje się operacją odwrotną. Batching grupuje szybkie zmiany (jak przeciąganie) w pojedyncze wpisy cofania.
+
+### Schowek
+
+Dwukierunkowy schowek kompatybilny z Figmą. Koduje/dekoduje binarne Kiwi (ten sam format co pliki .fig) używając natywnych zdarzeń kopiuj/wklej przeglądarki (synchronicznych, nie asynchronicznego API Schowka). Wklejanie obsługuje skalowanie ścieżek wektorowych, wypełnianie dzieci instancji, wykrywanie zestawów komponentów i stosowanie nadpisań.
+
+### Serwer MCP
+
+`@open-pencil/mcp` udostępnia 75 narzędzi core + 3 narzędzia zarządzania plikami dla narzędzi kodowania AI. Dwa transporty: stdio dla Claude Code/Cursor/Windsurf, HTTP z Hono + Streamable HTTP dla skryptów i CI. Narzędzia są definiowane raz w `packages/core/src/tools/schema.ts` i adaptowane dla chatu AI (valibot), MCP (zod) i CLI (polecenie eval).
+
+### Współpraca P2P
+
+Współpraca peer-to-peer w czasie rzeczywistym przez Trystero (WebRTC) + Yjs CRDT. Bez serwera relay — sygnalizacja przez publiczne brokery MQTT, STUN/TURN dla traversalu NAT. Protokół awareness zapewnia kursory na żywo, selekcje i obecność. Lokalna persystencja przez y-indexeddb.
diff --git a/packages/docs/pl/guide/comparison.md b/packages/docs/pl/guide/comparison.md
index 2dc14b8b3..8f56c0161 100644
--- a/packages/docs/pl/guide/comparison.md
+++ b/packages/docs/pl/guide/comparison.md
@@ -1,18 +1,235 @@
-# Porównanie z Penpotem
+# Open Pencil vs Penpot: Porównanie architektury i wydajności
-| Metric | Open Pencil | Penpot |
+Dlaczego porównujemy? OpenPencil istnieje, ponieważ zamknięte platformy projektowe kontrolują co jest możliwe. Zrozumienie różnic architektonicznych pokazuje, co otwarta alternatywa local-first może zrobić inaczej.
+
+::: info Renderer WASM Penpota
+Penpot 2.x zawiera renderer Rust/Skia WASM (`render-wasm/v1`) aktywowany przez flagi serwera lub parametr URL `?wasm=true`. Stary renderer SVG pozostaje domyślny. Ta strona obejmuje oba.
+:::
+
+## 1. Skala i rozmiar kodu
+
+| Metryka | Open Pencil | Penpot |
+|---------|-------------|--------|
+| LOC ogółem | **~26 000** | **~299 000** |
+| Pliki źródłowe | ~143 | ~2 900 |
+| Języki | TypeScript, Vue | Clojure, ClojureScript, Rust, JS, SQL, SCSS |
+| Silnik renderowania | 1 646 LOC (TS) | 22 000 LOC (Rust/Skia WASM) |
+| Kod UI | ~4 500 LOC | ~175 000 LOC (CLJS + SCSS) |
+| Backend | Brak (local-first) | 32 600 LOC + 151 plików SQL |
+| Stosunek LOC | **1×** | **~11×** |
+
+Open Pencil jest **~11× mniejszy** — i o to chodzi. To nie uproszczenie; to fundamentalnie inna architektura.
+
+## 2. Architektura
+
+### Open Pencil: Klient monolityczny
+
+```
+┌─────────────────────────────────┐
+│ Tauri (natywna powłoka) │
+│ ┌───────────────────────────┐ │
+│ │ Vue 3 + TypeScript │ │
+│ │ ┌─────────┐ ┌──────────┐│ │
+│ │ │ Editor │ │ Kiwi ││ │
+│ │ │ Store │ │ Codec ││ │
+│ │ └────┬─────┘ └──────────┘│ │
+│ │ │ │ │
+│ │ ┌────▼────────────────┐ │ │
+│ │ │ Scene Graph (TS) │ │ │
+│ │ │ Map │ │ │
+│ │ └────┬────────────────┘ │ │
+│ │ │ │ │
+│ │ ┌────▼────┐ ┌──────────┐│ │
+│ │ │ Skia │ │ Yoga ││ │
+│ │ │CanvasKit│ │ Layout ││ │
+│ │ │ (WASM) │ │ (WASM) ││ │
+│ │ └─────────┘ └──────────┘│ │
+│ └───────────────────────────┘ │
+└─────────────────────────────────┘
+```
+
+**Wszystko w jednym procesie.** Bez serwera, bazy danych, Dockera.
+
+### Penpot: Rozproszony klient-serwer
+
+```
+┌───────────────────────────────────────────────────────┐
+│ Docker Compose │
+│ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐ │
+│ │ Frontend │ │ Backend │ │ Exporter │ │
+│ │ ClojureScript│ │ Clojure │ │ (Chromium) │ │
+│ │ shadow-cljs │ │ JVM │ │ │ │
+│ │ ┌─────────┐ │ │ ┌────────┐ │ └──────────────┘ │
+│ │ │render- │ │ │ │Postgres│ │ │
+│ │ │wasm │ │ │ │Valkey │ │ ┌──────────────┐ │
+│ │ │(Rust→ │ │ │ │ MinIO │ │ │ MCP │ │
+│ │ │ Skia │ │ │ └────────┘ │ │ Server │ │
+│ │ │ WASM) │ │ │ │ └──────────────┘ │
+│ │ └─────────┘ │ │ │ │
+│ └──────────────┘ └─────────────┘ │
+└───────────────────────────────────────────────────────┘
+```
+
+**Minimum 5+ usług.** PostgreSQL, Redis (Valkey), MinIO, backend JVM, eksporter Node.js (headless Chromium), plus frontend ClojureScript.
+
+### Werdykt: Architektura
+
+Architektura jednoprocesowa Open Pencil eliminuje: opóźnienie sieci, narzut serializacji, złożoność orkiestracji kontenerów i narzut zapytań do bazy danych.
+
+## 3. Pipeline renderowania
+
+### Open Pencil: TS → CanvasKit WASM (bezpośrednio)
+
+```typescript
+renderSceneToCanvas(canvas, graph, pageId) {
+ this.fillPaint.setColor(...)
+ canvas.drawRRect(rrect, this.fillPaint)
+}
+```
+
+- **1 przekroczenie granicy:** TS → WASM (CanvasKit)
+- 1 646 LOC renderera łącznie
+
+### Penpot: JS (skompilowany z CLJS) → Rust WASM → Skia
+
+```
+ClojureScript (skompilowany do JS)
+ → dekompozycja na prymitywy + pakowanie binarne do pamięci liniowej WASM
+ → Rust WASM (przez Emscripten C FFI)
+ → skia-safe (bindingi Rust Skia)
+ → Skia (WebGL)
+```
+
+Gdy wyłączone (domyślnie), renderowanie jako drzewo DOM SVG. Gdy włączone, system renderowania oparty na kafelkach z 11 powierzchniami.
+
+### Werdykt: Renderowanie
+
+| Aspekt | Open Pencil | Penpot |
|--------|-------------|--------|
-| Total LOC | **~26,000** | **~299,000** |
-| Source files | 125 | ~2,900 |
-| Languages | TypeScript, Vue | Clojure, ClojureScript, Rust, JS, SQL, SCSS |
-| LOC ratio | **1×** | **~11×** |
-| Rendering | Skia CanvasKit (GPU, WASM) | Skia Rust/WASM (render-wasm v1) |
-| Layout | Yoga WASM (CSS flexbox) | Custom CLJS engine |
-| File format | Figma Kiwi binary (.fig) | Custom SVG + metadata |
-| Desktop | Tauri v2 (~5 MB) | No native client |
-| Backend | None (P2P) | Clojure + PostgreSQL + Redis |
-| Collaboration | P2P (Trystero + Yjs CRDT) | Client-server |
-| AI tools | 29 tools + MCP server | Plugin system |
-| CLI | ✅ 12 commands | ❌ |
+| Granica JS→WASM | Bezpośrednia (obiekty TS) | Pakowanie binarne (104 bajty na kształt) |
+| Model renderowania | Natychmiastowy/pełne przerysowanie | Cache kafelkowy |
+| Zarządzanie powierzchniami | 1 powierzchnia | 11 powierzchni |
+| Narzut pamięci | Niski | Wysoki (1024 wpisy cache) |
+| Złożoność kodu | 1 646 LOC | 22 000 LOC |
+| Kod unsafe | Brak | Globalny stan `unsafe` |
-[Full details in English](/guide/comparison)
+## 4. Graf sceny i model danych
+
+### Open Pencil
+
+```typescript
+nodes: Map
+// 29 typów węzłów ze schematu Kiwi Figmy
+// ~390 pól na NodeChange (kompatybilny z Figmą)
+```
+
+### Penpot
+
+- Dane rozproszone w `common/` (49 600 LOC .cljc)
+- Walidacja schematu w runtime (Malli)
+
+### Werdykt: Model danych
+
+Open Pencil reutylizuje sprawdzony schemat Figmy (194 definicje Kiwi) bezpośrednio w TypeScript. Penpot utrzymuje własny system typów w trzech językach.
+
+## 5. Silnik layoutu
+
+### Open Pencil: Yoga WASM (314 LOC)
+
+```typescript
+import Yoga from 'yoga-layout'
+const root = Yoga.Node.create()
+root.setFlexDirection(FlexDirection.Row)
+root.calculateLayout()
+```
+
+314 linii. Synchroniczny, w procesie.
+
+### Penpot: Podwójna implementacja
+
+Penpot utrzymuje **dwa niezależne silniki layoutu** (CLJS i Rust) — ~3 000+ LOC zduplikowanego kodu.
+
+## 6. Format pliku i kompatybilność z Figmą
+
+### Open Pencil
+
+- **Natywny format binarny Kiwi** — ta sama serializacja co Figma
+- Bezpośredni import `.fig`, wklejanie ze schowka Figmy
+- Kompatybilny z protokołem multiplayer Figmy
+
+### Penpot
+
+- **Archiwum ZIP** (`.penpot`) z manifestami JSON i zasobami binarnymi
+- Brak natywnego importu `.fig`
+
+### Werdykt: Format pliku
+
+Open Pencil ma znaczącą przewagę — może czytać pliki Figmy natywnie i wklejać dane ze schowka Figmy.
+
+## 7. Zarządzanie stanem i cofanie
+
+### Open Pencil
+
+```typescript
+// 110 LOC — wzorzec komendy odwrotnej
+class UndoManager {
+ apply(entry) { entry.forward(); this.undoStack.push(entry) }
+ undo() { entry.inverse(); this.redoStack.push(entry) }
+}
+```
+
+### Penpot
+
+Zarządzanie stanem przez Potok. Cofanie z wektorami zmian odwrotnych (max 50 wpisów), auto-wygasanie po 20 sekundach.
+
+## 8. Doświadczenie developerskie
+
+| Metryka | Open Pencil | Penpot |
+|---------|-------------|--------|
+| Setup dev | `bun install && bun dev` | Docker Compose + JVM + Node + Rust |
+| Hot reload | Vite HMR (~50ms) | shadow-cljs (sekundy) |
+| Sprawdzanie typów | TypeScript (strict) | Runtime (schematy Malli) |
+| Czas buildu | <5s (Vite) | Minuty (JVM + CLJS + Rust WASM) |
+| Bariera pierwszej kontrybucji | Niska (TS/Vue) | Wysoka (Clojure + Rust + Docker) |
+| Desktop | Tauri v2 (~5MB) | N/A (tylko przeglądarka) |
+
+## 9. Charakterystyki wydajności
+
+| Scenariusz | Open Pencil | Penpot |
+|------------|-------------|--------|
+| Zimny start | <2s (ładowanie WASM) | 10s+ (serwer + klient + WASM) |
+| Opóźnienie operacji | <1ms (w procesie) | 10-50ms (round-trip sieci) |
+| Klatka renderowania | Bezpośrednie wywołanie Skia | CLJS→JS→WASM FFI→Skia |
+| Pamięć bazowa | ~50MB (karta przeglądarki) | ~300MB+ (JVM + Postgres + Valkey + przeglądarka) |
+| Zdolność offline | Pełna (local-first) | Brak (zależy od serwera) |
+
+## 10. Co Penpot robi lepiej
+
+1. **Współpraca serwerowa** — centralna edycja wieloużytkownikowa z WebSockets, kontami i kontrolą dostępu
+2. **Eksport serwerowy** — usługa eksportu headless Chromium
+3. **System pluginów** — pełne API z sandboxowanym wykonywaniem
+4. **Tokeny projektowe** — natywne wsparcie design tokenów
+5. **CSS Grid layout** — własna implementacja (Open Pencil czeka na Yoga Grid)
+6. **Self-hosting** — wdrożenie Docker dla zespołów
+7. **Dojrzałość** — lata użytkowania w produkcji
+
+## 11. Scripting i rozszerzalność
+
+OpenPencil zawiera [komendę `eval`](/eval-command) oferującą API Plugin kompatybilne z Figmą do skryptowania headless. Ponadto 75 narzędzi AI dostępnych przez wbudowany chat, serwer MCP (stdio + HTTP) i CLI. Penpot ma system pluginów z sandboxem, ale bez API skryptowania headless ani integracji MCP.
+
+## Podsumowanie
+
+| Wymiar | Zwycięzca | Dlaczego |
+|--------|-----------|----------|
+| **Prostota architektoniczna** | Open Pencil | Jeden proces vs 5+ usług |
+| **Wydajność renderowania** | Open Pencil | Bezpośredni CanvasKit vs SVG DOM (domyślnie) lub WASM pakowany |
+| **Utrzymywalność kodu** | Open Pencil | ~26K LOC w 1 języku vs 299K w 4+ |
+| **Kompatybilność z Figmą** | Open Pencil | Natywny kodek Kiwi vs brak wsparcia .fig |
+| **Onboarding developerów** | Open Pencil | TS/Vue vs Clojure/Rust/Docker |
+| **Doświadczenie desktop** | Open Pencil | Natywne Tauri vs tylko przeglądarka |
+| **Silnik layoutu** | Open Pencil | Yoga (sprawdzony) vs podwójna implementacja |
+| **Współpraca** | Remis | Penpot: serwer z kontrolą dostępu; Open Pencil: P2P przez Trystero + Yjs |
+| **Self-hosting** | Penpot | Gotowy Docker vs tylko desktop |
+| **Dojrzałość ekosystemu** | Penpot | Lata produkcji vs wczesny etap |
+
+Open Pencil jest architektonicznie szczuplejszy — jednoprocesowy renderer CanvasKit w ~26K LOC TypeScript, kompatybilny z Figmą z założenia. Penpot to platforma full-stack z ~299K LOC. Open Pencil ma skryptowanie headless, 75 narzędzi AI/MCP i natywną aplikację desktop.
diff --git a/packages/docs/pl/guide/features.md b/packages/docs/pl/guide/features.md
index 24341bafa..6b438b1a2 100644
--- a/packages/docs/pl/guide/features.md
+++ b/packages/docs/pl/guide/features.md
@@ -2,36 +2,162 @@
## Dlaczego OpenPencil
-Open-source'owa alternatywa: MIT, kompatybilna z Figmą, w pełni lokalna i programowalna.
+Narzędzia projektowe to problem łańcucha dostaw. Gdy narzędzie jest zamknięte, dostawca kontroluje co jest możliwe — może zepsuć automatyzację z dnia na dzień. OpenPencil to alternatywa open-source: licencja MIT, kompatybilny z Figmą, w pełni lokalny i programowalny.
-## Import i eksport .fig
-Otwiera i zapisuje natywne pliki Figmy. Pełny schemat Kiwi (194 definicje). Wierna kompatybilność round-trip.
+## Import i eksport plików .fig Figmy
-## Kopiuj i wklej z Figmy
-Kopiuj w Figmie, wklej w OpenPencil i odwrotnie. Ten sam format binarny Kiwi.
+Otwieraj i zapisuj natywne pliki Figmy bezpośrednio. Import dekoduje pełny schemat Kiwi z 194 definicjami w tym wiadomości NodeChange z ~390 polami. Eksport koduje graf sceny z powrotem do binarnego Kiwi z kompresją Zstd i generowaniem miniatur. Zapisz (⌘S) i Zapisz jako (⇧⌘S) używają natywnych okien dialogowych OS.
+
+## Kopiuj i wklej z Figmą
+
+Zaznacz węzły w Figmie, ⌘C, przełącz się na OpenPencil, ⌘V — pojawiają się z wypełnieniami, obrysami, auto-layoutem, tekstem, promieniami narożników, efektami i sieciami wektorowymi. Działa też w drugą stronę.
+
+Wklejanie obsługuje złożone scenariusze: ścieżki wektorowe są skalowane z `normalizedSize` Figmy, dzieci instancji są wypełniane z `symbolData` komponentu, zestawy komponentów są wykrywane, a `symbolOverrides` są stosowane. Czcionki są ładowane automatycznie.
+
+## Sieci wektorowe
+
+Narzędzie pióro używa modelu sieci wektorowej Figmy — nie prostych ścieżek. Kliknij dla punktów narożnych, kliknij+przeciągnij dla krzywych Béziera. Obsługa ścieżek otwartych i zamkniętych.
## Narzędzia kształtów
-Prostokąt (R), Elipsa (O), Linia (L), Wielokąt, Gwiazda. Wypełnienie, obrys, efekty.
-## Auto-layout
-Yoga WASM (flexbox). Kierunek, gap, padding, wyrównanie. ⇧A aby włączyć.
+Pasek narzędzi udostępnia wszystkie podstawowe narzędzia kształtów Figmy: Prostokąt (R), Elipsa (O), Linia (L), Wielokąt i Gwiazda. Wszystkie obsługują wypełnienie, obrys, podświetlenie przy najechaniu i kontur zaznaczenia.
-## Edycja tekstu
-Natywna edycja na płótnie. Wirtualny selektor czcionek. Formatowanie (B/I/U/S).
+## Auto-Layout
+
+Yoga WASM zapewnia layout CSS flexbox. Ramki obsługują: kierunek, gap, padding, justify, align i wymiarowanie dzieci. Shift+A przełącza auto-layout.
+
+## Edycja tekstu inline
+
+Natywna edycja tekstu na canvasie. Podwójne kliknięcie na węźle tekstowym wchodzi w tryb edycji. **Wybieracz czcionek** z wirtualnym przewijaniem, filtrem wyszukiwania i podglądem CSS. W Tauri czcionki systemowe są enumerowane przez crate Rust `font-kit`.
+
+## Formatowanie tekstu bogatego
+
+Formatowanie per-znak: ⌘B pogrubienie, ⌘I kursywa, ⌘U podkreślenie, lub przyciski B/I/U/S. Zaimplementowane przez model StyleRun. Zachowane przy imporcie/eksporcie .fig.
## Cofnij/Ponów
-⌘Z / ⇧⌘Z. Wzorzec inverse-command. Każda operacja jest odwracalna.
+
+Każda operacja jest cofalna. Wzorzec komendy odwrotnej. ⌘Z cofa, ⇧⌘Z ponawia.
+
+## Prowadnice snap
+
+Przyciąganie do krawędzi i centrów z czerwonymi liniami prowadzącymi. Uwzględnia rotację.
+
+## Linijki canvasu
+
+Linijki na górze i po lewej pokazują skale współrzędnych z badge'ami współrzędnych przy zaznaczeniu.
+
+## Wybieracz kolorów i typy wypełnień
+
+Wybór koloru HSV ze sliderem odcienia, sliderem alfa, wejściem hex i kontrolą przezroczystości. Typy: Jednolity, Gradient (Liniowy, Radialny, Kątowy, Diamentowy) i Obraz.
+
+## Panel warstw
+
+Widok drzewa hierarchii dokumentu. Panele są zmiennych rozmiarów.
+
+## Panel właściwości
+
+Interfejs z kartami **Design** | **Kod** | **AI**. Karta Design pokazuje sekcje kontekstowe: Wygląd, Wypełnienie, Obrys, Efekty, Typografia, Layout, Pozycja, Eksport i Strona.
+
+## Grupuj/Rozgrupuj
+
+⌘G grupuje. ⇧⌘G rozgrupowuje. Węzły są sortowane wg pozycji wizualnej.
+
+## Sekcje
+
+Sekcje (S) to kontenery organizacyjne najwyższego poziomu na canvasie z pigułkami tytułu i automatyczną inwersją koloru tekstu.
+
+## Dokumenty wielostronicowe
+
+Dokumenty obsługują wiele stron. Każda strona utrzymuje niezależny stan viewportu.
+
+## Podświetlenie przy najechaniu
+
+Węzły podświetlają się konturem podążającym za rzeczywistą geometrią.
+
+## Zaawansowane renderowanie (Tier 1)
+
+Renderer CanvasKit obsługuje pełne cechy wizualne Tier 1: wypełnienia gradientowe, wypełnienia obrazem, efekty, właściwości obrysu, dane łuku, culling viewportu, ponowne użycie Paint i koalescencja RAF.
## Komponenty i instancje
-Komponenty wielokrotnego użytku (⌥⌘K), zestawy (⇧⌘K), synchronizacja na żywo, nadpisania.
+
+Komponenty wielokrotnego użytku (⌥⌘K), zestawy (⇧⌘K), instancje przez menu kontekstowe, odłącz (⌥⌘B). **Synchronizacja na żywo** i **obsługa nadpisań**. Fioletowe etykiety z ikoną diamentu.
## Zmienne
-Tokeny projektowe z kolekcjami i trybami. Wiązanie do wypełnień.
+
+Tokeny projektowe z kolekcjami i trybami. Dialog TanStack Table. Obsługuje COLOR z pełnym UI, FLOAT/STRING/BOOLEAN zdefiniowane. Wszystkie operacje są cofalne.
+
+## Eksport obrazów
+
+PNG, JPG, WEBP ze skalą 0,5×–4×, podgląd na żywo i ⇧⌘E.
+
+## Menu kontekstowe
+
+Kliknij prawym dla: Schowek, Kolejność Z, Grupowanie, Komponenty (fioletowe pozycje), Widoczność, Przenieś na stronę.
+
+## Kolejność Z, widoczność i blokada
+
+] przenosi na wierzch, [ wysyła na spód. ⇧⌘H widoczność. ⇧⌘L blokada.
+
+## Aplikacja webowa i desktopowa
+
+OpenPencil działa w przeglądarce na [app.openpencil.dev](https://app.openpencil.dev). Aplikacja desktopowa używa Tauri v2 (~5 MB). Działa w pełni offline.
+
+## Menu aplikacji (przeglądarka)
+
+Pasek menu z reka-ui: **Plik**, **Edycja**, **Widok**, **Obiekt**, **Tekst**, **Rozmieszczenie**. Skróty klawiszowe dostosowane do platformy. Ukryte w Tauri.
+
+## Automatyczny zapis
+
+Pliki zapisywane 3 sekundy po ostatniej zmianie. Debounce na `sceneVersion`. Wyłączone dla nowych dokumentów bez tytułu.
+
+## Współpraca P2P
+
+Współpraca peer-to-peer w czasie rzeczywistym — bez serwera. Oparta na Trystero (WebRTC) + Yjs (CRDT).
+
+- **Zero kosztów hostingu** — sygnalizacja przez publiczne brokery MQTT
+- **Traversal NAT** — serwery Google STUN, Cloudflare STUN i Open Relay TURN
+- **Kursory na żywo** — kolorowe strzałki w stylu Figmy z pigułkami imion
+- **Obecność** — kolorowe awatary
+- **Tryb śledzenia** — kliknij awatar peera aby śledzić jego viewport
+- **Lokalna persystencja** — y-indexeddb utrzymuje pokój między przeładowaniami
+- **Bezpieczne pokoje** — ID przez `crypto.getRandomValues()`
+
+## Karty wieloplikowe
+
+Otwieraj wiele dokumentów w kartach. ⌘N/⌘T nowa karta, ⌘W zamknij, ⌘O otwórz w nowej karcie. Każda karta utrzymuje własny stan dokumentu.
+
+## Renderowanie efektów
+
+Pełne renderowanie efektów Figmy: **Cień rzutowany**, **Cień wewnętrzny**, **Rozmycie warstwy** (Gaussowskie), **Rozmycie tła** (efekt szkła/matowania), **Rozmycie pierwszego planu**. Cache SkPicture per węzeł dla wydajności.
+
+## Właściwości wielokrotnego zaznaczenia
+
+Zaznacz wiele węzłów i edytuj wspólne właściwości. Wspólne wartości wyświetlane normalnie, różne pokazują "Mixed". Odwróć H/V dotyczy wszystkich węzłów.
+
+## ScrubInput
+
+Wszystkie wejścia numeryczne używają interakcji przeciągnij-aby-zmienić. Obsługuje sufiksy (°, px, %).
+
+## Budowanie CI/CD
+
+GitHub Actions buduje aplikacje Tauri na tagach wersji. macOS podpisany i notaryzowany. Noty wydania auto-wypełniane z CHANGELOG.md.
+
+## @open-pencil/core i CLI
+
+Silnik wyodrębniony do `packages/core/`. CLI udostępnia: info, tree, find, export, analyze, node, pages, variables, eval. Wszystko obsługuje `--json`. Komenda `eval` wykonuje JavaScript z API Plugin Figma. Zobacz [Komenda Eval](/eval-command).
+
+## Renderer JSX
+
+Programistyczne tworzenie designu przez buildery TreeNode. Propsy shorthand w stylu Tailwind.
## Chat AI
-29 narzędzi przez OpenRouter. Serwer MCP (stdio + HTTP).
-## CLI
-info, tree, find, export, analyze, eval. Wszystkie komendy obsługują `--json`.
+Wbudowany asystent AI przez ⌘J. **75 narzędzi** w `schema.ts` obejmujących: odczyt, tworzenie, modyfikację, manipulację węzłów, CRUD zmiennych, narzędzia wektorowe, kontrolę viewportu i `eval`. **Serwer MCP** udostępnia 78 narzędzi łącznie (75 core + 3 zarządzanie plikami) dla zewnętrznych narzędzi kodowania AI.
-[Pełne szczegóły po angielsku](/guide/features)
+## Panel kodu
+
+Karta Kod pokazuje JSX zaznaczenia z podświetlaniem składni Prism.js i kopiowaniem.
+
+## Jakość kodu
+
+Wykrywanie kopiuj-wklej przez jscpd — duplikacja zredukowana z 15,6% do 0,62%. Pipeline importu zoptymalizowany z O(n²) do O(n).
diff --git a/packages/docs/pl/guide/figma-comparison.md b/packages/docs/pl/guide/figma-comparison.md
index 1b66a8698..af0f1fef3 100644
--- a/packages/docs/pl/guide/figma-comparison.md
+++ b/packages/docs/pl/guide/figma-comparison.md
@@ -1,9 +1,226 @@
-# Matryca funkcji Figma
+# Matryca funkcji Figmy
-**Coverage:** 87 / 152 — 69 ✅, 18 🟡, 65 🔲. (2026-03-03)
+Porównanie funkcja po funkcji możliwości Figma Design z aktualnym stanem implementacji Open Pencil.
-✅ = Full | 🟡 = Partial | 🔲 = Not yet
+::: tip Legenda statusów
+✅ Obsługiwane — funkcja działa w pełni · 🟡 Częściowe — podstawowe zachowanie istnieje, brakuje niektórych pod-funkcji · 🔲 Jeszcze nie zaimplementowane
+:::
-[Full feature matrix in English](/guide/figma-comparison)
+**Pokrycie:** 88 ze 152 elementów Figmy uwzględnionych — 70 ✅ w pełni obsługiwanych, 18 🟡 częściowych, 64 🔲 oczekujących. Ostatnia aktualizacja: 2026-03-04.
-[Features](/pl/guide/features) · [Comparison](/pl/guide/comparison)
+## Interfejs i nawigacja
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Pasek narzędzi projektowych | ✅ | Pasek dolny (styl UI3): Zaznacz, Frame, Sekcja, Prostokąt, Elipsa, Linia, Tekst, Ręka, Pióro |
+| Panel warstw (lewy panel boczny) | ✅ | Widok drzewa z rozwijaniem/zwijaniem, zmianą kolejności, przełącznikiem widoczności; zmienna szerokość |
+| Panel stron | ✅ | Dodaj, usuń, zmień nazwę stron; stan viewportu per strona |
+| Panel właściwości (prawy panel boczny) | ✅ | Sekcje: Wygląd, Wypełnienie, Obrys, Efekty, Typografia, Layout, Pozycja; zmienna szerokość |
+| Zoom i panorama | ✅ | Ctrl+scroll, pinch, ⌘+/⌘−/⌘0, spacja+przeciągnij, środkowy przycisk myszy, narzędzie ręki (H) |
+| Linijki canvasu | ✅ | Linijki góra/lewo z pasmami zaznaczenia i badge'ami współrzędnych |
+| Kolor tła canvasu | ✅ | Tło per strona przez panel właściwości |
+| Prowadnice canvasu | 🔲 | Figma obsługuje przeciągane prowadnice z linijek |
+| Menu akcji / paleta poleceń | 🔲 | Szybkie wyszukiwanie akcji Figmy |
+| Menu kontekstowe | ✅ | Prawy klik z schowkiem, kolejnością-z, grupowaniem, komponentem, widocznością, blokadą, przenieś-na-stronę |
+| Skróty klawiszowe | 🟡 | Podstawowe + komponenty + kolejność-z + widoczność/blokada zaimplementowane; Skala, Strzałka, Ołówek, odbijanie, formatowanie tekstu jeszcze nie podłączone |
+| Szukaj i zamień | 🔲 | Wyszukiwanie/zamiana tekstu w dokumencie |
+| Widok konturów warstw | 🔲 | Widok wireframe wszystkich warstw |
+| Niestandardowe miniatury | 🔲 | Miniatura generowana przy eksporcie, ale bez selektora |
+| Ustawienia wartości nudge | 🔲 | Domyślnie 1px/10px; Figma pozwala na wartości niestandardowe |
+| Menu aplikacji (tryb przeglądarkowy) | ✅ | Menu Plik, Edycja, Widok, Obiekt, Tekst, Rozmieszczenie; Tauri używa natywnych menu |
+| Narzędzia AI | 🟡 | 75 narzędzi przez OpenRouter + serwer MCP; bez obrazów generowanych przez AI ani wyszukiwania AI jeszcze |
+
+## Warstwy i kształty
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Narzędzia kształtów (Prostokąt, Elipsa, Linia, Wielokąt, Gwiazda) | ✅ | Wszystkie podstawowe typy kształtów; boki wielokąta i promień wewnętrzny gwiazdy konfigurowalne |
+| Ramki | ✅ | Przycinanie zawartości, niezależny układ współrzędnych |
+| Grupy | ✅ | ⌘G grupowanie, ⇧⌘G rozgrupowanie |
+| Sekcje | ✅ | Pigułki tytułu, auto-adopcja nakładających się węzłów, tekst adaptacyjny do luminancji |
+| Narzędzie łuku (łuki, półkola, pierścienie) | ✅ | arcData z kątem początkowym/końcowym i promieniem wewnętrznym |
+| Narzędzie ołówka (odręczne) | 🔲 | Narzędzie rysowania odręcznego Figmy |
+| Maski | 🔲 | Maski kształtów do przycinania warstw |
+| Typy warstw i hierarchia | ✅ | 17 typów węzłów, płaska Mapa + drzewo rodzic-dziecko |
+| Zaznaczanie warstw | ✅ | Klik, shift-klik, zaznaczenie markerowe |
+| Wyrównanie i pozycja | ✅ | Pozycja, rotacja, wymiary w panelu |
+| Kopiuj i wklej obiekty | ✅ | Standardowy schowek + format binarny Kiwi Figmy |
+| Skaluj warstwy proporcjonalnie | 🟡 | Shift-zmiana rozmiaru utrzymuje proporcje; brak dedykowanego narzędzia Scale (K) |
+| Zablokuj i odblokuj warstwy | ✅ | ⇧⌘L przełącza blokadę |
+| Przełącz widoczność warstwy | ✅ | Ikona oka w panelu + skrót ⇧⌘H |
+| Zmień nazwę warstw | 🟡 | Programistyczna zmiana nazwy; brak inline UI jeszcze |
+| Przenieś na wierzch / Wyślij na spód | ✅ | Skróty ] i [; też w menu kontekstowym |
+| Przenieś na stronę | ✅ | Przenoszenie węzłów między stronami przez menu kontekstowe |
+| Ograniczenia (responsywna zmiana rozmiaru) | 🔲 | Przypięcie krawędzi/centrum dla zachowania resize rodzica |
+| Inteligentna selekcja (rozmieść/wyrównaj) | 🔲 | Równomierne rozmieszczanie i wyrównywanie |
+| Prowadnice layoutu (kolumny, wiersze, siatka) | 🔲 | Prowadnice kolumn/wierszy/siatki na ramkach |
+| Mierzenie odległości między warstwami | 🔲 | Alt-najechanie pokazuje odległości |
+| Edycja obiektów zbiorowo | ✅ | Panel wielokrotnego zaznaczenia: wspólne wartości normalne, różne pokazują "Mixed" |
+| Identyfikacja pasujących obiektów | 🔲 | Znajdowanie podobnych warstw |
+| Kopiuj/wklej właściwości | 🔲 | Kopiowanie wypełnienia/obrysu/efektów między warstwami |
+| Relacje rodzic-dziecko | ✅ | Pełna hierarchia z parentIndex, re-parentowanie przez przeciąganie |
+
+## Narzędzia wektorowe
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Sieci wektorowe | ✅ | Model kompatybilny z Figmą, nie proste ścieżki |
+| Narzędzie pióro | ✅ | Punkty narożne, krzywe Béziera, ścieżki otwarte/zamknięte |
+| Edytuj warstwy wektorowe | 🟡 | Tworzenie działa; zaawansowana edycja wierzchołków ograniczona |
+| Operacje booleowskie (Suma, Różnica, Przecięcie, Wykluczenie) | 🔲 | Łączenie kształtów operacjami booleowskimi |
+| Spłaszczanie warstw | 🔲 | Łączenie ścieżek wektorowych |
+| Konwersja obrysów na ścieżki | 🔲 | Polecenie Outline Stroke |
+| Konwersja tekstu na ścieżki | 🔲 | Spłaszczanie tekstu na kontury wektorowe |
+| Narzędzie shape builder | 🔲 | Interaktywne narzędzie booleowskie |
+| Offset ścieżki | 🔲 | Inset/outset ścieżki wektorowej |
+| Uproszczenie ścieżki | 🔲 | Redukcja liczby punktów wektorowych |
+
+## Tekst i typografia
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Narzędzie tekstowe i edycja inline | ✅ | Natywna edycja na canvasie, phantom textarea, style run (⌘B/I/U, przycisk S) |
+| Renderowanie tekstu (Paragraph API) | ✅ | CanvasKit Paragraph do kształtowania, łamania linii, metryk |
+| Ładowanie czcionek (czcionki systemowe) | ✅ | Inter domyślny, font-kit w Tauri z cache OnceLock, queryLocalFonts w przeglądarce |
+| Rodzina i grubość czcionki | ✅ | FontPicker z wirtualnym scrollem, wyszukiwaniem, podglądem CSS |
+| Rozmiar czcionki i interlinia | ✅ | Edytowalne w sekcji typografii |
+| Wyrównanie tekstu | 🟡 | Podstawowe wyrównanie; Figma ma wyrównanie pionowe i tryby auto-szerokość/wysokość |
+| Style tekstu | 🟡 | Pogrubienie/kursywa/podkreślenie/przekreślenie per zaznaczenie; brak presetów wielokrotnego użytku |
+| Tryby zmiany rozmiaru tekstu | 🔲 | Tryby auto-szerokość, auto-wysokość, stały-rozmiar Figmy |
+| Listy punktowane i numerowane | 🔲 | Formatowanie list w tekście |
+| Linki w tekście | 🔲 | Hiperlinki w treści tekstowej |
+| Emoji i symbole inteligentne | 🔲 | Renderowanie emoji i znaków specjalnych |
+| Funkcje OpenType | 🔲 | Ligatury, alternatywy stylistyczne, cyfry tabelaryczne |
+| Czcionki zmienne | 🔲 | Regulowane osie czcionki (grubość, szerokość, pochylenie) |
+| Obsługa tekstu CJK | 🔲 | Renderowanie tekstu chińskiego, japońskiego, koreańskiego |
+| Obsługa tekstu RTL | 🔲 | Layout tekstu od prawej do lewej |
+| Czcionki ikon | 🔲 | Specjalna obsługa glifów czcionek ikon |
+
+## Kolor, gradienty i obrazy
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Wybieracz kolorów (HSV) | ✅ | Kwadrat HSV, slider odcienia, slider alfa, wejście hex |
+| Wypełnienia jednolite | ✅ | Kolor hex z przezroczystością |
+| Gradient liniowy | ✅ | Punkty stopu, uchwyty transformacji |
+| Gradient radialny | ✅ | Renderowanie przez shadery CanvasKit |
+| Gradient kątowy | ✅ | Obsługa gradientu sweep/stożkowego |
+| Gradient diamentowy | ✅ | Gradient diamentowy czteropunktowy |
+| Wypełnienia obrazem | ✅ | Dekodowane z danych blob z trybami skali (fill, fit, crop, tile) |
+| Wypełnienia wzorem | 🔲 | Powtarzające się wypełnienia obrazem/wzorem |
+| Tryby mieszania | 🔲 | Tryby mieszania warstwy i wypełnienia (multiply, screen, overlay, itp.) |
+| Dodawanie obrazów i wideo | 🟡 | Wypełnienia obrazem renderowane; brak importu drag-and-drop ani obsługi wideo |
+| Regulacja właściwości obrazu | 🔲 | Ekspozycja, kontrast, nasycenie, itp. |
+| Przycinanie obrazu | 🔲 | Interaktywne przycinanie obrazów |
+| Narzędzie kroplomierza | 🔲 | Próbkowanie kolorów z canvasu |
+| Edycja koloru w selekcji mieszanej | 🔲 | Regulacja kolorów w heterogenicznej selekcji |
+| Modele kolorów (RGB, HSL, HSB, Hex) | 🟡 | HSV + Hex w wybieraczu; brak przełączania trybu HSL lub RGB |
+
+## Efekty i właściwości
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Cień rzutowany | ✅ | Offset, promień rozmycia, kolor przez filtry CanvasKit |
+| Cień wewnętrzny | ✅ | Efekt cienia wewnętrznego |
+| Rozmycie warstwy | ✅ | Rozmycie gaussowskie na warstwie |
+| Rozmycie tła | ✅ | Rozmycie zawartości za warstwą |
+| Rozmycie pierwszego planu | ✅ | Rozmycie na pierwszym planie |
+| Grubość obrysu | ✅ | Konfigurowalny w panelu właściwości |
+| Zakończenie obrysu (round, square, arrow) | ✅ | NONE, ROUND, SQUARE, ARROW_LINES, ARROW_EQUILATERAL |
+| Złączenie obrysu (miter, bevel, round) | ✅ | Wszystkie trzy typy złączeń |
+| Wzory przerywane | ✅ | Wzór obrysu dash-on/dash-off |
+| Promień narożnika | ✅ | Jednolity i per narożnik z niezależnym przełącznikiem |
+| Wygładzanie narożnika (styl iOS) | 🔲 | Ciągłe zaokrąglanie narożników Figmy |
+| Wielokrotne wypełnienia/obrysy na warstwę | 🔲 | Figma pozwala na nakładanie wypełnień i obrysów |
+
+## Auto Layout
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Przepływ poziomy i pionowy | ✅ | Silnik flexbox Yoga WASM |
+| Przełącz auto layout (⇧A) | ✅ | Przełącz na ramce lub owijaj zaznaczenie |
+| Gap (odstęp między dziećmi) | ✅ | Konfigurowalny w panelu właściwości |
+| Padding (jednolity i per strona) | ✅ | Wszystkie cztery strony niezależnie |
+| Justify content | ✅ | Start, center, end, space-between |
+| Align items | ✅ | Start, center, end, stretch |
+| Wymiarowanie dzieci (stałe, wypełnij, dopasuj) | ✅ | Tryby wymiarowania per dziecko |
+| Wrap | ✅ | Flex wrap dla layoutu wieloliniowego |
+| Przepływ auto layout siatka | 🔲 | Auto layout oparty na siatce Figmy |
+| Przepływy połączone (zagnieżdżone) | ✅ | Zagnieżdżone ramki auto-layout z różnymi kierunkami |
+| Zmiana kolejności przeciąganiem w auto layout | ✅ | Wizualny wskaźnik wstawiania |
+| Min/max szerokość i wysokość | 🔲 | Figma obsługuje ograniczenia min/max |
+
+## Komponenty i systemy projektowe
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Tworzenie komponentów | 🟡 | ⌥⌘K tworzy z ramki/grupy; brak UI właściwości komponentu jeszcze |
+| Zestawy komponentów | 🟡 | ⇧⌘K łączy komponenty; przerywana fioletowa ramka; brak edycji właściwości wariantów |
+| Instancje komponentów | 🟡 | Tworzenie instancji z menu kontekstowego; sync na żywo; brak UI edycji nadpisań |
+| Warianty | 🔲 | Przełączanie wariantów i selekcja po właściwościach |
+| Właściwości komponentu | 🔲 | Właściwości boolean, tekst, zamiana instancji |
+| Propagacja nadpisań | ✅ | Zmiany w głównym komponencie propagowane; nadpisania zachowane |
+| Zmienne (kolor, liczba, string, boolean) | 🟡 | COLOR z pełnym UI; FLOAT/STRING/BOOLEAN zdefiniowane bez UI edycji |
+| Kolekcje i tryby zmiennych | 🟡 | Kolekcje, tryby, zmiana activeMode działają; brak UI tematyzacji |
+| Style (kolor, tekst, efekt, layout) | 🔲 | Presety stylów wielokrotnego użytku |
+| Biblioteki (publikuj, udostępniaj, aktualizuj) | 🔲 | Współdzielone biblioteki komponentów/stylów |
+| Odłącz instancję | ✅ | ⌥⌘B konwertuje instancję na ramkę |
+| Przejdź do głównego komponentu | ✅ | Nawigacja do komponentu źródłowego, cross-page |
+
+## Prototypowanie
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Połączenia prototypu | 🔲 | Planowane na Fazę 6 |
+| Wyzwalacze (klik, najechanie, przeciągnięcie, itp.) | 🔲 | Planowane na Fazę 6 |
+| Akcje (nawiguj, overlay, scroll, itp.) | 🔲 | Planowane na Fazę 6 |
+| Animacje i przejścia | 🔲 | Planowane na Fazę 6 |
+| Smart animate | 🔲 | Auto-animowanie pasujących warstw |
+| Overlaye | 🔲 | Prototypowanie modalne/popover |
+| Zachowanie scroll i overflow | 🔲 | Przewijalne ramki w prototypach |
+| Przepływy prototypu | 🔲 | Nazwane punkty startowe |
+| Zmienne w prototypach | 🔲 | Logika warunkowa ze zmiennymi |
+| Easing i animacje sprężynowe | 🔲 | Niestandardowe krzywe animacji |
+| Prezentuj i odtwarzaj prototypy | 🔲 | Pełnoekranowy widok prototypu |
+
+## Import i eksport
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Import pliku .fig | ✅ | Pełny kodek Kiwi: 194 definicje, ~390 pól per NodeChange |
+| Eksport pliku .fig | ✅ | Kodowanie Kiwi + kompresja Zstd + generowanie miniatur |
+| Zapisz / Zapisz jako | ✅ | ⌘S / ⇧⌘S; natywne dialogi (Tauri), File System Access API (Chrome/Edge), fallback pobierania (Safari) |
+| Schowek Figmy (wklej) | ✅ | Dekodowanie binarnego Kiwi ze schowka Figmy |
+| Schowek Figmy (kopiuj) | ✅ | Kodowanie binarnego Kiwi czytelnego przez Figmę |
+| Import pliku Sketch | 🔲 | Parsowanie plików .sketch |
+| Eksport obrazu/SVG | 🟡 | PNG/JPG/WEBP z selektorem skali i podglądem; SVG/PDF jeszcze nie |
+| Historia wersji | 🔲 | Przeglądanie i przywracanie poprzednich wersji |
+| Kopiowanie zasobów między narzędziami | 🟡 | Schowek Figmy działa; brak schowka SVG/PDF |
+
+## API pluginów i skryptowanie
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Komenda eval z Figma Plugin API | ✅ | Headless wykonywanie JavaScript z globalnym obiektem figma kompatybilnym |
+
+## Współpraca i tryb deweloperski
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Komentarze (przypinanie, wątki, rozwiązywanie) | 🔲 | Planowane na Fazę 6 |
+| Multiplayer w czasie rzeczywistym | ✅ | P2P przez Trystero + Yjs CRDT, kursory, tryb śledzenia; bez serwera |
+| Chat przy kursorze | 🔲 | Bąbelki czatu inline przy kursorze |
+| Branching i merging | 🔲 | Gałęzie wersji dla plików projektowych |
+| Tryb deweloperski (inspekcja) | 🟡 | Karta Kod pokazuje JSX; brak właściwości CSS ani specyfikacji handoff |
+| Code Connect | 🔲 | Łączenie komponentów projektowych z kodem |
+| Fragmenty kodu | 🟡 | Eksport JSX z podświetlaniem i kopiowaniem; brak fragmentów CSS/Swift/Kotlin |
+| Figma for VS Code | 🔲 | Integracja z pluginem edytora |
+| Serwer MCP | ✅ | @open-pencil/mcp z transportami stdio + HTTP; 75 narzędzi core + 3 zarządzanie plikami |
+| Narzędzia CLI | ✅ | Headless CLI: info, tree, find, export, analyze, node, pages, variables, eval; serwer MCP |
+
+## Figma Draw
+
+| Funkcja | Status | Uwagi |
+|---------|--------|-------|
+| Narzędzia ilustracji | 🔲 | Specjalistyczne narzędzia rysowania Figma Draw |
+| Transformacje wzorów | 🔲 | Tworzenie powtarzających się wzorów z transformacjami |
diff --git a/packages/docs/pl/guide/tech-stack.md b/packages/docs/pl/guide/tech-stack.md
index f91ab3de6..459361234 100644
--- a/packages/docs/pl/guide/tech-stack.md
+++ b/packages/docs/pl/guide/tech-stack.md
@@ -1,17 +1,63 @@
# Stack technologiczny
-| Layer | Technology | Why |
-|-------|-----------|-----|
-| **Rendering** | Skia CanvasKit WASM | GPU-accelerated, same as Figma |
-| **UI** | Vue 3 + VueUse | Reactive, TypeScript |
-| **Components** | Reka UI | Headless, accessible |
-| **Styling** | Tailwind CSS 4 | Utility-first |
-| **Layout** | Yoga WASM | CSS flexbox (Meta) |
-| **File Format** | Kiwi binary + Zstd | Figma .fig compatible |
-| **Desktop** | Tauri v2 | ~5 MB (vs Electron ~100 MB) |
-| **Build** | Vite 7 | Fast HMR |
-| **Testing** | Playwright + bun:test | E2E + unit |
-| **Linting** | oxlint | Rust-based |
-| **Type Checking** | typescript-go (tsgo) | Native Go |
+## Główne technologie
-[Full details in English](/guide/tech-stack)
+| Warstwa | Technologia | Dlaczego |
+|---------|-----------|----------|
+| **Renderowanie** | Skia CanvasKit WASM | Ten sam silnik co Figma — sprawdzona wydajność, akceleracja GPU, idealny piksel |
+| **Framework UI** | Vue 3 + VueUse | Reaktywne API kompozycji, doskonałe wsparcie TypeScript |
+| **Komponenty** | Reka UI | Bezgłowe, dostępne prymitywy UI (drzewo, suwak, itp.) |
+| **Stylowanie** | Tailwind CSS 4 | Utility-first, szybka iteracja, ciemny motyw |
+| **Layout** | Yoga WASM | Silnik CSS flexbox od Mety, sprawdzony w React Native |
+| **Format pliku** | Kiwi binarny + Zstd | Własny format Figmy — kompaktowy, szybkie parsowanie, kompatybilny z .fig |
+| **Współpraca** | Trystero + Yjs | P2P WebRTC przez sygnalizację MQTT, sync CRDT, persystencja y-indexeddb |
+| **Kolor** | culori | Konwersje przestrzeni kolorów (HSV, RGB, hex) |
+| **AI/MCP** | MCP SDK + Hono | 75 narzędzi dla kodowania AI, transporty stdio + HTTP |
+| **Desktop** | Tauri v2 | ~5 MB natywna aplikacja (vs ~100 MB Electrona), backend Rust |
+| **Build** | Vite 7 | Szybki HMR, natywne moduły ES |
+| **Testowanie** | Playwright + bun:test | Regresja wizualna (E2E) + szybkie testy jednostkowe |
+| **Linting** | oxlint | Oparty na Rust, rzędy wielkości szybszy niż ESLint |
+| **Formatowanie** | oxfmt | Formater oparty na Rust |
+| **Weryfikacja typów** | typescript-go (tsgo) | Natywna implementacja w Go sprawdzania typów TypeScript |
+
+## Główne zależności
+
+```json
+{
+ "canvaskit-wasm": "^0.40.0",
+ "vue": "^3.5.29",
+ "yoga-layout": "^3.2.1",
+ "reka-ui": "^2.8.2",
+ "tailwindcss": "^4.2.1",
+ "culori": "^4.0.2",
+ "fzstd": "^0.1.1",
+ "fflate": "^0.8.2",
+ "trystero": "^0.20.0",
+ "yjs": "^13.6.24",
+ "y-indexeddb": "^9.0.12"
+}
+```
+
+## Dlaczego nie...
+
+### Dlaczego nie renderowanie SVG?
+
+SVG jest wolny dla złożonych dokumentów. Każdy węzeł to element DOM — 10 000 węzłów oznacza 10 000 elementów DOM z narzutem layoutu, rysowania i kompozycji. CanvasKit rysuje wszystko na jednej powierzchni GPU.
+
+### Dlaczego nie Electron (jak Figma desktop)?
+
+Tauri v2 używa systemowego webview (~5 MB) zamiast pakowania Chromium (~100 MB). Backend Rust zapewnia natywną wydajność dla I/O plików i integracji systemowej.
+
+### Dlaczego nie React?
+
+Projekt migrował z Reacta do Vue 3 na wczesnym etapie. System reaktywności Vue i composable VueUse okazały się bardziej ergonomiczne.
+
+### Dlaczego nie własny silnik layoutu?
+
+Yoga jest utrzymywana przez Metę, przetestowana na miliardach urządzeń React Native i implementuje specyfikację CSS flexbox.
+
+## Planowane technologie
+
+| Technologia | Cel | Faza |
+|-----------|---------|-------|
+| CSS Grid w Yoga | Auto layout oparty na siatce | Zablokowane przez upstream (facebook/yoga#1893) |
diff --git a/packages/docs/pl/reference/mcp-tools.md b/packages/docs/pl/reference/mcp-tools.md
index 33f8870cb..f6b8eb587 100644
--- a/packages/docs/pl/reference/mcp-tools.md
+++ b/packages/docs/pl/reference/mcp-tools.md
@@ -24,7 +24,7 @@ Add to your MCP config (e.g. `~/.claude/settings.json` or `.cursor/mcp.json`):
}
```
-Instalacja:Lub uruchom ze źródeł:
+Lub uruchom ze źródeł:
::: code-group
```json [Bun]
@@ -73,7 +73,7 @@ Starts on port 3100 (override with `PORT` env var). Endpoints:
5. **Structure** — `reparent_node`, `group_nodes`, `clone_node`, `delete_node`
6. **Save** — `save_file` to write back to `.fig`
-## Tools (29)
+## Tools (75)
### Document
diff --git a/packages/docs/reference/mcp-tools.md b/packages/docs/reference/mcp-tools.md
index 40664ebd6..1d30cc404 100644
--- a/packages/docs/reference/mcp-tools.md
+++ b/packages/docs/reference/mcp-tools.md
@@ -81,7 +81,7 @@ Server starts on port 3100 (override with `PORT` env var). Endpoints:
5. **Structure** — `reparent_node`, `group_nodes`, `clone_node`, `delete_node`
6. **Save** — `save_file` to write back to `.fig`
-## Tools (29)
+## Tools (75)
### Document