# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
npm start          # Run the Electron app in development
npm run build      # Build macOS app bundle (no DMG, arm64 + x64)
npm run dist       # Build and package as DMG for distribution
./setup.sh         # First-time setup: npm install + npm start
```

There are no tests or linting configured.

## Architecture

This is a macOS Electron desktop app for batch-renaming photo files. It follows strict Electron security practices: `contextIsolation: true`, `nodeIntegration: false`.

**Process boundary:** All filesystem access lives exclusively in `src/main.js` (main process). The renderer never touches `fs` directly.

**IPC surface** (defined in `main.js`, bridged via `preload.js` as `window.api`):
- `select-folder` → opens native folder picker, returns path
- `list-images` → reads directory, returns `{name, path, mtime, size}[]` filtered to image extensions
- `read-image` → reads file, returns base64 data URL for display
- `rename-files({folderPath, files, prefix, digits})` → two-phase rename (temp names first, then final names) to avoid collisions when new names overlap old names
- `reveal-folder` → opens folder in Finder via `shell.openPath`

**Renderer (`src/renderer.js`):** Single-file, no framework. All state is module-level globals:
- `files[]` — ordered array of file objects; order determines rename sequence
- `selectedIdxs` — `Set<number>` of selected card indices
- Thumbnail grid uses CSS `--thumb-size` custom property (150–400px), adjusted via trackpad pinch (`ctrlKey + wheel`)
- Rubber-band selection: drag on empty grid area to select multiple cards; `Shift` adds to existing selection; `Cmd+click` toggles individual cards
- Drag-and-drop reorder: single card drag or multi-card drag (moves selected group); DOM reorder avoids re-fetching images by remapping existing card elements via `card.dataset.filepath`
- Thumbnails load in batches of 10 (`Promise.all`) to avoid blocking the UI

**Styling:** All CSS is inline in `src/index.html`. Dark theme with CSS variables defined in `:root`. The macOS traffic-light buttons sit in `#titlebar` which uses `-webkit-app-region: drag`.

**Build output:** `electron-builder` targets DMG for arm64 and x64. The app icon must be at `assets/icon.icns`.