# AGENTS.md

This file provides guidance to OpenCode and other agents when working with code
in this repository.

## SEARCHING VENDORED MAPLIBRE-NATIVE CODEBASE:

When searching the vendored maplibre-native codebase:

- Location: Look in `lib/maplibre-native-bindings-jni/vendor/maplibre-native/`
- Key Directories:
  - `platform/linux/` `- Linux-specific code (includes linux.cmake)
  - `platform/windows/` - Windows-specific code (includes windows.cmake)
  - `platform/darwin/` - macOS/iOS-specific code (includes darwin.cmake)
  - `platform/default/` - Cross-platform code
  - `include/mbgl/` - Public headers
  - `src/mbgl/` - Implementation files
- Common Search Patterns:
  - Platform-specific cmake: `platform/*/platform/*.cmake`
  - MLN options: `option(MLN*WITH*\*`
  - Compiler flags: `target_compile_options`, `target_link_options`
  - Feature detection: `MLN_WITH_OPENGL`, `MLN_WITH_VULKAN`

## Development Commands

### Building and Running

- **Run desktop demo:** `./gradlew :demo-app:run`
- **Run web demo:** `./gradlew :demo-app:jsRun`
- **Build all modules:** `./gradlew build`
- **Clean build:** `./gradlew clean`

### Documentation

- **Generate docs:** `./gradlew generateDocs` (builds both MkDocs site and Dokka
  API reference)
- **Build MkDocs only:** `./gradlew mkdocsBuild`
- **Build API docs only:** `./gradlew dokkaGenerate`

### Testing

Tests are located in platform-specific source sets:

- Android device tests: `src/androidDeviceTest`
- Android host tests: `src/androidHostTest`
- iOS tests: `src/iosTest`
- Common tests: `src/commonTest`

## Architecture Overview

MapLibre Compose is a Kotlin Multiplatform wrapper around MapLibre SDKs for
rendering interactive maps across Android, iOS, Desktop, and Web platforms.

### Project Structure

- **`lib/`**: Core library modules
  - `maplibre-compose`: Main map composables and core functionality
  - `maplibre-compose-material3`: Material 3 themed UI components
  - `maplibre-compose-gms`: Google location services components
  - `maplibre-js-bindings`: Kotlin/JS bindings for MapLibre GL JS
    - This wraps the TypeScript library whose original types are available at
      build/js/node_modules/maplibre-gl/dist/maplibre-gl.d.ts
  - `maplibre-native-bindings`: Kotlin/JVM bindings for MapLibre Native
  - `maplibre-native-bindings-jni`: C++ library required by
    `maplibre-native-bindings`
    - This wraps the C++ library vendored at
      lib/maplibre-native-bindings-jni/vendor/maplibre-native
- **`demo-app/`**: Multiplatform demo application
- **`iosApp/`**: iOS-specific demo app wrapper
- **`buildSrc/`**: Custom Gradle build conventions

### Key Packages

- `org.maplibre.compose.map`: Core map composable and components
- `org.maplibre.compose.camera`: Camera controls and positioning
- `org.maplibre.compose.layers`: Layer composables for map visualization
- `org.maplibre.compose.sources`: Data source composables
- `org.maplibre.compose.expressions`: DSL for MapLibre expressions
- `org.maplibre.compose.offline`: Offline map data management
- `org.maplibre.compose.location`: Location engine

### Platform Implementation

The library uses platform-specific implementations:

- **Android/iOS**: MapLibre Native SDKs (MapLibre Android SDK, MapLibre iOS)
- **Web**: MapLibre GL JS via `maplibre-js-bindings`
- **Desktop**: MapLibre Native Core via `maplibre-native-bindings`

### Build Configuration

- Kotlin version: Check `gradle/libs.versions.toml`
- Android SDK: min 23, compile/target 35
- iOS deployment target: 12.0
- JVM toolchain: 21, target: 11