CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Before You Code
6 
7Read and follow the **karpathy-guidelines** skill (`.claude/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## Dependencies
27 
28Managed via npm (`package.json`):
29- **Electron** — desktop shell (Chromium + Node.js)
30- **React 18** + **react-dom** — UI framework
31- **xterm.js** (`@xterm/xterm`) — terminal emulator with WebGL addon
32- **node-pty** — native PTY for terminal backend
33- **Monaco Editor** — code editor (VS Code's editor component)
34- **zustand** — lightweight state management
35- **chokidar** — filesystem watching
36- **simple-git** — git operations
37- **@phosphor-icons/react** — icons
38- **electron-updater** — auto-update (GitHub Releases)
39 
40## Architecture
41 
42### Process Model (Electron)
43 
44- **Main process** (`src/main/`) — window management, IPC handlers, native APIs
45- **Preload** (`src/preload/`) — secure bridge exposing IPC to renderer
46- **Renderer** (`src/renderer/`) — React app with canvas UI
47 
48IPC channels are defined in `src/shared/ipc-channels.ts`. Type definitions in `src/shared/types.ts`.
49 
50### Coordinate System & Canvas
51 
52The 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.
53 
54### Canvas Interaction
55 
56`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.
57 
58### Panel System
59 
60Panel definitions are centralised in `src/shared/panels.ts`. The detachable panel
61types (`PanelType` in `src/shared/types.ts`) are: terminal, browser, editor,
62canvas, agent, document, extension. Renderer components live in `src/renderer/panels/`:
63- **EditorPanel** — Monaco Editor with syntax highlighting
64- **TerminalPanel** — xterm.js terminal with WebGL renderer, backed by node-pty
65- **BrowserPanel** — embedded webview (file:// allowed for local HTML)
66- **CanvasPanel** — nested canvas
67- **DocumentPanel** — PDF / docx preview
68- **AgentPanel** — Claude-Code agent thread (sidebar + dock)
69- **ExtensionPanel** — third-party extension panel (isolated webview served by an extension server)
70 
71The file tree (`src/renderer/sidebar/FileExplorer.tsx`) and recent-projects
72switcher (`src/renderer/sidebar/ProjectList.tsx`) are **sidebar** components, not
73detachable panels.
74 
75Each 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.
76 
77### State Management
78 
79Zustand stores in `src/renderer/stores/`:
80- **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.
81- **appStore** — workspaces, panels, selected workspace, sidebar
82- **dockStore** — dock-zone layout (per window)
83- **settingsStore** — user preferences
84- **shortcutStore** — keyboard shortcut bindings
85- **statusStore** — status bar state
86- **uiStore** — transient UI state (command palette, etc.)
87- **extensionsStore** — renderer-side mirror of the main process's extension registry (enabled-extension set)
88 
89Persisted state is stored as hand-editable JSON files under `userData` (no
90electron-store). `settingsFile.ts` owns `settings.json`; `jsonStateFile.ts` is a
91reusable factory for that same pattern — it delegates the in-memory-authority
92engine to `jsonStateStore.ts` and keeps the filesystem backend (sync load,
93debounced atomic write, chokidar external-edit watcher, corrupt-file quarantine).
94`workspaceStateStore.ts` uses it for `recent-projects.json`, `sidebar.json`,
95`remote-workspaces.json`, and `layouts.json`. Per-project canvas/session state
96lives in `<project>/.cate/workspace.json` + `session.json`. AI provider credentials are
97global in `userData/pi-agent/auth.json` (+ `models.json`), mirrored into each
98workspace's `.cate/pi-agent/`.
99 
100### Key Patterns
101 
102- **Functional React** with hooks for all logic
103- **Zustand** for global state (no Redux/Context boilerplate)
104- **Tailwind CSS** for styling
105- **IPC** for all main↔renderer communication (filesystem, git, terminal, shell)
106- Keyboard shortcuts via `useShortcuts` hook
107- File explorer is git-aware (tracks file status)
108