photo-renamer/CLAUDE.md

CLAUDE.md

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

Commands

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.