# CLAUDE.md

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

## Project Overview

`rust_api` is a Flutter FFI plugin using **flutter_rust_bridge v2.12.0** to call Rust functions from Dart. The Rust
library is compiled as both `cdylib` (dynamic) and `staticlib`, and bundled into Flutter apps on all platforms
(Android, iOS, macOS, Linux, Windows) via the `ffiPlugin: true` flag in `pubspec.yaml`.

## Build System

Platform builds are orchestrated by **cargokit** (`cargokit/`), a third-party build harness that invokes Cargo and
integrates with each platform's build system (Gradle for Android, CocoaPods for Apple, CMake for Linux/Windows).

Rust compilation happens automatically as part of the host Flutter app's build — there's no standalone build step for
this plugin.

## Code Generation

All Dart-Rust bindings are generated by `flutter_rust_bridge_codegen`. The mapping is configured in
`flutter_rust_bridge.yaml`:

```yaml
rust_input: crate::api        # Rust source: rust/src/api/
rust_root: rust/
dart_output: lib/src/rust     # Generated Dart output
```

**To regenerate bindings** after changing Rust code:

```bash
flutter_rust_bridge_codegen generate
```

The generated files are `lib/src/rust/frb_generated.dart`, `lib/src/rust/frb_generated.io.dart`,
`lib/src/rust/frb_generated.web.dart`, `lib/src/rust/api/<module>.dart` (one per Rust source module),
and `rust/src/frb_generated.rs`. These should not be edited by hand.

## Architecture

```
Rust source                Generated Dart            Public Dart API
─────────────────────      ─────────────────────     ─────────────────
rust/src/api/              lib/src/rust/api/          lib/rust_api.dart
  mod.rs ──► init.rs         (init has no Dart file)
  named_pipe.rs              named_pipe.dart
                           lib/src/rust/
                             frb_generated.dart      (re-exports RustLib)
                             frb_generated.io.dart   (FFI for native)
                             frb_generated.web.dart  (stub for web)
```

- **Rust side** (`rust/src/api/`): Functions annotated with `#[flutter_rust_bridge::frb]` attributes. The `mod.rs`
  declares API modules.
- **Generated Dart** (`lib/src/rust/`): Auto-generated top-level functions that delegate through `RustLib.instance.api`.
- **Public API** (`lib/rust_api.dart`): Re-exports generated functions and `RustLib` for initialization.
- **`RustLib`** is the singleton entrypoint. Call `RustLib.init()` before calling any API functions, and
  `RustLib.dispose()` on teardown.

## Adding a New Rust Function

1. Add a public function in `rust/src/api/` (in an existing module or a new one)
2. If a new module, add `pub mod <name>;` to `rust/src/api/mod.rs`
3. Run `flutter_rust_bridge_codegen generate`
4. Export the new generated Dart file from `lib/rust_api.dart` if a new module was added