penpot/AGENTS.md

# Penpot – Instructions

## Architecture Overview

Penpot is a full-stack design tool composed of several distinct components:

| Component | Language | Role |
|-----------|----------|------|
| `frontend/` | ClojureScript + SCSS | Single-page React app (design editor) |
| `backend/` | Clojure (JVM) | HTTP/RPC server, PostgreSQL, Redis |
| `common/` | Cljc (shared Clojure/ClojureScript) | Data types, geometry, schemas, utilities |
| `exporter/` | ClojureScript (Node.js) | Headless Playwright-based export (SVG/PDF) |
| `render-wasm/` | Rust → WebAssembly | High-performance canvas renderer using Skia |
| `mcp/` | TypeScript | Model Context Protocol integration |
| `plugins/` | TypeScript | Plugin runtime and example plugins |

The monorepo is managed with `pnpm` workspaces. The `manage.sh`
orchestrates cross-component builds. `run-ci.sh` defines the CI
pipeline.

## Search Standards

When searching code, always use `ripgrep` (rg) instead of grep if
available, as it respects `.gitignore` by default.

If using grep, try to exclude node_modules and .shadow-cljs directories


## Build, Test & Lint Commands

### Frontend (`cd frontend`)

Run `./scripts/setup` for setup all dependencies.


```bash
# Build (Producution)
./scripts/build

# Tests
pnpm run test                      # Build ClojureScript tests + run node target/tests/test.js

# Lint
pnpm run lint:js              # Linter for JS/TS
pnpm run lint:clj             # Linter for CLJ/CLJS/CLJC
pnpm run lint:scss            # Linter for SCSS

# Check Code Formart
pnpm run check-fmt:clj        # Format CLJ/CLJS/CLJC
pnpm run check-fmt:js         # Format JS/TS
pnpm run check-fmt:scss       # Format SCSS

# Code Format (Automatic Formating)
pnpm run fmt:clj              # Format CLJ/CLJS/CLJC
pnpm run fmt:js               # Format JS/TS
pnpm run fmt:scss             # Format SCSS
```

To run a focused ClojureScript unit test: edit
`test/frontend_tests/runner.cljs` to narrow the test suite, then `pnpm
run build:test && node target/tests/test.js`.


### Backend (`cd backend`)

Run `pnpm install` for install all dependencies.

```bash
# Run full test suite
pnpm run test

# Run single namespace
pnpm run test --focus backend-tests.rpc-doc-test

# Check Code Format
pnpm run check-fmt

# Code Format (Automatic Formatting)
pnpm run fmt

# Code Linter
pnpm run lint
```

Test config is in `backend/tests.edn`; test namespaces match
`.*-test$` under `test/` directory. You should not touch this file,
just use it for reference.


### Common (`cd common`)

This contains code that should compile and run under different runtimes: JVM & JS so the commands are
separarated for each runtime.

```bash
clojure -M:dev:test                                    # Run full test suite under JVM
clojure -M:dev:test --focus backend-tests.my-ns-test   # Run single namespace under JVM

# Run full test suite under JS or JVM runtimes
pnpm run test:js
pnpm run test:jvm

# Run single namespace (only on JVM)
pnpm run test:jvm --focus common-tests.my-ns-test

# Lint
pnpm run lint:clj        # Lint CLJ/CLJS/CLJC code

# Check Format
pnpm run check-fmt:clj   # Check CLJ/CLJS/CLJS code
pnpm run check-fmt:js    # Check JS/TS code

# Code Format (Automatic Formatting)
pnpm run fmt:clj         # Check CLJ/CLJS/CLJS code
pnpm run fmt:js          # Check JS/TS code
```

To run a focused ClojureScript unit test: edit
`test/common_tests/runner.cljs` to narrow the test suite, then `pnpm
run build:test && node target/tests/test.js`.


### Render-WASM (`cd render-wasm`)

```bash
./test                        # Rust unit tests (cargo test)
./build                       # Compile to WASM (requires Emscripten)
cargo fmt --check
./lint --debug
```

## Key Conventions

### Namespace Structure

The backend, frontend and exporter are developed using clojure and
clojurescript and code is organized in namespaces. This is a general
overview of the available namespaces.

**Backend:**
- `app.rpc.commands.*` – RPC command implementations (`auth`, `files`, `teams`, etc.)
- `app.http.*` – HTTP routes and middleware
- `app.db.*` – Database layer
- `app.tasks.*` – Background job tasks
- `app.main` – Integrant system setup and entrypoint
- `app.loggers` – Internal loggers (auditlog, mattermost, etc) (do not be confused with `app.common.loggin`)

**Frontend:**
- `app.main.ui.*` – React UI components (`workspace`, `dashboard`, `viewer`)
- `app.main.data.*` – Potok event handlers (state mutations + side effects)
- `app.main.refs` – Reactive subscriptions (okulary lenses)
- `app.main.store` – Potok event store
- `app.util.*` – Utilities (DOM, HTTP, i18n, keyboard shortcuts)

**Common:**
- `app.common.types.*` – Shared data types for shapes, files, pages using Malli schemas
- `app.common.schema` – Malli abstraction layer, exposes the most used functions from malli
- `app.common.geom.*` – Geometry and shape transformation helpers
- `app.common.data` – Generic helpers used around all application
- `app.common.math` – Generic math helpers used around all aplication
- `app.common.json` – Generic JSON encoding/decoding helpers
- `app.common.data.macros` – Performance macros used everywhere


### Backend RPC Commands

The PRC methods are implement in a some kind of multimethod structure using
`app.util.serivices` namespace. All RPC methods are collected under `app.rpc`
namespace and exposed under `/api/rpc/command/<cmd-name>`. The RPC method
accepts POST and GET requests indistinctly and uses `Accept` header for
negotiate the response encoding (which can be transit, the defaut or plain
json). It also accepts transit (defaut) or json as input, which should be
indicated using `Content-Type` header.

This is an example:

```clojure
(sv/defmethod ::my-command
  {::rpc/auth true            ;; requires auth
   ::doc/added "1.18"
   ::sm/params [:map ...]     ;; malli input schema
   ::sm/result [:map ...]}    ;; malli output schema
  [{:keys [::db/pool] :as cfg} {:keys [::rpc/profile-id] :as params}]
  ;; return a plain map or throw
  {:id (uuid/next)})
```

Look under `src/app/rpc/commands/*.clj` to see more examples.


### Frontend State Management (Potok)

State is a single atom managed by a Potok store. Events implement protocols
(funcool/potok library):

```clojure
(defn my-event
  "doc string"
  [data]
  (ptk/reify ::my-event
    ptk/UpdateEvent
    (update [_ state]           ;; synchronous state transition
      (assoc state :key data))

    ptk/WatchEvent
    (watch [_ state stream]     ;; async: returns an observable
      (->> (rp/cmd! :some-rpc-command params)
           (rx/map success-event)
           (rx/catch error-handler)))

    ptk/EffectEvent
    (effect [_ state _]         ;; pure side effects (DOM, logging)
      (dom/focus (dom/get-element "id")))))
```

The state is located under `app.main.store` namespace where we have
the `emit!` function responsible of emiting events.

Example:

```cljs
(ns some.ns
  (:require
    [app.main.data.my-events :refer [my-event]]
    [app.main.store :as st]))

(defn on-click
  [event]
  (st/emit! (my-event)))
```

On `app.main.refs` we have reactive references which lookup into the main state
for just inner data or precalculated data. That references are very usefull but
should be used with care because, per example if we have complex operation, this
operation will be executed on each state change, and sometimes is better to have
simple references and use react `use-memo` for more granular memoization.

Prefer helpers from `app.util.dom` instead of using direct dom calls, if no helper is
available, prefer adding a new helper for handling it and the use the
new helper.


### CSS (Modules Pattern)

Styles are co-located with components. Each `.cljs` file has a corresponding
`.scss` file:

```clojure
;; In the component namespace:
(require '[app.main.style :as stl])

;; In the render function:
[:div {:class (stl/css :container :active)}]

;; Conditional:
[:div {:class (stl/css-case :some-class true :selected (= drawtool :rect))}]

;; When you need concat an existing class:
[:div {:class [existing-class (stl/css-case :some-class true :selected (= drawtool :rect))]}]
```

### Integration tests (Playwright)

Integration tests are developed under `frontend/playwright` directory, we use
mocks for remove communication with backend.

The tests should be executed under `./frontend` directory:

```
cd frontend/

pnpm run test:e2e                   # Playwright e2e tests
pnpm run test:e2e --grep "pattern"  # Single e2e test by pattern
```

Ensure everything installed with `./scripts/setup` script.


### Performance Macros (`app.common.data.macros`)

Always prefer these macros over their `clojure.core` equivalents — they compile to faster JavaScript:

```clojure
(dm/select-keys m [:a :b])     ;; ~6x faster than core/select-keys
(dm/get-in obj [:a :b :c])     ;; faster than core/get-in
(dm/str "a" "b" "c")           ;; string concatenation
```

### Shared Code under Common (CLJC)

Files in `common/src/app/common/` use reader conditionals to target both runtimes:

```clojure
#?(:clj  (import java.util.UUID)
   :cljs (:require [cljs.core :as core]))
```

Both frontend and backend depend on `common` as a local library (`penpot/common
{:local/root "../common"}`).



### Component Standards & Syntax (React & Rumext: mf/defc)

The codebase contains various component patterns. When creating or refactoring
components, follow the Modern Syntax rules outlined below.

1. The * Suffix Convention

The most recent syntax uses a * suffix in the component name (e.g.,
my-component*). This suffix signals the mf/defc macro to apply specific rules
for props handling and destructuring and optimization.

2. Component Definition

Modern components should use the following structure:

```clj
(mf/defc my-component*
  {::mf/wrap [mf/memo]}         ;; Equivalent to React.memo
  [{:keys [name on-click]}]     ;; Destructured props
  [:div {:class (stl/css :root)
         :on-click on-click}
   name])
```

3. Hooks

Use the mf namespace for hooks to maintain consistency with the macro's
lifecycle management. These are analogous to standard React hooks:

```clj
(mf/use-state)  ;; analogous to React.useState adapted to cljs semantics
(mf/use-effect) ;; analogous to React.useEffect
(mf/use-memo)   ;; analogous to React.useMemo
(mf/use-fn)     ;; analogous to React.useCallback
```

The `mf/use-state` in difference with React.useState, returns an atom-like
object, where you can use `swap!` or `reset!` for to perform an update and
`deref` for get the current value.

You also has `mf/deref` hook (which does not follow the `use-` naming pattern)
and it's purpose is watch (subscribe to changes) on atom or derived atom (from
okulary) and get the current value. Is mainly used for subscribe to lenses
defined in `app.main.refs` or (private lenses defined in namespaces).

Rumext also comes with improved syntax macros as alternative to `mf/use-effect`
and `mf/use-memo` functions. Examples:


Example for `mf/with-memo` macro:

```clj
;; Using functions
(mf/use-effect
  (mf/deps team-id)
  (fn []
    (st/emit! (dd/initialize team-id))
    (fn []
      (st/emit! (dd/finalize team-id)))))

;; The same effect but using mf/with-effect
(mf/with-effect [team-id]
  (st/emit! (dd/initialize team-id))
  (fn []
    (st/emit! (dd/finalize team-id))))
```

Example for `mf/with-memo` macro:

```
;; Using functions
(mf/use-memo
  (mf/deps projects team-id)
  (fn []
    (->> (vals projects)
         (filterv #(= team-id (:team-id %))))))

;; Using the macro
(mf/with-memo [projects team-id]
  (->> (vals projects)
       (filterv #(= team-id (:team-id %)))))
```

Prefer using the macros for it syntax simplicity.


4. Component Usage (Hiccup Syntax)

When invoking a component within Hiccup, always use the [:> component* props]
pattern.

Requirements for props:

- Must be a map literal or a symbol pointing to a JavaScript props object.
- To create a JS props object, use the `#js` literal or the `mf/spread-object` helper macro.

Examples:

```clj
;; Using object literal (no need of #js because macro already interprets it)
[:> my-component* {:data-foo "bar"}]

;; Using object literal (no need of #js because macro already interprets it)
(let [props #js {:data-foo "bar"
                 :className "myclass"}]
  [:> my-component* props])

;; Using the spread helper
(let [props (mf/spread-object base-props {:extra "data"})]
  [:> my-component* props])
```

4. Checklist

- [ ] Does the component name end with *?


## Commit Format Guidelines

Format: `<emoji-code> <subject>`

```
:bug: Fix unexpected error on launching modal

Optional body explaining the why.

Signed-off-by: Fullname <email>
```

**Subject rules:** imperative mood, capitalize first letter, no
trailing period, ≤ 80 characters. Add an entry to `CHANGES.md` if
applicable.

**Code patches must include a DCO sign-off** (`git commit -s`).

| Emoji | Emoji-Code | Use for |
|-------|------|---------|
| 🐛 | `:bug:` | Bug fix |
| ✨ | `:sparkles:` | Improvement |
| 🎉 | `:tada:` | New feature |
| ♻️ | `:recycle:` | Refactor |
| 💄 | `:lipstick:` | Cosmetic changes |
| 🚑 | `:ambulance:` | Critical bug fix |
| 📚 | `:books:` | Docs |
| 🚧 | `:construction:` | WIP |
| 💥 | `:boom:` | Breaking change |
| 🔧 | `:wrench:` | Config update |
| ⚡ | `:zap:` | Performance |
| 🐳 | `:whale:` | Docker |
| 📎 | `:paperclip:` | Other non-relevant changes |
| ⬆️ | `:arrow_up:` | Dependency upgrade |
| ⬇️ | `:arrow_down:` | Dependency downgrade |
| 🔥 | `:fire:` | Remove files or code |
| 🌐 | `:globe_with_meridians:` | Translations |


## SCSS Rules & Migration

### General rules

- Prefer CSS custom properties ( `margin: var(--sp-xs);`) instead of scss
  variables and get the already defined properties from `_sizes.scss`. The SCSS
  variables are allowed and still used, just prefer properties if they are
  already defined.
- If a value isn't in the DS, use the `px2rem(n)` mixin: `@use "ds/_utils.scss"
  as *; padding: px2rem(23);`.
- Do **not** create new SCSS variables for one-off values.
- Use physical directions with logical ones to support RTL/LTR naturally.
  - ❌ `margin-left`, `padding-right`, `left`, `right`.
  - ✅ `margin-inline-start`, `padding-inline-end`, `inset-inline-start`.
- Always use the `use-typography` mixin from `ds/typography.scss`.
  - ✅ `@include t.use-typography("title-small");`
- Use `$br-*` for radius and `$b-*` for thickness from `ds/_borders.scss`.
- Use only tokens from `ds/colors.scss`. Do **NOT** use `design-tokens.scss` or
  legacy color variables.
- Use mixins only those defined in`ds/mixins.scss`. Avoid legacy mixins like
  `@include flexCenter;`. Write standard CSS (flex/grid) instead.

### Syntax & Structure

- Use the `@use` instead of `@import`. If you go to refactor existing SCSS file,
  try to replace all `@import` with `@use`. Example: `@use "ds/_sizes.scss" as
  *;` (Use `as *` to expose variables directly).
- Avoid deep selector nesting or high-specificity (IDs). Flatten selectors:
  - ❌ `.card { .title { ... } }`
  - ✅ `.card-title { ... }`
- Leverage component-level CSS variables for state changes (hover/focus) instead
  of rewriting properties.

### Checklist

- [ ] No references to `common/refactor/` 
- [ ] All `@import` converted to `@use` (only if refactoring)
- [ ] Physical properties (left/right) using logical properties (inline-start/end).
- [ ] Typography implemented via `use-typography()` mixin.
- [ ] Hardcoded pixel values wrapped in `px2rem()`.
- [ ] Selectors are flat (no deep nesting).