# flutter_rust_bridge Hello Spike

Chanora proof-of-concept. **Not product code.**

| Field | Value |
|---|---|
| PoC name | `flutter_rust_bridge_hello` (dir kept underscored for Dart-package naming) |
| PoC plan | [`docs/architecture/proof-of-concept-plan.md`](../../docs/architecture/proof-of-concept-plan.md) §2 |
| Purpose | Prove the command / result / event DTO boundary between Flutter and Rust |
| Exit criterion | "Flutter can call Rust and receive event stream data" |

> **Naming note.** The PoC plan lists this spike as
> `flutter-rust-bridge-hello`. Dart pubspec package names require
> underscores, so the on-disk directory is `flutter_rust_bridge_hello`.
> This is a naming convention, not a scope change.

## What it does

| API | Direction | Demonstrates |
|---|---|---|
| `greet(name)` | Dart → Rust → Dart (sync) | Typed `GreetResult` DTO + typed `GreetError` (Result-style fallible command) |
| `counterStream(count, intervalMs)` | Rust → Dart (async stream) | Typed `CounterTick` event stream with ordered delivery and clean close |

The `lib/main.dart` demo wires both into a Material 3 surface (button +
text field + live tick list). This UI is illustrative only — the
Chanora Design System belongs to the product Flutter app, not this PoC.

## Layout

```text
flutter_rust_bridge_hello/
  rust/                 # Rust crate (cdylib + staticlib)
    src/
      lib.rs            # crate root; declares api + frb_generated
      api/
        mod.rs
        simple.rs       # public API (greet, counter_stream, DTOs)
      frb_generated.rs  # autogenerated; do not edit
    Cargo.toml
  lib/
    main.dart           # demo UI
    src/rust/           # autogenerated Dart bindings; do not edit
  test/
    poc_verification_test.dart   # headless verification (flutter test)
  integration_test/
    simple_test.dart    # same checks, runs under integration_test driver
  flutter_rust_bridge.yaml
  pubspec.yaml
  linux/ android/ ios/ macos/ windows/ web/
  rust_builder/         # cargokit build hook (generated)
```

## Reproduce

Requires Flutter stable (developed against 3.41.9 / Dart 3.11.5),
`flutter_rust_bridge_codegen` 2.12.0, Rust stable (developed against 1.95).
Linux desktop toolchain (clang, cmake, ninja, GTK3) for the build path
proven here. Network access required for first build (cargo + pub).

```bash
# Generate bindings whenever rust/src/api/*.rs changes
flutter_rust_bridge_codegen generate

# Build for Linux desktop (also builds the cdylib via cargokit)
flutter build linux --debug

# Headless verification — exercises the same API the demo UI uses.
LD_LIBRARY_PATH="$PWD/build/linux/x64/debug/bundle/lib:$LD_LIBRARY_PATH" \
    flutter test test/poc_verification_test.dart

# Interactive run (requires a display)
flutter run -d linux
```

## Scope boundaries

- No TeamSpeak / `tsclientlib` integration (covered by
  `tsclientlib-connect-spike`).
- No platform secure storage, SQLite, or audio (separate PoCs).
- No real DTO catalogue, no error taxonomy, no event-key conventions —
  `chanora_bridge` will own those per SAD §7.2.
- Only the Linux desktop target has been built and verified. Android,
  iOS, macOS, Windows are scaffolded by `flutter create` but unverified
  here.

## Verification log

See `VERIFICATION.md` in this directory.