penpot/frontend/AGENTS.md

Penpot Frontend – Agent Instructions

ClojureScript based frontend application that uses React, RxJS as main architectural pieces.

General Guidelines

This is a golden rule for frontend development standards. To ensure consistency across the penpot stack, all contributions must adhere to these criteria:

1. Testing & Validation

Unit Tests

If code is added or modified in src/, corresponding tests in test/frontend_tests/ must be added or updated.

• Environment: Tests should run in a Node.js or browser-isolated environment without requiring the full application state or a running backend. Test are developed using cljs.test.
• Mocks & Stubs: * Use proper mocks for any side-effecting functions (e.g., API calls, storage access).
  • Avoid testing through the UI (DOM), we have e2e tests for that/
  • Use with-redefs or similar ClojureScript mocking utilities to isolate the logic under test.
• No Flakiness: Tests must be deterministic. Do not use setTimeout or real network calls. Use synchronous mocks for asynchronous workflows where possible.
• Location: Place tests in the test/frontend_tests/ directory, following the namespace structure of the source code (e.g., app.utils.timers -> frontend-tests.util-timers-test).
• Execution:
  • Isolated: To run a focused ClojureScript unit test: edit the test/frontend_tests/runner.cljs to narrow the test suite, then pnpm run test.
  • Regression: Run pnpm run test without modifications on the runner (preferred)

Integration Tests (Playwright)

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

You should not add, modify or run the integration tests unless it exlicitly asked for.

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

Ensure everything installed before executing tests with ./scripts/setup script.

2. Code Quality & Formatting

• Linting: All code changes must pass linter checks:
  • Run pnpm run lint:clj for CLJ/CLJS/CLJC
  • Run pnpm run lint:js for JS
  • Run pnpm run lint:scss for SCSS
• Formatting: All code changes must pass the formatting check
  • Run pnpm run check-fmt:clj for CLJ/CLJS/CLJC
  • Run pnpm run check-fmt:js for JS
  • Run pnpm run check-fmt:scss for SCSS
  • Use the pnpm run fmt fix all the formatting issues (pnpm run fmt:clj, pnpm run fmt:js or pnpm run fmt:scss for isolated formatting fix)

3. Implementation Rules

• Logic vs. View: If logic is embedded in an UI component, extract it into a function in the same namespace if is only used locally or look for a helper namespace to make it unit-testable.

Code Conventions

Namespace Overview

The source is located under src directory and this is a general overview of namespaces structure:

• 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)

State Management (Potok)

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

(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:

(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.

UI Components (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:

(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:

(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:

;; 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:

;; 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])

5. Styles

Styles on component code

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

Example of clojurescript code for reference classes defined on styles (we use CSS modules pattern):

;; 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))]}]

General rules for styling

• 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 inds/mixins.scss. Avoid legacy mixins like @include flexCenter;. Write standard CSS (flex/grid) instead.
• 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).

Performance Macros (app.common.data.macros)

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

(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

Configuration

src/app/config.clj reads globally defined variables and exposes precomputed configuration vars ready to be used from other parts of the application