# CLAUDE.md

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

## What This Project Is

SoliCards is a native SwiftUI solitaire card game for iOS 17+, iPadOS 17+, and macOS 14+. It was ported from a web-based JavaScript game following the XCode-Claude-Workflow methodology.

## Build Commands

```bash
# Generate Xcode project (required after cloning or editing project.yml)
xcodegen generate

# Build for iOS Simulator
xcodebuild build -project SoliCards.xcodeproj -scheme SoliCards -destination 'platform=iOS Simulator,name=iPhone 16'

# Build for macOS
xcodebuild build -project SoliCards.xcodeproj -scheme SoliCards -destination 'platform=macOS' CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=NO

# Run tests
xcodebuild test -project SoliCards.xcodeproj -scheme SoliCardsTests -destination 'platform=iOS Simulator,name=iPhone 16'

# Static analysis
xcodebuild analyze -project SoliCards.xcodeproj -scheme SoliCards -destination 'platform=iOS Simulator,name=iPhone 16'
```

## Architecture

**MVVM + Protocol-Oriented Strategy** — see ARCHITECTURE.md for full details.

- `GameRules` protocol with 3 conforming structs: `KlondikeRules`, `SpiderRules`, `FreeCellRules`
- `@Observable` macro for property-level SwiftUI observation
- `@MainActor` on ViewModels for Swift 6 concurrency safety
- `DragGesture` + `PreferenceKey` frame hit-testing for card drag & drop
- SwiftData for persistence (`GameRecord`, `StatsRecord`, `PrefsRecord`)
- Zero external dependencies

## Key Conventions

- `.xcodeproj` is generated by xcodegen from `project.yml` — do not edit it by hand
- `Array.trailingSuffix(while:)` extension replaces missing stdlib `suffix(while:)`
- Card images loaded from asset catalog via platform-conditional helpers in `CardView`
- Long press (0.15s) + drag for card movement; tap for auto-move; swipe to scroll (iOS landscape)

## Test Suite

57 tests across 12 suites in `SoliCardsTests/` using Swift Testing (`@Test`, `#expect`).