📚 Document better the tokens value in plugins API

And add poc plugin example

.github/workflows/tests-mcp.yml

@@ -0,0 +1,45 @@
+name: "MCP CI"
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - staging
+      - main
+
+    types:
+      - opened
+      - synchronize
+
+    paths:
+      - 'mcp/**'
+
+  push:
+    branches:
+      - develop
+      - staging
+      - main
+
+    paths:
+      - 'mcp/**'
+
+jobs:
+  test:
+    name: "Test"
+    runs-on: penpot-runner-02
+    container: penpotapp/devenv:latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup
+        working-directory: ./mcp
+        run: ./scripts/setup
+
+      - name: Check
+        working-directory: ./mcp
+        run: |
+          pnpm run fmt:check;
+          pnpm -r run build;
+          pnpm -r run types:check;

backend/resources/app/templates/base.tmpl

@@ -5,7 +5,6 @@
     <meta name="robots" content="noindex,nofollow">
     <meta http-equiv="x-ua-compatible" content="ie=edge" />
     <title>{% block title %}{% endblock %}</title>
-    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=JetBrains+Mono">
     <style>
       {% include "app/templates/styles.css"  %}
     </style>

backend/resources/app/templates/error-list.tmpl

@@ -5,23 +5,25 @@ penpot - error list
 {% endblock %}
 
 {% block content %}
-<nav>
-  <div class="title">
-    <h1>Error reports (last 200)
-      <a href="/dbg">[GO BACK]</a>
-    </h1>
-  </div>
-</nav>
-<main class="horizontal-list">
-  <ul>
-    {% for item in items %}
-      <li>
-        <a class="date" href="/dbg/error/{{item.id}}">{{item.created-at}}</a>
-        <a class="hint" href="/dbg/error/{{item.id}}">
-          <span class="title">{{item.hint|abbreviate:150}}</span>
-        </a>
-      </li>
-    {% endfor %}
-  </ul>
-</main>
+  <nav>
+    <div class="title">
+      <a href="/dbg"> [BACK]</a>
+      <h1>Error reports (last 300)</h1>
+
+      <a class="{% if version = 3 %}strong{% endif %}" href="?version=3">[BACKEND ERRORS]</a>
+      <a class="{% if version = 4 %}strong{% endif %}" href="?version=4">[FRONTEND ERRORS]</a>
+    </div>
+  </nav>
+  <main class="horizontal-list">
+    <ul>
+      {% for item in items %}
+        <li>
+          <a class="date" href="/dbg/error/{{item.id}}">{{item.created-at}}</a>
+          <a class="hint" href="/dbg/error/{{item.id}}">
+            <span class="title">{{item.hint|abbreviate:150}}</span>
+          </a>
+        </li>
+      {% endfor %}
+    </ul>
+  </main>
 {% endblock %}

backend/resources/app/templates/error-report.v3.tmpl

@@ -6,7 +6,7 @@ Report: {{hint|abbreviate:150}} - {{id}} - Penpot Error Report (v3)
 
 {% block content %}
 <nav>
-  <div>[<a href="/dbg/error">⮜</a>]</div>
+  <div>[<a href="/dbg/error?version={{version}}">⮜</a>]</div>
   <div>[<a href="#head">head</a>]</div>
   <div>[<a href="#props">props</a>]</div>
   <div>[<a href="#context">context</a>]</div>

backend/resources/app/templates/error-report.v4.tmpl

@@ -0,0 +1,46 @@
+ {% extends "app/templates/base.tmpl" %}
+
+{% block title %}
+Report: {{hint|abbreviate:150}} - {{id}} - Penpot Error Report (v4)
+{% endblock %}
+
+{% block content %}
+<nav>
+  <div>[<a href="/dbg/error?version={{version}}">⮜</a>]</div>
+  <div>[<a href="#head">head</a>]</div>
+  <!-- <div>[<a href="#props">props</a>]</div> -->
+  <div>[<a href="#context">context</a>]</div>
+  {% if report %}
+  <div>[<a href="#report">report</a>]</div>
+  {% endif %}
+</nav>
+<main>
+  <div class="table">
+    <div class="table-row multiline">
+      <div id="head" class="table-key">HEAD</div>
+      <div class="table-val">
+        <h1><span class="not-important">Hint:</span> <br/> {{hint}}</h1>
+        <h2><span class="not-important">Reported at:</span> <br/> {{created-at}}</h2>
+        <h2><span class="not-important">Report ID:</span> <br/> {{id}}</h2>
+      </div>
+    </div>
+
+    <div class="table-row multiline">
+      <div id="context" class="table-key">CONTEXT: </div>
+
+      <div class="table-val">
+        <pre>{{context}}</pre>
+      </div>
+    </div>
+
+    {% if report %}
+    <div class="table-row multiline">
+      <div id="report" class="table-key">REPORT:</div>
+      <div class="table-val">
+        <pre>{{report}}</pre>
+      </div>
+    </div>
+    {% endif %}
+  </div>
+</main>
+{% endblock %}

backend/resources/app/templates/styles.css

@@ -1,5 +1,5 @@
 * {
-  font-family: "JetBrains Mono", monospace;
+  font-family: monospace;
   font-size: 12px;
 }
 
@@ -36,6 +36,10 @@ small {
   color: #888;
 }
 
+.strong {
+  font-weight: 900;
+}
+
 .not-important {
   color: #888;
   font-weight: 200;
@@ -57,14 +61,26 @@ nav {
 
 nav > .title {
   display: flex;
-  justify-content: center;
   width: 100%;
 }
 
+nav > .title > a {
+  color: black;
+  text-decoration: none;
+}
+
+nav > .title > a.strong {
+  text-decoration: underline;
+}
+
 nav > .title > h1 {
-  padding: 0px;
   margin: 0px;
   font-size: 11px;
+  display: block;
+}
+
+nav > .title > * {
+  padding: 0px 6px;
 }
 
 nav > div {

backend/src/app/http/debug.clj

@@ -232,13 +232,22 @@
             (-> (io/resource "app/templates/error-report.v3.tmpl")
                 (tmpl/render (-> content
                                  (assoc :id id)
+                                 (assoc :version 3)
+                                 (assoc :created-at (ct/format-inst created-at :rfc1123))))))
+
+          (render-template-v4 [{:keys [content id created-at]}]
+            (-> (io/resource "app/templates/error-report.v4.tmpl")
+                (tmpl/render (-> content
+                                 (assoc :id id)
+                                 (assoc :version 4)
                                  (assoc :created-at (ct/format-inst created-at :rfc1123))))))]
 
     (if-let [report (get-report request)]
       (let [result (case (:version report)
                      1 (render-template-v1 report)
                      2 (render-template-v2 report)
-                     3 (render-template-v3 report))]
+                     3 (render-template-v3 report)
+                     4 (render-template-v4 report))]
         {::yres/status 200
          ::yres/body result
          ::yres/headers {"content-type" "text/html; charset=utf-8"
@@ -246,20 +255,22 @@
       {::yres/status 404
        ::yres/body "not found"})))
 
-(def sql:error-reports
+(def ^:private sql:error-reports
   "SELECT id, created_at,
           content->>'~:hint' AS hint
      FROM server_error_report
+    WHERE version = ?
     ORDER BY created_at DESC
-    LIMIT 200")
+    LIMIT 300")
 
-(defn error-list-handler
-  [{:keys [::db/pool]} _request]
-  (let [items (->> (db/exec! pool [sql:error-reports])
-                   (map #(update % :created-at ct/format-inst :rfc1123)))]
+(defn- error-list-handler
+  [{:keys [::db/pool]} {:keys [params]}]
+  (let [version (or (some-> (get params :version) parse-long) 3)
+        items   (->> (db/exec! pool [sql:error-reports version])
+                     (map #(update % :created-at ct/format-inst :rfc1123)))]
     {::yres/status 200
      ::yres/body (-> (io/resource "app/templates/error-list.tmpl")
-                     (tmpl/render {:items items}))
+                     (tmpl/render {:items items :version version}))
      ::yres/headers {"content-type" "text/html; charset=utf-8"
                      "x-robots-tag" "noindex"}}))
 

backend/src/app/http/errors.clj

@@ -32,7 +32,7 @@
         (assoc :request/ip-addr (inet/parse-request request))
         (assoc :request/profile-id (get claims :uid))
         (assoc :request/auth-data auth)
-        (assoc :version/frontend (or (yreq/get-header request "x-frontend-version") "unknown")))))
+        (assoc :frontend/version (or (yreq/get-header request "x-frontend-version") "unknown")))))
 
 (defmulti handle-error
   (fn [cause _ _]

backend/src/app/loggers/audit.clj

@@ -113,6 +113,8 @@
 ;; COLLECTOR API
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
+(declare ^:private prepare-context-from-request)
+
 ;; Defines a service that collects the audit/activity log using
 ;; internal database. Later this audit log can be transferred to
 ;; an external storage and data cleared.
@@ -126,6 +128,8 @@
    [::props {:optional true} [:map-of :keyword :any]]
    [::context {:optional true} [:map-of :keyword :any]]
    [::tracked-at {:optional true} ::ct/inst]
+   [::created-at {:optional true} ::ct/inst]
+   [::source {:optional true} ::sm/text]
    [::webhooks/event? {:optional true} ::sm/boolean]
    [::webhooks/batch-timeout {:optional true} ::ct/duration]
    [::webhooks/batch-key {:optional true}
@@ -134,36 +138,8 @@
 (def ^:private check-event
   (sm/check-fn schema:event))
 
-(defn- prepare-context-from-request
-  [request]
-  (let [client-event-origin (get-client-event-origin request)
-        client-version      (get-client-version request)
-        client-user-agent   (get-client-user-agent request)
-        session-id          (get-external-session-id request)
-        key-id              (::http/auth-key-id request)
-        token-id            (::actoken/id request)
-        token-type          (::actoken/type request)]
-    (d/without-nils
-     {:external-session-id session-id
-      :initiator (or key-id "app")
-      :access-token-id (some-> token-id str)
-      :access-token-type (some-> token-type str)
-      :client-event-origin client-event-origin
-      :client-user-agent client-user-agent
-      :client-version client-version
-      :version (:full cf/version)})))
-
-(defn event-from-rpc-params
-  "Create a base event skeleton with pre-filled some important
-  data that can be extracted from RPC params object"
-  [params]
-  (let [context (some-> params meta ::http/request prepare-context-from-request)
-        event   {::type "action"
-                 ::profile-id (or (::rpc/profile-id params) uuid/zero)
-                 ::ip-addr (::rpc/ip-addr params)}]
-    (cond-> event
-      (some? context)
-      (assoc ::context context))))
+(def valid-event?
+  (sm/validator schema:event))
 
 (defn prepare-event
   [cfg mdata params result]
@@ -212,6 +188,38 @@
          (::webhooks/event? resultm)
          false)}))
 
+(defn- prepare-context-from-request
+  "Prepare backend event context from request"
+  [request]
+  (let [client-event-origin (get-client-event-origin request)
+        client-version      (get-client-version request)
+        client-user-agent   (get-client-user-agent request)
+        session-id          (get-external-session-id request)
+        key-id              (::http/auth-key-id request)
+        token-id            (::actoken/id request)
+        token-type          (::actoken/type request)]
+    (d/without-nils
+     {:external-session-id session-id
+      :initiator (or key-id "app")
+      :access-token-id (some-> token-id str)
+      :access-token-type (some-> token-type str)
+      :client-event-origin client-event-origin
+      :client-user-agent client-user-agent
+      :client-version client-version
+      :version (:full cf/version)})))
+
+(defn event-from-rpc-params
+  "Create a base event skeleton with pre-filled some important
+  data that can be extracted from RPC params object"
+  [params]
+  (let [context (some-> params meta ::http/request prepare-context-from-request)
+        event   {::type "action"
+                 ::profile-id (or (::rpc/profile-id params) uuid/zero)
+                 ::ip-addr (::rpc/ip-addr params)}]
+    (cond-> event
+      (some? context)
+      (assoc ::context context))))
+
 (defn- event->params
   [event]
   (let [params {:id (uuid/next)
@@ -238,8 +246,10 @@
 
 (defn- handle-event!
   [cfg event]
-  (let [params (event->params event)
-        tnow   (ct/now)]
+  (let [tnow   (ct/now)
+        params (-> (event->params event)
+                   (assoc :created-at tnow)
+                   (update :tracked-at #(or % tnow)))]
 
     (when (contains? cf/flags :audit-log-logger)
       (l/log! ::l/logger "app.audit"
@@ -255,10 +265,7 @@
       ;; NOTE: this operation may cause primary key conflicts on inserts
       ;; because of the timestamp precission (two concurrent requests), in
       ;; this case we just retry the operation.
-      (let [params (-> params
-                       (assoc :created-at tnow)
-                       (update :tracked-at #(or % tnow)))]
-        (append-audit-entry cfg params)))
+      (append-audit-entry cfg params))
 
     (when (and (or (contains? cf/flags :telemetry)
                    (cf/get :telemetry-enabled))
@@ -269,8 +276,6 @@
       ;;
       ;; NOTE: this is only executed when general audit log is disabled
       (let [params (-> params
-                       (assoc :created-at tnow)
-                       (update :tracked-at #(or % tnow))
                        (assoc :props {})
                        (assoc :context {}))]
         (append-audit-entry cfg params)))

backend/src/app/loggers/database.clj

@@ -14,6 +14,7 @@
    [app.common.schema :as sm]
    [app.config :as cf]
    [app.db :as db]
+   [app.loggers.audit :as audit]
    [clojure.spec.alpha :as s]
    [integrant.core :as ig]
    [promesa.exec :as px]
@@ -28,69 +29,108 @@
 (defonce enabled (atom true))
 
 (defn- persist-on-database!
-  [pool id report]
+  [pool id version report]
   (when-not (db/read-only? pool)
     (db/insert! pool :server-error-report
                 {:id id
-                 :version 3
+                 :version version
                  :content (db/tjson report)})))
 
+(defn- concurrent-exception?
+  [cause]
+  (or (instance? java.util.concurrent.CompletionException cause)
+      (instance? java.util.concurrent.ExecutionException cause)))
+
 (defn record->report
   [{:keys [::l/context ::l/message ::l/props ::l/logger ::l/level ::l/cause] :as record}]
   (assert (l/valid-record? record) "expectd valid log record")
-  (if (or (instance? java.util.concurrent.CompletionException cause)
-          (instance? java.util.concurrent.ExecutionException cause))
-    (-> record
-        (assoc ::trace (ex/format-throwable cause :data? true :explain? false :header? false :summary? false))
-        (assoc ::l/cause (ex-cause cause))
-        (record->report))
+  (let [data (if (concurrent-exception? cause)
+               (ex-data (ex-cause cause))
+               (ex-data cause))
 
-    (let [data (ex-data cause)
-          ctx  (-> context
-                   (assoc :tenant (cf/get :tenant))
-                   (assoc :host (cf/get :host))
-                   (assoc :public-uri (str (cf/get :public-uri)))
-                   (assoc :logger/name logger)
-                   (assoc :logger/level level)
-                   (dissoc :request/params :value :params :data))]
+        ctx  (-> context
+                 (assoc :service/tenant (cf/get :tenant))
+                 (assoc :service/host (cf/get :host))
+                 (assoc :service/public-uri (str (cf/get :public-uri)))
+                 (assoc :backend/version (:full cf/version))
+                 (assoc :logger/name logger)
+                 (assoc :logger/level level)
+                 (dissoc :request/params :value :params :data))]
 
-      (merge
-       {:context (-> (into (sorted-map) ctx)
-                     (pp/pprint-str :length 50))
-        :props   (pp/pprint-str props :length 50)
-        :hint    (or (when-let [message (ex-message cause)]
-                       (if-let [props-hint (:hint props)]
-                         (str props-hint ": " message)
-                         message))
-                     @message)
-        :trace   (or (::trace record)
-                     (some-> cause (ex/format-throwable :data? true :explain? false :header? false :summary? false)))}
+    (merge
+     {:context (-> (into (sorted-map) ctx)
+                   (pp/pprint-str :length 50))
+      :props   (pp/pprint-str props :length 50)
+      :hint    (or (when-let [message (ex-message cause)]
+                     (if-let [props-hint (:hint props)]
+                       (str props-hint ": " message)
+                       message))
+                   @message)
+      :trace   (or (::trace record)
+                   (some-> cause (ex/format-throwable :data? true :explain? false :header? false :summary? false)))}
 
-       (when-let [params (or (:request/params context) (:params context))]
-         {:params (pp/pprint-str params :length 20 :level 20)})
+     (when-let [params (or (:request/params context) (:params context))]
+       {:params (pp/pprint-str params :length 20 :level 20)})
 
-       (when-let [value (:value context)]
-         {:value (pp/pprint-str value :length 30 :level 13)})
+     (when-let [value (:value context)]
+       {:value (pp/pprint-str value :length 30 :level 13)})
 
-       (when-let [data (some-> data (dissoc ::s/problems ::s/value ::s/spec ::sm/explain :hint))]
-         {:data (pp/pprint-str data :length 30 :level 13)})
+     (when-let [data (some-> data (dissoc ::s/problems ::s/value ::s/spec ::sm/explain :hint))]
+       {:data (pp/pprint-str data :length 30 :level 13)})
 
-       (when-let [explain (ex/explain data :length 30 :level 13)]
-         {:explain explain})))))
+     (when-let [explain (ex/explain data :length 30 :level 13)]
+       {:explain explain}))))
 
-(defn error-record?
-  [{:keys [::l/level]}]
-  (= :error level))
-
-(defn- handle-event
+(defn- handle-log-record
+  "Convert the log record into a report object and persist it on the database"
   [{:keys [::db/pool]} {:keys [::l/id] :as record}]
   (try
     (let [uri    (cf/get :public-uri)
           report (-> record record->report d/without-nils)]
-      (l/debug :hint "registering error on database" :id id
-               :uri (str uri "/dbg/error/" id))
+      (l/dbg :hint "registering error on database"
+             :id id
+             :src "logging"
+             :uri (str uri "/dbg/error/" id))
+      (persist-on-database! pool id 3 report))
+    (catch Throwable cause
+      (l/warn :hint "unexpected exception on database error logger" :cause cause))))
 
-      (persist-on-database! pool id report))
+(defn- event->report
+  [{:keys [::audit/context ::audit/props ::audit/ip-addr] :as record}]
+  (let [context
+        (reduce-kv (fn [context k v]
+                     (let [k' (keyword "frontend" (name k))]
+                       (-> context
+                           (dissoc k)
+                           (assoc k' v))))
+                   context
+                   context)
+
+        context
+        (-> context
+            (assoc :backend/tenant (cf/get :tenant))
+            (assoc :backend/host (cf/get :host))
+            (assoc :backend/public-uri (str (cf/get :public-uri)))
+            (assoc :backend/version (:full cf/version))
+            (assoc :frontend/ip-addr ip-addr))]
+
+    {:context (-> (into (sorted-map) context)
+                  (pp/pprint-str :length 50))
+     :props   (pp/pprint-str props :length 50)
+     :hint    (get props :hint)
+     :report  (get props :report)}))
+
+(defn- handle-audit-event
+  "Convert the log record into a report object and persist it on the database"
+  [{:keys [::db/pool]} {:keys [::audit/id] :as event}]
+  (try
+    (let [uri    (cf/get :public-uri)
+          report (-> event event->report d/without-nils)]
+      (l/dbg :hint "registering error on database"
+             :id id
+             :src "audit-log"
+             :uri (str uri "/dbg/error/" id))
+      (persist-on-database! pool id 4 report))
     (catch Throwable cause
       (l/warn :hint "unexpected exception on database error logger" :cause cause))))
 
@@ -100,26 +140,49 @@
 
 (defmethod ig/init-key ::reporter
   [_ cfg]
-  (let [input (sp/chan :buf (sp/sliding-buffer 64)
-                       :xf  (filter error-record?))]
-    (add-watch l/log-record ::reporter #(sp/put! input %4))
+  (let [input  (sp/chan :buf (sp/sliding-buffer 256))
+        thread (px/thread
+                 {:name "penpot/reporter/database"}
+                 (l/info :hint "initializing database error persistence")
+                 (try
+                   (loop []
+                     (when-let [item (sp/take! input)]
+                       (cond
+                         (::l/id item)
+                         (handle-log-record cfg item)
 
-    (px/thread {:name "penpot/database-reporter"}
-      (l/info :hint "initializing database error persistence")
-      (try
-        (loop []
-          (when-let [record (sp/take! input)]
-            (handle-event cfg record)
-            (recur)))
-        (catch InterruptedException _
-          (l/debug :hint "reporter interrupted"))
-        (catch Throwable cause
-          (l/error :hint "unexpected error" :cause cause))
-        (finally
-          (sp/close! input)
-          (remove-watch l/log-record ::reporter)
-          (l/info :hint "reporter terminated"))))))
+                         (::audit/id item)
+                         (handle-audit-event cfg item)
+
+                         :else
+                         (l/warn :hint "received unexpected item" :item item))
+
+                       (recur)))
+
+                   (catch InterruptedException _
+                     (l/debug :hint "reporter interrupted"))
+                   (catch Throwable cause
+                     (l/error :hint "unexpected error" :cause cause))
+                   (finally
+                     (l/info :hint "reporter terminated"))))]
+
+    (add-watch l/log-record ::reporter
+               (fn [_ _ _ record]
+                 (when (= :error (::l/level record))
+                   (sp/put! input record))))
+
+    {::input input
+     ::thread thread}))
 
 (defmethod ig/halt-key! ::reporter
-  [_ thread]
-  (some-> thread px/interrupt!))
+  [_ {:keys [::input ::thread]}]
+  (remove-watch l/log-record ::reporter)
+  (sp/close! input)
+  (px/interrupt! thread))
+
+(defn emit
+  "Emit an event/report into the database reporter"
+  [cfg event]
+  (when-let [{:keys [::input]} (get cfg ::reporter)]
+    (sp/put! input event)))
+

backend/src/app/loggers/mattermost.clj

@@ -9,9 +9,10 @@
   (:require
    [app.common.exceptions :as ex]
    [app.common.logging :as l]
+   [app.common.uri :as u]
    [app.config :as cf]
    [app.http.client :as http]
-   [app.loggers.database :as ldb]
+   [app.loggers.audit :as audit]
    [app.util.json :as json]
    [integrant.core :as ig]
    [promesa.exec :as px]
@@ -20,24 +21,27 @@
 (defonce enabled (atom true))
 
 (defn- send-mattermost-notification!
-  [cfg {:keys [id public-uri] :as report}]
+  [cfg {:keys [id] :as report}]
 
 
-  (let [text (str "Exception: " public-uri "/dbg/error/" id " "
+  (let [url  (u/join (cf/get :public-uri) "/dbg/error/" id)
+
+        text (str "Exception: " url " "
                   (when-let [pid (:profile-id report)]
                     (str "(pid: #uuid-" pid ")"))
                   "\n"
                   "- host: #" (:host report) "\n"
                   "- tenant: #" (:tenant report) "\n"
-                  "- logger: #" (:logger report) "\n"
-                  "- request-path: `" (:request-path report) "`\n"
+                  "- origin: #" (:origin report) "\n"
+                  "- href: `" (:href report) "`\n"
                   "- frontend-version: `" (:frontend-version report) "`\n"
                   "- backend-version: `" (:backend-version report) "`\n"
                   "\n"
-                  "```\n"
-                  "Trace:\n"
-                  (:trace report)
-                  "```")
+                  (when-let [trace (:trace report)]
+                    (str "```\n"
+                         "Trace:\n"
+                         trace
+                         "```")))
 
         resp (http/req! cfg
                         {:uri (cf/get :error-report-webhook)
@@ -50,28 +54,49 @@
       (l/warn :hint "error on sending data"
               :response (pr-str resp)))))
 
-(defn record->report
+(defn- record->report
   [{:keys [::l/context ::l/id ::l/cause] :as record}]
   (assert (l/valid-record? record) "expectd valid log record")
+
+  (let [public-uri (cf/get :public-uri)]
+    {:id               id
+     :origin           "logging"
+     :tenant           (cf/get :tenant)
+     :host             (cf/get :host)
+     :backend-version  (:full cf/version)
+     :frontend-version (:frontend/version context)
+     :profile-id       (:request/profile-id context)
+     :href             (-> public-uri
+                           (assoc :path (:request/path context))
+                           (str))
+     :trace            (ex/format-throwable cause :detail? false :header? false)}))
+
+(defn- audit-event->report
+  [{:keys [::audit/context ::audit/props ::audit/id] :as event}]
   {:id               id
+   :origin           "audit-log"
    :tenant           (cf/get :tenant)
    :host             (cf/get :host)
-   :public-uri       (cf/get :public-uri)
-   :backend-version  (or (:version/backend context) (:full cf/version))
-   :frontend-version (:version/frontend context)
-   :profile-id       (:request/profile-id context)
-   :request-path     (:request/path context)
-   :logger           (::l/logger record)
-   :trace            (ex/format-throwable cause :detail? false :header? false)})
+   :backend-version  (:full cf/version)
+   :frontend-version (:version context)
+   :profile-id       (:audit/profile-id event)
+   :href             (get props :href)})
 
-(defn handle-event
+(defn- handle-log-record
   [cfg record]
-  (when @enabled
-    (try
-      (let [report (record->report record)]
-        (send-mattermost-notification! cfg report))
-      (catch Throwable cause
-        (l/warn :hint "unhandled error" :cause cause)))))
+  (try
+    (let [report (record->report record)]
+      (send-mattermost-notification! cfg report))
+    (catch Throwable cause
+      (l/warn :hint "unhandled error" :cause cause))))
+
+(defn- handle-audit-event
+  [cfg record]
+  (try
+    (let [report (audit-event->report record)]
+      (send-mattermost-notification! cfg report))
+    (catch Throwable cause
+      (l/warn :hint "unhandled error" :cause cause))))
 
 (defmethod ig/assert-key ::reporter
   [_ params]
@@ -80,27 +105,49 @@
 (defmethod ig/init-key ::reporter
   [_ cfg]
   (when-let [uri (cf/get :error-report-webhook)]
-    (px/thread
-      {:name "penpot/mattermost-reporter"
-       :virtual true}
-      (l/info :hint "initializing error reporter" :uri uri)
-      (let [input (sp/chan :buf (sp/sliding-buffer 128)
-                           :xf (filter ldb/error-record?))]
-        (add-watch l/log-record ::reporter #(sp/put! input %4))
-        (try
-          (loop []
-            (when-let [msg (sp/take! input)]
-              (handle-event cfg msg)
-              (recur)))
-          (catch InterruptedException _
-            (l/debug :hint "reporter interrupted"))
-          (catch Throwable cause
-            (l/error :hint "unexpected error" :cause cause))
-          (finally
-            (sp/close! input)
-            (remove-watch l/log-record ::reporter)
-            (l/info :hint "reporter terminated")))))))
+    (let [input  (sp/chan :buf (sp/sliding-buffer 256))
+          thread (px/thread
+                   {:name "penpot/reporter/mattermost"}
+                   (l/info :hint "initializing error reporter" :uri uri)
+
+                   (try
+                     (loop []
+                       (when-let [item (sp/take! input)]
+                         (when @enabled
+                           (cond
+                             (::l/id item)
+                             (handle-log-record cfg item)
+
+                             (::audit/id item)
+                             (handle-audit-event cfg item)
+
+                             :else
+                             (l/warn :hint "received unexpected item" :item item)))
+
+                         (recur)))
+                     (catch InterruptedException _
+                       (l/debug :hint "reporter interrupted"))
+                     (catch Throwable cause
+                       (l/error :hint "unexpected error" :cause cause))
+                     (finally
+                       (l/info :hint "reporter terminated"))))]
+
+      (add-watch l/log-record ::reporter
+                 (fn [_ _ _ record]
+                   (when (= :error (::l/level record))
+                     (sp/put! input record))))
+
+      {::input input
+       ::thread thread})))
 
 (defmethod ig/halt-key! ::reporter
-  [_ thread]
+  [_ {:keys [::input ::thread]}]
+  (remove-watch l/log-record ::reporter)
+  (some-> input sp/close!)
   (some-> thread px/interrupt!))
+
+(defn emit
+  "Emit an event/report into the mattermost reporter"
+  [cfg event]
+  (when-let [{:keys [::input]} (get cfg ::reporter)]
+    (sp/put! input event)))

backend/src/app/main.clj

@@ -337,7 +337,13 @@
     ::setup/props        (ig/ref ::setup/props)
 
     ::email/blacklist    (ig/ref ::email/blacklist)
-    ::email/whitelist    (ig/ref ::email/whitelist)}
+    ::email/whitelist    (ig/ref ::email/whitelist)
+
+    :app.loggers.database/reporter
+    (ig/ref :app.loggers.database/reporter)
+
+    :app.loggers.mattermost/reporter
+    (ig/ref :app.loggers.mattermost/reporter)}
 
    :app.nitrate/client
    {::http.client/client (ig/ref ::http.client/client)

backend/src/app/migrations.clj

@@ -456,7 +456,10 @@
     :fn (mg/resource "app/migrations/sql/0142-add-sso-provider-table.sql")}
 
    {:name "0143-http-session-v2-table"
-    :fn (mg/resource "app/migrations/sql/0143-add-http-session-v2-table.sql")}])
+    :fn (mg/resource "app/migrations/sql/0143-add-http-session-v2-table.sql")}
+
+   {:name "0144-mod-server-error-report-table"
+    :fn (mg/resource "app/migrations/sql/0144-mod-server-error-report-table.sql")}])
 
 (defn apply-migrations!
   [pool name migrations]

backend/src/app/migrations/sql/0144-mod-server-error-report-table.sql

@@ -0,0 +1,4 @@
+ALTER TABLE server_error_report DROP CONSTRAINT server_error_report_pkey;
+ALTER TABLE server_error_report ADD PRIMARY KEY (id);
+CREATE INDEX server_error_report__version__idx
+    ON server_error_report ( version );

backend/src/app/rpc/commands/audit.clj

@@ -16,6 +16,8 @@
    [app.db :as db]
    [app.http :as-alias http]
    [app.loggers.audit :as-alias audit]
+   [app.loggers.database :as loggers.db]
+   [app.loggers.mattermost :as loggers.mm]
    [app.rpc :as-alias rpc]
    [app.rpc.climit :as-alias climit]
    [app.rpc.doc :as-alias doc]
@@ -36,52 +38,79 @@
    :context])
 
 (defn- event->row [event]
-  [(uuid/next)
-   (:name event)
-   (:source event)
-   (:type event)
-   (:timestamp event)
-   (:created-at event)
-   (:profile-id event)
-   (db/inet (:ip-addr event))
-   (db/tjson (:props event))
-   (db/tjson (d/without-nils (:context event)))])
+  [(::audit/id event)
+   (::audit/name event)
+   (::audit/source event)
+   (::audit/type event)
+   (::audit/tracked-at event)
+   (::audit/created-at event)
+   (::audit/profile-id event)
+   (db/inet (::audit/ip-addr event))
+   (db/tjson (::audit/props event))
+   (db/tjson (d/without-nils (::audit/context event)))])
 
 (defn- adjust-timestamp
-  [{:keys [timestamp created-at] :as event}]
-  (let [margin (inst-ms (ct/diff timestamp created-at))]
+  [{:keys [::audit/tracked-at ::audit/created-at] :as event}]
+  (let [margin (inst-ms (ct/diff tracked-at created-at))]
     (if (or (neg? margin)
             (> margin 3600000))
       ;; If event is in future or lags more than 1 hour, we reasign
-      ;; timestamp to the server creation date
+      ;; tracked-at to the server creation date
       (-> event
-          (assoc :timestamp created-at)
-          (update :context assoc :original-timestamp timestamp))
+          (assoc ::audit/tracked-at created-at)
+          (update ::audit/context assoc :original-tracked-at tracked-at))
       event)))
 
-(defn- handle-events
-  [{:keys [::db/pool]} {:keys [::rpc/profile-id events] :as params}]
+(defn- exception-event?
+  [{:keys [::audit/type ::audit/name] :as ev}]
+  (and (= "action" type)
+       (or (= "unhandled-exception" name)
+           (= "exception-page" name))))
+
+(def ^:private xf:map-event-row
+  (comp
+   (map adjust-timestamp)
+   (map event->row)))
+
+(defn- get-events
+  [{:keys [::rpc/request-at ::rpc/profile-id events] :as params}]
   (let [request (-> params meta ::http/request)
         ip-addr (inet/parse-request request)
-        tnow    (ct/now)
-        xform   (comp
-                 (map (fn [event]
-                        (-> event
-                            (assoc :created-at tnow)
-                            (assoc :profile-id profile-id)
-                            (assoc :ip-addr ip-addr)
-                            (assoc :source "frontend"))))
-                 (filter :profile-id)
-                 (map adjust-timestamp)
-                 (map event->row))
-        events  (sequence xform events)]
-    (when (seq events)
-      (db/insert-many! pool :audit-log event-columns events))))
 
-(def valid-event-types
+        xform   (map (fn [event]
+                       {::audit/id (uuid/next)
+                        ::audit/type (:type event)
+                        ::audit/name (:name event)
+                        ::audit/props (:props event)
+                        ::audit/context (:context event)
+                        ::audit/profile-id profile-id
+                        ::audit/ip-addr ip-addr
+                        ::audit/source "frontend"
+                        ::audit/tracked-at (:timestamp event)
+                        ::audit/created-at request-at}))]
+
+    (sequence xform events)))
+
+(defn- handle-events
+  [{:keys [::db/pool] :as cfg} params]
+  (let [events (get-events params)]
+
+    ;; Look for error reports and save them on internal reports table
+    (when-let [events (->> events
+                           (sequence (filter exception-event?))
+                           (not-empty))]
+      (run! (partial loggers.db/emit cfg) events)
+      (run! (partial loggers.mm/emit cfg) events))
+
+    ;; Process and save events
+    (when (seq events)
+      (let [rows (sequence xf:map-event-row events)]
+        (db/insert-many! pool :audit-log event-columns rows)))))
+
+(def ^:private valid-event-types
   #{"action" "identify" "trigger"})
 
-(def schema:event
+(def ^:private schema:frontend-event
   [:map {:title "Event"}
    [:name
     [:and {:gen/elements ["update-file", "get-profile"]}
@@ -93,12 +122,13 @@
      [::sm/one-of {:format "string"} valid-event-types]]]
    [:props
     [:map-of :keyword ::sm/any]]
+   [:timestamp ::ct/inst]
    [:context {:optional true}
     [:map-of :keyword ::sm/any]]])
 
-(def schema:push-audit-events
+(def ^:private schema:push-audit-events
   [:map {:title "push-audit-events"}
-   [:events [:vector schema:event]]])
+   [:events [:vector schema:frontend-event]]])
 
 (sv/defmethod ::push-audit-events
   {::climit/id :submit-audit-events/by-profile

backend/test/backend_tests/helpers.clj

@@ -103,6 +103,14 @@
                      (assoc-in [::db/pool ::db/username] (:database-username config))
                      (assoc-in [::db/pool ::db/password] (:database-password config))
                      (assoc-in [:app.rpc/methods :app.setup/templates] templates)
+                     (assoc-in [:app.rpc/methods :app.setup/templates] templates)
+                     (update :app.rpc/methods
+                             (fn [state]
+                               (-> state
+                                   (assoc :app.setup/templates templates)
+                                   (assoc :app.loggers.mattermost/reporter nil)
+                                   (assoc :app.loggers.database/reporter nil))))
+
                      (dissoc :app.srepl/server
                              :app.http/server
                              :app.http/route

common/src/app/common/exceptions.cljc

@@ -239,22 +239,63 @@
                        (recur cause))))))]
 
        (with-out-str
-         (print-all cause)))))
+         (print-all cause))))
+
+   :cljs
+   (defn format-throwable
+     [cause & {:as opts}]
+     (with-out-str
+       (when-let [exdata (ex-data cause)]
+         (when-let [hint (get exdata :hint)]
+           (when (str/index-of hint "\n")
+             (println "Hint:")
+             (println "--------------------")
+             (println hint)
+             (println)))
+
+         (when-let [explain (get exdata ::sm/explain)]
+           (println "Explain:")
+           (println "--------------------")
+
+           (println (sm/humanize-explain explain))
+           (println))
+
+         (when-let [explain (get exdata :explain)]
+           (println "Server Explain:")
+           (println "--------------------")
+           (println explain))
+
+         (println "Data:")
+         (println "--------------------")
+         (pp/pprint (dissoc exdata ::sm/explain :explain))
+         (println))
+
+       (when-let [trace (.-stack cause)]
+         (println "Trace:")
+         (println "--------------------")
+         (println (.-stack cause))))))
+
+(defn first-line
+  [s]
+  (let [break-index (str/index-of s "\n")]
+    (if (pos? break-index)
+      (subs s 0 break-index)
+      s)))
 
 (defn print-throwable
   [cause & {:as opts}]
   #?(:clj
      (println (format-throwable cause opts))
      :cljs
-     (let [prefix (get opts :prefix "exception")
-           title  (str prefix ": " (ex-message cause))
-           exdata (ex-data cause)]
+     (let [prefix (get opts :prefix)
+           data   (ex-data cause)
+           title  (cond->> (or (some-> (:hint data) first-line)
+                               (ex-message cause))
+                    (string? prefix)
+                    (str prefix ": "))]
+
        (js/console.group title)
-       (when-let [explain (get exdata ::sm/explain)]
-         (println (sm/humanize-explain explain)))
-
-       (js/console.log "\nData:")
-       (pp/pprint (dissoc exdata ::sm/explain))
-
-       (js/console.log "\nTrace:")
-       (js/console.error (.-stack cause)))))
+       (try
+         (js/console.log (format-throwable cause))
+         (finally
+           (js/console.groupEnd))))))

docker/devenv/Dockerfile

@@ -181,7 +181,8 @@ FROM base AS setup-utils
 
 ENV CLJKONDO_VERSION=2026.01.19 \
     BABASHKA_VERSION=1.12.208 \
-    CLJFMT_VERSION=0.15.6
+    CLJFMT_VERSION=0.15.6 \
+    PIXI_VERSION=0.63.2
 
 RUN set -ex; \
     ARCH="$(dpkg --print-architecture)"; \
@@ -224,6 +225,26 @@ RUN set -ex; \
     tar -xf /tmp/babashka.tar.gz; \
     rm -rf /tmp/babashka.tar.gz;
 
+RUN set -ex; \
+    ARCH="$(dpkg --print-architecture)"; \
+    case "${ARCH}" in \
+       aarch64|arm64) \
+         BINARY_URL="https://github.com/prefix-dev/pixi/releases/download/v$PIXI_VERSION/pixi-aarch64-unknown-linux-musl.tar.gz"; \
+         ;; \
+       amd64|x86_64) \
+         BINARY_URL="https://github.com/prefix-dev/pixi/releases/download/v$PIXI_VERSION/pixi-x86_64-unknown-linux-musl.tar.gz"; \
+         ;; \
+       *) \
+         echo "Unsupported arch: ${ARCH}"; \
+         exit 1; \
+         ;; \
+    esac; \
+    cd /tmp; \
+    curl -LfsSo /tmp/pixi.tar.gz ${BINARY_URL}; \
+    cd /opt/utils/bin; \
+    tar -xf /tmp/pixi.tar.gz; \
+    rm -rf /tmp/pixi.tar.gz;
+
 RUN set -ex; \
     ARCH="$(dpkg --print-architecture)"; \
     case "${ARCH}" in \

docker/devenv/docker-compose.yaml

@@ -46,6 +46,11 @@ services:
       - 9090:9090
       - 9091:9091
 
+      # MCP
+      - 4400:4400
+      - 4401:4401
+      - 4402:4402
+
     environment:
       - EXTERNAL_UID=${CURRENT_USER_ID}
       # SMTP setup

docker/devenv/files/nginx.conf

@@ -121,6 +121,28 @@ http {
             proxy_http_version 1.1;
         }
 
+        location /mcp {
+            alias /home/penpot/penpot/mcp/packages/plugin/dist;
+            proxy_http_version 1.1;
+        }
+
+        location /mcp/ws {
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_pass http://127.0.0.1:4402;
+            proxy_http_version 1.1;
+        }
+
+        location /mcp/stream {
+            proxy_pass http://127.0.0.1:4401/mcp;
+            proxy_http_version 1.1;
+        }
+
+        location /mcp/sse {
+            proxy_pass http://127.0.0.1:4401/sse;
+            proxy_http_version 1.1;
+        }
+
         location /admin {
             proxy_pass http://127.0.0.1:6063/admin;
         }

docker/images/Dockerfile.mcp

@@ -0,0 +1,58 @@
+FROM ubuntu:24.04
+LABEL maintainer="Penpot <docker@penpot.app>"
+
+ENV LANG=en_US.UTF-8 \
+    LC_ALL=en_US.UTF-8 \
+    NODE_VERSION=v22.21.1 \
+    DEBIAN_FRONTEND=noninteractive \
+    PATH=/opt/node/bin:$PATH
+
+RUN set -ex; \
+    useradd -U -M -u 1001 -s /bin/false -d /opt/penpot penpot; \
+    mkdir -p /etc/resolvconf/resolv.conf.d; \
+    echo "nameserver 127.0.0.11" > /etc/resolvconf/resolv.conf.d/tail; \
+    apt-get -qq update; \
+    apt-get -qqy --no-install-recommends install \
+      curl \
+      tzdata \
+      locales \
+      ca-certificates \
+    ; \
+    rm -rf /var/lib/apt/lists/*; \
+    echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen; \
+    locale-gen; \
+    find /usr/share/i18n/locales/ -type f ! -name "en_US" ! -name "POSIX" ! -name "C" -delete;
+
+RUN set -eux; \
+    ARCH="$(dpkg --print-architecture)"; \
+    case "${ARCH}" in \
+       aarch64|arm64) \
+         BINARY_URL="https://nodejs.org/dist/${NODE_VERSION}/node-${NODE_VERSION}-linux-arm64.tar.gz"; \
+         ;; \
+       amd64|x86_64) \
+         BINARY_URL="https://nodejs.org/dist/${NODE_VERSION}/node-${NODE_VERSION}-linux-x64.tar.gz"; \
+         ;; \
+       *) \
+         echo "Unsupported arch: ${ARCH}"; \
+         exit 1; \
+         ;; \
+    esac; \
+    curl -LfsSo /tmp/nodejs.tar.gz ${BINARY_URL}; \
+    mkdir -p /opt/node; \
+    cd /opt/node; \
+    tar -xf /tmp/nodejs.tar.gz --strip-components=1; \
+    chown -R root /opt/node; \
+    rm -rf /tmp/nodejs.tar.gz; \
+    corepack enable; \
+    mkdir -p /opt/penpot; \
+    chown -R penpot:penpot /opt/penpot;
+
+ARG BUNDLE_PATH="./bundle-mcp/"
+COPY --chown=penpot:penpot $BUNDLE_PATH /opt/penpot/mcp/
+
+WORKDIR /opt/penpot/mcp
+USER penpot:penpot
+
+RUN ./setup
+
+CMD ["node", "index.js", "--multi-user"]

docker/images/docker-compose.yaml

@@ -198,6 +198,13 @@ services:
       ## Valkey (or previously Redis) is used for the websockets notifications.
       PENPOT_REDIS_URI: redis://penpot-valkey/0
 
+  penpot-mcp:
+    image: penpotapp/mcp:${PENPOT_VERSION:-latest}
+    restart: always
+
+    networks:
+      - penpot
+
   penpot-postgres:
     image: "postgres:15"
     restart: always

docker/images/files/nginx.conf.template

@@ -130,6 +130,7 @@ http {
         }
 
         location /readyz {
+            access_log off;
             proxy_pass $PENPOT_BACKEND_URI$request_uri;
         }
 

frontend/playwright.config.js

@@ -1,4 +1,5 @@
 import { defineConfig, devices } from "@playwright/test";
+import { platform } from "os";
 
 /**
  * Read environment variables from file.
@@ -6,6 +7,10 @@ import { defineConfig, devices } from "@playwright/test";
  */
 // require('dotenv').config();
 
+const userAgent = platform === 'darwin' ?
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" :
+  undefined;
+
 /**
  * @see https://playwright.dev/docs/test-configuration
  */
@@ -43,12 +48,20 @@ export default defineConfig({
   projects: [
     {
       name: "default",
-      use: { ...devices["Desktop Chrome"] },
       testDir: "./playwright/ui/specs",
       use: {
+        ...devices["Desktop Chrome"],
+        viewport: { width: 1920, height: 1080 }, // Add custom viewport size
         video: 'retain-on-failure',
         trace: 'retain-on-failure',
-      }
+        userAgent,
+      },
+      snapshotPathTemplate: "{testDir}/{testFilePath}-snapshots/{arg}.png",
+      expect: {
+        toHaveScreenshot: {
+          maxDiffPixelRatio: 0.001,
+        },
+      },
     },
     {
       name: "ds",

frontend/playwright/data/workspace/create-file-object-thumbnail.json

@@ -0,0 +1,7 @@
+{
+  "~:file-id": "~u8d38942d-b01f-800e-8007-79ee6a9bac45",
+  "~:tag": "component",
+  "~:object-id": "8d38942d-b01f-800e-8007-79ee6a9bac45/8d38942d-b01f-800e-8007-79ee6a9bac46/6b68aedd-4c5b-80b9-8007-7b38c1d34ce4/component",
+  "~:media-id": "~ube2dc82e-615b-486b-a193-8768bdb51d7a",
+  "~:created-at": "~m1769523563389"
+}

frontend/playwright/ui/pages/WorkspacePage.js

@@ -253,7 +253,7 @@ export class WorkspacePage extends BaseWebSocketPage {
 
   async #waitForWebSocketReadiness() {
     // TODO: find a better event to settle whether the app is ready to receive notifications via ws
-    await expect(this.pageName).toHaveText("Page 1");
+    await expect(this.pageName).toHaveText("Page 1", { timeout: 30000 })
   }
 
   async sendPresenceMessage(fixture) {
@@ -383,19 +383,46 @@ export class WorkspacePage extends BaseWebSocketPage {
     await this.page.keyboard.press("T");
     await this.page.waitForTimeout(timeToWait);
     await this.clickAndMove(x1, y1, x2, y2);
-    await this.page.waitForTimeout(timeToWait);
+    await expect(this.page.getByTestId("text-editor")).toBeVisible();
+
     if (initialText) {
       await this.page.keyboard.type(initialText);
     }
   }
 
   /**
-   * Copies the selected element into the clipboard.
+   * Copies the selected element into the clipboard, or copy the
+   * content of the locator into the clipboard.
    *
    * @returns {Promise<void>}
    */
-  async copy() {
-    return this.page.keyboard.press("Control+C");
+  async copy(kind = "keyboard", locator = undefined) {
+    if (kind === "context-menu" && locator) {
+      await locator.click({ button: "right" });
+      await this.page.getByText("Copy", { exact: true }).click();
+    } else {
+      await this.page.keyboard.press("ControlOrMeta+C");
+    }
+    // wait for the clipboard to be updated
+    await this.page.waitForFunction(async () => {
+      const content = await navigator.clipboard.readText()
+      return content !== "";
+    }, { timeout: 1000 });
+  }
+
+  async cut(kind = "keyboard", locator = undefined) {
+    if (kind === "context-menu" && locator) {
+      await locator.click({ button: "right" });
+      await this.page.getByText("Cut", { exact: true }).click();
+    } else {
+      await this.page.keyboard.press("ControlOrMeta+X");
+    }
+    // wait for the clipboard to be updated
+    await this.page.waitForFunction(async () => {
+      const content = await navigator.clipboard.readText()
+      return content !== "";
+    }, { timeout: 1000 });
+
   }
 
   /**
@@ -407,9 +434,9 @@ export class WorkspacePage extends BaseWebSocketPage {
   async paste(kind = "keyboard") {
     if (kind === "context-menu") {
       await this.viewport.click({ button: "right" });
-      return this.page.getByText("PasteCtrlV").click();
+      return this.page.getByText("Paste", { exact: true }).click();
     }
-    return this.page.keyboard.press("Control+V");
+    return this.page.keyboard.press("ControlOrMeta+V");
   }
 
   async panOnViewportAt(x, y, width, height) {
@@ -448,11 +475,11 @@ export class WorkspacePage extends BaseWebSocketPage {
     const layer = this.layers
       .getByTestId("layer-row")
       .filter({ hasText: name });
-    const button = layer.getByRole("button");
+    const button = layer.getByTestId("toggle-content");
 
-    await button.waitFor();
+    await expect(button).toBeVisible();
     await button.click(clickOptions);
-    await this.page.waitForTimeout(500);
+    await button.waitFor({ ariaExpanded: true });
   }
 
   async expectSelectedLayer(name) {
@@ -495,13 +522,7 @@ export class WorkspacePage extends BaseWebSocketPage {
 
   async clickColorPalette(clickOptions = {}) {
     await this.palette
-      .getByRole("button", { name: "Color Palette (Alt+P)" })
-      .click(clickOptions);
-  }
-
-  async clickColorPalette(clickOptions = {}) {
-    await this.palette
-      .getByRole("button", { name: "Color Palette (Alt+P)" })
+      .getByRole("button", { name: /Color Palette/ })
       .click(clickOptions);
   }
 

frontend/playwright/ui/specs/onboarding.spec.js

@@ -15,6 +15,8 @@ test("User can complete the onboarding", async ({ page }) => {
   const dashboardPage = new DashboardPage(page);
   const onboardingPage = new OnboardingPage(page);
 
+  await dashboardPage.mockConfigFlags(["enable-onboarding"]);
+
   await dashboardPage.goToDashboard();
   await expect(
     page.getByRole("heading", { name: "Help us get to know you" }),

frontend/playwright/ui/specs/render-wasm.spec.js

@@ -1,5 +1,5 @@
 import { test, expect } from "@playwright/test";
-import { WasmWorkspacePage, WASM_FLAGS } from "../pages/WasmWorkspacePage";
+import { WasmWorkspacePage } from "../pages/WasmWorkspacePage";
 
 test.beforeEach(async ({ page }) => {
   await WasmWorkspacePage.init(page);

frontend/playwright/ui/specs/text-editor-v2.spec.js

@@ -5,7 +5,7 @@ import { WorkspacePage } from "../pages/WorkspacePage";
 const timeToWait = 100;
 
 test.beforeEach(async ({ page, context }) => {
-  await Clipboard.enable(context, Clipboard.Permission.ONLY_WRITE);
+  await Clipboard.enable(context, Clipboard.Permission.ALL);
 
   await WorkspacePage.init(page);
   await WorkspacePage.mockConfigFlags(page, ["enable-feature-text-editor-v2"]);

frontend/playwright/ui/specs/tokens/crud.spec.js

@@ -158,7 +158,7 @@ test.describe("Tokens - creation", () => {
     const selfReferenceError = "Token has self reference";
     const missingReferenceError = "Missing token references";
     const { tokensUpdateCreateModal, tokenThemesSetsSidebar, tokensSidebar } =
-          await setupEmptyTokensFile(page);
+      await setupEmptyTokensFile(page);
 
     await tokensSidebar
       .getByRole("button", { name: "Add Token: Color" })
@@ -189,7 +189,7 @@ test.describe("Tokens - creation", () => {
     // 2. Invalid value → disabled + error message
     await valueField.fill("1");
     const invalidValueErrorNode =
-          tokensUpdateCreateModal.getByText(invalidValueError);
+      tokensUpdateCreateModal.getByText(invalidValueError);
     await expect(invalidValueErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
 
@@ -197,7 +197,7 @@ test.describe("Tokens - creation", () => {
     await nameField.fill("");
 
     const emptyNameErrorNode =
-          tokensUpdateCreateModal.getByText(emptyNameError);
+      tokensUpdateCreateModal.getByText(emptyNameError);
 
     await expect(emptyNameErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -207,7 +207,7 @@ test.describe("Tokens - creation", () => {
     await valueField.fill("{color.primary}");
 
     const selfRefErrorNode =
-          tokensUpdateCreateModal.getByText(selfReferenceError);
+      tokensUpdateCreateModal.getByText(selfReferenceError);
 
     await expect(selfRefErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -320,7 +320,7 @@ test.describe("Tokens - creation", () => {
     const missingReferenceError = "Missing token references";
 
     const { tokensUpdateCreateModal, tokenThemesSetsSidebar } =
-          await setupEmptyTokensFile(page);
+      await setupEmptyTokensFile(page);
 
     // Open modal
     const tokensTabPanel = page.getByRole("tabpanel", { name: "tokens" });
@@ -356,7 +356,7 @@ test.describe("Tokens - creation", () => {
     await nameField.fill("");
 
     const emptyNameErrorNode =
-          tokensUpdateCreateModal.getByText(emptyNameError);
+      tokensUpdateCreateModal.getByText(emptyNameError);
 
     await expect(emptyNameErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -366,7 +366,7 @@ test.describe("Tokens - creation", () => {
     await valueField.fill("{my-token}");
 
     const selfRefErrorNode =
-          tokensUpdateCreateModal.getByText(selfReferenceError);
+      tokensUpdateCreateModal.getByText(selfReferenceError);
 
     await expect(selfRefErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -459,13 +459,13 @@ test.describe("Tokens - creation", () => {
 
   test("User creates font weight token", async ({ page }) => {
     const invalidValueError =
-          "Invalid font weight value: use numeric values (100-950) or standard names (thin, light, regular, bold, etc.) optionally followed by 'Italic'";
+      "Invalid font weight value: use numeric values (100-950) or standard names (thin, light, regular, bold, etc.) optionally followed by 'Italic'";
     const emptyNameError = "Name should be at least 1 character";
     const selfReferenceError = "Token has self reference";
     const missingReferenceError = "Missing token references";
 
     const { tokensUpdateCreateModal, tokenThemesSetsSidebar } =
-          await setupEmptyTokensFile(page);
+      await setupEmptyTokensFile(page);
 
     // Open modal
     const tokensTabPanel = page.getByRole("tabpanel", { name: "tokens" });
@@ -501,7 +501,7 @@ test.describe("Tokens - creation", () => {
     await valueField.fill("red");
 
     const invalidValueErrorNode =
-          tokensUpdateCreateModal.getByText(invalidValueError);
+      tokensUpdateCreateModal.getByText(invalidValueError);
 
     await expect(invalidValueErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -510,7 +510,7 @@ test.describe("Tokens - creation", () => {
     await nameField.fill("");
 
     const emptyNameErrorNode =
-          tokensUpdateCreateModal.getByText(emptyNameError);
+      tokensUpdateCreateModal.getByText(emptyNameError);
 
     await expect(emptyNameErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -520,7 +520,7 @@ test.describe("Tokens - creation", () => {
     await valueField.fill("{my-token}");
 
     const selfRefErrorNode =
-          tokensUpdateCreateModal.getByText(selfReferenceError);
+      tokensUpdateCreateModal.getByText(selfReferenceError);
 
     await expect(selfRefErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -595,13 +595,13 @@ test.describe("Tokens - creation", () => {
 
   test("User creates text case token", async ({ page }) => {
     const invalidValueError =
-          "Invalid token value: only none, Uppercase, Lowercase or Capitalize are accepted";
+      "Invalid token value: only none, Uppercase, Lowercase or Capitalize are accepted";
     const emptyNameError = "Name should be at least 1 character";
     const selfReferenceError = "Token has self reference";
     const missingReferenceError = "Missing token references";
 
     const { tokensUpdateCreateModal, tokenThemesSetsSidebar } =
-          await setupEmptyTokensFile(page);
+      await setupEmptyTokensFile(page);
 
     // Open modal
     const tokensTabPanel = page.getByRole("tabpanel", { name: "tokens" });
@@ -637,7 +637,7 @@ test.describe("Tokens - creation", () => {
     await valueField.fill("red");
 
     const invalidValueErrorNode =
-          tokensUpdateCreateModal.getByText(invalidValueError);
+      tokensUpdateCreateModal.getByText(invalidValueError);
 
     await expect(invalidValueErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -646,7 +646,7 @@ test.describe("Tokens - creation", () => {
     await nameField.fill("");
 
     const emptyNameErrorNode =
-          tokensUpdateCreateModal.getByText(emptyNameError);
+      tokensUpdateCreateModal.getByText(emptyNameError);
 
     await expect(emptyNameErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -656,7 +656,7 @@ test.describe("Tokens - creation", () => {
     await valueField.fill("{my-token}");
 
     const selfRefErrorNode =
-          tokensUpdateCreateModal.getByText(selfReferenceError);
+      tokensUpdateCreateModal.getByText(selfReferenceError);
 
     await expect(selfRefErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -711,13 +711,13 @@ test.describe("Tokens - creation", () => {
 
   test("User creates text decoration token", async ({ page }) => {
     const invalidValueError =
-          "Invalid token value: only none, underline and strike-through are accepted";
+      "Invalid token value: only none, underline and strike-through are accepted";
     const emptyNameError = "Name should be at least 1 character";
     const selfReferenceError = "Token has self reference";
     const missingReferenceError = "Missing token references";
 
     const { tokensUpdateCreateModal, tokenThemesSetsSidebar } =
-          await setupEmptyTokensFile(page);
+      await setupEmptyTokensFile(page);
 
     // Open modal
     const tokensTabPanel = page.getByRole("tabpanel", { name: "tokens" });
@@ -755,7 +755,7 @@ test.describe("Tokens - creation", () => {
     await valueField.fill("red");
 
     const invalidValueErrorNode =
-          tokensUpdateCreateModal.getByText(invalidValueError);
+      tokensUpdateCreateModal.getByText(invalidValueError);
 
     await expect(invalidValueErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -764,7 +764,7 @@ test.describe("Tokens - creation", () => {
     await nameField.fill("");
 
     const emptyNameErrorNode =
-          tokensUpdateCreateModal.getByText(emptyNameError);
+      tokensUpdateCreateModal.getByText(emptyNameError);
 
     await expect(emptyNameErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -774,7 +774,7 @@ test.describe("Tokens - creation", () => {
     await valueField.fill("{my-token}");
 
     const selfRefErrorNode =
-          tokensUpdateCreateModal.getByText(selfReferenceError);
+      tokensUpdateCreateModal.getByText(selfReferenceError);
 
     await expect(selfRefErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -831,7 +831,7 @@ test.describe("Tokens - creation", () => {
     const emptyNameError = "Name should be at least 1 character";
 
     const { tokensUpdateCreateModal, tokenThemesSetsSidebar } =
-          await setupEmptyTokensFile(page, { flags: ["enable-token-shadow"] });
+      await setupEmptyTokensFile(page, { flags: ["enable-token-shadow"] });
 
     // Open modal
     const tokensTabPanel = page.getByRole("tabpanel", { name: "tokens" });
@@ -900,7 +900,7 @@ test.describe("Tokens - creation", () => {
     await nameField.fill("");
 
     const emptyNameErrorNode =
-          tokensUpdateCreateModal.getByText(emptyNameError);
+      tokensUpdateCreateModal.getByText(emptyNameError);
 
     await expect(emptyNameErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -977,9 +977,9 @@ test.describe("Tokens - creation", () => {
 
     await nameField.fill("my-token-2");
     const referenceToggle =
-          tokensUpdateCreateModal.getByTestId("reference-opt");
+      tokensUpdateCreateModal.getByTestId("reference-opt");
     const compositeToggle =
-          tokensUpdateCreateModal.getByTestId("composite-opt");
+      tokensUpdateCreateModal.getByTestId("composite-opt");
     await referenceToggle.click();
 
     const referenceInput = tokensUpdateCreateModal.getByPlaceholder(
@@ -1012,7 +1012,7 @@ test.describe("Tokens - creation", () => {
     page,
   }) => {
     const { tokensUpdateCreateModal, tokenThemesSetsSidebar, tokensSidebar } =
-          await setupTypographyTokensFile(page);
+      await setupTypographyTokensFile(page);
 
     const tokensTabPanel = page.getByRole("tabpanel", { name: "tokens" });
     await tokensTabPanel
@@ -1038,7 +1038,7 @@ test.describe("Tokens - creation", () => {
 
     // Switch to reference tab, should not be submittable either
     const referenceTabButton =
-          tokensUpdateCreateModal.getByTestId("reference-opt");
+      tokensUpdateCreateModal.getByTestId("reference-opt");
     await referenceTabButton.click();
     await expect(submitButton).toBeDisabled();
   });
@@ -1047,7 +1047,7 @@ test.describe("Tokens - creation", () => {
     const emptyNameError = "Name should be at least 1 character";
 
     const { tokensUpdateCreateModal, tokenThemesSetsSidebar } =
-          await setupEmptyTokensFile(page, {flags: ["enable-token-shadow"]});
+      await setupEmptyTokensFile(page, { flags: ["enable-token-shadow"] });
 
     // Open modal
     const tokensTabPanel = page.getByRole("tabpanel", { name: "tokens" });
@@ -1116,7 +1116,7 @@ test.describe("Tokens - creation", () => {
     await nameField.fill("");
 
     const emptyNameErrorNode =
-          tokensUpdateCreateModal.getByText(emptyNameError);
+      tokensUpdateCreateModal.getByText(emptyNameError);
 
     await expect(emptyNameErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -1198,9 +1198,9 @@ test.describe("Tokens - creation", () => {
 
     await nameField.fill("my-token-2");
     const referenceToggle =
-          tokensUpdateCreateModal.getByTestId("reference-opt");
+      tokensUpdateCreateModal.getByTestId("reference-opt");
     const compositeToggle =
-          tokensUpdateCreateModal.getByTestId("composite-opt");
+      tokensUpdateCreateModal.getByTestId("composite-opt");
     await referenceToggle.click();
 
     const referenceInput = tokensUpdateCreateModal.getByPlaceholder(
@@ -1232,7 +1232,7 @@ test.describe("Tokens - creation", () => {
   test("User creates typography token", async ({ page }) => {
     const emptyNameError = "Name should be at least 1 character";
     const { tokensUpdateCreateModal, tokenThemesSetsSidebar } =
-          await setupEmptyTokensFile(page);
+      await setupEmptyTokensFile(page);
 
     // Open modal
     const tokensTabPanel = page.getByRole("tabpanel", { name: "tokens" });
@@ -1287,7 +1287,7 @@ test.describe("Tokens - creation", () => {
     await nameField.fill("");
 
     const emptyNameErrorNode =
-          tokensUpdateCreateModal.getByText(emptyNameError);
+      tokensUpdateCreateModal.getByText(emptyNameError);
 
     await expect(emptyNameErrorNode).toBeVisible();
     await expect(submitButton).toBeDisabled();
@@ -1443,9 +1443,9 @@ test.describe("Tokens - creation", () => {
     await nameField.fill("my-token-2");
 
     const referenceToggle =
-          tokensUpdateCreateModal.getByTestId("reference-opt");
+      tokensUpdateCreateModal.getByTestId("reference-opt");
     const compositeToggle =
-          tokensUpdateCreateModal.getByTestId("composite-opt");
+      tokensUpdateCreateModal.getByTestId("composite-opt");
 
     await referenceToggle.click();
 
@@ -1479,7 +1479,7 @@ test.describe("Tokens - creation", () => {
 
   test("User adds typography token with reference", async ({ page }) => {
     const { tokensUpdateCreateModal, tokenThemesSetsSidebar, tokensSidebar } =
-          await setupTypographyTokensFile(page);
+      await setupTypographyTokensFile(page);
 
     const newTokenTitle = "NewReference";
 
@@ -1508,7 +1508,7 @@ test.describe("Tokens - creation", () => {
     });
 
     const resolvedValue =
-          await tokensUpdateCreateModal.getByText("Resolved value:");
+      await tokensUpdateCreateModal.getByText("Resolved value:");
     await expect(resolvedValue).toBeVisible();
     await expect(resolvedValue).toContainText("Font Family: 42dot Sans");
     await expect(resolvedValue).toContainText("Font Size: 100");
@@ -1531,7 +1531,7 @@ test.describe("Tokens - creation", () => {
 
   test("User creates grouped color token", async ({ page }) => {
     const { workspacePage, tokensUpdateCreateModal, tokensSidebar } =
-          await setupEmptyTokensFile(page);
+      await setupEmptyTokensFile(page);
 
     await tokensSidebar
       .getByRole("button", { name: "Add Token: Color" })
@@ -1591,7 +1591,7 @@ test.describe("Tokens - creation", () => {
 
   test("User duplicate color token", async ({ page }) => {
     const { tokensSidebar, tokenContextMenuForToken } =
-          await setupTokensFile(page);
+      await setupTokensFile(page);
 
     await expect(tokensSidebar).toBeVisible();
 
@@ -1613,15 +1613,11 @@ test.describe("Tokens - creation", () => {
   });
 });
 
-
-
 test("User creates grouped color token", async ({ page }) => {
   const { workspacePage, tokensUpdateCreateModal, tokensSidebar } =
-        await setupEmptyTokensFile(page);
+    await setupEmptyTokensFile(page);
 
-  await tokensSidebar
-    .getByRole("button", { name: "Add Token: Color" })
-    .click();
+  await tokensSidebar.getByRole("button", { name: "Add Token: Color" }).click();
 
   // Create grouped color token with mouse
 
@@ -1647,9 +1643,7 @@ test("User creates grouped color token", async ({ page }) => {
   await expect(tokensSidebar.getByLabel("primary")).toBeEnabled();
 });
 
-test("User cant create regular token with value missing", async ({
-  page,
-}) => {
+test("User cant create regular token with value missing", async ({ page }) => {
   const { tokensUpdateCreateModal } = await setupEmptyTokensFile(page);
 
   const tokensTabPanel = page.getByRole("tabpanel", { name: "tokens" });
@@ -1677,7 +1671,7 @@ test("User cant create regular token with value missing", async ({
 
 test("User duplicate color token", async ({ page }) => {
   const { tokensSidebar, tokenContextMenuForToken } =
-        await setupTokensFile(page);
+    await setupTokensFile(page);
 
   await expect(tokensSidebar).toBeVisible();
 
@@ -1703,7 +1697,7 @@ test.describe("Tokens tab - edition", () => {
     page,
   }) => {
     const { tokensUpdateCreateModal, tokenThemesSetsSidebar, tokensSidebar } =
-          await setupTypographyTokensFile(page);
+      await setupTypographyTokensFile(page);
 
     await tokensSidebar
       .getByRole("button")
@@ -1724,8 +1718,8 @@ test.describe("Tokens tab - edition", () => {
 
     // Fill font-family to verify to verify that input value doesn't get split into list of characters
     const fontFamilyField = tokensUpdateCreateModal
-          .getByLabel("Font family")
-          .first();
+      .getByLabel("Font family")
+      .first();
     await fontFamilyField.fill("OneWord");
 
     // Invalidate incorrect values for font size
@@ -1746,11 +1740,11 @@ test.describe("Tokens tab - edition", () => {
 
     const fontWeightField = tokensUpdateCreateModal.getByLabel(/Font Weight/i);
     const letterSpacingField =
-          tokensUpdateCreateModal.getByLabel(/Letter Spacing/i);
+      tokensUpdateCreateModal.getByLabel(/Letter Spacing/i);
     const lineHeightField = tokensUpdateCreateModal.getByLabel(/Line Height/i);
     const textCaseField = tokensUpdateCreateModal.getByLabel(/Text Case/i);
     const textDecorationField =
-          tokensUpdateCreateModal.getByLabel(/Text Decoration/i);
+      tokensUpdateCreateModal.getByLabel(/Text Decoration/i);
 
     // Capture all values before switching tabs
     const originalValues = {
@@ -1765,14 +1759,14 @@ test.describe("Tokens tab - edition", () => {
 
     // Switch to reference tab and back to composite tab
     const referenceTabButton =
-          tokensUpdateCreateModal.getByTestId("reference-opt");
+      tokensUpdateCreateModal.getByTestId("reference-opt");
     await referenceTabButton.click();
 
     // Empty reference tab should be disabled
     await expect(saveButton).toBeDisabled();
 
     const compositeTabButton =
-          tokensUpdateCreateModal.getByTestId("composite-opt");
+      tokensUpdateCreateModal.getByTestId("composite-opt");
     await compositeTabButton.click();
 
     // Filled composite tab should be enabled
@@ -1799,7 +1793,7 @@ test.describe("Tokens tab - edition", () => {
     page,
   }) => {
     const { tokensUpdateCreateModal, tokensSidebar, tokenContextMenuForToken } =
-          await setupTokensFile(page);
+      await setupTokensFile(page);
 
     await expect(tokensSidebar).toBeVisible();
 
@@ -1835,7 +1829,7 @@ test.describe("Tokens tab - edition", () => {
     page,
   }) => {
     const { workspacePage, tokensUpdateCreateModal, tokenThemesSetsSidebar } =
-          await setupEmptyTokensFile(page);
+      await setupEmptyTokensFile(page);
 
     const tokensTabPanel = page.getByRole("tabpanel", { name: "tokens" });
     await tokensTabPanel
@@ -1890,7 +1884,7 @@ test.describe("Tokens tab - edition", () => {
 test.describe("Tokens tab - delete", () => {
   test("User delete color token", async ({ page }) => {
     const { tokensSidebar, tokenContextMenuForToken } =
-          await setupTokensFile(page);
+      await setupTokensFile(page);
 
     await expect(tokensSidebar).toBeVisible();
 
@@ -1910,7 +1904,7 @@ test.describe("Tokens tab - delete", () => {
   });
 
   test("User removes node and all child tokens", async ({ page }) => {
-    const { tokensSidebar, workspacePage } = await setupTokensFile(page);
+    const { tokensSidebar } = await setupTokensFile(page);
 
     await expect(tokensSidebar).toBeVisible();
 
@@ -1919,7 +1913,7 @@ test.describe("Tokens tab - delete", () => {
 
     // Verify that the node and child token are visible before deletion
     const colorNode = tokensSidebar.getByRole("button", {
-      name: "blue",
+      name: "colors",
       exact: true,
     });
     const colorNodeToken = tokensSidebar.getByRole("button", {
@@ -1943,5 +1937,13 @@ test.describe("Tokens tab - delete", () => {
     await expect(colorNode).not.toBeVisible();
     // Verify that child token is also removed
     await expect(colorNodeToken).not.toBeVisible();
+
+    // Save the type button to verify that expands/folds
+    const tokenTypeButton = await tokensSidebar.getByRole("button", {
+      name: "Color",
+      exact: true,
+    });
+
+    await expect(tokenTypeButton).toHaveAttribute("aria-expanded", "false");
   });
 });

frontend/playwright/ui/specs/variants.spec.js

@@ -1,12 +1,19 @@
 import { test, expect } from "@playwright/test";
-import { WorkspacePage } from "../pages/WorkspacePage";
+import { WorkspacePage  } from "../pages/WorkspacePage";
 import { BaseWebSocketPage } from "../pages/BaseWebSocketPage";
+import { Clipboard } from "../../helpers/Clipboard";
+
+test.beforeEach(async ({ page, context }) => {
+  await Clipboard.enable(context, Clipboard.Permission.ALL);
 
-test.beforeEach(async ({ page }) => {
   await WorkspacePage.init(page);
   await BaseWebSocketPage.mockRPC(page, "get-teams", "get-teams-variants.json");
 });
 
+test.afterEach(async ({ context }) => {
+  context.clearPermissions();
+});
+
 const setupVariantsFile = async (workspacePage) => {
   await workspacePage.setupEmptyFile();
   await workspacePage.mockRPC(
@@ -34,9 +41,9 @@ const setupVariantsFileWithVariant = async (workspacePage) => {
   await setupVariantsFile(workspacePage);
 
   await workspacePage.clickLeafLayer("Rectangle");
-  await workspacePage.page.keyboard.press("Control+k");
+  await workspacePage.page.keyboard.press("ControlOrMeta+k");
   await workspacePage.page.waitForTimeout(500);
-  await workspacePage.page.keyboard.press("Control+k");
+  await workspacePage.page.keyboard.press("ControlOrMeta+k");
   await workspacePage.page.waitForTimeout(500);
 
   // We wait until layer-row starts looking like it an component
@@ -156,7 +163,7 @@ test("User duplicates a variant container", async ({ page }) => {
   await variant.container.click();
 
   //Duplicate the variant container
-  await workspacePage.page.keyboard.press("Control+d");
+  await workspacePage.page.keyboard.press("ControlOrMeta+d");
 
   const variant_original = await findVariant(workspacePage, 1); // On duplicate, the new item is the first
   const variant_duplicate = await findVariant(workspacePage, 0);
@@ -169,25 +176,27 @@ test("User duplicates a variant container", async ({ page }) => {
   await validateVariant(variant_duplicate);
 });
 
-test("User copy paste a variant container", async ({ page }) => {
+test("User copy paste a variant container", async ({ page, context }) => {
   const workspacePage = new WorkspacePage(page);
+  // Access to the read/write clipboard necesary for this functionality
   await setupVariantsFileWithVariant(workspacePage);
+  await workspacePage.mockRPC(
+    /create-file-object-thumbnail.*/,
+    "workspace/create-file-object-thumbnail.json",
+  );
 
   const variant = findVariantNoWait(workspacePage, 0);
 
-  // await variant.container.waitFor();
-
-  // Select the variant container
-  await variant.container.click();
-
-  await workspacePage.page.waitForTimeout(1000);
-
   // Copy the variant container
-  await workspacePage.page.keyboard.press("Control+c");
+  await workspacePage.clickLeafLayer("Rectangle");
+  await workspacePage.copy("keyboard");
 
   // Paste the variant container
   await workspacePage.clickAt(400, 400);
-  await workspacePage.page.keyboard.press("Control+v");
+  await workspacePage.paste("keyboard");
+
+  const variants = workspacePage.layers.getByText("Rectangle");
+  await expect(variants).toHaveCount(2);
 
   const variantDuplicate = findVariantNoWait(workspacePage, 0);
   const variantOriginal = findVariantNoWait(workspacePage, 1);
@@ -212,18 +221,17 @@ test("User cut paste a variant container", async ({ page }) => {
   await variant.container.click();
 
   //Cut the variant container
-  await workspacePage.page.keyboard.press("Control+x");
-  await workspacePage.page.waitForTimeout(500);
+  await workspacePage.cut("keyboard");
 
   //Paste the variant container
   await workspacePage.clickAt(500, 500);
-  await workspacePage.page.keyboard.press("Control+v");
+  await workspacePage.paste("keyboard");
   await workspacePage.page.waitForTimeout(500);
 
   const variantPasted = await findVariant(workspacePage, 0);
 
   // Expand the layers
-  await variantPasted.container.locator("button").first().click();
+  await workspacePage.clickToggableLayer("Rectangle");
 
   // The variants are valid
   await validateVariant(variantPasted);
@@ -239,27 +247,34 @@ test("User cut paste a variant container into a board, and undo twice", async ({
 
   //Create a board
   await workspacePage.boardButton.click();
-  await workspacePage.clickWithDragViewportAt(500, 500, 100, 100);
+  // NOTE: this board should not intersect the existing variants, otherwise
+  // this test is flaky
+  await workspacePage.clickWithDragViewportAt(200, 200, 100, 100);
   await workspacePage.clickAt(495, 495);
   const board = await workspacePage.rootShape.locator("Board");
 
   // Select the variant container
-  await variant.container.click();
+  // await variant.container.click();
+  await workspacePage.clickLeafLayer("Rectangle");
 
   //Cut the variant container
-  await workspacePage.page.keyboard.press("Control+x");
-  await workspacePage.page.waitForTimeout(500);
+  await workspacePage.cut("keyboard");
+  await expect(variant.container).not.toBeVisible();
 
   //Select the board
   await workspacePage.clickLeafLayer("Board");
 
   //Paste the variant container inside the board
-  await workspacePage.page.keyboard.press("Control+v");
+  await workspacePage.paste("keyboard");
+  await expect(variant.container).toBeVisible();
 
   //Undo twice
-  await workspacePage.page.keyboard.press("Control+z");
-  await workspacePage.page.keyboard.press("Control+z");
-  await workspacePage.page.waitForTimeout(500);
+  await workspacePage.page.keyboard.press("ControlOrMeta+z");
+
+  await expect(variant.container).not.toBeVisible();
+
+  await workspacePage.page.keyboard.press("ControlOrMeta+z");
+  await expect(variant.container).toBeVisible();
 
   const variantAfterUndo = await findVariant(workspacePage, 0);
 
@@ -276,12 +291,12 @@ test("User copy paste a variant", async ({ page }) => {
   // Select the variant1
   await variant.variant1.click();
 
-  //Cut the variant
-  await workspacePage.page.keyboard.press("Control+c");
+  // Copy the variant
+  await workspacePage.copy("keyboard");
 
-  //Paste the variant
+  // Paste the variant
   await workspacePage.clickAt(500, 500);
-  await workspacePage.page.keyboard.press("Control+v");
+  await workspacePage.paste("keyboard");
 
   const copy = await workspacePage.layers
     .getByTestId("layer-row")
@@ -302,11 +317,11 @@ test("User cut paste a variant outside the container", async ({ page }) => {
   await variant.variant1.click();
 
   //Cut the variant
-  await workspacePage.page.keyboard.press("Control+x");
+  await workspacePage.cut("keyboard");
 
   //Paste the variant
   await workspacePage.clickAt(500, 500);
-  await workspacePage.page.keyboard.press("Control+v");
+  await workspacePage.paste("keyboard");
 
   const component = await workspacePage.layers
     .getByTestId("layer-row")
@@ -324,15 +339,11 @@ test("User drag and drop a variant outside the container", async ({ page }) => {
   const variant = await findVariant(workspacePage, 0);
 
   // Drag and drop the variant
-  await workspacePage.clickWithDragViewportAt(350, 400, 0, 200);
+  // FIXME: to make this test more resilient, we should get the bounding box of the Value 1 variant
+  // and use it to calculate the target position
+  await workspacePage.clickWithDragViewportAt(600, 500, 0, 300);
 
-  const component = await workspacePage.layers
-    .getByTestId("layer-row")
-    .filter({ has: workspacePage.page.getByText("Rectangle / Value 1") })
-    .filter({ has: workspacePage.page.getByTestId("icon-component") });
-
-  //The component exists and is visible
-  await expect(component).toBeVisible();
+  await expect(workspacePage.layers.getByText("Rectangle / Value 1")).toBeVisible();
 });
 
 test("User cut paste a component inside a variant", async ({ page }) => {
@@ -345,14 +356,14 @@ test("User cut paste a component inside a variant", async ({ page }) => {
   await workspacePage.ellipseShapeButton.click();
   await workspacePage.clickWithDragViewportAt(500, 500, 20, 20);
   await workspacePage.clickLeafLayer("Ellipse");
-  await workspacePage.page.keyboard.press("Control+k");
+  await workspacePage.page.keyboard.press("ControlOrMeta+k");
 
   //Cut the component
-  await workspacePage.page.keyboard.press("Control+x");
+  await workspacePage.cut("keyboard");
 
   //Paste the component inside the variant
   await variant.container.click();
-  await workspacePage.page.keyboard.press("Control+v");
+  await workspacePage.paste("keyboard");
 
   const variant3 = await workspacePage.layers
     .getByTestId("layer-row")
@@ -376,7 +387,7 @@ test("User cut paste a component with path inside a variant", async ({
   await workspacePage.ellipseShapeButton.click();
   await workspacePage.clickWithDragViewportAt(500, 500, 20, 20);
   await workspacePage.clickLeafLayer("Ellipse");
-  await workspacePage.page.keyboard.press("Control+k");
+  await workspacePage.page.keyboard.press("ControlOrMeta+k");
 
   //Rename the component
   await workspacePage.layers.getByText("Ellipse").dblclick();
@@ -387,11 +398,11 @@ test("User cut paste a component with path inside a variant", async ({
   await workspacePage.page.keyboard.press("Enter");
 
   //Cut the component
-  await workspacePage.page.keyboard.press("Control+x");
+  await workspacePage.cut("keyboard");
 
   //Paste the component inside the variant
   await variant.container.click();
-  await workspacePage.page.keyboard.press("Control+v");
+  await workspacePage.paste("keyboard");
 
   const variant3 = await workspacePage.layers
     .getByTestId("layer-row")
@@ -415,7 +426,7 @@ test("User drag and drop a component with path inside a variant", async ({
   await workspacePage.ellipseShapeButton.click();
   await workspacePage.clickWithDragViewportAt(500, 500, 20, 20);
   await workspacePage.clickLeafLayer("Ellipse");
-  await workspacePage.page.keyboard.press("Control+k");
+  await workspacePage.page.keyboard.press("ControlOrMeta+k");
 
   //Rename the component
   await workspacePage.layers.getByText("Ellipse").dblclick();
@@ -426,7 +437,7 @@ test("User drag and drop a component with path inside a variant", async ({
   await workspacePage.page.keyboard.press("Enter");
 
   //Drag and drop the component the component
-  await workspacePage.clickWithDragViewportAt(510, 510, 0, -200);
+  await workspacePage.clickWithDragViewportAt(510, 510, 200, 0);
 
   const variant3 = await workspacePage.layers
     .getByTestId("layer-row")
@@ -446,8 +457,8 @@ test("User cut paste a variant into another container", async ({ page }) => {
   await workspacePage.ellipseShapeButton.click();
   await workspacePage.clickWithDragViewportAt(500, 500, 20, 20);
   await workspacePage.clickLeafLayer("Ellipse");
-  await workspacePage.page.keyboard.press("Control+k");
-  await workspacePage.page.keyboard.press("Control+k");
+  await workspacePage.page.keyboard.press("ControlOrMeta+k");
+  await workspacePage.page.keyboard.press("ControlOrMeta+k");
 
   const variantOrigin = await findVariantNoWait(workspacePage, 1);
 
@@ -457,11 +468,11 @@ test("User cut paste a variant into another container", async ({ page }) => {
   await variantOrigin.variant1.click();
 
   //Cut the variant
-  await workspacePage.page.keyboard.press("Control+x");
+  await workspacePage.cut("keyboard");
 
   //Paste the variant
   await workspacePage.layers.getByText("Ellipse").first().click();
-  await workspacePage.page.keyboard.press("Control+v");
+  await workspacePage.paste("keyboard");
 
   const variant3 = workspacePage.layers
     .getByTestId("layer-row")

frontend/playwright/ui/specs/workspace.spec.js

@@ -1,13 +1,13 @@
 import { test, expect } from "@playwright/test";
-import { WorkspacePage } from "../pages/WorkspacePage";
+import { WasmWorkspacePage } from "../pages/WorkspacePage";
 import { presenceFixture, joinFixture2, joinFixture3 } from "../../data/workspace/ws-notifications";
 
 test.beforeEach(async ({ page }) => {
-  await WorkspacePage.init(page);
+  await WasmWorkspacePage.init(page);
 });
 
 test("User loads worskpace with empty file", async ({ page }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile(page);
 
   await workspacePage.goToWorkspace();
@@ -16,7 +16,7 @@ test("User loads worskpace with empty file", async ({ page }) => {
 });
 
 test("User opens a file with a bad page id", async ({ page }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile(page);
 
   await workspacePage.goToWorkspace({
@@ -29,7 +29,7 @@ test("User opens a file with a bad page id", async ({ page }) => {
 test("User receives presence notifications updates in the workspace", async ({
   page,
 }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile();
 
   await workspacePage.goToWorkspace();
@@ -63,7 +63,7 @@ test("BUG 13058 - Presence list shows up to 3 user avatars", async ({
 });
 
 test("User draws a rect", async ({ page }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile();
   await workspacePage.mockRPC(
     "update-file?id=*",
@@ -74,13 +74,12 @@ test("User draws a rect", async ({ page }) => {
   await workspacePage.rectShapeButton.click();
   await workspacePage.clickWithDragViewportAt(128, 128, 200, 100);
 
-  const shape = await workspacePage.rootShape.locator("rect");
-  await expect(shape).toHaveAttribute("width", "200");
-  await expect(shape).toHaveAttribute("height", "100");
+  await workspacePage.hideUI();
+  await expect(workspacePage.canvas).toHaveScreenshot();
 });
 
 test("User makes a group", async ({ page }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile();
   await workspacePage.mockRPC(
     /get\-file\?/,
@@ -96,14 +95,14 @@ test("User makes a group", async ({ page }) => {
     pageId: "6191cd35-bb1f-81f7-8004-7cc63d087375",
   });
   await workspacePage.clickLeafLayer("Rectangle");
-  await workspacePage.page.keyboard.press("Control+g");
+  await workspacePage.page.keyboard.press("ControlOrMeta+g");
   await workspacePage.expectSelectedLayer("Group");
 });
 
 test("Bug 7654 - Toolbar keeps toggling on and off on spacebar press", async ({
   page,
 }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile();
   await workspacePage.goToWorkspace();
 
@@ -113,10 +112,10 @@ test("Bug 7654 - Toolbar keeps toggling on and off on spacebar press", async ({
   await workspacePage.expectHiddenToolbarOptions();
 });
 
-test("Bug 7525 - User moves a scrollbar and no selciont rectangle appears", async ({
+test("Bug 7525 - User moves a scrollbar and no selection rectangle appears", async ({
   page,
 }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile();
   await workspacePage.mockRPC(
     /get\-file\?/,
@@ -132,8 +131,8 @@ test("Bug 7525 - User moves a scrollbar and no selciont rectangle appears", asyn
     pageId: "6191cd35-bb1f-81f7-8004-7cc63d087375",
   });
 
-  // Move created rect to a corner, in orther to get scrollbars
-  await workspacePage.panOnViewportAt(128, 128, 300, 300);
+  // Move created rect to a corner, in order to get scrollbars
+  await workspacePage.panOnViewportAt(128, 128, 600, 600);
 
   // Check scrollbars appear
   const horizontalScrollbar = workspacePage.horizontalScrollbar;
@@ -152,7 +151,7 @@ test("Bug 7525 - User moves a scrollbar and no selciont rectangle appears", asyn
 test("User adds a library and its automatically selected in the color palette", async ({
   page,
 }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile();
   await workspacePage.mockRPC(
     "link-file-to-library",
@@ -197,7 +196,7 @@ test("User adds a library and its automatically selected in the color palette",
 test("Bug 10179 - Drag & drop doesn't add colors to the Recent Colors palette", async ({
   page,
 }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile();
   await workspacePage.goToWorkspace();
   await workspacePage.moveButton.click();
@@ -240,7 +239,7 @@ test("Bug 10179 - Drag & drop doesn't add colors to the Recent Colors palette",
 test("Bug 7489 - Workspace-palette items stay hidden when opening with keyboard-shortcut", async ({
   page,
 }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile();
   await workspacePage.goToWorkspace();
 
@@ -257,7 +256,7 @@ test("Bug 7489 - Workspace-palette items stay hidden when opening with keyboard-
 test("Bug 8784 - Use keyboard arrow to move inside a text input does not change tabs", async ({
   page,
 }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile();
   await workspacePage.goToWorkspace();
   await workspacePage.pageName.click();
@@ -267,7 +266,7 @@ test("Bug 8784 - Use keyboard arrow to move inside a text input does not change
 });
 
 test("Bug 9066 - Problem with grid layout", async ({ page }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile(page);
   await workspacePage.mockRPC(/get\-file\?/, "workspace/get-file-9066.json");
 
@@ -295,7 +294,7 @@ test("Bug 9066 - Problem with grid layout", async ({ page }) => {
 });
 
 test("User have toolbar", async ({ page }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile(page);
   await workspacePage.goToWorkspace();
 
@@ -304,7 +303,7 @@ test("User have toolbar", async ({ page }) => {
 });
 
 test("User have edition menu entries", async ({ page }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile(page);
   await workspacePage.goToWorkspace();
 
@@ -320,7 +319,7 @@ test("User have edition menu entries", async ({ page }) => {
 });
 
 test("Copy/paste properties", async ({ page, context }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile(page);
   await workspacePage.mockRPC(
     /get\-file\?/,
@@ -386,23 +385,23 @@ test("Copy/paste properties", async ({ page, context }) => {
 });
 
 test("[Taiga #9929] Paste text in workspace", async ({ page, context }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile(page);
   await workspacePage.goToWorkspace();
   await context.grantPermissions(["clipboard-read", "clipboard-write"]);
   await page.evaluate(() => navigator.clipboard.writeText("Lorem ipsum dolor"));
   await workspacePage.viewport.click({ button: "right" });
-  await page.getByText("PasteCtrlV").click();
+  await page.getByText(/^Paste/i).click();
   await workspacePage.viewport
     .getByRole("textbox")
     .getByText("Lorem ipsum dolor");
 });
 
-test("[Taiga #9930] Zoom fit all doesn't fits all", async ({
+test("[Taiga #9930] Zoom fit all doesn't fit all shapes", async ({
   page,
   context,
 }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile(page);
   await workspacePage.mockRPC(/get\-file\?/, "workspace/get-file-9930.json");
   await workspacePage.goToWorkspace({
@@ -410,16 +409,18 @@ test("[Taiga #9930] Zoom fit all doesn't fits all", async ({
     pageId: "fb9798e7-a547-80ae-8005-9ffda4a13e2c",
   });
 
-  const zoom = await page.getByTitle("Zoom");
+  const zoom = page.getByTitle("Zoom");
   await zoom.click();
 
-  const zoomIn = await page.getByRole("button", { name: "Zoom in" });
+  const zoomIn = page.getByRole("button", { name: "Zoom in" });
   await zoomIn.click();
   await zoomIn.click();
   await zoomIn.click();
 
   // Zoom fit all
   await page.keyboard.press("Shift+1");
+  // Select all shapes to display selrect
+  await workspacePage.page.keyboard.press("ControlOrMeta+a");
 
   const ids = [
     "shape-165d1e5a-5873-8010-8005-9ffdbeaeec59",
@@ -441,7 +442,7 @@ test("[Taiga #9930] Zoom fit all doesn't fits all", async ({
 
   const viewportBoundingBox = await workspacePage.viewport.boundingBox();
   for (const id of ids) {
-    const shape = await page.locator(`.ws-shape-wrapper > g#${id}`);
+    const shape = page.locator(`.viewport-selrect`);
     const shapeBoundingBox = await shape.boundingBox();
     expect(contains(viewportBoundingBox, shapeBoundingBox)).toBeTruthy();
   }
@@ -450,7 +451,7 @@ test("[Taiga #9930] Zoom fit all doesn't fits all", async ({
 test("Bug 9877, user navigation to dashboard from header goes to blank page", async ({
   page,
 }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile(page);
 
   await workspacePage.goToWorkspace();
@@ -467,7 +468,7 @@ test("Bug 9877, user navigation to dashboard from header goes to blank page", as
 test("Bug 8371 - Flatten option is not visible in context menu", async ({
   page,
 }) => {
-  const workspacePage = new WorkspacePage(page);
+  const workspacePage = new WasmWorkspacePage(page);
   await workspacePage.setupEmptyFile(page);
   await workspacePage.mockGetFile("workspace/get-file-8371.json");
   await workspacePage.goToWorkspace({

frontend/resources/wasm-playground/shadows.html

@@ -0,0 +1,90 @@
+<!DOCTYPE html>
+<html lang="es">
+<head>
+  <meta charset="UTF-8" />
+  <title>WASM + WebGL2 Canvas</title>
+  <style>
+    body {
+      margin: 0;
+      background: #111;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      height: 100vh;
+      overflow: hidden;
+    }
+    canvas {
+      width: 100%;
+      height: 100%;
+      position: absolute;
+    }
+  </style>
+</head>
+<body>
+  <canvas id="canvas"></canvas>
+  <script type="module">
+    import initWasmModule from '/js/render-wasm.js';
+    import {
+      init, addShapeSolidFill, assignCanvas, hexToU32ARGB, getRandomInt, getRandomColor,
+      getRandomFloat, useShape, setShapeChildren, setupInteraction, addShapeSolidStrokeFill
+    } from './js/lib.js';
+
+    const canvas = document.getElementById("canvas");
+    canvas.width =  window.innerWidth;
+    canvas.height = window.innerHeight;
+
+    const params = new URLSearchParams(document.location.search);
+    const shapes = params.get("shapes") || 1000;
+
+    initWasmModule().then(Module => {
+      init(Module);
+      assignCanvas(canvas);
+      Module._set_canvas_background(hexToU32ARGB("#FABADA", 1));
+      Module._init_shapes_pool(shapes + 1);
+      setupInteraction(canvas);
+
+      const children = [];
+      for (let i = 0; i < shapes; i++) {
+        const uuid = crypto.randomUUID();
+        children.push(uuid);
+
+        useShape(uuid);
+        Module._set_parent(0, 0, 0, 0);
+        Module._set_shape_type(3);
+        const x1 = getRandomInt(0, canvas.width);
+        const y1 = getRandomInt(0, canvas.height);
+        const width = getRandomInt(20, 100);
+        const height = getRandomInt(20, 100);
+        Module._set_shape_selrect(x1, y1, x1 + width, y1 + height);
+
+        const color = getRandomColor();
+        const argb = hexToU32ARGB(color, getRandomFloat(0.1, 1.0));
+        addShapeSolidFill(argb)
+
+        Module._add_shape_center_stroke(10, 0,  0, 0);
+        const argb2 = hexToU32ARGB(color, getRandomFloat(0.1, 1.0));
+        addShapeSolidStrokeFill(argb2);
+
+        // Add shadows
+        // Shadow 1: drop-shadow, #dedede opacity 0.33, blur 4, spread -2, offsetX 0, offsetY 2
+        Module._add_shape_shadow(hexToU32ARGB("#dedede", 0.33), 4, -2, 0, 2, 0, false);
+        // Shadow 2: drop-shadow, #dedede opacity 1, blur 12, spread -8, offsetX 0, offsetY 12
+        Module._add_shape_shadow(hexToU32ARGB("#dedede", 1), 12, -8, 0, 12, 0, false);
+        // Shadow 3: inner-shadow, #002046 opacity 0.12, blur 12, spread -8, offsetX 0, offsetY -4
+        Module._add_shape_shadow(hexToU32ARGB("#002046", 0.12), 12, -8, 0, -4, 1, false);
+      }
+
+      useShape("00000000-0000-0000-0000-000000000000");
+      setShapeChildren(children);
+
+      performance.mark('render:begin');
+      Module._set_view(1, 0, 0);
+      Module._render(Date.now());
+      performance.mark('render:end');
+      const { duration } = performance.measure('render', 'render:begin', 'render:end');
+      // alert(`render time: ${duration.toFixed(2)}ms`);
+    });
+    
+  </script>
+</body>
+</html>

frontend/src/app/main/data/workspace.cljs

@@ -1410,6 +1410,7 @@
 (dm/export dwt/start-move-selected)
 (dm/export dwt/move-selected)
 (dm/export dwt/update-position)
+(dm/export dwt/update-positions)
 (dm/export dwt/flip-horizontal-selected)
 (dm/export dwt/flip-vertical-selected)
 (dm/export dwly/set-opacity)

frontend/src/app/main/data/workspace/tokens/library_edit.cljs

@@ -62,6 +62,52 @@
       (watch [_ _ _]
         (rx/of (dwsh/update-shapes [id] #(merge % attrs)))))))
 
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Toggle tree nodes
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(defn- remove-paths-recursively
+  [path paths]
+  (->> paths
+       (remove #(str/starts-with? % (str path)))
+       vec))
+
+(defn add-path
+  [path paths]
+  (let [split-path (cpn/split-path path :separator ".")
+        partial-paths (->> split-path
+                           (reduce
+                            (fn [acc segment]
+                              (let [new-acc (if (empty? acc)
+                                              segment
+                                              (str (last acc) "." segment))]
+                                (conj acc new-acc)))
+                            []))]
+    (->> paths
+         (into partial-paths)
+         distinct
+         vec)))
+
+(defn clear-tokens-paths
+  []
+  (ptk/reify ::clear-tokens-paths
+    ptk/UpdateEvent
+    (update [_ state]
+      (assoc-in state [:workspace-tokens :unfolded-token-paths] []))))
+
+(defn toggle-token-path
+  [path]
+  (ptk/reify ::toggle-token-path
+    ptk/UpdateEvent
+    (update [_ state]
+      (update-in state [:workspace-tokens :unfolded-token-paths]
+                 (fn [paths]
+                   (let [paths (or paths [])]
+                     (if (some #(= % path) paths)
+                       (remove-paths-recursively path paths)
+                       (add-path path paths))))))))
+
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; TOKENS Actions
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -245,8 +291,9 @@
                         (pcb/with-library-data data)
                         (clt/generate-toggle-token-set tlib name))]
 
-        (rx/of (dch/commit-changes changes)
-               (dwtp/propagate-workspace-tokens))))))
+        (rx/of
+         (dch/commit-changes changes)
+         (dwtp/propagate-workspace-tokens))))))
 
 (defn toggle-token-set-group
   [group-path]
@@ -257,6 +304,7 @@
             changes (-> (pcb/empty-changes)
                         (pcb/with-library-data data)
                         (clt/generate-toggle-token-set-group (get-tokens-lib state) group-path))]
+
         (rx/of
          (dch/commit-changes changes)
          (dwtp/propagate-workspace-tokens))))))
@@ -486,35 +534,7 @@
 ;; TOKEN UI OPS
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
-(defn clean-tokens-paths
-  []
-  (ptk/reify ::clean-tokens-paths
-    ptk/UpdateEvent
-    (update [_ state]
-      (assoc-in state [:workspace-tokens :unfolded-token-paths] []))))
 
-(defn toggle-token-path
-  [path]
-  (ptk/reify ::toggle-token-path
-    ptk/UpdateEvent
-    (update [_ state]
-      (update-in state [:workspace-tokens :unfolded-token-paths]
-                 (fn [paths]
-                   (let [paths (or paths [])]
-                     (if (some #(= % path) paths)
-                       (vec (remove #(or (= % path)
-                                         (str/starts-with? % (str path ".")))
-                                    paths))
-                       (let [split-path (cpn/split-path path :separator ".")
-                             partial-paths (reduce
-                                            (fn [acc segment]
-                                              (let [new-acc (if (empty? acc)
-                                                              segment
-                                                              (str (last acc) "." segment))]
-                                                (conj acc new-acc)))
-                                            []
-                                            split-path)]
-                         (into paths partial-paths)))))))))
 
 (defn assign-token-context-menu
   [{:keys [position] :as params}]

frontend/src/app/main/data/workspace/transforms.cljs

@@ -1050,6 +1050,20 @@
                                         :ignore-touched (:ignore-touched options)
                                         :ignore-snap-pixel true}))))))))
 
+(defn update-positions
+  "Move multiple shapes to a new position."
+  ([ids position] (update-positions ids position nil))
+  ([ids position options]
+   (assert (every? uuid? ids)
+           "expected valid coll of uuids")
+   (assert (map? position) "expected a valid map for `position`")
+   (ptk/reify ::update-positions
+     ptk/WatchEvent
+     (watch [_ _ _]
+       (->> ids
+            (map (fn [id] (update-position id position options)))
+            (rx/from))))))
+
 (defn position-shapes
   [shapes]
   (ptk/reify ::position-shapes

frontend/src/app/main/errors.cljs

@@ -9,15 +9,16 @@
   (:require
    [app.common.exceptions :as ex]
    [app.common.pprint :as pp]
-   [app.common.schema :as sm]
+   [app.config :as cf]
    [app.main.data.auth :as da]
+   [app.main.data.event :as ev]
    [app.main.data.modal :as modal]
    [app.main.data.notifications :as ntf]
    [app.main.data.workspace :as-alias dw]
    [app.main.router :as rt]
    [app.main.store :as st]
    [app.main.worker]
-   [app.util.globals :as glob]
+   [app.util.globals :as g]
    [app.util.i18n :refer [tr]]
    [app.util.timers :as ts]
    [cuerdas.core :as str]
@@ -32,44 +33,6 @@
 ;; Will contain last uncaught exception
 (def last-exception nil)
 
-(defn- print-data!
-  [data]
-  (-> data
-      (dissoc ::sm/explain)
-      (dissoc :explain)
-      (dissoc ::trace)
-      (dissoc ::instance)
-      (pp/pprint {:width 70})))
-
-(defn- print-explain!
-  [data]
-  (when-let [{:keys [errors] :as explain} (::sm/explain data)]
-    (let [errors (mapv #(update % :schema sm/form) errors)]
-      (pp/pprint errors {:width 100 :level 15 :length 20})))
-
-  (when-let [explain (:explain data)]
-    (js/console.log explain)))
-
-(defn- print-trace!
-  [data]
-  (some-> data ::trace js/console.log))
-
-(defn- print-group!
-  [message f]
-  (try
-    (js/console.group message)
-    (f)
-    (catch :default _ nil)
-    (finally
-      (js/console.groupEnd message))))
-
-(defn print-cause!
-  [message cause]
-  (print-group! message (fn []
-                          (print-data! cause)
-                          (print-explain! cause)
-                          (print-trace! cause))))
-
 (defn exception->error-data
   [cause]
   (let [data (ex-data cause)]
@@ -78,18 +41,6 @@
         (assoc ::instance cause)
         (assoc ::trace (.-stack cause)))))
 
-(defn print-error!
-  [cause]
-  (cond
-    (map? cause)
-    (print-cause! (:hint cause "Unexpected Error") cause)
-
-    (ex/error? cause)
-    (print-cause! (ex-message cause) (ex-data cause))
-
-    :else
-    (print-cause! (ex-message cause) (exception->error-data cause))))
-
 (defn on-error
   "A general purpose error handler."
   [error]
@@ -104,13 +55,66 @@
 ;; Set the main potok error handler
 (reset! st/on-error on-error)
 
+(defn generate-report
+  [cause]
+  (try
+    (let [team-id    (:current-team-id @st/state)
+          file-id    (:current-file-id @st/state)
+          profile-id (:profile-id @st/state)
+          data       (ex-data cause)]
+
+      (with-out-str
+        (println "Context:")
+        (println "--------------------")
+        (println "Hint:    " (or (:hint data) (ex-message cause) "--"))
+        (println "Prof ID: " (str (or profile-id "--")))
+        (println "Team ID: " (str (or team-id "--")))
+        (when-let [file-id (or (:file-id data) file-id)]
+          (println "File ID: " (str file-id)))
+        (println "Version: " (:full cf/version))
+        (println "URI:     " (str cf/public-uri))
+        (println "HREF:    " (rt/get-current-href))
+        (println)
+
+        (println
+         (ex/format-throwable cause))
+        (println)
+
+        (println "Last events:")
+        (println "--------------------")
+        (pp/pprint @st/last-events {:length 200})
+        (println)))
+    (catch :default cause
+      (.error js/console "error on generating report" cause)
+      nil)))
+
+(defn- show-not-blocking-error
+  "Show a non user blocking error notification"
+  [cause]
+  (let [data (ex-data cause)
+        hint (or (some-> (:hint data) ex/first-line)
+                 (ex-message cause))]
+
+    (st/emit!
+     (ev/event {::ev/name "unhandled-exception"
+                :hint hint
+                :href (rt/get-current-href)
+                :type (get data :type :unknown)
+                :report (generate-report cause)})
+
+     (ntf/show {:content (tr "errors.unexpected-exception" hint)
+                :type :toast
+                :level :error
+                :timeout 3000}))))
+
 (defmethod ptk/handle-error :default
   [error]
-  (st/async-emit! (rt/assign-exception error))
-  (print-group! "Unhandled Error"
-                (fn []
-                  (print-trace! error)
-                  (print-data! error))))
+  (if (and (string? (:hint error))
+           (str/starts-with? (:hint error) "Assert failed:"))
+    (ptk/handle-error (assoc error :type :assertion))
+    (when-let [cause (::instance error)]
+      (ex/print-throwable cause :prefix "Unexpected Error")
+      (show-not-blocking-error cause))))
 
 ;; We receive a explicit authentication error; If the uri is for
 ;; workspace, dashboard, viewer or settings, then assign the exception
@@ -142,10 +146,10 @@
 
 (defmethod ptk/handle-error :validation
   [{:keys [code] :as error}]
-  (print-group! "Validation Error"
-                (fn []
-                  (print-data! error)
-                  (print-explain! error)))
+
+  (when-let [instance (get error ::instance)]
+    (ex/print-throwable instance :prefix "Validation Error"))
+
   (cond
     (= code :invalid-paste-data)
     (let [message (tr "errors.paste-data-validation")]
@@ -193,23 +197,14 @@
     :else
     (st/async-emit! (rt/assign-exception error))))
 
-
 ;; This is a pure frontend error that can be caused by an active
 ;; assertion (assertion that is preserved on production builds). From
 ;; the user perspective this should be treated as internal error.
 (defmethod ptk/handle-error :assertion
   [error]
-  (ts/schedule
-   #(st/emit! (ntf/show {:content (tr "errors.internal-assertion-error")
-                         :type :toast
-                         :level :error
-                         :timeout 3000})))
-
-  (print-group! "Internal Assertion Error"
-                (fn []
-                  (print-trace! error)
-                  (print-data! error)
-                  (print-explain! error))))
+  (when-let [cause (::instance error)]
+    (show-not-blocking-error cause)
+    (ex/print-throwable cause :prefix "Assertion Error")))
 
 ;; ;; All the errors that happens on worker are handled here.
 (defmethod ptk/handle-error :worker-error
@@ -221,9 +216,8 @@
                 :level :error
                 :timeout 3000})))
 
-  (print-group! "Internal Worker Error"
-                (fn []
-                  (print-data! error))))
+  (some-> (::instance error)
+          (ex/print-throwable :prefix "Web Worker Error")))
 
 ;; Error on parsing an SVG
 (defmethod ptk/handle-error :svg-parser
@@ -252,11 +246,9 @@
 
 (defmethod ptk/handle-error ::exceptional-state
   [error]
-  (when-let [cause (::instance error)]
-    (js/console.log (.-stack cause)))
-
-  (ts/schedule
-   #(st/emit! (rt/assign-exception error))))
+  (when-let [instance (get error ::instance)]
+    (ex/print-throwable instance :prefix "Exceptional State"))
+  (ts/schedule #(st/emit! (rt/assign-exception error))))
 
 (defn- redirect-to-dashboard
   []
@@ -264,7 +256,7 @@
         project-id (:current-project-id @st/state)]
     (if (and project-id team-id)
       (st/emit! (rt/nav :dashboard-files {:team-id team-id :project-id project-id}))
-      (set! (.-href glob/location) ""))))
+      (set! (.-href g/location) ""))))
 
 (defmethod ptk/handle-error :restriction
   [{:keys [code] :as error}]
@@ -312,9 +304,10 @@
                                           :text (tr "errors.deprecated.contact.text")
                                           :after (tr "errors.deprecated.contact.after")
                                           :on-click #(st/emit! (rt/nav :settings-feedback))}}))
-
     :else
-    (print-cause! "Restriction Error" error)))
+    (when-let [cause (::instance error)]
+      (ex/print-throwable cause :prefix "Restriction Error")
+      (show-not-blocking-error cause))))
 
 ;; This happens when the backed server fails to process the
 ;; request. This can be caused by an internal assertion or any other
@@ -322,24 +315,9 @@
 
 (defmethod ptk/handle-error :server-error
   [error]
-  (st/async-emit! (rt/assign-exception error))
-  (print-group! "Server Error"
-                (fn []
-                  (print-data! (dissoc error :data))
-
-                  (when-let [werror (:data error)]
-                    (cond
-                      (= :assertion (:type werror))
-                      (print-group! "Assertion Error"
-                                    (fn []
-                                      (print-data! werror)
-                                      (print-explain! werror)))
-
-                      :else
-                      (print-group! "Unexpected"
-                                    (fn []
-                                      (print-data! werror)
-                                      (print-explain! werror))))))))
+  (when-let [instance (get error ::instance)]
+    (ex/print-throwable instance :prefix "Server Error"))
+  (st/async-emit! (rt/assign-exception error)))
 
 (defonce uncaught-error-handler
   (letfn [(is-ignorable-exception? [cause]
@@ -354,28 +332,19 @@
             (when-let [cause (unchecked-get event "error")]
               (set! last-exception cause)
               (when-not (is-ignorable-exception? cause)
-                (ex/print-throwable cause :prefix "uncaught exception")
-                (st/async-emit!
-                 (ntf/show {:content (tr "errors.unexpected-exception" (ex-message cause))
-                            :type :toast
-                            :level :error
-                            :timeout 3000})))))
-
+                (ex/print-throwable cause :prefix "Uncaught Exception")
+                (ts/schedule #(show-not-blocking-error cause)))))
 
           (on-unhandled-rejection [event]
             (.preventDefault ^js event)
             (when-let [cause (unchecked-get event "reason")]
               (set! last-exception cause)
-              (ex/print-throwable cause :prefix "uncaught rejection")
-              (st/async-emit!
-               (ntf/show {:content (tr "errors.unexpected-exception" (ex-message cause))
-                          :type :toast
-                          :level :error
-                          :timeout 3000}))))]
+              (ex/print-throwable cause :prefix "Uncaught Rejection")
+              (ts/schedule #(show-not-blocking-error cause))))]
 
-    (.addEventListener glob/window "error" on-unhandled-error)
-    (.addEventListener glob/window "unhandledrejection" on-unhandled-rejection)
+    (.addEventListener g/window "error" on-unhandled-error)
+    (.addEventListener g/window "unhandledrejection" on-unhandled-rejection)
     (fn []
-      (.removeEventListener glob/window "error" on-unhandled-error)
-      (.removeEventListener glob/window "unhandledrejection" on-unhandled-rejection))))
+      (.removeEventListener g/window "error" on-unhandled-error)
+      (.removeEventListener g/window "unhandledrejection" on-unhandled-rejection))))
 

frontend/src/app/main/ui/dashboard/import.cljs

@@ -9,12 +9,12 @@
   (:require
    [app.common.data :as d]
    [app.common.data.macros :as dm]
+   [app.common.exceptions :as ex]
    [app.common.logging :as log]
    [app.main.data.dashboard :as dd]
    [app.main.data.event :as ev]
    [app.main.data.modal :as modal]
    [app.main.data.notifications :as ntf]
-   [app.main.errors :as errors]
    [app.main.store :as st]
    [app.main.ui.components.file-uploader :refer [file-uploader*]]
    [app.main.ui.ds.product.loader :refer [loader*]]
@@ -360,7 +360,7 @@
                  on-error
                  (fn [cause]
                    (reset! status* :error)
-                   (errors/print-error! cause)
+                   (ex/print-throwable cause)
                    (rx/of (modal/hide)
                           (ntf/error (tr "dashboard.libraries-and-templates.import-error"))))
 

frontend/src/app/main/ui/inspect/styles/rows/properties_row.cljs

@@ -21,7 +21,7 @@
 (def ^:private schema:properties-row
   [:map
    [:term :string]
-   [:detail :string]
+   [:detail {:optional true} [:maybe :string]]
    [:property {:optional true} :string] ;; CSS valid property
    [:token {:optional true} :any] ;; resolved token object
    [:copiable {:optional true} :boolean]])

frontend/src/app/main/ui/static.cljs

@@ -36,7 +36,6 @@
    [app.util.webapi :as wapi]
    [beicon.v2.core :as rx]
    [cuerdas.core :as str]
-   [potok.v2.core :as ptk]
    [rumext.v2 :as mf]))
 
 ;; FIXME: this is a workaround until we export this class on beicon library
@@ -447,25 +446,24 @@
                        (rx/of default)
                        (rx/throw cause)))))))
 
-
 (mf/defc exception-section*
   {::mf/private true}
   [{:keys [data route] :as props}]
   (let [type   (get data :type)
         report (mf/with-memo [data]
-                 (generate-report data))
+                 (some-> data ::errors/instance errors/generate-report))
         props  (mf/spread-props props {:report report})]
 
     (mf/with-effect [data route report]
       (let [params (:query-params route)
             params (u/map->query-string params)]
-        (st/emit! (ptk/data-event ::ev/event
-                                  {::ev/name "exception-page"
-                                   :type (get data :type :unknown)
-                                   :hint (get data :hint)
-                                   :path (get route :path)
-                                   :report report
-                                   :params params}))))
+        (st/emit! (ev/event {::ev/name "exception-page"
+                             :type (get data :type :unknown)
+                             :href (rt/get-current-href)
+                             :hint (get data :hint)
+                             :path (get route :path)
+                             :report report
+                             :params params}))))
 
     (case type
       :not-found

frontend/src/app/main/ui/workspace/left_header.cljs

@@ -78,13 +78,15 @@
          (fn []
            (close-modals)
            ;; FIXME: move set-mode to uri?
-           (st/emit! (dw/set-options-mode :design)
+           (st/emit! :interrupt
+                     (dw/set-options-mode :design)
                      (dcm/go-to-dashboard-recent))))
 
         nav-to-project
         (mf/use-fn
          (mf/deps project-id)
-         #(st/emit! (dcm/go-to-dashboard-files ::rt/new-window true :project-id project-id)))]
+         #(st/emit! :interrupt
+                    (dcm/go-to-dashboard-files ::rt/new-window true :project-id project-id)))]
 
     (mf/with-effect [editing?]
       (when ^boolean editing?

frontend/src/app/main/ui/workspace/shapes/text/v2_editor.cljs

@@ -401,7 +401,8 @@
                              (dm/fmt "scale(%)" maybe-zoom))}))]
 
     [:g.text-editor {:clip-path (dm/fmt "url(#%)" clip-id)
-                     :transform (dm/str transform)}
+                     :transform (dm/str transform)
+                     :data-testid "text-editor"}
      [:defs
       [:clipPath {:id clip-id}
        [:rect {:x x :y y :width width :height height}]]]

frontend/src/app/main/ui/workspace/sidebar/layer_item.cljs

@@ -119,7 +119,8 @@
             [:button {:class (stl/css-case
                               :toggle-content true
                               :inverse expanded?)
-                      :aria-label "Toggle layer"
+                      :data-testid "toggle-content"
+                      :aria-expanded expanded?
                       :on-click on-toggle-collapse}
              deprecated-icon/arrow])
 

frontend/src/app/main/ui/workspace/sidebar/layer_name.cljs

@@ -108,6 +108,7 @@
         :on-blur accept-edit
         :on-key-down on-key-down
         :auto-focus true
+        :id (dm/str "layer-name-" shape-id)
         :default-value (d/nilv default-value "")}]
       [:*
        [:span
@@ -118,6 +119,7 @@
                  :hidden is-hidden
                  :type-comp type-comp
                  :type-frame type-frame)
+         :id (dm/str "layer-name-" shape-id)
          :style {"--depth" depth "--parent-size" parent-size}
          :ref ref
          :on-double-click start-edit}

frontend/src/app/main/ui/workspace/sidebar/options/menus/measures.cljs

@@ -283,7 +283,7 @@
            (if (or (string? value) (number? value))
              (do
                (st/emit! (udw/trigger-bounding-box-cloaking ids))
-               (st/emit! (udw/update-position ids {attr value})))
+               (st/emit! (udw/update-positions ids {attr value})))
              (st/emit! (udw/trigger-bounding-box-cloaking ids)
                        (dwta/toggle-token {:token (first value)
                                            :attrs #{attr}

frontend/src/app/main/ui/workspace/tokens/management.cljs

@@ -94,10 +94,7 @@
         ;; This only checks for the currently explicitly selected set
         ;; id, it is ephimeral and can be nil
         ;; FIXME: this is a repeated deref for the same `:workspace-tokens` state
-        selected-token-set-id
-        (mf/deref refs/selected-token-set-id)
-
-
+        selected-token-set-id  (mf/deref refs/selected-token-set-id)
 
         ;; If we have not selected any set explicitly we just
         ;; select the first one from the list of sets
@@ -112,6 +109,7 @@
         tokens
         (sd/use-resolved-tokens* tokens)
 
+        ;; Group tokens by their type
         tokens-by-type
         (mf/with-memo [tokens selected-token-set-tokens]
           (let [tokens (reduce-kv (fn [tokens k _]
@@ -129,9 +127,9 @@
         ;; Filter tokens by their path and return their ids
         filter-tokens-by-path-ids
         (mf/use-fn
-         (mf/deps tokens)
+         (mf/deps selected-token-set-tokens)
          (fn [type path]
-           (->> tokens
+           (->> selected-token-set-tokens
                 (filter (fn [token]
                           (let [[_ token-value] token]
                             (and (= (:type token-value) type) (str/starts-with? (:name token-value) path)))))
@@ -139,12 +137,47 @@
                         (let [[_ token-value] token]
                           (:id token-value)))))))
 
+        remaining-tokens-of-type-in-set?
+        (mf/use-fn
+         (fn [selected-token-set-tokens tokens-in-path-ids]
+           (let [token-ids (set tokens-in-path-ids)
+                 remaining-tokens (filter (fn [token]
+                                            (not (contains? token-ids (:id token))))
+                                          selected-token-set-tokens)
+                 _ (prn "Remaining tokens:" remaining-tokens)]
+             (seq remaining-tokens))))
+
+        delete-token
+        (mf/with-memo [selected-token-set-tokens selected-token-set-id]
+          (fn [token]
+            (let [id (:id token)
+                  type (:type token)
+                  path (:name token)
+                  tokens-by-type (ctob/group-by-type selected-token-set-tokens)
+                  tokens-filtered-by-type (get tokens-by-type type)
+                  tokens-in-path-ids (filter-tokens-by-path-ids type path)
+                  remaining-tokens? (remaining-tokens-of-type-in-set? tokens-filtered-by-type tokens-in-path-ids)]
+              ;; Delete the token
+              (st/emit! (dwtl/delete-token selected-token-set-id id))
+              ;; Remove from unfolded tree path
+              (if remaining-tokens?
+                (st/emit! (dwtl/toggle-token-path (str (name type) "." path)))
+                (st/emit! (dwtl/toggle-token-path (name type)))))))
+
         delete-node
-        (mf/with-memo [tokens selected-token-set-id]
+        (mf/with-memo [selected-token-set-tokens selected-token-set-id]
           (fn [node type]
             (let [path (:path node)
-                  tokens-in-path-ids (filter-tokens-by-path-ids type path)]
-              (st/emit! (dwtl/bulk-delete-tokens selected-token-set-id tokens-in-path-ids)))))]
+                  tokens-by-type (ctob/group-by-type selected-token-set-tokens)
+                  tokens-filtered-by-type (get tokens-by-type type)
+                  tokens-in-path-ids (filter-tokens-by-path-ids type path)
+                  remaining-tokens? (remaining-tokens-of-type-in-set? tokens-filtered-by-type tokens-in-path-ids)]
+              ;; Delete tokens in path
+              (st/emit! (dwtl/bulk-delete-tokens selected-token-set-id tokens-in-path-ids))
+              ;; Remove from unfolded tree path
+              (if remaining-tokens?
+                (st/emit! (dwtl/toggle-token-path (str (name type) "." path)))
+                (st/emit! (dwtl/toggle-token-path (name type)))))))]
 
     (mf/with-effect [tokens-lib selected-token-set-id]
       (when (and tokens-lib
@@ -157,7 +190,7 @@
             (st/emit! (dwtl/set-selected-token-set-id (ctob/get-id match)))))))
 
     [:*
-     [:& token-context-menu]
+     [:& token-context-menu {:on-delete-token delete-token}]
      [:> token-node-context-menu* {:on-delete-node delete-node}]
 
      [:> selected-set-info* {:tokens-lib tokens-lib

frontend/src/app/main/ui/workspace/tokens/management/context_menu.cljs

@@ -316,8 +316,9 @@
                         (generic-attribute-actions #{:y} "Y" (assoc context-data :on-update-shape dwta/update-shape-position)))
                        (clean-separators)))}))
 
-(defn default-actions [{:keys [token selected-token-set-id]}]
-  (let [{:keys [modal]} (dwta/get-token-properties token)]
+(defn default-actions [{:keys [token selected-token-set-id on-delete-token]}]
+  (let [{:keys [modal]} (dwta/get-token-properties token)
+        on-duplicate-token #(st/emit! (dwtl/duplicate-token (:id token)))]
     [{:title (tr "workspace.tokens.edit")
       :no-selectable true
       :action (fn [event]
@@ -333,12 +334,10 @@
                                              :token token}))))}
      {:title (tr "workspace.tokens.duplicate")
       :no-selectable true
-      :action #(st/emit! (dwtl/duplicate-token (:id token)))}
+      :action on-duplicate-token}
      {:title (tr "workspace.tokens.delete")
       :no-selectable true
-      :action #(st/emit! (dwtl/delete-token
-                          selected-token-set-id
-                          (:id token)))}]))
+      :action #(on-delete-token token)}]))
 
 (defn- allowed-shape-attributes [shapes]
   (reduce into #{} (map #(ctt/shape-type->attributes (:type %) (:layout %)) shapes)))
@@ -464,7 +463,7 @@
                  :selected? selected?}])])))
 
 (mf/defc token-context-menu-tree
-  [{:keys [width errors] :as mdata}]
+  [{:keys [width errors on-delete-token] :as mdata}]
   (let [objects  (mf/deref refs/workspace-page-objects)
         selected (mf/deref refs/selected-shapes)
 
@@ -488,10 +487,11 @@
                     :errors errors
                     :selected-token-set-id selected-token-set-id
                     :selected-shapes selected-shapes
-                    :is-selected-inside-layout is-selected-inside-layout}]]))
+                    :is-selected-inside-layout is-selected-inside-layout
+                    :on-delete-token on-delete-token}]]))
 
 (mf/defc token-context-menu
-  []
+  [{:keys [on-delete-token]}]
   (let [mdata               (mf/deref tokens-menu-ref)
         is-open?            (boolean mdata)
         width               (mf/use-state 0)
@@ -538,5 +538,5 @@
                         :left (dm/str left "px")}
                 :on-context-menu prevent-default}
           (when mdata
-            [:& token-context-menu-tree (assoc mdata :width @width)])]])
+            [:& token-context-menu-tree (assoc mdata :width @width :on-delete-token on-delete-token)])]])
        (dom/get-body)))))

frontend/src/app/main/ui/workspace/tokens/sets.cljs

@@ -16,6 +16,7 @@
    [rumext.v2 :as mf]))
 
 (defn- on-select-token-set-click [id]
+  (st/emit! (dwtl/clear-tokens-paths))
   (st/emit! (dwtl/set-selected-token-set-id id)))
 
 (defn- on-toggle-token-set-click [name]

frontend/src/app/plugins/register.cljs

@@ -10,6 +10,7 @@
    [app.common.data.macros :as dm]
    [app.common.schema :as sm]
    [app.common.types.plugins :as ctp]
+   [app.common.uri :as u]
    [app.common.uuid :as uuid]
    [app.main.repo :as rp]
    [app.main.store :as st]
@@ -50,7 +51,13 @@
           (contains? permissions "comment:write")
           (conj "comment:read"))
 
-        origin (obj/get (js/URL. plugin-url) "origin")
+        plugin-url
+        (u/uri plugin-url)
+
+        origin
+        (-> plugin-url
+            (u/join ".")
+            (str))
 
         prev-plugin
         (->> (:data @registry)
@@ -59,12 +66,13 @@
                        (and (= name (:name plugin))
                             (= origin (:host plugin))))))
 
-        plugin-id (d/nilv (:plugin-id prev-plugin) (str (uuid/next)))
+        plugin-id
+        (d/nilv (:plugin-id prev-plugin) (str (uuid/next)))
 
         manifest
         (d/without-nils
          {:plugin-id plugin-id
-          :url plugin-url
+          :url (str plugin-url)
           :name name
           :description desc
           :host origin

frontend/src/debug.cljs

@@ -391,7 +391,7 @@
             (group-by :code)
             (clj->js))
        (catch :default cause
-         (errors/print-error! cause))))))
+         (ex/print-throwable cause))))))
 
 (defn ^:export validate-schema
   []
@@ -399,7 +399,7 @@
     (let [file (dsh/lookup-file @st/state)]
       (cfv/validate-file-schema! file))
     (catch :default cause
-      (errors/print-error! cause))))
+      (ex/print-throwable cause))))
 
 (defn ^:export repair
   [reload?]
@@ -431,7 +431,7 @@
                           (when reload?
                             (dom/reload-current-window)))
                         (fn [cause]
-                          (errors/print-error! cause)))))))))
+                          (ex/print-throwable cause)))))))))
 
 (defn ^:export fix-orphan-shapes
   []

frontend/test/frontend_tests/logic/update_position_test.cljs

@@ -0,0 +1,37 @@
+;; This Source Code Form is subject to the terms of the Mozilla Public
+;; License, v. 2.0. If a copy of the MPL was not distributed with this
+;; file, You can obtain one at http://mozilla.org/MPL/2.0/.
+;;
+;; Copyright (c) KALEIDOS INC
+
+(ns frontend-tests.logic.update-position-test
+  (:require
+   [app.common.geom.rect :as grc]
+   [app.common.test-helpers.compositions :as ctho]
+   [app.common.test-helpers.files :as cthf]
+   [app.common.test-helpers.shapes :as cths]
+   [app.main.data.workspace :as dw]
+   [cljs.test :as t :include-macros true]
+   [frontend-tests.helpers.state :as ths]))
+
+(t/deftest test-update-positions-multiple-ids
+  (t/async
+    done
+    (let [file   (-> (cthf/sample-file :file1)
+                     (ctho/add-rect :rect1 :x 10 :y 20 :width 10 :height 10)
+                     (ctho/add-rect :rect2 :x 30 :y 40 :width 10 :height 10))
+          store  (ths/setup-store file)
+          rect1  (cths/get-shape file :rect1)
+          rect2  (cths/get-shape file :rect2)
+          ids    [(:id rect1) (:id rect2)]
+          events [(dw/update-positions ids {:x 123.45})]]
+      (ths/run-store
+       store done events
+       (fn [new-state]
+         (let [file' (ths/get-file-from-state new-state)
+               rect1' (cths/get-shape file' :rect1)
+               rect2' (cths/get-shape file' :rect2)
+               x1     (-> rect1' :points grc/points->rect :x)
+               x2     (-> rect2' :points grc/points->rect :x)]
+           (t/is (= 123.45 x1))
+           (t/is (= 123.45 x2))))))))

frontend/translations/en.po

@@ -1467,7 +1467,7 @@ msgid "errors.generic"
 msgstr "Something wrong has happened."
 
 msgid "errors.unexpected-exception"
-msgstr "Unexpected exception: %s"
+msgstr "Unexpected error: %s"
 
 #: src/app/main/errors.cljs:200
 msgid "errors.internal-assertion-error"

manage.sh

@@ -215,6 +215,23 @@ function build-frontend-bundle {
     echo ">> bundle frontend end";
 }
 
+function build-mcp-bundle {
+    echo ">> bundle mcp start";
+
+    mkdir -p ./bundles
+    local version=$(print-current-version);
+    local bundle_dir="./bundles/mcp";
+
+    build "mcp";
+
+    rm -rf $bundle_dir;
+    mv ./mcp/dist $bundle_dir;
+    echo $version > $bundle_dir/version.txt;
+    put-license-file $bundle_dir;
+    echo ">> bundle mcp end";
+}
+
+
 function build-backend-bundle {
     echo ">> bundle backend start";
 
@@ -309,6 +326,16 @@ function build-exporter-docker-image {
     popd;
 }
 
+function build-mcp-docker-image {
+    rsync -avr --delete ./bundles/mcp/ ./docker/images/bundle-mcp/;
+    pushd ./docker/images;
+    docker build \
+        -t penpotapp/mcp:$CURRENT_BRANCH -t penpotapp/mcp:latest \
+        --build-arg BUNDLE_PATH="./bundle-mcp/" \
+        -f Dockerfile.mcp .;
+    popd;
+}
+
 function build-storybook-docker-image {
     rsync -avr --delete ./bundles/storybook/ ./docker/images/bundle-storybook/;
     pushd ./docker/images;
@@ -346,6 +373,7 @@ function usage {
     echo "- build-frontend-docker-image      Build frontend docker images."
     echo "- build-backend-docker-image       Build backend docker images."
     echo "- build-exporter-docker-image      Build exporter docker images."
+    echo "- build-mcp-docker-image           Build exporter docker images."
     echo "- build-storybook-docker-image     Build storybook docker images."
     echo ""
     echo "- version                          Show penpot's version."
@@ -397,6 +425,7 @@ case $1 in
     ## production builds
     build-bundle)
         build-frontend-bundle;
+        build-mcp-bundle;
         build-backend-bundle;
         build-exporter-bundle;
         build-storybook-bundle;
@@ -406,6 +435,10 @@ case $1 in
         build-frontend-bundle;
         ;;
 
+    build-mcp-bundle)
+        build-mcp-bundle;
+        ;;
+
     build-backend-bundle)
         build-backend-bundle;
         ;;
@@ -431,6 +464,7 @@ case $1 in
         build-frontend-docker-image
         build-backend-docker-image
         build-exporter-docker-image
+        build-mcp-docker-image
         build-storybook-docker-image
         ;;
 
@@ -445,7 +479,11 @@ case $1 in
     build-exporter-docker-image)
         build-exporter-docker-image
         ;;
- 
+
+    build-mcp-docker-image)
+        build-mcp-docker-image
+        ;;
+
     build-storybook-docker-image)
         build-storybook-docker-image
         ;;

mcp/.gitignore

@@ -0,0 +1,11 @@
+.idea
+node_modules
+dist
+*.bak
+*.orig
+temp
+*.tsbuildinfo
+
+# Log files
+logs/
+*.log

mcp/.prettierignore

@@ -0,0 +1,7 @@
+*.md
+*.json
+python-scripts/
+.serena/
+
+# auto-generated files
+mcp-server/data/api_types.yml

mcp/.prettierrc

@@ -0,0 +1,20 @@
+{
+    "tabWidth": 4,
+    "overrides": [
+        {
+            "files": "*.yml",
+            "options": {
+                "tabWidth": 2
+            }
+        }
+    ],
+    "useTabs": false,
+    "semi": true,
+    "singleQuote": false,
+    "quoteProps": "as-needed",
+    "trailingComma": "es5",
+    "bracketSpacing": true,
+    "arrowParens": "always",
+    "printWidth": 120,
+    "endOfLine": "auto"
+}

mcp/.serena/.gitignore

@@ -0,0 +1 @@
+/cache

mcp/.serena/memories/code_style_conventions.md

@@ -0,0 +1,25 @@
+# Code Style and Conventions
+
+## General Principles
+- **Object-Oriented Design**: VERY IMPORTANT: Use idiomatic, object-oriented style with explicit abstractions
+- **Strategy Pattern**: Prefer explicitly typed interfaces over bare functions for non-trivial functionality
+- **Clean Architecture**: Tools implement a common interface for consistent registration and execution
+
+## TypeScript Configuration
+- **Strict Mode**: All strict TypeScript options enabled
+- **Target**: ES2022
+- **Module System**: CommonJS
+- **Declaration Files**: Generated with source maps
+
+## Naming Conventions
+- **Classes**: PascalCase (e.g., `ExeceuteCodeTool`, `PenpotMcpServer`)
+- **Interfaces**: PascalCase (e.g., `Tool`)
+- **Methods**: camelCase (e.g., `execute`, `registerTools`)
+- **Constants**: camelCase for readonly properties (e.g., `definition`)
+- **Files**: PascalCase for classes (e.g., `ExecuteCodeTool.ts`)
+
+## Documentation Style
+- **JSDoc**: Use comprehensive JSDoc comments for classes, methods, and interfaces
+- **Description Format**: Initial elliptical phrase that defines *what* it is, followed by details
+- **Comment Style**: VERY IMPORTANT: Start with lowercase for comments of code blocks (unless lengthy explanation with multiple sentences)
+

mcp/.serena/memories/project_overview.md

@@ -0,0 +1,91 @@
+# Penpot MCP Project Overview - Updated
+
+## Purpose
+This project is a Model Context Protocol (MCP) server for Penpot integration. It provides a TypeScript-based server that can be used to extend Penpot's functionality through custom tools with bidirectional WebSocket communication.
+
+## Tech Stack
+- **Language**: TypeScript
+- **Runtime**: Node.js
+- **Framework**: MCP SDK (@modelcontextprotocol/sdk)
+- **Build Tool**: TypeScript Compiler (tsc) + esbuild
+- **Package Manager**: pnpm
+- **WebSocket**: ws library for real-time communication
+
+## Project Structure
+```
+penpot-mcp/
+├── common/                    # Shared type definitions
+│   ├── src/
+│   │   ├── index.ts           # Exports for shared types
+│   │   └── types.ts           # PluginTaskResult, request/response interfaces
+│   └── package.json           # @penpot-mcp/common package
+├── mcp-server/                # Main MCP server implementation
+│   ├── src/
+│   │   ├── index.ts           # Main server entry point
+│   │   ├── PenpotMcpServer.ts # Enhanced with request/response correlation
+│   │   ├── PluginTask.ts      # Now supports result promises
+│   │   ├── tasks/             # PluginTask implementations
+│   │   └── tools/             # Tool implementations
+│   └── package.json           # Includes @penpot-mcp/common dependency
+├── penpot-plugin/             # Penpot plugin with response capability
+│   ├── src/
+│   │   ├── main.ts            # Enhanced WebSocket handling with response forwarding
+│   │   └── plugin.ts          # Now sends task responses back to server
+│   └── package.json           # Includes @penpot-mcp/common dependency
+└── prepare-api-docs           # Python project for the generation of API docs
+```
+
+## Key Tasks
+
+### Adding a new Tool
+
+1. Implement the tool class in `mcp-server/src/tools/` following the `Tool` interface. 
+   IMPORTANT: Do not catch any exceptions in the `executeCore` method. Let them propagate to be handled centrally.
+2. Register the tool in `PenpotMcpServer`.
+
+Look at `PrintTextTool` as an example.
+
+Many tools are linked to tasks that are handled in the plugin, i.e. they have an associated `PluginTask` implementation in `mcp-server/src/tasks/`.
+
+### Adding a new PluginTask
+
+1. Implement the input data interface for the task in `common/src/types.ts`.
+2. Implement the `PluginTask` class in `mcp-server/src/tasks/`.
+3. Implement the corresponding task handler class in the plugin (`penpot-plugin/src/task-handlers/`).
+    * In the success case, call `task.sendSuccess`.
+    * In the failure case, just throw an exception, which will be handled centrally!
+    * Look at `PrintTextTaskHandler` as an example.
+4. Register the task handler in `penpot-plugin/src/plugin.ts` in the `taskHandlers` list.
+
+
+## Key Components
+
+### Enhanced WebSocket Protocol
+- **Request Format**: `{id: string, task: string, params: any}`
+- **Response Format**: `{id: string, result: {success: boolean, error?: string, data?: any}}`
+- **Request/Response Correlation**: Using unique UUIDs for task tracking
+- **Timeout Handling**: 30-second timeout with automatic cleanup
+- **Type Safety**: Shared definitions via @penpot-mcp/common package
+
+### Core Classes
+- **PenpotMcpServer**: Enhanced with pending task tracking and response handling
+- **PluginTask**: Now creates result promises that resolve when plugin responds
+- **Tool implementations**: Now properly await task completion and report results
+- **Plugin handlers**: Send structured responses back to server
+
+### New Features
+1. **Bidirectional Communication**: Plugin now responds with success/failure status
+2. **Task Result Promises**: Every executePluginTask() sets and returns a promise
+3. **Error Reporting**: Failed tasks properly report error messages to tools
+4. **Shared Type Safety**: Common package ensures consistency across projects
+5. **Timeout Protection**: Tasks don't hang indefinitely (30s limit)
+6. **Request Correlation**: Unique IDs match requests to responses
+
+## Task Flow
+
+```
+LLM Tool Call → MCP Server → WebSocket (Request) → Plugin → Penpot API
+                    ↑                                  ↓
+             Tool Response ← MCP Server ← WebSocket (Response) ← Plugin Result
+```
+

mcp/.serena/memories/suggested_commands.md

@@ -0,0 +1,70 @@
+# Suggested Commands
+
+## Development Commands
+```bash
+# Navigate to MCP server directory
+cd penpot/mcp/server
+
+# Install dependencies
+pnpm install
+
+# Build the TypeScript project
+pnpm run build
+
+# Start the server (production)
+pnpm run start
+
+# Start the server in development mode
+npm run start:dev
+```
+
+## Testing and Development
+```bash
+# Run TypeScript compiler in watch mode
+pnpx tsc --watch
+
+# Check TypeScript compilation without emitting files
+pnpx tsc --noEmit
+```
+
+## Windows-Specific Commands
+```cmd
+# Directory navigation
+cd penpot/mcp/server
+dir                    # List directory contents
+type package.json      # Display file contents
+
+# Git operations
+git status
+git add .
+git commit -m "message"
+git push
+
+# File operations
+copy src\file.ts backup\file.ts    # Copy files
+del dist\*                         # Delete files
+mkdir new-directory                # Create directory
+rmdir /s directory                 # Remove directory recursively
+```
+
+## Project Structure Navigation
+```bash
+# Key directories
+cd penpot/mcp/server/src              # Source code
+cd penpot/mcp/server/src/tools        # Tool implementations
+cd penpot/mcp/server/src/interfaces   # Type definitions
+cd penpot/mcp/server/dist             # Compiled output
+```
+
+## Common Utilities
+```cmd
+# Search for text in files
+findstr /s /i "HelloWorld" *.ts
+
+# Find files by name
+dir /s /b *Tool.ts
+
+# Process management
+tasklist | findstr node    # Find Node.js processes
+taskkill /f /im node.exe   # Kill Node.js processes
+```

mcp/.serena/memories/task_completion_guidelines.md

@@ -0,0 +1,56 @@
+# Task Completion Guidelines
+
+## After Making Code Changes
+
+### 1. Build and Test
+```bash
+cd mcp-server
+npm run build:full  # or npm run build for faster bundling only
+```
+
+### 2. Verify TypeScript Compilation
+```bash
+npx tsc --noEmit
+```
+
+### 3. Test the Server
+```bash
+# Start in development mode to test changes
+npm run dev
+```
+
+### 4. Code Quality Checks
+- Ensure all code follows the established conventions
+- Verify JSDoc comments are complete and accurate
+- Check that error handling is appropriate
+- Use clean imports WITHOUT file extensions (esbuild handles resolution)
+- Validate that tool interfaces are properly implemented
+
+### 5. Integration Testing
+- Test tool registration in the main server
+- Verify MCP protocol compliance
+- Ensure tool definitions match implementation
+
+## Before Committing Changes
+1. **Build Successfully**: `npm run build:full` completes without errors
+2. **No TypeScript Errors**: `npx tsc --noEmit` passes
+3. **Documentation Updated**: JSDoc comments reflect changes
+4. **Tool Registry Updated**: New tools added to `registerTools()` method
+5. **Interface Compliance**: All tools implement the `Tool` interface correctly
+
+## File Organization
+- Place new tools in `src/tools/` directory
+- Update main server registration in `src/index.ts`
+- Follow existing naming conventions
+
+## Common Patterns
+- All tools must implement the `Tool` interface
+- Use readonly properties for tool definitions
+- Include comprehensive error handling
+- Follow the established documentation style
+- Import WITHOUT file extensions (esbuild resolves them automatically)
+
+## Build System
+- Uses esbuild for fast bundling and TypeScript for declarations
+- Import statements should omit file extensions entirely
+- IDE refactoring is safe - no extension-related build failures

mcp/.serena/project.yml

@@ -0,0 +1,130 @@
+
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: |
+  IMPORTANT: You use an idiomatic, object-oriented style.
+  In particular, this implies that, for any non-trivial interfaces, you use interfaces that expect explicitly typed abstractions 
+  rather than mere functions (i.e. use the strategy pattern, for example).
+
+  Comments: 
+  When describing parameters, methods/functions and classes, you use a precise style, where the initial (elliptical) phrase
+  clearly defines *what* it is. Any details then follow in subsequent sentences.
+
+  When describing what blocks of code do, you also use an elliptical style and start with a lower-case letter unless
+  the comment is a lengthy explanation with at least two sentences (in which case you start with a capital letter, as is 
+  required for sentences).
+# the name by which the project can be referenced within Serena
+project_name: "penpot-mcp"
+
+# list of mode names to that are always to be included in the set of active modes
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this setting overrides the global configuration.
+# Set this to [] to disable base modes for this project.
+# Set this to a list of mode names to always include the respective modes for this project.
+base_modes:
+
+# list of mode names that are to be activated by default.
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+default_modes:
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default)
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+fixed_tools: []
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: utf-8
+
+
+
+# list of languages for which language servers are started; choose from:
+#   al                  bash                clojure             cpp                 csharp
+#   csharp_omnisharp    dart                elixir              elm                 erlang
+#   fortran             fsharp              go                  groovy              haskell
+#   java                julia               kotlin              lua                 markdown
+#   matlab              nix                 pascal              perl                php
+#   powershell          python              python_jedi         r                   rego
+#   ruby                ruby_solargraph     rust                scala               swift
+#   terraform           toml                typescript          typescript_vts      vue
+#   yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- typescript

mcp/README.md

@@ -0,0 +1,291 @@
+![mcp-server-cover-github-1](https://github.com/user-attachments/assets/dcd14e63-fecd-424f-9a50-c1b1eafe2a4f)
+
+# Penpot's Official MCP Server
+
+Penpot integrates a LLM layer built on the Model Context Protocol
+(MCP) via Penpot's Plugin API to interact with a Penpot design
+file. Penpot's MCP server enables LLMs to perfom data queries,
+transformation and creation operations.
+
+Penpot's MCP Server is unlike any other you've seen. You get
+design-to- design, code-to-design and design-code supercharged
+workflows.
+
+
+[![Penpot MCP video playlist](https://github.com/user-attachments/assets/204f1d99-ce51-41dd-a5dd-1ef739f8f089)](https://www.youtube.com/playlist?list=PLgcCPfOv5v57SKMuw1NmS0-lkAXevpn10)
+
+
+## Architecture
+
+The **Penpot MCP Server** exposes tools to AI clients (LLMs), which
+support the retrieval of design data as well as the modification and
+creation of design elements.  The MCP server communicates with Penpot
+via the dedicated **Penpot MCP Plugin**,
+which connects to the MCP server via WebSocket.  
+This enables the LLM to carry out tasks in the context of a design file by 
+executing code that leverages the Penpot Plugin API.
+The LLM is free to write and execute arbitrary code snippets
+within the Penpot Plugin environment to accomplish its tasks.
+
+![Architecture](resources/architecture.png)
+
+This repository thus contains not only the MCP server implementation itself
+but also the supporting Penpot MCP Plugin 
+(see section [Repository Structure](#repository-structure) below).
+
+## Demonstration
+
+[![Video](https://v32155.1blu.de/penpot/PenpotFest2025_thumbnail.png)](https://v32155.1blu.de/penpot/PenpotFest2025.mp4)
+
+
+## Usage
+
+To use the Penpot MCP server, you must
+ * run the MCP server and connect your AI client to it,
+ * run the web server providing the Penpot MCP plugin, and
+ * open the Penpot MCP plugin in Penpot and connect it to the MCP server. 
+
+Follow the steps below to enable the integration.
+
+
+### Prerequisites
+
+The project requires [Node.js](https://nodejs.org/) (tested with v22.x
+with corepack).
+
+Following the installation of Node.js, the tools `pnpm` and `npx`
+should be available in your terminal. For ensure corepack installed
+and enabled correctly, just execute the `./scripts/setup`.
+
+It is also required to have `caddy` executeable in the path, it is
+used for start a local server for generate types documentation from
+the current branch. If you want to run it outside devenv where all
+dependencies are already provided, please download caddy from
+[here](https://caddyserver.com/download).
+
+You should probably be using penpot devenv, where all this
+dependencies are already present and correctly setup. But nothing
+prevents you execute this outside of devenv if you satisfy the
+specified dependencies.
+
+
+### 1. Build & Launch the MCP Server and the Plugin Server
+
+If it's your first execution, install the required dependencies:
+
+```shell
+cd mcp/
+./scripts/setup
+```
+
+Then build all components and start the two servers:
+
+```shell
+pnpm run bootstrap
+```
+
+This bootstrap command will:
+
+  * install dependencies for all components (`pnpm -r run install`)
+  * build all components (`pnpm -r run build`)
+  * start all components (`pnpm -r --parallel run start`)
+
+If you want to have types scrapped from a remote repository, the best
+approach is executing the following:
+
+```shell
+PENPOT_PLUGINS_API_DOC_URL=https://doc.plugins.penpot.app pnpm run build:types
+pnpm run bootstrap
+```
+
+Or this, if you want skip build step bacause you have already have all
+build artifacts ready (per example from previous `bootstrap` command):
+
+```
+PENPOT_PLUGINS_API_DOC_URL=https://doc.plugins.penpot.app pnpm run build:types
+pnpm run start
+```
+
+If you want just to update the types definitions with the plugins api doc from the
+current branch:
+
+```shell
+pnpm run build:types
+```
+
+(That command will build plugins doc locally and will generate the types yaml from
+the locally build documentation)
+
+### 2. Load the Plugin in Penpot and Establish the Connection
+
+> [!NOTE]
+> **Browser Connectivity Restrictions**
+>
+> Starting with Chromium version 142, the private network access (PNA) restrictions have been hardened,
+> and when connecting to `localhost` from a web application served from a different origin
+> (such as https://design.penpot.app), the connection must explicitly be allowed.
+>
+> Most Chromium-based browsers (e.g. Chrome, Vivaldi) will display a popup requesting permission
+> to access the local network. Be sure to approve the request to allow the connection.
+>
+> Some browsers take additional security measures, and you may need to disable them.
+> For example, in Brave, disable the "Shield" for the Penpot website to allow local network access.
+>
+> If your browser refuses to connect to the locally served plugin, check its configuration or
+> try a different browser (e.g. Firefox) that does not enforce these restrictions.
+
+1. Open Penpot in your browser
+2. Navigate to a design file
+3. Open the Plugins menu
+4. Load the plugin using the development URL (`http://localhost:4400/manifest.json` by default)
+5. Open the plugin UI
+6. In the plugin UI, click "Connect to MCP server".
+   The connection status should change from "Not connected" to "Connected to MCP server".
+   (Check the browser's developer console for WebSocket connection logs.
+   Check the MCP server terminal for WebSocket connection messages.)
+
+> [!IMPORTANT]
+> Do not close the plugin's UI while using the MCP server, as this will close the connection.
+
+### 3. Connect an MCP Client
+
+By default, the server runs on port 4401 and provides:
+
+- **Modern Streamable HTTP endpoint**: `http://localhost:4401/mcp`
+- **Legacy SSE endpoint**: `http://localhost:4401/sse`
+
+These endpoints can be used directly by MCP clients that support them.
+Simply configure the client to connect the MCP server by providing the respective URL.
+
+When using a client that only supports stdio transport,
+a proxy like `mcp-remote` is required.
+
+#### Using a Proxy for stdio Transport
+
+NOTE: only relevant if you are executing this outside of devenv
+
+The `mcp-remote` package can proxy stdio transport to HTTP/SSE, 
+allowing clients that support only stdio to connect to the MCP server indirectly.
+
+1. Install `mcp-remote` globally if you haven't already:
+
+        npm install -g mcp-remote
+
+2. Use `mcp-remote` to provide the launch command for your MCP client:
+
+        npx -y mcp-remote http://localhost:4401/sse --allow-http
+
+#### Example: Claude Desktop
+
+For Windows and macOS, there is the official [Claude Desktop app](https://claude.ai/download), which you can use as an MCP client.
+For Linux, there is an [unofficial community version](https://github.com/aaddrick/claude-desktop-debian).
+
+Since Claude Desktop natively supports only stdio transport, you will need to use a proxy like `mcp-remote`.
+Install it as described above.
+
+To add the server to Claude Desktop's configuration, locate the configuration file (or find it via Menu / File / Settings / Developer):
+
+- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+Add a `penpot` entry under `mcpServers` with the following content: 
+
+```json
+{
+    "mcpServers": {
+        "penpot": {
+            "command": "npx",
+            "args": ["-y", "mcp-remote", "http://localhost:4401/sse", "--allow-http"]
+        }
+    }
+}
+```
+
+After updating the configuration file, restart Claude Desktop completely for the changes to take effect.
+
+> [!IMPORTANT] 
+> Be sure to fully quit the app for the changes to take effect; closing the window is *not* sufficient.   
+> To fully terminate the app, choose Menu / File / Quit.
+
+After the restart, you should see the MCP server listed when clicking on the "Search and tools" icon at the bottom
+of the prompt input area.
+
+#### Example: Claude Code
+
+To add the Penpot MCP server to a Claude Code project, issue the command
+
+    claude mcp add penpot -t http http://localhost:4401/mcp
+
+## Repository Structure
+
+This repository is a monorepo containing four main components:
+
+1. **Common Types** (`common/`):
+    - Shared TypeScript definitions for request/response protocol
+    - Ensures type safety across server and plugin components
+
+2. **Penpot MCP Server** (`mcp-server/`):
+    - Provides MCP tools to LLMs for Penpot interaction
+    - Runs a WebSocket server accepting connections from the Penpot MCP plugin
+    - Implements request/response correlation with unique task IDs
+    - Handles task timeouts and proper error reporting
+
+3. **Penpot MCP Plugin** (`penpot-plugin/`):
+    - Connects to the MCP server via WebSocket
+    - Executes tasks in Penpot using the Plugin API
+    - Sends structured responses back to the server#
+
+4. **Helper Scripts** (`python-scripts/`):
+    - Python scripts that prepare data for the MCP server (development use)
+
+The core components are written in TypeScript, rendering interactions with the
+Penpot Plugin API both natural and type-safe.
+
+## Configuration
+
+The Penpot MCP server can be configured using environment variables. All configuration
+options use the `PENPOT_MCP_` prefix for consistency.
+
+### Server Configuration
+
+| Environment Variable               | Description                                                                | Default      |
+|------------------------------------|----------------------------------------------------------------------------|--------------|
+| `PENPOT_MCP_SERVER_LISTEN_ADDRESS` | Address on which the MCP server listens (binds to)                         | `localhost`  |
+| `PENPOT_MCP_SERVER_PORT`           | Port for the HTTP/SSE server                                               | `4401`       |
+| `PENPOT_MCP_WEBSOCKET_PORT`        | Port for the WebSocket server (plugin connection)                          | `4402`       |
+| `PENPOT_MCP_REPL_PORT`             | Port for the REPL server (development/debugging)                           | `4403`       |
+| `PENPOT_MCP_SERVER_ADDRESS`        | Hostname or IP address via which clients can reach the MCP server          | `localhost`  |
+| `PENPOT_MCP_REMOTE_MODE`           | Enable remote mode (disables file system access). Set to `true` to enable. | `false`      |
+
+### Logging Configuration
+
+| Environment Variable   | Description                                          | Default  |
+|------------------------|------------------------------------------------------|----------|
+| `PENPOT_MCP_LOG_LEVEL` | Log level: `trace`, `debug`, `info`, `warn`, `error` | `info`   |
+| `PENPOT_MCP_LOG_DIR`   | Directory for log files                              | `logs`   |
+
+### Plugin Server Configuration
+
+| Environment Variable                      | Description                                                                             | Default      |
+|-------------------------------------------|-----------------------------------------------------------------------------------------|--------------|
+| `PENPOT_MCP_PLUGIN_SERVER_LISTEN_ADDRESS` | Address on which the plugin web server listens (single address or comma-separated list) | (local only) |
+
+## Beyond Local Execution
+
+The above instructions describe how to run the MCP server and plugin server locally.
+We are working on enabling remote deployments of the MCP server, particularly
+in [multi-user mode](docs/multi-user-mode.md), where multiple Penpot users will
+be able to connect to the same MCP server instance.
+
+To run the server remotely (even for a single user),
+you may set the following environment variables to configure the two servers
+(MCP server & plugin server) appropriately:
+ * `PENPOT_MCP_REMOTE_MODE=true`: This ensures that the MCP server is operating
+   in remote mode, with local file system access disabled.
+ * `PENPOT_MCP_SERVER_LISTEN_ADDRESS` and `PENPOT_MCP_PLUGIN_SERVER_LISTEN_ADDRESS`:
+   Set these according to your requirements for remote connectivity.
+   To bind all interfaces, use `0.0.0.0` (use caution in untrusted networks).
+ * `PENPOT_MCP_SERVER_ADDRESS=<your-address>`: This sets the hostname or IP address
+   where the MCP server can be reached. The Penpot MCP Plugin uses this to construct
+   the WebSocket URL as `ws://<your-address>:<port>` (default port: `4402`).

mcp/docs/multi-user-mode.md

@@ -0,0 +1,41 @@
+# Multi-User Mode
+
+> [!WARNING]
+> Multi-user mode is under development and not yet fully integrated.
+> This information is provided for testing purposes only.
+
+The Penpot MCP server supports a multi-user mode, allowing multiple Penpot users
+to connect to the same MCP server instance simultaneously.
+This supports remote deployments of the MCP server, without requiring each user
+to run their own server instance.
+
+## Limitations
+
+Multi-user mode has the limitation that tools which read from or write to
+the local file system are not supported, as the server cannot access
+the client's file system. This affects the import and export tools.
+
+## Running Components in Multi-User Mode
+
+To run the MCP server and the Penpot MCP plugin in multi-user mode (for testing),
+you can use the following command:
+
+```shell
+npm run bootstrap:multi-user
+```
+
+This will:
+* launch the MCP server in multi-user mode (adding the `--multi-user` flag),
+* build and launch the Penpot MCP plugin server in multi-user mode.
+
+See the package.json scripts for both `mcp-server` and `penpot-plugin` for details.
+
+In multi-user mode, users are required to be authenticated via a token.
+
+* This token is provided in the URL used to connect to the MCP server,
+  e.g. `http://localhost:4401/mcp?userToken=USER_TOKEN`.
+* The same token must be provided when connecting the Penpot MCP plugin
+  to the MCP server.    
+  In the future, the token will, most likely be generated by Penpot and
+  provided to the plugin automatically.
+  :warning: For now, it is hard-coded in the plugin's source code for testing purposes.

mcp/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "mcp-meta",
+  "version": "1.0.0",
+  "description": "",
+  "scripts": {
+    "build": "pnpm -r run build",
+    "build:multi-user": "pnpm -r run build:multi-user",
+    "build:types": "./scripts/build-types",
+    "start": "pnpm -r --parallel run start",
+    "start:multi-user": "pnpm -r --parallel --filter \"./packages/*\"  run start:multi-user",
+    "bootstrap": "pnpm -r install && pnpm run build && pnpm run start",
+    "bootstrap:multi-user": "pnpm -r install && pnpm run build:multi-user && pnpm run start:multi-user",
+    "fmt": "prettier --write packages/",
+    "fmt:check": "prettier --check packages/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/penpot/penpot.git"
+  },
+  "packageManager": "pnpm@10.28.2+sha512.41872f037ad22f7348e3b1debbaf7e867cfd448f2726d9cf74c08f19507c31d2c8e7a11525b983febc2df640b5438dee6023ebb1f84ed43cc2d654d2bc326264",
+  "private": true,
+  "devDependencies": {
+    "concurrently": "^9.2.1",
+    "prettier": "^3.0.0"
+  }
+}

mcp/packages/common/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "mcp-common",
+  "version": "1.0.0",
+  "description": "Shared type definitions and interfaces for Penpot MCP",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "packageManager": "pnpm@10.28.2+sha512.41872f037ad22f7348e3b1debbaf7e867cfd448f2726d9cf74c08f19507c31d2c8e7a11525b983febc2df640b5438dee6023ebb1f84ed43cc2d654d2bc326264",
+  "scripts": {
+    "build": "tsc --build --clean && tsc --build",
+    "watch": "tsc --watch",
+    "types:check": "tsc --noEmit",
+    "clean": "rm -rf dist/"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist/**/*"
+  ]
+}

mcp/packages/common/src/index.ts

@@ -0,0 +1 @@
+export * from "./types";

mcp/packages/common/src/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Result of a plugin task execution.
+ *
+ * Contains the outcome status of a task and any additional result data.
+ */
+export interface PluginTaskResult<T> {
+    /**
+     * Optional result data from the task execution.
+     */
+    data?: T;
+}
+
+/**
+ * Request message sent from server to plugin.
+ *
+ * Contains a unique identifier, task name, and parameters for execution.
+ */
+export interface PluginTaskRequest {
+    /**
+     * Unique identifier for request/response correlation.
+     */
+    id: string;
+
+    /**
+     * The name of the task to execute.
+     */
+    task: string;
+
+    /**
+     * The parameters for task execution.
+     */
+    params: any;
+}
+
+/**
+ * Response message sent from plugin back to server.
+ *
+ * Contains the original request ID and the execution result.
+ */
+export interface PluginTaskResponse<T> {
+    /**
+     * Unique identifier matching the original request.
+     */
+    id: string;
+
+    /**
+     * Whether the task completed successfully.
+     */
+    success: boolean;
+
+    /**
+     * Optional error message if the task failed.
+     */
+    error?: string;
+
+    /**
+     * The result of the task execution.
+     */
+    data?: T;
+}
+
+/**
+ * Parameters for the executeCode task.
+ */
+export interface ExecuteCodeTaskParams {
+    /**
+     * The JavaScript code to be executed.
+     */
+    code: string;
+}
+
+/**
+ * Result data for the executeCode task.
+ */
+export interface ExecuteCodeTaskResultData<T> {
+    /**
+     * The result of the executed code, if any.
+     */
+    result: T;
+
+    /**
+     * Captured console output during code execution.
+     */
+    log: string;
+}

mcp/packages/common/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

mcp/packages/plugin/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

mcp/packages/plugin/README.md

@@ -0,0 +1,21 @@
+# Penpot MCP Plugin
+
+This project contains a Penpot plugin that accompanies the Penpot MCP server.
+It connects to the MCP server via WebSocket, subsequently allowing the MCP
+server to execute tasks in Penpot using the Plugin API.
+
+## Setup
+
+1. Install Dependencies
+
+        pnpm install
+
+2. Build the Project
+
+        pnpm run build
+
+3. Start a Local Development Server
+
+        pnpm run start
+
+   This will start a local development server at `http://localhost:4400`.

mcp/packages/plugin/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Penpot plugin example</title>
+    </head>
+    <body>
+        <button type="button" data-appearance="secondary" data-handler="connect-mcp">Connect to MCP server</button>
+
+        <div id="connection-status" style="margin-top: 10px; font-size: 12px; color: #666">Not connected</div>
+
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>

mcp/packages/plugin/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "mcp-plugin",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "start": "vite build --watch --config vite.config.ts",
+    "start:multi-user": "cross-env MULTI_USER_MODE=true vite build --watch --config vite.config.ts",
+    "build": "tsc && vite build --config vite.release.config.ts",
+    "build:multi-user": "tsc && cross-env MULTI_USER_MODE=true vite build  --config vite.release.config.ts",
+    "types:check": "tsc --noEmit",
+    "clean": "rm -rf dist/"
+  },
+  "dependencies": {
+    "@penpot/plugin-styles": "1.4.1",
+    "@penpot/plugin-types": "1.4.1"
+  },
+  "devDependencies": {
+    "cross-env": "^7.0.3",
+    "typescript": "^5.8.3",
+    "vite": "^7.0.8",
+    "vite-live-preview": "^0.3.2"
+  }
+}

mcp/packages/plugin/public/manifest.json

@@ -0,0 +1,6 @@
+{
+    "name": "Penpot MCP Plugin",
+    "code": "plugin.js",
+    "description": "This plugin enables interaction with the Penpot MCP server",
+    "permissions": ["content:read", "content:write", "library:read", "library:write", "comment:read", "comment:write"]
+}

mcp/packages/plugin/src/PenpotUtils.ts

@@ -0,0 +1,425 @@
+import { Board, Fill, FlexLayout, GridLayout, Page, Rectangle, Shape } from "@penpot/plugin-types";
+
+export class PenpotUtils {
+    /**
+     * Generates an overview structure of the given shape,
+     * providing its id, name and type, and recursively its children's attributes.
+     * The `type` field indicates the type in the Penpot API.
+     * If the shape has a layout system (flex or grid), includes layout information.
+     *
+     * @param shape - The root shape to generate the structure from
+     * @param maxDepth - Optional maximum depth to traverse (leave undefined for unlimited)
+     * @returns An object representing the shape structure
+     */
+    public static shapeStructure(shape: Shape, maxDepth: number | undefined = undefined): object {
+        let children = undefined;
+        if (maxDepth === undefined || maxDepth > 0) {
+            if ("children" in shape && shape.children) {
+                children = shape.children.map((child) =>
+                    this.shapeStructure(child, maxDepth === undefined ? undefined : maxDepth - 1)
+                );
+            }
+        }
+
+        const result: any = {
+            id: shape.id,
+            name: shape.name,
+            type: shape.type,
+            children: children,
+        };
+
+        // add layout information if present
+        if ("flex" in shape && shape.flex) {
+            const flex: FlexLayout = shape.flex;
+            result.layout = {
+                type: "flex",
+                dir: flex.dir,
+                rowGap: flex.rowGap,
+                columnGap: flex.columnGap,
+            };
+        } else if ("grid" in shape && shape.grid) {
+            const grid: GridLayout = shape.grid;
+            result.layout = {
+                type: "grid",
+                rows: grid.rows,
+                columns: grid.columns,
+                rowGap: grid.rowGap,
+                columnGap: grid.columnGap,
+            };
+        }
+
+        return result;
+    }
+
+    /**
+     * Finds all shapes that matches the given predicate in the given shape tree.
+     *
+     * @param predicate - A function that takes a shape and returns true if it matches the criteria
+     * @param root - The root shape to start the search from (defaults to penpot.root)
+     */
+    public static findShapes(predicate: (shape: Shape) => boolean, root: Shape | null = penpot.root): Shape[] {
+        let result = new Array<Shape>();
+
+        let find = function (shape: Shape | null) {
+            if (!shape) {
+                return;
+            }
+            if (predicate(shape)) {
+                result.push(shape);
+            }
+            if ("children" in shape && shape.children) {
+                for (let child of shape.children) {
+                    find(child);
+                }
+            }
+        };
+
+        find(root);
+        return result;
+    }
+
+    /**
+     * Finds the first shape that matches the given predicate in the given shape tree.
+     *
+     * @param predicate - A function that takes a shape and returns true if it matches the criteria
+     * @param root - The root shape to start the search from (if null, searches all pages)
+     */
+    public static findShape(predicate: (shape: Shape) => boolean, root: Shape | null = null): Shape | null {
+        let find = function (shape: Shape | null): Shape | null {
+            if (!shape) {
+                return null;
+            }
+            if (predicate(shape)) {
+                return shape;
+            }
+            if ("children" in shape && shape.children) {
+                for (let child of shape.children) {
+                    let result = find(child);
+                    if (result) {
+                        return result;
+                    }
+                }
+            }
+            return null;
+        };
+
+        if (root === null) {
+            const pages = penpot.currentFile?.pages;
+            if (pages) {
+                for (let page of pages) {
+                    let result = find(page.root);
+                    if (result) {
+                        return result;
+                    }
+                }
+            }
+            return null;
+        } else {
+            return find(root);
+        }
+    }
+
+    /**
+     * Finds a shape by its unique ID.
+     *
+     * @param id - The unique ID of the shape to find
+     * @returns The shape with the matching ID, or null if not found
+     */
+    public static findShapeById(id: string): Shape | null {
+        return this.findShape((shape) => shape.id === id);
+    }
+
+    public static findPage(predicate: (page: Page) => boolean): Page | null {
+        let page = penpot.currentFile!.pages.find(predicate);
+        return page || null;
+    }
+
+    public static getPages(): { id: string; name: string }[] {
+        return penpot.currentFile!.pages.map((page) => ({ id: page.id, name: page.name }));
+    }
+
+    public static getPageById(id: string): Page | null {
+        return this.findPage((page) => page.id === id);
+    }
+
+    public static getPageByName(name: string): Page | null {
+        return this.findPage((page) => page.name.toLowerCase() === name.toLowerCase());
+    }
+
+    public static getPageForShape(shape: Shape): Page | null {
+        for (const page of penpot.currentFile!.pages) {
+            if (page.getShapeById(shape.id)) {
+                return page;
+            }
+        }
+        return null;
+    }
+
+    public static generateCss(shape: Shape): string {
+        const page = this.getPageForShape(shape);
+        if (!page) {
+            throw new Error("Shape is not part of any page");
+        }
+        penpot.openPage(page);
+        return penpot.generateStyle([shape], { type: "css", includeChildren: true });
+    }
+
+    /**
+     * Checks if a child shape is fully contained within its parent's bounds.
+     * Visual containment means all edges of the child are within the parent's bounding box.
+     *
+     * @param child - The child shape to check
+     * @param parent - The parent shape to check against
+     * @returns true if child is fully contained within parent bounds, false otherwise
+     */
+    public static isContainedIn(child: Shape, parent: Shape): boolean {
+        return (
+            child.x >= parent.x &&
+            child.y >= parent.y &&
+            child.x + child.width <= parent.x + parent.width &&
+            child.y + child.height <= parent.y + parent.height
+        );
+    }
+
+    /**
+     * Sets the position of a shape relative to its parent's position.
+     * This is a convenience method since parentX and parentY are read-only properties.
+     *
+     * @param shape - The shape to position
+     * @param parentX - The desired X position relative to the parent
+     * @param parentY - The desired Y position relative to the parent
+     * @throws Error if the shape has no parent
+     */
+    public static setParentXY(shape: Shape, parentX: number, parentY: number): void {
+        if (!shape.parent) {
+            throw new Error("Shape has no parent - cannot set parent-relative position");
+        }
+        shape.x = shape.parent.x + parentX;
+        shape.y = shape.parent.y + parentY;
+    }
+
+    /**
+     * Adds a flex layout to a container while preserving the visual order of existing children.
+     * Without this, adding a flex layout can arbitrarily reorder children.
+     *
+     * The method sorts children by their current position (x for "row", y for "column") before
+     * adding the layout, then reorders them to maintain that visual sequence.
+     *
+     * @param container - The container (board) to add the flex layout to
+     * @param dir - The layout direction: "row" for horizontal, "column" for vertical
+     * @returns The created FlexLayout instance
+     */
+    public static addFlexLayout(container: Board, dir: "column" | "row"): FlexLayout {
+        // obtain children sorted by position (ascending)
+        const children = "children" in container && container.children ? [...container.children] : [];
+        const sortedChildren = children.sort((a, b) => (dir === "row" ? a.x - b.x : a.y - b.y));
+
+        // add the flex layout
+        const flexLayout = container.addFlexLayout();
+        flexLayout.dir = dir;
+
+        // reorder children to preserve visual order; since the children array is reversed
+        // relative to visual order for dir="column" or dir="row", we insert each child at
+        // index 0 in sorted order, which places the first (smallest position) at the highest
+        // index, making it appear first visually
+        for (const child of sortedChildren) {
+            child.setParentIndex(0);
+        }
+
+        return flexLayout;
+    }
+
+    /**
+     * Analyzes all descendants of a shape by applying an evaluator function to each.
+     * Only descendants for which the evaluator returns a non-null/non-undefined value are included in the result.
+     * This is a general-purpose utility for validation, analysis, or collecting corrector functions.
+     *
+     * @param root - The root shape whose descendants to analyze
+     * @param evaluator - Function called for each descendant with (root, descendant); return null/undefined to skip
+     * @param maxDepth - Optional maximum depth to traverse (undefined for unlimited)
+     * @returns Array of objects containing the shape and the evaluator's result
+     */
+    public static analyzeDescendants<T>(
+        root: Shape,
+        evaluator: (root: Shape, descendant: Shape) => T | null | undefined,
+        maxDepth: number | undefined = undefined
+    ): Array<{ shape: Shape; result: NonNullable<T> }> {
+        const results: Array<{ shape: Shape; result: NonNullable<T> }> = [];
+
+        const traverse = (shape: Shape, currentDepth: number): void => {
+            const result = evaluator(root, shape);
+            if (result !== null && result !== undefined) {
+                results.push({ shape, result: result as NonNullable<T> });
+            }
+
+            if (maxDepth === undefined || currentDepth < maxDepth) {
+                if ("children" in shape && shape.children) {
+                    for (const child of shape.children) {
+                        traverse(child, currentDepth + 1);
+                    }
+                }
+            }
+        };
+
+        // Start traversal with root's children (not root itself)
+        if ("children" in root && root.children) {
+            for (const child of root.children) {
+                traverse(child, 1);
+            }
+        }
+
+        return results;
+    }
+
+    /**
+     * Decodes a base64 string to a Uint8Array.
+     * This is required because the Penpot plugin environment does not provide the atob function.
+     *
+     * @param base64 - The base64-encoded string to decode
+     * @returns The decoded data as a Uint8Array
+     */
+    public static atob(base64: string): Uint8Array {
+        const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+        const lookup = new Uint8Array(256);
+        for (let i = 0; i < chars.length; i++) {
+            lookup[chars.charCodeAt(i)] = i;
+        }
+
+        let bufferLength = base64.length * 0.75;
+        if (base64[base64.length - 1] === "=") {
+            bufferLength--;
+            if (base64[base64.length - 2] === "=") {
+                bufferLength--;
+            }
+        }
+
+        const bytes = new Uint8Array(bufferLength);
+        let p = 0;
+        for (let i = 0; i < base64.length; i += 4) {
+            const encoded1 = lookup[base64.charCodeAt(i)];
+            const encoded2 = lookup[base64.charCodeAt(i + 1)];
+            const encoded3 = lookup[base64.charCodeAt(i + 2)];
+            const encoded4 = lookup[base64.charCodeAt(i + 3)];
+
+            bytes[p++] = (encoded1 << 2) | (encoded2 >> 4);
+            bytes[p++] = ((encoded2 & 15) << 4) | (encoded3 >> 2);
+            bytes[p++] = ((encoded3 & 3) << 6) | (encoded4 & 63);
+        }
+
+        return bytes;
+    }
+
+    /**
+     * Imports an image from base64 data into the Penpot design as a Rectangle shape filled with the image.
+     * The rectangle has the image's original proportions by default.
+     * Optionally accepts position (x, y) and dimensions (width, height) parameters.
+     * If only one dimension is provided, the other is calculated to maintain the image's aspect ratio.
+     *
+     * This function is used internally by the ImportImageTool in the MCP server.
+     *
+     * @param base64 - The base64-encoded image data
+     * @param mimeType - The MIME type of the image (e.g., "image/png")
+     * @param name - The name to assign to the newly created rectangle shape
+     * @param x - The x-coordinate for positioning the rectangle (optional)
+     * @param y - The y-coordinate for positioning the rectangle (optional)
+     * @param width - The desired width of the rectangle (optional)
+     * @param height - The desired height of the rectangle (optional)
+     */
+    public static async importImage(
+        base64: string,
+        mimeType: string,
+        name: string,
+        x: number | undefined,
+        y: number | undefined,
+        width: number | undefined,
+        height: number | undefined
+    ): Promise<Rectangle> {
+        // convert base64 to Uint8Array
+        const bytes = PenpotUtils.atob(base64);
+
+        // upload the image data to Penpot
+        const imageData = await penpot.uploadMediaData(name, bytes, mimeType);
+
+        // create a rectangle shape
+        const rect = penpot.createRectangle();
+        rect.name = name;
+
+        // calculate dimensions
+        let rectWidth, rectHeight;
+        const hasWidth = width !== undefined;
+        const hasHeight = height !== undefined;
+
+        if (hasWidth && hasHeight) {
+            // both width and height provided - use them directly
+            rectWidth = width;
+            rectHeight = height;
+        } else if (hasWidth) {
+            // only width provided - maintain aspect ratio
+            rectWidth = width;
+            rectHeight = rectWidth * (imageData.height / imageData.width);
+        } else if (hasHeight) {
+            // only height provided - maintain aspect ratio
+            rectHeight = height;
+            rectWidth = rectHeight * (imageData.width / imageData.height);
+        } else {
+            // neither provided - use original dimensions
+            rectWidth = imageData.width;
+            rectHeight = imageData.height;
+        }
+
+        // set rectangle dimensions
+        rect.resize(rectWidth, rectHeight);
+
+        // set position if provided
+        if (x !== undefined) {
+            rect.x = x;
+        }
+        if (y !== undefined) {
+            rect.y = y;
+        }
+
+        // apply the image as a fill
+        rect.fills = [{ fillOpacity: 1, fillImage: imageData }];
+
+        return rect;
+    }
+
+    /**
+     * Exports the given shape (or its fill) to BASE64 image data.
+     *
+     * This function is used internally by the ExportImageTool in the MCP server.
+     *
+     * @param shape - The shape whose image data to export
+     * @param mode - Either "shape" (to export the entire shape, including descendants) or "fill"
+     *    to export the shape's raw fill image data
+     * @param asSVG - Whether to export as SVG rather than as a pixel image (only supported for mode "shape")
+     * @returns A byte array containing the exported image data.
+     *   - For mode="shape", it will be PNG or SVG data depending on the value of `asSVG`.
+     *   - For mode="fill", it will be whatever format the fill image is stored in.
+     */
+    public static async exportImage(shape: Shape, mode: "shape" | "fill", asSVG: boolean): Promise<Uint8Array> {
+        switch (mode) {
+            case "shape":
+                return shape.export({ type: asSVG ? "svg" : "png" });
+            case "fill":
+                if (asSVG) {
+                    throw new Error("Image fills cannot be exported as SVG");
+                }
+                // check whether the shape has the `fills` member
+                if (!("fills" in shape)) {
+                    throw new Error("Shape with `fills` member is required for fill export mode");
+                }
+                // find first fill that has fillImage
+                const fills: Fill[] = (shape as any).fills;
+                for (const fill of fills) {
+                    if (fill.fillImage) {
+                        const imageData = fill.fillImage;
+                        return imageData.data();
+                    }
+                }
+                throw new Error("No fill with image data found in the shape");
+            default:
+                throw new Error(`Unsupported export mode: ${mode}`);
+        }
+    }
+}

mcp/packages/plugin/src/TaskHandler.ts

@@ -0,0 +1,77 @@
+/**
+ * Represents a task received from the MCP server in the Penpot MCP plugin
+ */
+export class Task<TParams = any> {
+    public isResponseSent: boolean = false;
+
+    /**
+     * @param requestId Unique identifier for the task request
+     * @param taskType The type of the task to execute
+     * @param params Task parameters/arguments
+     */
+    constructor(
+        public requestId: string,
+        public taskType: string,
+        public params: TParams
+    ) {}
+
+    /**
+     * Sends a task response back to the MCP server.
+     */
+    protected sendResponse(success: boolean, data: any = undefined, error: any = undefined): void {
+        if (this.isResponseSent) {
+            console.error("Response already sent for task:", this.requestId);
+            return;
+        }
+
+        const response = {
+            type: "task-response",
+            response: {
+                id: this.requestId,
+                success: success,
+                data: data,
+                error: error,
+            },
+        };
+
+        // Send to main.ts which will forward to MCP server via WebSocket
+        penpot.ui.sendMessage(response);
+        console.log("Sent task response:", response);
+        this.isResponseSent = true;
+    }
+
+    public sendSuccess(data: any = undefined): void {
+        this.sendResponse(true, data);
+    }
+
+    public sendError(error: string): void {
+        this.sendResponse(false, undefined, error);
+    }
+}
+
+/**
+ * Abstract base class for task handlers in the Penpot MCP plugin.
+ *
+ * @template TParams - The type of parameters this handler expects
+ */
+export abstract class TaskHandler<TParams = any> {
+    /** The task type this handler is responsible for */
+    abstract readonly taskType: string;
+
+    /**
+     * Checks if this handler can process the given task.
+     *
+     * @param task - The task identifier to check
+     * @returns True if this handler applies to the given task
+     */
+    isApplicableTo(task: Task): boolean {
+        return this.taskType === task.taskType;
+    }
+
+    /**
+     * Handles the task with the provided parameters.
+     *
+     * @param task - The task to be handled
+     */
+    abstract handle(task: Task<TParams>): Promise<void>;
+}

mcp/packages/plugin/src/main.ts

@@ -0,0 +1,110 @@
+import "./style.css";
+
+// get the current theme from the URL
+const searchParams = new URLSearchParams(window.location.search);
+document.body.dataset.theme = searchParams.get("theme") ?? "light";
+
+// Determine whether multi-user mode is enabled based on URL parameters
+const isMultiUserMode = searchParams.get("multiUser") === "true";
+console.log("Penpot MCP multi-user mode:", isMultiUserMode);
+
+// WebSocket connection management
+let ws: WebSocket | null = null;
+const statusElement = document.getElementById("connection-status");
+
+/**
+ * Updates the connection status display element.
+ *
+ * @param status - the base status text to display
+ * @param isConnectedState - whether the connection is in a connected state (affects color)
+ * @param message - optional additional message to append to the status
+ */
+function updateConnectionStatus(status: string, isConnectedState: boolean, message?: string): void {
+    if (statusElement) {
+        const displayText = message ? `${status}: ${message}` : status;
+        statusElement.textContent = displayText;
+        statusElement.style.color = isConnectedState ? "var(--accent-primary)" : "var(--error-700)";
+    }
+}
+
+/**
+ * Sends a task response back to the MCP server via WebSocket.
+ *
+ * @param response - The response containing task ID and result
+ */
+function sendTaskResponse(response: any): void {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify(response));
+        console.log("Sent response to MCP server:", response);
+    } else {
+        console.error("WebSocket not connected, cannot send response");
+    }
+}
+
+/**
+ * Establishes a WebSocket connection to the MCP server.
+ */
+function connectToMcpServer(): void {
+    if (ws?.readyState === WebSocket.OPEN) {
+        updateConnectionStatus("Already connected", true);
+        return;
+    }
+
+    try {
+        let wsUrl = PENPOT_MCP_WEBSOCKET_URL;
+        if (isMultiUserMode) {
+            // TODO obtain proper userToken from penpot
+            const userToken = "dummyToken";
+            wsUrl += `?userToken=${encodeURIComponent(userToken)}`;
+        }
+        ws = new WebSocket(wsUrl);
+        updateConnectionStatus("Connecting...", false);
+
+        ws.onopen = () => {
+            console.log("Connected to MCP server");
+            updateConnectionStatus("Connected to MCP server", true);
+        };
+
+        ws.onmessage = (event) => {
+            console.log("Received from MCP server:", event.data);
+            try {
+                const request = JSON.parse(event.data);
+                // Forward the task request to the plugin for execution
+                parent.postMessage(request, "*");
+            } catch (error) {
+                console.error("Failed to parse WebSocket message:", error);
+            }
+        };
+
+        ws.onclose = (event: CloseEvent) => {
+            console.log("Disconnected from MCP server");
+            const message = event.reason || undefined;
+            updateConnectionStatus("Disconnected", false, message);
+            ws = null;
+        };
+
+        ws.onerror = (error) => {
+            console.error("WebSocket error:", error);
+            // note: WebSocket error events typically don't contain detailed error messages
+            updateConnectionStatus("Connection error", false);
+        };
+    } catch (error) {
+        console.error("Failed to connect to MCP server:", error);
+        const message = error instanceof Error ? error.message : undefined;
+        updateConnectionStatus("Connection failed", false, message);
+    }
+}
+
+document.querySelector("[data-handler='connect-mcp']")?.addEventListener("click", () => {
+    connectToMcpServer();
+});
+
+// Listen plugin.ts messages
+window.addEventListener("message", (event) => {
+    if (event.data.source === "penpot") {
+        document.body.dataset.theme = event.data.theme;
+    } else if (event.data.type === "task-response") {
+        // Forward task response back to MCP server
+        sendTaskResponse(event.data.response);
+    }
+});

mcp/packages/plugin/src/plugin.ts

@@ -0,0 +1,69 @@
+import { ExecuteCodeTaskHandler } from "./task-handlers/ExecuteCodeTaskHandler";
+import { Task, TaskHandler } from "./TaskHandler";
+
+/**
+ * Registry of all available task handlers.
+ */
+const taskHandlers: TaskHandler[] = [new ExecuteCodeTaskHandler()];
+
+// Determine whether multi-user mode is enabled based on build-time configuration
+declare const IS_MULTI_USER_MODE: boolean;
+const isMultiUserMode = typeof IS_MULTI_USER_MODE !== "undefined" ? IS_MULTI_USER_MODE : false;
+
+// Open the plugin UI (main.ts)
+penpot.ui.open("Penpot MCP Plugin", `?theme=${penpot.theme}&multiUser=${isMultiUserMode}`, { width: 158, height: 200 });
+
+// Handle messages
+penpot.ui.onMessage<string | { id: string; task: string; params: any }>((message) => {
+    // Handle plugin task requests
+    if (typeof message === "object" && message.task && message.id) {
+        handlePluginTaskRequest(message).catch((error) => {
+            console.error("Error in handlePluginTaskRequest:", error);
+        });
+    }
+});
+
+/**
+ * Handles plugin task requests received from the MCP server via WebSocket.
+ *
+ * @param request - The task request containing ID, task type and parameters
+ */
+async function handlePluginTaskRequest(request: { id: string; task: string; params: any }): Promise<void> {
+    console.log("Executing plugin task:", request.task, request.params);
+    const task = new Task(request.id, request.task, request.params);
+
+    // Find the appropriate handler
+    const handler = taskHandlers.find((h) => h.isApplicableTo(task));
+
+    if (handler) {
+        try {
+            // Cast the params to the expected type and handle the task
+            console.log("Processing task with handler:", handler);
+            await handler.handle(task);
+
+            // check whether a response was sent and send a generic success if not
+            if (!task.isResponseSent) {
+                console.warn("Handler did not send a response, sending generic success.");
+                task.sendSuccess("Task completed without a specific response.");
+            }
+
+            console.log("Task handled successfully:", task);
+        } catch (error) {
+            console.error("Error handling task:", error);
+            const errorMessage = error instanceof Error ? error.message : "Unknown error";
+            task.sendError(`Error handling task: ${errorMessage}`);
+        }
+    } else {
+        console.error("Unknown plugin task:", request.task);
+        task.sendError(`Unknown task type: ${request.task}`);
+    }
+}
+
+// Handle theme change in the iframe
+penpot.on("themechange", (theme) => {
+    penpot.ui.sendMessage({
+        source: "penpot",
+        type: "themechange",
+        theme,
+    });
+});

mcp/packages/plugin/src/style.css

@@ -0,0 +1,10 @@
+@import "@penpot/plugin-styles/styles.css";
+
+body {
+    line-height: 1.5;
+    padding: 10px;
+}
+
+p {
+    margin-block-end: 0.75rem;
+}

mcp/packages/plugin/src/task-handlers/ExecuteCodeTaskHandler.ts

@@ -0,0 +1,212 @@
+import { Task, TaskHandler } from "../TaskHandler";
+import { ExecuteCodeTaskParams, ExecuteCodeTaskResultData } from "../../../common/src";
+import { PenpotUtils } from "../PenpotUtils.ts";
+
+/**
+ * Console implementation that captures all log output for code execution.
+ *
+ * Provides the same interface as the native console object but appends
+ * all output to an internal log string that can be retrieved.
+ */
+class ExecuteCodeTaskConsole {
+    /**
+     * Accumulated log output from all console method calls.
+     */
+    private logOutput: string = "";
+
+    /**
+     * Resets the accumulated log output to empty string.
+     * Should be called before each code execution to start with clean logs.
+     */
+    resetLog(): void {
+        this.logOutput = "";
+    }
+
+    /**
+     * Gets the accumulated log output from all console method calls.
+     * @returns The complete log output as a string
+     */
+    getLog(): string {
+        return this.logOutput;
+    }
+
+    /**
+     * Appends a formatted message to the log output.
+     * @param level - Log level prefix (e.g., "LOG", "WARN", "ERROR")
+     * @param args - Arguments to log, will be stringified and joined
+     */
+    private appendToLog(level: string, ...args: any[]): void {
+        const message = args
+            .map((arg) => (typeof arg === "object" ? JSON.stringify(arg, null, 2) : String(arg)))
+            .join(" ");
+        this.logOutput += `[${level}] ${message}\n`;
+    }
+
+    /**
+     * Logs a message to the captured output.
+     */
+    log(...args: any[]): void {
+        this.appendToLog("LOG", ...args);
+    }
+
+    /**
+     * Logs a warning message to the captured output.
+     */
+    warn(...args: any[]): void {
+        this.appendToLog("WARN", ...args);
+    }
+
+    /**
+     * Logs an error message to the captured output.
+     */
+    error(...args: any[]): void {
+        this.appendToLog("ERROR", ...args);
+    }
+
+    /**
+     * Logs an informational message to the captured output.
+     */
+    info(...args: any[]): void {
+        this.appendToLog("INFO", ...args);
+    }
+
+    /**
+     * Logs a debug message to the captured output.
+     */
+    debug(...args: any[]): void {
+        this.appendToLog("DEBUG", ...args);
+    }
+
+    /**
+     * Logs a message with trace information to the captured output.
+     */
+    trace(...args: any[]): void {
+        this.appendToLog("TRACE", ...args);
+    }
+
+    /**
+     * Logs a table to the captured output (simplified as JSON).
+     */
+    table(data: any): void {
+        this.appendToLog("TABLE", data);
+    }
+
+    /**
+     * Starts a timer (simplified implementation that just logs).
+     */
+    time(label?: string): void {
+        this.appendToLog("TIME", `Timer started: ${label || "default"}`);
+    }
+
+    /**
+     * Ends a timer (simplified implementation that just logs).
+     */
+    timeEnd(label?: string): void {
+        this.appendToLog("TIME_END", `Timer ended: ${label || "default"}`);
+    }
+
+    /**
+     * Logs messages in a group (simplified to just log the label).
+     */
+    group(label?: string): void {
+        this.appendToLog("GROUP", label || "");
+    }
+
+    /**
+     * Logs messages in a collapsed group (simplified to just log the label).
+     */
+    groupCollapsed(label?: string): void {
+        this.appendToLog("GROUP_COLLAPSED", label || "");
+    }
+
+    /**
+     * Ends the current group (simplified implementation).
+     */
+    groupEnd(): void {
+        this.appendToLog("GROUP_END", "");
+    }
+
+    /**
+     * Clears the console (no-op in this implementation since we want to capture logs).
+     */
+    clear(): void {
+        // intentionally empty - we don't want to clear captured logs
+    }
+
+    /**
+     * Counts occurrences of calls with the same label (simplified implementation).
+     */
+    count(label?: string): void {
+        this.appendToLog("COUNT", label || "default");
+    }
+
+    /**
+     * Resets the count for a label (simplified implementation).
+     */
+    countReset(label?: string): void {
+        this.appendToLog("COUNT_RESET", label || "default");
+    }
+
+    /**
+     * Logs an assertion (simplified to just log if condition is false).
+     */
+    assert(condition: boolean, ...args: any[]): void {
+        if (!condition) {
+            this.appendToLog("ASSERT", ...args);
+        }
+    }
+}
+
+/**
+ * Task handler for executing JavaScript code in the plugin context.
+ *
+ * Maintains a persistent context object that preserves state between code executions
+ * and captures all console output during execution.
+ */
+export class ExecuteCodeTaskHandler extends TaskHandler<ExecuteCodeTaskParams> {
+    readonly taskType = "executeCode";
+
+    /**
+     * Persistent context object that maintains state between code executions.
+     * Contains the penpot API, storage object, and custom console implementation.
+     */
+    private readonly context: any;
+
+    constructor() {
+        super();
+
+        // initialize context, making penpot, penpotUtils, storage and the custom console available
+        this.context = {
+            penpot: penpot,
+            storage: {},
+            console: new ExecuteCodeTaskConsole(),
+            penpotUtils: PenpotUtils,
+        };
+    }
+
+    async handle(task: Task<ExecuteCodeTaskParams>): Promise<void> {
+        if (!task.params.code) {
+            task.sendError("executeCode task requires 'code' parameter");
+            return;
+        }
+
+        this.context.console.resetLog();
+
+        const context = this.context;
+        const code = task.params.code;
+
+        let result: any = await (async (ctx) => {
+            const fn = new Function(...Object.keys(ctx), `return (async () => { ${code} })();`);
+            return fn(...Object.values(ctx));
+        })(context);
+
+        console.log("Code execution result:", result);
+
+        // return result and captured log
+        let resultData: ExecuteCodeTaskResultData<any> = {
+            result: result,
+            log: this.context.console.getLog(),
+        };
+        task.sendSuccess(resultData);
+    }
+}

mcp/packages/plugin/src/vite-env.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="vite/client" />
+
+declare const IS_MULTI_USER_MODE: boolean;
+declare const PENPOT_MCP_WEBSOCKET_URL: string;

mcp/packages/plugin/tsconfig.json

@@ -0,0 +1,24 @@
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "useDefineForClassFields": true,
+        "module": "ESNext",
+        "lib": ["ES2020", "DOM", "DOM.Iterable"],
+        "skipLibCheck": true,
+        "typeRoots": ["./node_modules/@types", "./node_modules/@penpot"],
+        "types": ["plugin-types"],
+        /* Bundler mode */
+        "moduleResolution": "bundler",
+        "allowImportingTsExtensions": true,
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "noEmit": true,
+
+        /* Linting */
+        "strict": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noFallthroughCasesInSwitch": true
+    },
+    "include": ["src"]
+}

mcp/packages/plugin/vite.config.ts

@@ -0,0 +1,43 @@
+import { defineConfig } from "vite";
+import livePreview from "vite-live-preview";
+
+// Debug: Log the environment variables
+console.log("MULTI_USER_MODE env:", process.env.MULTI_USER_MODE);
+console.log("Will define IS_MULTI_USER_MODE as:", JSON.stringify(process.env.MULTI_USER_MODE === "true"));
+
+let WS_URI = "http://localhost:4402";
+console.log("Will define PENPOT_MCP_WEBSOCKET_URL as:", JSON.stringify(WS_URI));
+
+export default defineConfig({
+    plugins: [
+        livePreview({
+            reload: true,
+            config: {
+                build: {
+                    sourcemap: true,
+                },
+            },
+        }),
+    ],
+    build: {
+        rollupOptions: {
+            input: {
+                plugin: "src/plugin.ts",
+                index: "./index.html",
+            },
+            output: {
+                entryFileNames: "[name].js",
+            },
+        },
+    },
+    preview: {
+        host: "0.0.0.0",
+        port: 4400,
+        cors: true,
+        allowedHosts: [],
+    },
+    define: {
+        IS_MULTI_USER_MODE: JSON.stringify(process.env.MULTI_USER_MODE === "true"),
+        PENPOT_MCP_WEBSOCKET_URL: JSON.stringify(WS_URI),
+    },
+});

mcp/packages/plugin/vite.release.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig, mergeConfig } from "vite";
+import baseConfig from "./vite.config";
+
+export default mergeConfig(
+    baseConfig,
+    defineConfig({
+        base: "./",
+        plugins: [],
+    })
+);

mcp/packages/server/README.md

@@ -0,0 +1,24 @@
+# Penpot MCP Server
+
+A Model Context Protocol (MCP) server that provides Penpot integration
+capabilities for AI clients supporting the model context protocol (MCP).
+
+## Setup
+
+1. Install Dependencies
+
+        pnpm install
+
+2. Build the Project
+
+        pnpm run build
+
+3. Run the Server
+
+        pnpm run start
+
+
+## Penpot Plugin API REPL
+
+The MCP server includes a REPL interface for testing Penpot Plugin API calls.
+To use it, connect to the URL reported at startup.

mcp/packages/server/data/prompts.yml

@@ -0,0 +1,267 @@
+# Prompts configuration for Penpot MCP Server
+# This file contains various prompts and instructions that can be used by the server
+
+initial_instructions: |
+  You have access to Penpot tools in order to interact with a Penpot design project directly.
+  As a precondition, the user must connect the Penpot design project to the MCP server using the Penpot MCP Plugin.
+
+  IMPORTANT: When transferring styles from a Penpot design to code, make sure that you strictly adhere to the design.
+    NEVER make assumptions about missing values and don't get overly creative (e.g. don't pick your own colours and stick to
+    non-creative defaults such as white/black if you are lacking information).
+
+  # Executing Code
+
+  One of your key tools is the `execute_code` tool, which allows you to run JavaScript code using the Penpot Plugin API
+  directly in the connected project.
+
+  VERY IMPORTANT: When writing code, NEVER LOG INFORMATION YOU ARE ALSO RETURNING. It would duplicate the information you receive!
+
+  To execute code correctly, you need to understand the Penpot Plugin API. You can retrieve API documentation via 
+  the `penpot_api_info` tool.
+
+  This is the full list of types/interfaces in the Penpot API: $api_types
+
+  You use the `storage` object extensively to store data and utility functions you define across tool calls.
+  This allows you to inspect intermediate results while still being able to build on them in subsequent code executions.
+
+  # The Structure of Penpot Designs
+
+  A Penpot design ultimately consists of shapes. 
+  The type `Shape` is a union type, which encompasses both containers and low-level shapes.
+  Shapes in a Penpot design are organized hierarchically.
+  At the top level, a design project contains one or more `Page` objects.
+  Each `Page` contains a tree of elements. For a given instance `page`, its root shape is `page.root`.
+  A Page is frequently structured into boards. A `Board` is a high-level grouping element.
+  A `Group` is a more low-level grouping element used to organize low-level shapes into a logical unit.
+  Actual low-level shape types are `Rectangle`, `Path`, `Text`, `Ellipse`, `Image`, `Boolean`, and `SvgRaw`.
+  `ShapeBase` is a base type most shapes build upon.
+
+  # Core Shape Properties and Methods
+
+  **Type**: 
+      Any given shape contains information on the concrete type via its `type` field.
+
+  **Position and Dimensions**:
+    * The location properties `x` and `y` refer to the top left corner of a shape's bounding box in the absolute (Page) coordinate system.
+      These are writable - set them directly to position shapes.
+    * `parentX` and `parentY` (as well as `boardX` and `boardY`) are READ-ONLY computed properties showing position relative to parent/board.
+      To position relative to parent, use `penpotUtils.setParentXY(shape, parentX, parentY)` or manually set `shape.x = parent.x + parentX`.
+    * `width` and `height` are READ-ONLY. Use `resize(width, height)` method to change dimensions.
+    * `bounds` is a READ-ONLY property. Use `x`, `y` with `resize()` to modify shape bounds.
+
+  **Other Writable Properties**:
+    * `name` - Shape name
+    * `fills`, `strokes` - Styling properties
+    * `rotation`, `opacity`, `blocked`, `hidden`, `visible`
+
+  **Z-Order**:
+    * The z-order of shapes is determined by the order in the `children` array of the parent shape.
+      Therefore, when creating shapes that should be on top of each other, add them to the parent in the correct order
+      (i.e. add background shapes first, then foreground shapes later).
+      CRITICAL: NEVER use the broken function `appendChild` to achieve this, ALWAYS use `parent.insertChild(parent.children.length, shape)`
+    * To modify z-order after creation, use these methods: `bringToFront()`, `sendToBack()`, `bringForward()`, `sendBackward()`,
+      and, for precise control, `setParentIndex(index)` (0-based).
+
+  **Modification Methods**:
+    * `resize(width, height)` - Change dimensions (required for width/height since they're read-only)
+    * `rotate(angle, center?)` - Rotate shape
+    * `remove()` - Permanently destroy the shape (use only for deletion, NOT for reparenting)
+
+  **Hierarchical Structure**:
+    * `parent` - The parent shape (null for root shapes)
+      Note: Hierarchical nesting does not necessarily imply visual containment
+    * CRITICAL: To add children to a parent shape (e.g. a `Board`):
+      - ALWAYS use `parent.insertChild(index, shape)` to add a child, e.g. `parent.insertChild(parent.children.length, shape)` to append
+      - NEVER use `parent.appendChild(shape)` as it is BROKEN and will not insert in a predictable place (except in flex layout boards)
+    * Reparenting: `newParent.appendChild(shape)` or `newParent.insertChild(index, shape)` will move a shape to new parent
+      - Automatically removes the shape from its old parent
+      - Absolute x/y positions are preserved (use `penpotUtils.setParentXY` to adjust relative position)
+
+  # Images
+
+  The `Image` type is a legacy type. Images are now typically embedded in a `Fill`, with `fillImage` set to an 
+  `ImageData` object, i.e. the `fills` property of of a shape (e.g. a `Rectangle`) will contain a fill where `fillImage` is set.
+  Use the `export_shape` and `import_image` tools to export and import images.
+
+  # Layout Systems
+
+  Boards can have layout systems that automatically control the positioning and spacing of their children:
+
+    * If a board has a layout system, then child positions are controlled by the layout system.
+      For every child, key properties of the child within the layout are stored in `child.layoutChild: LayoutChildProperties`:
+      - `absolute: boolean` - if true, child position is not controlled by layout system. x/y will set *relative* position within parent!
+      - margins (`topMargin`, `rightMargin`, `bottomMargin`, `leftMargin` or combined `verticalMargin`, `horizontalMargin`)
+      - sizing (`verticalSizing`, `horizontalSizing`: "fill" | "auto" | "fix")
+      - min/max sizes (`minWidth`, `maxWidth`, `minHeight`, `maxHeight`)
+      - `zIndex: number` (higher numbers on top)
+      
+    * **Flex Layout**: A flexbox-style layout system
+      - Properties: `dir`, `rowGap`, `columnGap`, `alignItems`, `justifyContent`;
+         - `dir`: "row" | "column" | "row-reverse" | "column-reverse"
+         - Padding: `topPadding`, `rightPadding`, `bottomPadding`, `leftPadding`, or combined `verticalPadding`, `horizontalPadding`
+         - To modify spacing: adjust `rowGap` and `columnGap` properties, not individual child positions.
+           Optionally, adjust indivudual child margins via `child.layoutChild`.
+      - When a board has flex layout, 
+         - child positions are controlled by the layout system, not by individual x/y coordinates (unless `child.layoutChild.absolute` is true);
+           appending or inserting children automatically positions them according to the layout rules.
+         - CRITICAL: For for dir="column" or dir="row", the order of the `children` array is reversed relative to the visual order!
+           Therefore, the element that appears first in the array, appears visually at the end (bottom/right) and vice versa.
+           ALWAYS BEAR IN MIND THAT THE CHILDREN ARRAY ORDER IS REVERSED FOR dir="column" OR dir="row"!
+      - CRITICAL: The FlexLayout method `board.flex.appendChild` is BROKEN. To append children to a flex layout board such that
+        they appear visually at the end, ALWAYS use the Board's method `board.appendChild(shape)`; it will insert at the front
+        of the `children` array for dir="column" or dir="row", which is what you want. So call it in the order of visual appearance.
+        To insert at a specific index, use `board.insertChild(index, shape)`, bearing in mind the reversed order for dir="column" 
+        or dir="row".
+      - Add to a board with `board.addFlexLayout(): FlexLayout`; instance then accessible via `board.flex`.
+        IMPORTANT: When adding a flex layout to a container that already has children, 
+        use `penpotUtils.addFlexLayout(container, dir)` instead! This preserves the existing visual order of children.
+        Otherwise, children will be arbitrarily reordered when the children order suddenly determines the display order. 
+      - Check with: `if (board.flex) { ... }`
+    
+    * **Grid Layout**: A CSS grid-style layout system
+      - Add to a board with `board.addGridLayout(): GridLayout`; instance then accessibly via `board.grid`;
+        Check with: `if (board.grid) { ... }`
+      - Properties: `rows`, `columns`, `rowGap`, `columnGap`
+      - Children are positioned via 1-based row/column indices
+          - Add to grid via `board.flex.appendChild(shape, row, column)` 
+          - Modify grid positioning after the fact via `shape.layoutCell: LayoutCellProperties`
+    
+    * When working with boards:
+      - ALWAYS check if the board has a layout system before attempting to reposition children
+      - Modify layout properties (gaps, padding) instead of trying to set child x/y positions directly
+      - Layout systems override manual positioning of children
+
+  # Text Elements
+
+  The rendered content of `Text` element is given by the `characters` property.
+
+  To change the size of the text, change the `fontSize` property; applying `resize()` does NOT change the font size,
+  it only changes the formal bounding box; if the text does not fit it, it will overflow.
+  The bounding box is sized automatically as long as the `growType` property is set to "auto-width" or "auto-height".
+  `resize` always sets `growType` to "fixed", so ALWAYS set it back to "auto-*" if you want automatic sizing - otherwise the bounding box will be meaningless, with the text overflowing!
+  The auto-sizing is not immediate; sleep for a short time (100ms) if you want to read the updated bounding box.
+
+  # The `penpot` and `penpotUtils` Objects, Exploring Designs
+
+  A key object to use in your code is the `penpot` object (which is of type `Penpot`):
+    * `penpot.selection` provides the list of shapes the user has selected in the Penpot UI.
+       If it is unclear which elements to work on, you can ask the user to select them for you.
+       ALWAYS immediately copy the selected shape(s) into `storage`! Do not assume that the selection remains unchanged.
+    * `penpot.root` provides the root shape of the currently active page.
+    * Generation of CSS content for elements via `penpot.generateStyle`
+    * Generation of HTML/SVG content for elements via `penpot.generateMarkup`
+
+  For example, to generate CSS for the currently selected elements, you can execute this:
+      return penpot.generateStyle(penpot.selection, { type: "css", withChildren: true });
+
+  CRITICAL: The `penpotUtils` object provides essential utilities - USE THESE INSTEAD OF WRITING YOUR OWN:
+    * getPages(): { id: string; name: string }[]
+    * getPageById(id: string): Page | null
+    * getPageByName(name: string): Page | null
+    * shapeStructure(shape: Shape, maxDepth: number | undefined = undefined): { id, name, type, children?, layout? }
+      Generates an overview structure of the given shape.
+      - children: recursive, limited by maxDepth 
+      - layout: present if shape has flex/grid layout, contains { type: "flex" | "grid", ... }
+    * findShapeById(id: string): Shape | null
+    * findShape(predicate: (shape: Shape) => boolean, root: Shape | null = null): Shape | null
+      If no root is provided, search globally (in all pages).
+    * findShapes(predicate: (shape: Shape) => boolean, root: Shape | null = null): Shape[]
+    * isContainedIn(shape: Shape, container: Shape): boolean
+      Returns true iff shape is fully within the container's geometric bounds.
+      Note that a shape's bounds may not always reflect its actual visual content - descendants can overflow; check using analyzeDescendants (see below). 
+    * setParentXY(shape: Shape, parentX: number, parentY: number): void
+      Sets shape position relative to its parent (since parentX/parentY are read-only)
+    * analyzeDescendants<T>(root: Shape, evaluator: (root: Shape, descendant: Shape) => T | null | undefined, maxDepth?: number): Array<{ shape: Shape, result: T }>
+      General-purpose utility for analyzing/validating descendants
+      Calls evaluator on each descendant; collects non-null/undefined results
+      Powerful pattern: evaluator can return corrector functions or diagnostic data
+
+  General pointers for working with Penpot designs:
+    * Prefer `penpotUtils` helper functions — avoid reimplementing shape searching.
+    * To get an overview of a single page, use `penpotUtils.shapeStructure(page.root, 3)`. 
+      Note that `penpot.root` refers to the current page only. When working across pages, first determine the relevant page(s).
+    * Use `penpotUtils.findShapes()` or `penpotUtils.findShape()` with predicates to locate elements efficiently.
+
+  Common tasks - Quick Reference (ALWAYS use penpotUtils for these):
+    * Find all images:
+        const images = penpotUtils.findShapes(
+          shape => shape.type === 'image' || shape.fills?.some(fill => fill.fillImage),
+          penpot.root
+        );
+    * Find text elements:
+        const texts = penpotUtils.findShapes(shape => shape.type === 'text', penpot.root);
+    * Find (the first) shape with a given name:
+        const shape = penpotUtils.findShape(shape => shape.name === 'MyShape');
+    * Get structure of current selection:
+        const structure = penpotUtils.shapeStructure(penpot.selection[0]);
+    * Find shapes in current selection/board:
+        const shapes = penpotUtils.findShapes(predicate, penpot.selection[0] || penpot.root);
+    * Validate/analyze descendants (returning corrector functions):
+        const fixes = penpotUtils.analyzeDescendants(board, (root, shape) => {
+          const xMod = shape.parentX % 4;
+          if (xMod !== 0) {
+            return () => penpotUtils.setParentXY(shape, Math.round(shape.parentX / 4) * 4, shape.parentY);
+          }
+        });
+        fixes.forEach(f => f.result()); // Apply all fixes
+    * Find containment violations:
+        const violations = penpotUtils.analyzeDescendants(board, (root, shape) => {
+          return !penpotUtils.isContainedIn(shape, root) ? 'outside-bounds' : null;
+        });
+        Always validate against the root container that is supposed to contain the shapes.
+
+  # Visual Inspection of Designs
+
+  For many tasks, it can be critical to visually inspect the design. Remember to use the `export_shape` tool for this purpose! 
+
+  # Revising Designs
+
+  * Before applying design changes, ask: "Would a designer consider this appropriate?"
+  * When dealing with containment issues, ask: Is the parent too small OR is the child too large?
+    Container sizes are usually intentional, check content first.
+  * Check for reasonable font sizes and typefaces
+  * The use of flex layouts is encouraged for cases where elements are arranged in rows or columns with consistent spacing/positioning.
+    Consider converting boards to flex layout when appropriate.
+
+  # Asset Libraries
+    
+  Libraries in Penpot are collections of reusable design assets (components, colors, and typographies) that can be shared across files. 
+  They enable design systems and consistent styling across projects.
+  Each Penpot file has its own local library and can connect to external shared libraries.
+    
+  Accessing libraries: via `penpot.library` (type: `LibraryContext`):
+    * `penpot.library.local` (type: `Library`) - The current file's own library
+    * `penpot.library.connected` (type: `Library[]`) - Array of already-connected external libraries
+    * `penpot.library.availableLibraries()` (returns: `Promise<LibrarySummary[]>`) - Libraries available to connect
+    * `penpot.library.connectLibrary(libraryId: string)` (returns: `Promise<Library>`) - Connect a new library
+    
+  Each `Library` object has:
+    * `id: string`
+    * `name: string`
+    * `components: LibraryComponent[]` - Array of components
+    * `colors: LibraryColor[]` - Array of colors
+    * `typographies: LibraryTypography[]` - Array of typographies
+    
+  Using library components:
+    * find a component in the library by name:
+        const component: LibraryComponent = library.components.find(comp => comp.name.includes('Button'));
+    * create a new instance of the component on the current page: 
+        const instance: Shape = component.instance();
+      This returns a `Shape` (often a `Board` containing child elements).
+      After instantiation, modify the instance's properties as desired.
+    * get the reference to the main component shape:
+        const mainShape: Shape = component.mainInstance();
+    
+  Adding assets to a library:
+    * const newColor: LibraryColor = penpot.library.local.createColor();
+      newColor.name = 'Brand Primary';
+      newColor.color = '#0066FF';
+    * const newTypo: LibraryTypography = penpot.library.local.createTypography();
+      newTypo.name = 'Heading Large';
+      // Set typography properties...
+    * const shapes: Shape[] = [shape1, shape2]; // shapes to include
+      const newComponent: LibraryComponent = penpot.library.local.createComponent(shapes);
+      newComponent.name = 'My Button';
+    
+  --
+  You have hereby read the 'Penpot High-Level Overview' and need not use a tool to read it again.

mcp/packages/server/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Penpot integration",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build:server": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.js --external:@modelcontextprotocol/* --external:ws --external:express --external:class-transformer --external:class-validator --external:reflect-metadata --external:pino --external:pino-pretty --external:js-yaml --external:sharp",
+    "build": "pnpm run build:server && cp -r src/static dist/static && cp -r data dist/data",
+    "build:multi-user": "pnpm run build",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "start": "node dist/index.js",
+    "start:multi-user": "node dist/index.js --multi-user",
+    "start:dev": "node --import ts-node/register src/index.ts",
+    "start:dev:multi-user": "node --loader ts-node/esm src/index.ts --multi-user",
+    "types:check": "tsc --noEmit",
+    "clean": "rm -rf dist/"
+  },
+  "keywords": [
+    "mcp",
+    "penpot",
+    "server"
+  ],
+  "author": "",
+  "license": "MIT",
+  "packageManager": "pnpm@10.28.2+sha512.41872f037ad22f7348e3b1debbaf7e867cfd448f2726d9cf74c08f19507c31d2c8e7a11525b983febc2df640b5438dee6023ebb1f84ed43cc2d654d2bc326264",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.3",
+    "express": "^5.1.0",
+    "js-yaml": "^4.1.1",
+    "penpot-mcp": "file:..",
+    "pino": "^9.10.0",
+    "pino-pretty": "^13.1.1",
+    "reflect-metadata": "^0.1.13",
+    "sharp": "^0.34.5",
+    "ws": "^8.18.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@penpot/mcp-common": "workspace:../common",
+    "@types/express": "^4.17.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.10",
+    "esbuild": "^0.25.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.0.0"
+  },
+  "ts-node": {
+    "esm": true
+  }
+}

mcp/packages/server/src/ApiDocs.ts

@@ -0,0 +1,128 @@
+import * as yaml from "js-yaml";
+import * as fs from "fs";
+import * as path from "path";
+
+/**
+ * Represents a single type/interface defined in the Penpot API
+ */
+export class ApiType {
+    private readonly name: string;
+    private readonly overview: string;
+    private readonly members: Record<string, Record<string, string>>;
+    private cachedFullText: string | null = null;
+
+    constructor(name: string, overview: string, members: Record<string, Record<string, string>>) {
+        this.name = name;
+        this.overview = overview;
+        this.members = members;
+    }
+
+    /**
+     * Returns the original name of this API type.
+     */
+    getName(): string {
+        return this.name;
+    }
+
+    /**
+     * Returns the overview text of this API type (which all signature/type declarations)
+     */
+    getOverviewText() {
+        return this.overview;
+    }
+
+    /**
+     * Creates a single markdown text document from all parts of this API type.
+     *
+     * The full text is cached within the object for performance.
+     */
+    getFullText(): string {
+        if (this.cachedFullText === null) {
+            let text = this.overview;
+
+            for (const [memberType, memberEntries] of Object.entries(this.members)) {
+                text += `\n\n## ${memberType}\n`;
+
+                for (const [memberName, memberDescription] of Object.entries(memberEntries)) {
+                    text += `\n### ${memberName}\n\n${memberDescription}`;
+                }
+            }
+
+            this.cachedFullText = text;
+        }
+
+        return this.cachedFullText;
+    }
+
+    /**
+     * Returns the description of the member with the given name.
+     *
+     * The member type doesn't matter for the search, as member names are unique
+     * across all member types within a single API type.
+     */
+    getMember(memberName: string): string | null {
+        for (const memberEntries of Object.values(this.members)) {
+            if (memberName in memberEntries) {
+                return memberEntries[memberName];
+            }
+        }
+        return null;
+    }
+}
+
+/**
+ * Loads and manages API documentation from YAML files.
+ *
+ * This class provides case-insensitive access to API type documentation
+ * loaded from the data/api_types.yml file.
+ */
+export class ApiDocs {
+    private readonly apiTypes: Map<string, ApiType> = new Map();
+
+    /**
+     * Creates a new ApiDocs instance and loads the API types from the YAML file.
+     */
+    constructor() {
+        this.loadApiTypes();
+    }
+
+    /**
+     * Loads API types from the data/api_types.yml file.
+     */
+    private loadApiTypes(): void {
+        const yamlPath = path.join(process.cwd(), "data", "api_types.yml");
+        const yamlContent = fs.readFileSync(yamlPath, "utf8");
+        const data = yaml.load(yamlContent) as Record<string, any>;
+
+        for (const [typeName, typeData] of Object.entries(data)) {
+            const overview = typeData.overview || "";
+            const members = typeData.members || {};
+
+            const apiType = new ApiType(typeName, overview, members);
+
+            // store with lower-case key for case-insensitive retrieval
+            this.apiTypes.set(typeName.toLowerCase(), apiType);
+        }
+    }
+
+    /**
+     * Retrieves an API type by name (case-insensitive).
+     */
+    getType(typeName: string): ApiType | null {
+        return this.apiTypes.get(typeName.toLowerCase()) || null;
+    }
+
+    /**
+     * Returns all available type names.
+     */
+    getTypeNames(): string[] {
+        return Array.from(this.apiTypes.values()).map((type) => type.getName());
+    }
+
+    /**
+     * Returns the number of loaded API types.
+     */
+    getTypeCount(): number {
+        return this.apiTypes.size;
+    }
+}

mcp/packages/server/src/ConfigurationLoader.ts

@@ -0,0 +1,85 @@
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import yaml from "js-yaml";
+import { createLogger } from "./logger.js";
+
+/**
+ * Interface defining the structure of the prompts configuration file.
+ */
+export interface PromptsConfig {
+    /** Initial instructions displayed when the server starts or connects to a client */
+    initial_instructions: string;
+    [key: string]: any; // Allow for future extension with additional prompt types
+}
+
+/**
+ * Configuration loader for prompts and server settings.
+ *
+ * Handles loading and parsing of YAML configuration files,
+ * providing type-safe access to configuration values with
+ * appropriate fallbacks for missing files or values.
+ */
+export class ConfigurationLoader {
+    private readonly logger = createLogger("ConfigurationLoader");
+    private readonly baseDir: string;
+    private promptsConfig: PromptsConfig | null = null;
+
+    /**
+     * Creates a new configuration loader instance.
+     *
+     * @param baseDir - Base directory for resolving configuration file paths
+     */
+    constructor(baseDir: string) {
+        this.baseDir = baseDir;
+    }
+
+    /**
+     * Loads the prompts configuration from the YAML file.
+     *
+     * Reads and parses the prompts.yml file, providing cached access
+     * to configuration values on subsequent calls.
+     *
+     * @returns The parsed prompts configuration object
+     */
+    public getPromptsConfig(): PromptsConfig {
+        if (this.promptsConfig !== null) {
+            return this.promptsConfig;
+        }
+
+        const promptsPath = join(this.baseDir, "data", "prompts.yml");
+
+        if (!existsSync(promptsPath)) {
+            throw new Error(`Prompts configuration file not found at ${promptsPath}, using defaults`);
+        }
+
+        const fileContent = readFileSync(promptsPath, "utf8");
+        const parsedConfig = yaml.load(fileContent) as PromptsConfig;
+
+        this.promptsConfig = parsedConfig || {};
+        this.logger.info(`Loaded prompts configuration from ${promptsPath}`);
+
+        return this.promptsConfig;
+    }
+
+    /**
+     * Gets the initial instructions for the MCP server.
+     *
+     * @returns The initial instructions string, or undefined if not configured
+     */
+    public getInitialInstructions(): string {
+        const config = this.getPromptsConfig();
+        return config.initial_instructions;
+    }
+
+    /**
+     * Reloads the configuration from disk.
+     *
+     * Forces a fresh read of the configuration file on the next access,
+     * useful for development or when configuration files are updated at runtime.
+     */
+    public reloadConfiguration(): void {
+        this.promptsConfig = null;
+        this.logger.info("Configuration cache cleared, will reload on next access");
+    }
+}

mcp/packages/server/src/PenpotMcpServer.ts

@@ -0,0 +1,262 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { AsyncLocalStorage } from "async_hooks";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { ExecuteCodeTool } from "./tools/ExecuteCodeTool";
+import { PluginBridge } from "./PluginBridge";
+import { ConfigurationLoader } from "./ConfigurationLoader";
+import { createLogger } from "./logger";
+import { Tool } from "./Tool";
+import { HighLevelOverviewTool } from "./tools/HighLevelOverviewTool";
+import { PenpotApiInfoTool } from "./tools/PenpotApiInfoTool";
+import { ExportShapeTool } from "./tools/ExportShapeTool";
+import { ImportImageTool } from "./tools/ImportImageTool";
+import { ReplServer } from "./ReplServer";
+import { ApiDocs } from "./ApiDocs";
+
+/**
+ * Session context for request-scoped data.
+ */
+export interface SessionContext {
+    userToken?: string;
+}
+
+export class PenpotMcpServer {
+    private readonly logger = createLogger("PenpotMcpServer");
+    private readonly server: McpServer;
+    private readonly tools: Map<string, Tool<any>>;
+    public readonly configLoader: ConfigurationLoader;
+    private app: any;
+    public readonly pluginBridge: PluginBridge;
+    private readonly replServer: ReplServer;
+    private apiDocs: ApiDocs;
+
+    /**
+     * Manages session-specific context, particularly user tokens for each request.
+     */
+    private readonly sessionContext = new AsyncLocalStorage<SessionContext>();
+
+    private readonly transports = {
+        streamable: {} as Record<string, StreamableHTTPServerTransport>,
+        sse: {} as Record<string, { transport: SSEServerTransport; userToken?: string }>,
+    };
+
+    private readonly port: number;
+    private readonly webSocketPort: number;
+    private readonly replPort: number;
+    private readonly listenAddress: string;
+    /**
+     * the address (domain name or IP address) via which clients can reach the MCP server
+     */
+    public readonly serverAddress: string;
+
+    constructor(private isMultiUser: boolean = false) {
+        // read port configuration from environment variables
+        this.port = parseInt(process.env.PENPOT_MCP_SERVER_PORT ?? "4401", 10);
+        this.webSocketPort = parseInt(process.env.PENPOT_MCP_WEBSOCKET_PORT ?? "4402", 10);
+        this.replPort = parseInt(process.env.PENPOT_MCP_REPL_PORT ?? "4403", 10);
+        this.listenAddress = process.env.PENPOT_MCP_SERVER_LISTEN_ADDRESS ?? "localhost";
+        this.serverAddress = process.env.PENPOT_MCP_SERVER_ADDRESS ?? "localhost";
+
+        this.configLoader = new ConfigurationLoader(process.cwd());
+        this.apiDocs = new ApiDocs();
+
+        this.server = new McpServer(
+            {
+                name: "penpot-mcp-server",
+                version: "1.0.0",
+            },
+            {
+                instructions: this.getInitialInstructions(),
+            }
+        );
+
+        this.tools = new Map<string, Tool<any>>();
+        this.pluginBridge = new PluginBridge(this, this.webSocketPort);
+        this.replServer = new ReplServer(this.pluginBridge, this.replPort);
+
+        this.registerTools();
+    }
+
+    /**
+     * Indicates whether the server is running in multi-user mode,
+     * where user tokens are required for authentication.
+     */
+    public isMultiUserMode(): boolean {
+        return this.isMultiUser;
+    }
+
+    /**
+     * Indicates whether the server is running in remote mode.
+     *
+     * In remote mode, the server is not assumed to be accessed only by a local user on the same machine,
+     * with corresponding limitations being enforced.
+     * Remote mode can be explicitly enabled by setting the environment variable PENPOT_MCP_REMOTE_MODE
+     * to "true". Enabling multi-user mode forces remote mode, regardless of the value of the environment
+     * variable.
+     */
+    public isRemoteMode(): boolean {
+        const isRemoteModeRequested: boolean = process.env.PENPOT_MCP_REMOTE_MODE === "true";
+        return this.isMultiUserMode() || isRemoteModeRequested;
+    }
+
+    /**
+     * Indicates whether file system access is enabled for MCP tools.
+     * Access is enabled only in local mode, where the file system is assumed
+     * to belong to the user running the server locally.
+     */
+    public isFileSystemAccessEnabled(): boolean {
+        return !this.isRemoteMode();
+    }
+
+    public getInitialInstructions(): string {
+        let instructions = this.configLoader.getInitialInstructions();
+        instructions = instructions.replace("$api_types", this.apiDocs.getTypeNames().join(", "));
+        return instructions;
+    }
+
+    /**
+     * Retrieves the current session context.
+     *
+     * @returns The session context for the current request, or undefined if not in a request context
+     */
+    public getSessionContext(): SessionContext | undefined {
+        return this.sessionContext.getStore();
+    }
+
+    private registerTools(): void {
+        // Create relevant tool instances (depending on file system access)
+        const toolInstances: Tool<any>[] = [
+            new ExecuteCodeTool(this),
+            new HighLevelOverviewTool(this),
+            new PenpotApiInfoTool(this, this.apiDocs),
+            new ExportShapeTool(this), // tool adapts to file system access internally
+        ];
+        if (this.isFileSystemAccessEnabled()) {
+            toolInstances.push(new ImportImageTool(this));
+        }
+
+        for (const tool of toolInstances) {
+            const toolName = tool.getToolName();
+            this.tools.set(toolName, tool);
+
+            // Register each tool with McpServer
+            this.logger.info(`Registering tool: ${toolName}`);
+            this.server.registerTool(
+                toolName,
+                {
+                    description: tool.getToolDescription(),
+                    inputSchema: tool.getInputSchema(),
+                },
+                async (args) => {
+                    return tool.execute(args);
+                }
+            );
+        }
+    }
+
+    private setupHttpEndpoints(): void {
+        /**
+         * Modern Streamable HTTP connection endpoint
+         */
+        this.app.all("/mcp", async (req: any, res: any) => {
+            const userToken = req.query.userToken as string | undefined;
+
+            await this.sessionContext.run({ userToken }, async () => {
+                const { randomUUID } = await import("node:crypto");
+
+                const sessionId = req.headers["mcp-session-id"] as string | undefined;
+                let transport: StreamableHTTPServerTransport;
+
+                if (sessionId && this.transports.streamable[sessionId]) {
+                    transport = this.transports.streamable[sessionId];
+                } else {
+                    transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => randomUUID(),
+                        onsessioninitialized: (id: string) => {
+                            this.transports.streamable[id] = transport;
+                        },
+                    });
+
+                    transport.onclose = () => {
+                        if (transport.sessionId) {
+                            delete this.transports.streamable[transport.sessionId];
+                        }
+                    };
+
+                    await this.server.connect(transport);
+                }
+
+                await transport.handleRequest(req, res, req.body);
+            });
+        });
+
+        /**
+         * Legacy SSE connection endpoint
+         */
+        this.app.get("/sse", async (req: any, res: any) => {
+            const userToken = req.query.userToken as string | undefined;
+
+            await this.sessionContext.run({ userToken }, async () => {
+                const transport = new SSEServerTransport("/messages", res);
+                this.transports.sse[transport.sessionId] = { transport, userToken };
+
+                res.on("close", () => {
+                    delete this.transports.sse[transport.sessionId];
+                });
+
+                await this.server.connect(transport);
+            });
+        });
+
+        /**
+         * SSE message POST endpoint (using previously established session)
+         */
+        this.app.post("/messages", async (req: any, res: any) => {
+            const sessionId = req.query.sessionId as string;
+            const session = this.transports.sse[sessionId];
+
+            if (session) {
+                await this.sessionContext.run({ userToken: session.userToken }, async () => {
+                    await session.transport.handlePostMessage(req, res, req.body);
+                });
+            } else {
+                res.status(400).send("No transport found for sessionId");
+            }
+        });
+    }
+
+    async start(): Promise<void> {
+        const { default: express } = await import("express");
+        this.app = express();
+        this.app.use(express.json());
+
+        this.setupHttpEndpoints();
+
+        return new Promise((resolve) => {
+            this.app.listen(this.port, this.listenAddress, async () => {
+                this.logger.info(`Multi-user mode: ${this.isMultiUserMode()}`);
+                this.logger.info(`Remote mode: ${this.isRemoteMode()}`);
+                this.logger.info(`Modern Streamable HTTP endpoint: http://${this.serverAddress}:${this.port}/mcp`);
+                this.logger.info(`Legacy SSE endpoint: http://${this.serverAddress}:${this.port}/sse`);
+                this.logger.info(`WebSocket server URL: ws://${this.serverAddress}:${this.webSocketPort}`);
+
+                // start the REPL server
+                await this.replServer.start();
+
+                resolve();
+            });
+        });
+    }
+
+    /**
+     * Stops the MCP server and associated services.
+     *
+     * Gracefully shuts down the REPL server and other components.
+     */
+    public async stop(): Promise<void> {
+        this.logger.info("Stopping Penpot MCP Server...");
+        await this.replServer.stop();
+        this.logger.info("Penpot MCP Server stopped");
+    }
+}

mcp/packages/server/src/PluginBridge.ts

@@ -0,0 +1,227 @@
+import { WebSocket, WebSocketServer } from "ws";
+import * as http from "http";
+import { PluginTask } from "./PluginTask";
+import { PluginTaskResponse, PluginTaskResult } from "@penpot/mcp-common";
+import { createLogger } from "./logger";
+import type { PenpotMcpServer } from "./PenpotMcpServer";
+
+interface ClientConnection {
+    socket: WebSocket;
+    userToken: string | null;
+}
+
+/**
+ * Manages WebSocket connections to Penpot plugin instances and handles plugin tasks
+ * over these connections.
+ */
+export class PluginBridge {
+    private readonly logger = createLogger("PluginBridge");
+    private readonly wsServer: WebSocketServer;
+    private readonly connectedClients: Map<WebSocket, ClientConnection> = new Map();
+    private readonly clientsByToken: Map<string, ClientConnection> = new Map();
+    private readonly pendingTasks: Map<string, PluginTask<any, any>> = new Map();
+    private readonly taskTimeouts: Map<string, NodeJS.Timeout> = new Map();
+
+    constructor(
+        public readonly mcpServer: PenpotMcpServer,
+        private port: number,
+        private taskTimeoutSecs: number = 30
+    ) {
+        this.wsServer = new WebSocketServer({ port: port });
+        this.setupWebSocketHandlers();
+    }
+
+    /**
+     * Sets up WebSocket connection handlers for plugin communication.
+     *
+     * Manages client connections and provides bidirectional communication
+     * channel between the MCP mcpServer and Penpot plugin instances.
+     */
+    private setupWebSocketHandlers(): void {
+        this.wsServer.on("connection", (ws: WebSocket, request: http.IncomingMessage) => {
+            // extract userToken from query parameters
+            const url = new URL(request.url!, `ws://${request.headers.host}`);
+            const userToken = url.searchParams.get("userToken");
+
+            // require userToken if running in multi-user mode
+            if (this.mcpServer.isMultiUserMode() && !userToken) {
+                this.logger.warn("Connection attempt without userToken in multi-user mode - rejecting");
+                ws.close(1008, "Missing userToken parameter");
+                return;
+            }
+
+            if (userToken) {
+                this.logger.info("New WebSocket connection established (token provided)");
+            } else {
+                this.logger.info("New WebSocket connection established");
+            }
+
+            // register the client connection with both indexes
+            const connection: ClientConnection = { socket: ws, userToken };
+            this.connectedClients.set(ws, connection);
+            if (userToken) {
+                // ensure only one connection per userToken
+                if (this.clientsByToken.has(userToken)) {
+                    this.logger.warn("Duplicate connection for given user token; rejecting new connection");
+                    ws.close(1008, "Duplicate connection for given user token; close previous connection first.");
+                }
+
+                this.clientsByToken.set(userToken, connection);
+            }
+
+            ws.on("message", (data: Buffer) => {
+                this.logger.debug("Received WebSocket message: %s", data.toString());
+                try {
+                    const response: PluginTaskResponse<any> = JSON.parse(data.toString());
+                    this.handlePluginTaskResponse(response);
+                } catch (error) {
+                    this.logger.error(error, "Failure while processing WebSocket message");
+                }
+            });
+
+            ws.on("close", () => {
+                this.logger.info("WebSocket connection closed");
+                const connection = this.connectedClients.get(ws);
+                this.connectedClients.delete(ws);
+                if (connection?.userToken) {
+                    this.clientsByToken.delete(connection.userToken);
+                }
+            });
+
+            ws.on("error", (error) => {
+                this.logger.error(error, "WebSocket connection error");
+                const connection = this.connectedClients.get(ws);
+                this.connectedClients.delete(ws);
+                if (connection?.userToken) {
+                    this.clientsByToken.delete(connection.userToken);
+                }
+            });
+        });
+
+        this.logger.info("WebSocket mcpServer started on port %d", this.port);
+    }
+
+    /**
+     * Handles responses from the plugin for completed tasks.
+     *
+     * Finds the pending task by ID and resolves or rejects its promise
+     * based on the execution result.
+     *
+     * @param response - The plugin task response containing ID and result
+     */
+    private handlePluginTaskResponse(response: PluginTaskResponse<any>): void {
+        const task = this.pendingTasks.get(response.id);
+        if (!task) {
+            this.logger.info(`Received response for unknown task ID: ${response.id}`);
+            return;
+        }
+
+        // Clear the timeout and remove the task from pending tasks
+        const timeoutHandle = this.taskTimeouts.get(response.id);
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+            this.taskTimeouts.delete(response.id);
+        }
+        this.pendingTasks.delete(response.id);
+
+        // Resolve or reject the task's promise based on the result
+        if (response.success) {
+            task.resolveWithResult({ data: response.data });
+        } else {
+            const error = new Error(response.error || "Task execution failed (details not provided)");
+            task.rejectWithError(error);
+        }
+
+        this.logger.info(`Task ${response.id} completed: success=${response.success}`);
+    }
+
+    /**
+     * Determines the client connection to use for executing a task.
+     *
+     * In single-user mode, returns the single connected client.
+     * In multi-user mode, returns the client matching the session's userToken.
+     *
+     * @returns The client connection to use
+     * @throws Error if no suitable connection is found or if configuration is invalid
+     */
+    private getClientConnection(): ClientConnection {
+        if (this.mcpServer.isMultiUserMode()) {
+            const sessionContext = this.mcpServer.getSessionContext();
+            if (!sessionContext?.userToken) {
+                throw new Error("No userToken found in session context. Multi-user mode requires authentication.");
+            }
+
+            const connection = this.clientsByToken.get(sessionContext.userToken);
+            if (!connection) {
+                throw new Error(
+                    `No plugin instance connected for user token. Please ensure the plugin is running and connected with the correct token.`
+                );
+            }
+
+            return connection;
+        } else {
+            // single-user mode: return the single connected client
+            if (this.connectedClients.size === 0) {
+                throw new Error(
+                    `No Penpot plugin instances are currently connected. Please ensure the plugin is running and connected.`
+                );
+            }
+            if (this.connectedClients.size > 1) {
+                throw new Error(
+                    `Multiple (${this.connectedClients.size}) Penpot MCP Plugin instances are connected. ` +
+                        `Ask the user to ensure that only one instance is connected at a time.`
+                );
+            }
+
+            // return the first (and only) connection
+            const connection = this.connectedClients.values().next().value;
+            return <ClientConnection>connection;
+        }
+    }
+
+    /**
+     * Executes a plugin task by sending it to connected clients.
+     *
+     * Registers the task for result correlation and returns a promise
+     * that resolves when the plugin responds with the execution result.
+     *
+     * @param task - The plugin task to execute
+     * @throws Error if no plugin instances are connected or available
+     */
+    public async executePluginTask<TResult extends PluginTaskResult<any>>(
+        task: PluginTask<any, TResult>
+    ): Promise<TResult> {
+        // get the appropriate client connection based on mode
+        const connection = this.getClientConnection();
+
+        // register the task for result correlation
+        this.pendingTasks.set(task.id, task);
+
+        // send task to the selected client
+        const requestMessage = JSON.stringify(task.toRequest());
+        if (connection.socket.readyState !== 1) {
+            // WebSocket is not open
+            this.pendingTasks.delete(task.id);
+            throw new Error(`Plugin instance is disconnected. Task could not be sent.`);
+        }
+
+        connection.socket.send(requestMessage);
+
+        // Set up a timeout to reject the task if no response is received
+        const timeoutHandle = setTimeout(() => {
+            const pendingTask = this.pendingTasks.get(task.id);
+            if (pendingTask) {
+                this.pendingTasks.delete(task.id);
+                this.taskTimeouts.delete(task.id);
+                pendingTask.rejectWithError(
+                    new Error(`Task ${task.id} timed out after ${this.taskTimeoutSecs} seconds`)
+                );
+            }
+        }, this.taskTimeoutSecs * 1000);
+
+        this.taskTimeouts.set(task.id, timeoutHandle);
+        this.logger.info(`Sent task ${task.id} to connected client`);
+
+        return await task.getResultPromise();
+    }
+}

mcp/packages/server/src/PluginTask.ts

@@ -0,0 +1,122 @@
+/**
+ * Base class for plugin tasks that are sent over WebSocket.
+ *
+ * Each task defines a specific operation for the plugin to execute
+ * along with strongly-typed parameters.
+ *
+ * @template TParams - The strongly-typed parameters for this task
+ */
+import { PluginTaskRequest, PluginTaskResult } from "@penpot/mcp-common";
+import { randomUUID } from "crypto";
+
+/**
+ * Base class for plugin tasks that are sent over WebSocket.
+ *
+ * Each task defines a specific operation for the plugin to execute
+ * along with strongly-typed parameters and request/response correlation.
+ *
+ * @template TParams - The strongly-typed parameters for this task
+ * @template TResult - The expected result type from task execution
+ */
+export abstract class PluginTask<TParams = any, TResult extends PluginTaskResult<any> = PluginTaskResult<any>> {
+    /**
+     * Unique identifier for request/response correlation.
+     */
+    public readonly id: string;
+
+    /**
+     * The name of the task to execute on the plugin side.
+     */
+    public readonly task: string;
+
+    /**
+     * The parameters for this task execution.
+     */
+    public readonly params: TParams;
+
+    /**
+     * Promise that resolves when the task execution completes.
+     */
+    private readonly result: Promise<TResult>;
+
+    /**
+     * Resolver function for the result promise.
+     */
+    private resolveResult?: (result: TResult) => void;
+
+    /**
+     * Rejector function for the result promise.
+     */
+    private rejectResult?: (error: Error) => void;
+
+    /**
+     * Creates a new plugin task instance.
+     *
+     * @param task - The name of the task to execute
+     * @param params - The parameters for task execution
+     */
+    constructor(task: string, params: TParams) {
+        this.id = randomUUID();
+        this.task = task;
+        this.params = params;
+        this.result = new Promise<TResult>((resolve, reject) => {
+            this.resolveResult = resolve;
+            this.rejectResult = reject;
+        });
+    }
+
+    /**
+     * Gets the result promise for this task.
+     *
+     * @returns Promise that resolves when the task execution completes
+     */
+    getResultPromise(): Promise<TResult> {
+        if (!this.result) {
+            throw new Error("Result promise not initialized");
+        }
+        return this.result;
+    }
+
+    /**
+     * Resolves the task with the given result.
+     *
+     * This method should be called when a task response is received
+     * from the plugin with matching ID.
+     *
+     * @param result - The task execution result
+     */
+    resolveWithResult(result: TResult): void {
+        if (!this.resolveResult) {
+            throw new Error("Result promise not initialized");
+        }
+        this.resolveResult(result);
+    }
+
+    /**
+     * Rejects the task with the given error.
+     *
+     * This method should be called when task execution fails
+     * or times out.
+     *
+     * @param error - The error that occurred during task execution
+     */
+    rejectWithError(error: Error): void {
+        if (!this.rejectResult) {
+            throw new Error("Result promise not initialized");
+        }
+        this.rejectResult(error);
+    }
+
+    /**
+     * Serializes the task to a request message for WebSocket transmission.
+     *
+     * @returns The request message containing ID, task name, and parameters
+     */
+    toRequest(): PluginTaskRequest {
+        return {
+            id: this.id,
+            task: this.task,
+            params: this.params,
+        };
+    }
+}

mcp/packages/server/src/ReplServer.ts

@@ -0,0 +1,112 @@
+import express from "express";
+import path from "path";
+import { fileURLToPath } from "url";
+import { PluginBridge } from "./PluginBridge";
+import { ExecuteCodePluginTask } from "./tasks/ExecuteCodePluginTask";
+import { createLogger } from "./logger";
+
+/**
+ * Web-based REPL server for executing code through the PluginBridge.
+ *
+ * Provides a REPL-style HTML interface that allows users to input
+ * JavaScript code and execute it via ExecuteCodePluginTask instances.
+ * The interface maintains command history, displays logs in <pre> tags,
+ * and shows results in visually separated blocks.
+ */
+export class ReplServer {
+    private readonly logger = createLogger("ReplServer");
+    private readonly app: express.Application;
+    private readonly port: number;
+    private server: any;
+
+    constructor(
+        private readonly pluginBridge: PluginBridge,
+        port: number = 4403
+    ) {
+        this.port = port;
+        this.app = express();
+        this.setupMiddleware();
+        this.setupRoutes();
+    }
+
+    /**
+     * Sets up Express middleware for request parsing and static content.
+     */
+    private setupMiddleware(): void {
+        this.app.use(express.json());
+    }
+
+    /**
+     * Sets up HTTP routes for the REPL interface and API endpoints.
+     */
+    private setupRoutes(): void {
+        // serve the main REPL interface
+        this.app.get("/", (req, res) => {
+            const __filename = fileURLToPath(import.meta.url);
+            const __dirname = path.dirname(__filename);
+            const htmlPath = path.join(__dirname, "static", "repl.html");
+            res.sendFile(htmlPath);
+        });
+
+        // API endpoint for executing code
+        this.app.post("/execute", async (req, res) => {
+            try {
+                const { code } = req.body;
+
+                if (!code || typeof code !== "string") {
+                    return res.status(400).json({
+                        error: "Code parameter is required and must be a string",
+                    });
+                }
+
+                const task = new ExecuteCodePluginTask({ code });
+                const result = await this.pluginBridge.executePluginTask(task);
+
+                // extract the result member from ExecuteCodeTaskResultData
+                const executeResult = result.data?.result;
+
+                res.json({
+                    success: true,
+                    result: executeResult,
+                    log: result.data?.log || "",
+                });
+            } catch (error) {
+                this.logger.error(error, "Failed to execute code in REPL");
+                res.status(500).json({
+                    error: error instanceof Error ? error.message : "Unknown error occurred",
+                });
+            }
+        });
+    }
+
+    /**
+     * Starts the REPL web server.
+     *
+     * Begins listening on the configured port and logs server startup information.
+     */
+    public async start(): Promise<void> {
+        return new Promise((resolve) => {
+            this.server = this.app.listen(this.port, () => {
+                this.logger.info(`REPL server started on port ${this.port}`);
+                this.logger.info(
+                    `REPL interface URL: http://${this.pluginBridge.mcpServer.serverAddress}:${this.port}`
+                );
+                resolve();
+            });
+        });
+    }
+
+    /**
+     * Stops the REPL web server.
+     */
+    public async stop(): Promise<void> {
+        if (this.server) {
+            return new Promise((resolve) => {
+                this.server.close(() => {
+                    this.logger.info("REPL server stopped");
+                    resolve();
+                });
+            });
+        }
+    }
+}

mcp/packages/server/src/Tool.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import "reflect-metadata";
+import { TextResponse, ToolResponse } from "./ToolResponse";
+import type { PenpotMcpServer, SessionContext } from "./PenpotMcpServer";
+import { createLogger } from "./logger";
+
+/**
+ * An empty arguments class for tools that do not require any parameters.
+ */
+export class EmptyToolArgs {
+    static schema = {};
+}
+
+/**
+ * Base class for type-safe tools with automatic schema generation and validation.
+ *
+ * This class provides type safety through automatic validation and strongly-typed
+ * protected methods. All tools should extend this class.
+ *
+ * @template TArgs - The strongly-typed arguments class for this tool
+ */
+export abstract class Tool<TArgs extends object> {
+    private readonly logger = createLogger("Tool");
+
+    protected constructor(
+        protected mcpServer: PenpotMcpServer,
+        private inputSchema: z.ZodRawShape
+    ) {}
+
+    /**
+     * Executes the tool with automatic validation and type safety.
+     *
+     * This method handles the unknown args from the MCP protocol,
+     * delegating to the type-safe implementation.
+     */
+    async execute(args: unknown): Promise<ToolResponse> {
+        try {
+            let argsInstance: TArgs = args as TArgs;
+            this.logger.info("Executing tool: %s; arguments: %s", this.getToolName(), this.formatArgs(argsInstance));
+
+            // execute the actual tool logic
+            let result = await this.executeCore(argsInstance);
+
+            this.logger.info("Tool execution completed: %s", this.getToolName());
+            return result;
+        } catch (error) {
+            this.logger.error(error);
+            return new TextResponse(`Tool execution failed: ${String(error)}`);
+        }
+    }
+
+    /**
+     * Formats tool arguments for readable logging.
+     *
+     * Multi-line strings are preserved with proper indentation.
+     */
+    protected formatArgs(args: TArgs): string {
+        const formatted: string[] = [];
+
+        for (const [key, value] of Object.entries(args)) {
+            if (typeof value === "string" && value.includes("\n")) {
+                // multi-line string - preserve formatting with indentation
+                const indentedValue = value
+                    .split("\n")
+                    .map((line, index) => (index === 0 ? line : "    " + line))
+                    .join("\n");
+                formatted.push(`  ${key}: ${indentedValue}`);
+            } else if (typeof value === "string") {
+                // single-line string
+                formatted.push(`  ${key}: "${value}"`);
+            } else if (value === null || value === undefined) {
+                formatted.push(`  ${key}: ${value}`);
+            } else {
+                // other types (numbers, booleans, objects, arrays)
+                const stringified = JSON.stringify(value, null, 2);
+                if (stringified.includes("\n")) {
+                    // multi-line JSON - indent it
+                    const indented = stringified
+                        .split("\n")
+                        .map((line, index) => (index === 0 ? line : "    " + line))
+                        .join("\n");
+                    formatted.push(`  ${key}: ${indented}`);
+                } else {
+                    formatted.push(`  ${key}: ${stringified}`);
+                }
+            }
+        }
+
+        return formatted.length > 0 ? "\n" + formatted.join("\n") : "{}";
+    }
+
+    /**
+     * Retrieves the current session context.
+     *
+     * @returns The session context for the current request, or undefined if not in a request context
+     */
+    protected getSessionContext(): SessionContext | undefined {
+        return this.mcpServer.getSessionContext();
+    }
+
+    public getInputSchema() {
+        return this.inputSchema;
+    }
+
+    /**
+     * Returns the tool's unique name.
+     */
+    public abstract getToolName(): string;
+
+    /**
+     * Returns the tool's description.
+     */
+    public abstract getToolDescription(): string;
+
+    /**
+     * Executes the tool's core logic.
+     *
+     * @param args - The (typed) tool arguments
+     */
+    protected abstract executeCore(args: TArgs): Promise<ToolResponse>;
+}

mcp/packages/server/src/ToolResponse.ts

@@ -0,0 +1,97 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+type CallToolContent = CallToolResult["content"][number];
+type TextItem = Extract<CallToolContent, { type: "text" }>;
+type ImageItem = Extract<CallToolContent, { type: "image" }>;
+
+export class TextContent implements TextItem {
+    [x: string]: unknown;
+    readonly type = "text" as const;
+    constructor(public text: string) {}
+
+    /**
+     * @param data - Text data as string or as object (from JSON representation where indices are mapped to character codes)
+     */
+    public static textData(data: string | object): string {
+        if (typeof data === "object") {
+            // convert object containing character codes (as obtained from JSON conversion of string) back to string
+            return String.fromCharCode(...(Object.values(data) as number[]));
+        } else {
+            return data;
+        }
+    }
+}
+
+export class ImageContent implements ImageItem {
+    [x: string]: unknown;
+    readonly type = "image" as const;
+
+    /**
+     * @param data - Base64-encoded image data
+     * @param mimeType - MIME type of the image (e.g., "image/png")
+     */
+    constructor(
+        public data: string,
+        public mimeType: string
+    ) {}
+
+    /**
+     * Utility function for ensuring a consistent Uint8Array representation of byte data.
+     * Input can be either a Uint8Array or an object (as obtained from JSON conversion of Uint8Array
+     * from the plugin).
+     *
+     * @param data - data as Uint8Array or as object (from JSON conversion of Uint8Array)
+     * @return data as Uint8Array
+     */
+    public static byteData(data: Uint8Array | object): Uint8Array {
+        if (typeof data === "object") {
+            // convert object (as obtained from JSON conversion of Uint8Array) back to Uint8Array
+            return new Uint8Array(Object.values(data) as number[]);
+        } else {
+            return data;
+        }
+    }
+}
+
+export class PNGImageContent extends ImageContent {
+    /**
+     * @param data - PNG image data as Uint8Array or as object (from JSON conversion of Uint8Array)
+     */
+    constructor(data: Uint8Array | object) {
+        let array = ImageContent.byteData(data);
+        super(Buffer.from(array).toString("base64"), "image/png");
+    }
+}
+
+export class ToolResponse implements CallToolResult {
+    [x: string]: unknown;
+    content: CallToolContent[]; // <- IMPORTANT: protocol’s union
+    constructor(content: CallToolContent[]) {
+        this.content = content;
+    }
+}
+
+export class TextResponse extends ToolResponse {
+    constructor(text: string) {
+        super([new TextContent(text)]);
+    }
+
+    /**
+     * Creates a TextResponse from text data given as string or as object (from JSON representation where indices are mapped to
+     * character codes).
+     *
+     * @param data - Text data as string or as object (from JSON representation where indices are mapped to character codes)
+     */
+    public static fromData(data: string | object): TextResponse {
+        return new TextResponse(TextContent.textData(data));
+    }
+}
+
+export class PNGResponse extends ToolResponse {
+    /**
+     * @param data - PNG image data as Uint8Array or as object (from JSON conversion of Uint8Array)
+     */
+    constructor(data: Uint8Array | object) {
+        super([new PNGImageContent(data)]);
+    }
+}

mcp/packages/server/src/index.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import { PenpotMcpServer } from "./PenpotMcpServer";
+import { createLogger, logFilePath } from "./logger";
+
+/**
+ * Entry point for Penpot MCP Server
+ *
+ * Creates and starts the MCP server instance, handling any startup errors
+ * gracefully and ensuring proper process termination.
+ *
+ * Configuration via environment variables (see README).
+ */
+async function main(): Promise<void> {
+    const logger = createLogger("main");
+
+    // log the file path early so it appears before any potential errors
+    logger.info(`Logging to file: ${logFilePath}`);
+
+    try {
+        const args = process.argv.slice(2);
+        let multiUser = false; // default to single-user mode
+
+        // parse command line arguments
+        for (let i = 0; i < args.length; i++) {
+            if (args[i] === "--multi-user") {
+                multiUser = true;
+            } else if (args[i] === "--help" || args[i] === "-h") {
+                logger.info("Usage: node dist/index.js [options]");
+                logger.info("Options:");
+                logger.info("  --multi-user           Enable multi-user mode (default: single-user)");
+                logger.info("  --help, -h             Show this help message");
+                logger.info("");
+                logger.info("Note that configuration is mostly handled through environment variables.");
+                logger.info("Refer to the README for more information.");
+                process.exit(0);
+            }
+        }
+
+        const server = new PenpotMcpServer(multiUser);
+        await server.start();
+
+        // keep the process alive
+        process.on("SIGINT", async () => {
+            logger.info("Received SIGINT, shutting down gracefully...");
+            await server.stop();
+            process.exit(0);
+        });
+
+        process.on("SIGTERM", async () => {
+            logger.info("Received SIGTERM, shutting down gracefully...");
+            await server.stop();
+            process.exit(0);
+        });
+    } catch (error) {
+        logger.error(error, "Failed to start MCP server");
+        process.exit(1);
+    }
+}
+
+// Start the server if this file is run directly
+if (import.meta.url.endsWith(process.argv[1]) || process.argv[1].endsWith("index.js")) {
+    main().catch((error) => {
+        createLogger("main").error(error, "Unhandled error in main");
+        process.exit(1);
+    });
+}