AGENTS.md

1# AGENTS.md
2 
3This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
4 
5## Before You Code
6 
7Read and follow the **karpathy-guidelines** skill (`.Codex/skills/karpathy-guidelines`) when writing, reviewing, or refactoring code here — surface assumptions, make surgical changes, keep it simple, and define verifiable success criteria.
8 
9## Project Overview
10 
11Cate is a desktop application that provides an infinite zoomable canvas where editor panels, terminal panels, and browser panels float spatially (similar to Figma/Miro, but for coding). Built with Electron + React + TypeScript, styled with Tailwind CSS.
12 
13## Build System
14 
15The Electron app lives at the project root. Uses **electron-vite** for bundling.
16 
17```bash
18npm install        # install dependencies
19npm run dev        # start dev server with hot reload
20npm run build      # production build
21npm test           # run vitest suite
22```
23 
24Tests use **Vitest** and live alongside the code they cover (`*.test.ts` / `*.test.tsx`). A few git-touching tests assume a clean working repo and may fail when the dev tree has a branch named `main` or local modifications — those failures are environmental, not regressions.
25 
26## Release Process
27 
28Before creating any beta or stable release, update `CHANGELOG.md` with the
29matching version, release date, summary, and categorized user-facing changes.
30The changelog entry must be complete before bumping or tagging the release.
31 
32## Dependencies
33 
34Managed via npm (`package.json`):
35- **Electron** — desktop shell (Chromium + Node.js)
36- **React 18** + **react-dom** — UI framework
37- **xterm.js** (`@xterm/xterm`) — terminal emulator with WebGL addon
38- **node-pty** — native PTY for terminal backend
39- **Monaco Editor** — code editor (VS Code's editor component)
40- **zustand** — lightweight state management
41- **chokidar** — filesystem watching
42- **simple-git** — git operations
43- **@phosphor-icons/react** — icons
44- **electron-updater** — auto-update (GitHub Releases)
45 
46## Architecture
47 
48### Process Model (Electron)
49 
50- **Main process** (`src/main/`) — window management, IPC handlers, native APIs
51- **Preload** (`src/preload/`) — secure bridge exposing IPC to renderer
52- **Renderer** (`src/renderer/`) — React app with canvas UI
53 
54IPC channels are defined in `src/shared/ipc-channels.ts`. Type definitions in `src/shared/types.ts`.
55 
56### Coordinate System & Canvas
57 
58The canvas (`Canvas.tsx`) positions nodes using CSS transforms. Panel positions are stored in **canvas-space** and converted to **view-space** via zoom level and viewport offset. Key conversions in `src/renderer/lib/canvas/coordinates.ts`: `canvasToView()` / `viewToCanvas()`. Zoom range defined by `ZOOM_MIN`/`ZOOM_MAX` in shared types.
59 
60### Canvas Interaction
61 
62`useCanvasInteraction` hook handles wheel events (Cmd+scroll = zoom, two-finger = pan) and right-click drag panning. Node drag/resize handled by `useCanvasNodeDrag` and `useNodeResize` hooks.
63 
64### Panel System
65 
66Panel definitions are centralised in `src/shared/panels.ts`. The detachable panel
67types (`PanelType` in `src/shared/types.ts`) are: terminal, browser, editor,
68canvas, agent, document, extension. Renderer components live in `src/renderer/panels/`:
69- **EditorPanel** — Monaco Editor with syntax highlighting
70- **TerminalPanel** — xterm.js terminal with WebGL renderer, backed by node-pty
71- **BrowserPanel** — embedded webview (file:// allowed for local HTML)
72- **CanvasPanel** — nested canvas
73- **DocumentPanel** — PDF / docx preview
74- **AgentPanel** — Codex agent thread (sidebar + dock)
75- **ExtensionPanel** — third-party extension panel (isolated webview served by an extension server)
76 
77The file tree (`src/renderer/sidebar/FileExplorer.tsx`) and recent-projects
78switcher (`src/renderer/sidebar/ProjectList.tsx`) are **sidebar** components, not
79detachable panels.
80 
81Each panel can be wrapped in a `CanvasNode` (`src/renderer/canvas/CanvasNode.tsx`) — title bar, drag, resize, close — or live inside a dock zone via `DockTabStack` (`src/renderer/docking/`). All panel records render through the shared `PanelHost` (`src/renderer/panels/PanelHost.tsx`); detached windows are dock windows (`src/renderer/shells/DockWindowShell.tsx`) with local panels state synced back to main for session persistence.
82 
83### State Management
84 
85Zustand stores in `src/renderer/stores/`:
86- **canvasStore** — nodes, regions, zoom, viewport offset, focus state, history; per-canvas instances created via `CanvasStoreContext`. A `focusEpoch` counter lets panels re-run focus side effects when the same node is re-focused.
87- **appStore** — workspaces, panels, selected workspace, sidebar
88- **dockStore** — dock-zone layout (per window)
89- **settingsStore** — user preferences
90- **shortcutStore** — keyboard shortcut bindings
91- **statusStore** — status bar state
92- **uiStore** — transient UI state (command palette, etc.)
93- **extensionsStore** — renderer-side mirror of the main process's extension registry (enabled-extension set)
94 
95Persisted state is stored as hand-editable JSON files under `userData` (no
96electron-store). `settingsFile.ts` owns `settings.json`; `jsonStateFile.ts` is a
97reusable factory for that same pattern — it delegates the in-memory-authority
98engine to `jsonStateStore.ts` and keeps the filesystem backend (sync load,
99debounced atomic write, chokidar external-edit watcher, corrupt-file quarantine).
100`workspaceStateStore.ts` uses it for `recent-projects.json`, `sidebar.json`,
101`remote-workspaces.json`, and `layouts.json`. Per-project canvas/session state
102lives in `<project>/.cate/workspace.json` + `session.json`. AI provider credentials are
103global in `userData/pi-agent/auth.json` (+ `models.json`), mirrored into each
104workspace's `.cate/pi-agent/`.
105 
106### Key Patterns
107 
108- **Functional React** with hooks for all logic
109- **Zustand** for global state (no Redux/Context boilerplate)
110- **Tailwind CSS** for styling
111- **IPC** for all main↔renderer communication (filesystem, git, terminal, shell)
112- Keyboard shortcuts via `useShortcuts` hook
113- File explorer is git-aware (tracks file status)
114