CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7`rust_api` is a Flutter FFI plugin using **flutter_rust_bridge v2.12.0** to call Rust functions from Dart. The Rust
8library is compiled as both `cdylib` (dynamic) and `staticlib`, and bundled into Flutter apps on all platforms
9(Android, iOS, macOS, Linux, Windows) via the `ffiPlugin: true` flag in `pubspec.yaml`.
10 
11## Build System
12 
13Platform builds are orchestrated by **cargokit** (`cargokit/`), a third-party build harness that invokes Cargo and
14integrates with each platform's build system (Gradle for Android, CocoaPods for Apple, CMake for Linux/Windows).
15 
16Rust compilation happens automatically as part of the host Flutter app's build — there's no standalone build step for
17this plugin.
18 
19## Code Generation
20 
21All Dart-Rust bindings are generated by `flutter_rust_bridge_codegen`. The mapping is configured in
22`flutter_rust_bridge.yaml`:
23 
24```yaml
25rust_input: crate::api        # Rust source: rust/src/api/
26rust_root: rust/
27dart_output: lib/src/rust     # Generated Dart output
28```
29 
30**To regenerate bindings** after changing Rust code:
31 
32```bash
33flutter_rust_bridge_codegen generate
34```
35 
36The generated files are `lib/src/rust/frb_generated.dart`, `lib/src/rust/frb_generated.io.dart`,
37`lib/src/rust/frb_generated.web.dart`, `lib/src/rust/api/<module>.dart` (one per Rust source module),
38and `rust/src/frb_generated.rs`. These should not be edited by hand.
39 
40## Architecture
41 
42```
43Rust source                Generated Dart            Public Dart API
44─────────────────────      ─────────────────────     ─────────────────
45rust/src/api/              lib/src/rust/api/          lib/rust_api.dart
46  mod.rs ──► init.rs         (init has no Dart file)
47  named_pipe.rs              named_pipe.dart
48                           lib/src/rust/
49                             frb_generated.dart      (re-exports RustLib)
50                             frb_generated.io.dart   (FFI for native)
51                             frb_generated.web.dart  (stub for web)
52```
53 
54- **Rust side** (`rust/src/api/`): Functions annotated with `#[flutter_rust_bridge::frb]` attributes. The `mod.rs`
55  declares API modules.
56- **Generated Dart** (`lib/src/rust/`): Auto-generated top-level functions that delegate through `RustLib.instance.api`.
57- **Public API** (`lib/rust_api.dart`): Re-exports generated functions and `RustLib` for initialization.
58- **`RustLib`** is the singleton entrypoint. Call `RustLib.init()` before calling any API functions, and
59  `RustLib.dispose()` on teardown.
60 
61## Adding a New Rust Function
62 
631. Add a public function in `rust/src/api/` (in an existing module or a new one)
642. If a new module, add `pub mod <name>;` to `rust/src/api/mod.rs`
653. Run `flutter_rust_bridge_codegen generate`
664. Export the new generated Dart file from `lib/rust_api.dart` if a new module was added