# CLAUDE.md

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

## Project Overview

**Directory MapView** - A reimagined file picker dialog that displays the filesystem like a road map.

### Vision

Traditional file dialogs show directories as indented trees or lists. You never see what's beside you or the broader context. Directory MapView changes this:

- Directories appear as connected pathways/roads with labels
- Current path highlighted like a navigation route
- "You are here" marker at current location
- Zoom out to see the big picture, zoom in for details
- Pan around to explore like Google Maps

### Interaction Model

- **Mouse wheel**: Zoom in/out
- **Left-click + drag**: Pan the view
- **Click on directory**: Navigate there
- **Hover**: Show directory info

## Development Commands

```bash
# Install for development
pip install -e ".[dev]"

# Run tests
pytest

# Run the demo
python -m dir_mapview.demo
```

## Architecture

### Technical Approach

- **PyQt6/PySide6** for the widget
- **QGraphicsScene** for zoomable/pannable canvas
- **Tree layout algorithm** for positioning directories
- Lazy loading for large filesystems
- Caching for performance

### Key Modules

- `src/dir_mapview/widget.py` - Main MapView widget (QGraphicsView subclass)
- `src/dir_mapview/scene.py` - Scene management and directory rendering
- `src/dir_mapview/layout.py` - Directory tree layout algorithm
- `src/dir_mapview/scanner.py` - Filesystem scanning with lazy loading
- `src/dir_mapview/dialog.py` - Drop-in file picker dialog replacement

### Key Paths

- **Source code**: `src/dir_mapview/`
- **Tests**: `tests/`
- **Documentation**: `docs/` (symlink to project-docs)

## Documentation

Documentation for this project lives in the centralized docs system:

- **Source**: `~/PycharmProjects/project-docs/docs/projects/dir-mapview/`
- **Public URL**: `https://pages.brrd.tech/rob/dir-mapview/`

When updating documentation:
1. Edit files in `docs/` (the symlink) or the full path above
2. Use `public: true` frontmatter for public-facing docs
3. Use `<!-- PRIVATE_START -->` / `<!-- PRIVATE_END -->` to hide sections
4. Run `~/PycharmProjects/project-docs/scripts/build-public-docs.sh dir-mapview --deploy` to publish

Do NOT create documentation files directly in this repository.