Architecture Rules

Follow these rules for the whole repository. More specific AGENTS.md files override/add rules for their folders.

Boundaries

core/: pure domain models only. See core/AGENTS.md.
commands/: the only write path for application state.
editor/: transient editor/app state types and app store, e.g. viewport/camera and selection.
keybinds/: keybind resolution; global consumer first, command fallback second.
renderer/: renders the current ImageDocument using the graphics backend, e.g. WebGL.
view/: React UI shell and controls only.

All persistent document state is represented by ImageDocument and related core/ models.
Transient editor state is application state too: viewport/camera, selection, tools, active artboard/layer, drag state, etc.
Commands are the only code allowed to create, replace, or mutate persistent or transient state.
React must not own, manage, derive authoritative, or alter document/editor state.
React may hold only local ephemeral UI details with no app meaning, e.g. open popover, hovered button, uncontrolled input draft before command submit.
Do not update state directly from React event handlers, renderer callbacks, effects, stores, services, or keybind handlers. Dispatch a command instead.

Every state change must be modeled as a command with an explicit id, payload, and context.
Commands must be deterministic and testable; avoid DOM, React, WebGL, timers, network, and filesystem access inside command execution.
Commands return/apply the next state; they should preserve domain invariants and validate payloads before changing state.
UI actions, menus, toolbar buttons, keybinds, and renderer interactions all request changes by dispatching commands.

React displays current state and exposes user intent.
React components receive state snapshots/selectors and command dispatch functions; they do not contain business rules.
Do not put rendering engine logic, document mutation logic, or editor workflow ownership in React components.
Effects are for UI integration/subscription setup only, not for deriving or correcting application state.

The renderer draws the current ImageDocument plus read-only editor state overlays.
Renderer code must not mutate document/editor state directly.
Renderer interactions may emit intents/events that are translated into commands.
Keep rendering backend details isolated behind renderer APIs; do not leak WebGL objects into core/, commands/, or React state.

Keybind handling is ordered and explicit.
First check the global keybind consumer/map.
If the global consumer handles the keybind, stop.
If not consumed globally, the keybind may be consumed by dispatching a command.
Keybind handlers must not mutate state directly.
Avoid ad-hoc component-local shortcuts unless they are purely local UI behavior and cannot affect app/editor/document state.

core/ imports nothing from app layers.
commands/ may import core/ and editor/; avoid importing React or renderer backend APIs.
editor/ may import core/ types and command dispatch infrastructure; it must not import React, renderer, storage, or backend APIs.
keybinds/ may import command dispatch types; it must not mutate state directly.
renderer/ may import core/ and editor/ types; it must not import React components.
view/ may import UI components and command dispatch interfaces; avoid importing renderer internals except through stable view-facing adapters.