# CLAUDE.md

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

## Build & Run Commands

| Platform | Command |
|----------|---------|
| Desktop | `./gradlew :desktopApp:run` |
| Desktop (hot reload) | `./gradlew :desktopApp:hotRun --auto` |
| Android APK | `./gradlew :androidApp:assembleDebug` |
| Web (JS) | `./gradlew :webApp:jsBrowserDevelopmentRun` |
| Web (WASM) | `./gradlew :webApp:wasmJsBrowserDevelopmentRun` |
| Web distribution | `./gradlew :webApp:composeCompatibilityBrowserDistribution` |
| iOS | Open `iosApp/iosApp.xcodeproj` in Xcode |

## Testing

Tests live in `sharedUI/src/commonTest/`. Run with:
```
./gradlew :sharedUI:allTests
```

Single test class:
```
./gradlew :sharedUI:jvmTest --tests "org.shahondin1624.ComposeTest"
```

Uses `androidx.compose.ui.test.runComposeUiTest` for Compose UI testing.

## Architecture

Kotlin Multiplatform project using Compose Multiplatform. All shared logic and UI lives in `sharedUI`; platform modules are thin entry points.

### Modules

- **sharedUI** — Shared business logic and Compose UI (targets: Android, JVM, JS, WASM, iOS)
- **androidApp** — Android entry point (`AppActivity`)
- **desktopApp** — Desktop JVM entry point (supports hot reload)
- **webApp** — Web entry point (JS + WASM targets)
- **iosApp** — iOS entry point (Xcode project, not in Gradle)

### Shared Code Layout (`sharedUI/src/commonMain/kotlin/org/shahondin1624/`)

- `App.kt` — Root composable. Scaffold with navigation drawer, top bar, theme toggle.
- `model/` — Domain model implementing Shadowrun 5e rules:
  - `charactermodel/ShadowrunCharacter` — Top-level aggregate: CharacterData + Attributes + Talents + DamageMonitor
  - `attributes/Attributes` — 8 core attributes + Edge. Calculates derived values (initiative, limits, composure, carry, etc.)
  - `attributes/AttributeType` — Enum with per-attribute color coding
  - `talents/` — 60+ predefined talents via `ProvidedTalentName`, sealed `TalentDefinition` with polymorphic serialization, custom talent support
  - `modifier/` — `SRModifier<T>` interface for composable modifiers on attributes, talents, and dice rolls. `ModifierCache` provides LRU caching (max 5).
  - `characterdata/CharacterData` — Name, metatype (Human/Elf/Dwarf/Ork/Troll), karma, nuyen, essence, etc.
  - `charactermodel/DamageMonitor` — Stun/physical/overflow damage tracking derived from attributes
  - `Defaults.kt` — `EXAMPLE_CHARACTER` used for development
  - `Versionable` — Interface for schema versioning (current: "v0.1")
- `lib/functions/` — Dice rolling system (`DiceRoll`, `rollDice`, `countSuccesses`) and `DataLoader` (JSON serialization via kotlinx.serialization)
- `lib/components/` — Compose UI components:
  - `charactermodel/attributespage/` — `AttributesPage` (grid layout), `Attribute` card, `Talent` card
  - `settings/Settings` — Placeholder
- `theme/` — Material 3 theme with MaterialKolor seed color `#1D3557`, dark/light mode via `LocalThemeIsDark` CompositionLocal

### Key Patterns

- **Modifier system**: `SRModifier<T>.apply(value)` + `accumulateModifiers()` fold for dice roll modifications
- **Serialization**: All model classes are `@Serializable`. `DataLoader` provides `serialize`/`deserialize` for `ShadowrunCharacter`.
- **Platform callbacks**: `App(onThemeChanged)` lets platform entry points react to theme changes (e.g., status bar styling)
- **Compose resources**: Drawables, fonts, and strings in `sharedUI/src/commonMain/composeResources/`

## Key Dependencies

- **Compose Multiplatform** 1.9.0 — UI framework
- **kotlinx.serialization** — JSON serialization for all model types
- **MaterialKolor** — Dynamic Material 3 color scheme generation
- **KStore** — Multiplatform key-value persistence
- **Ktor** — HTTP client (platform-specific engines)
- **Coil** — Image loading

Version catalog: `gradle/libs.versions.toml`