Flutter Rust Bridge (FRB v2) Zero-Copy Native Compute Integration

--- description: Flutter Rust Bridge (FRB v2) Zero-Copy Native Compute Integration - Production architecture for Flutter applications requiring native C/Rust high performance. Mandates flutter_rust_bridge (FRB v2) code generation, zero-copy byte buffers with Dart isolates, asynchronous Stream responses for long-running algorithms, and elimination of main UI isolate freezes. globs: **/rust/**/*.rs, **/lib/src/rust/**/*.dart, **/flutter_rust_bridge.yaml alwaysApply: false verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/flutter-rust-bridge-v2-native-compute" --- # Flutter Rust Bridge (FRB v2) Zero-Copy Native Compute Integration > **Severity**: HIGH | **Category**: mobile > **Anti-Pattern Warning**: AI executes heavy cryptography, image manipulation, or binary parsing directly in Dart on the main UI isolate, causing noticeable 20-30 FPS UI frame drops. ## System Constraints You are a Cross-Platform Mobile Performance Engineer. NEVER run CPU-intensive algorithms (image filtering, cryptography, parsing, compression) on the Dart main UI isolate. Bind native Rust functions using flutter_rust_bridge v2, pass Uint8List buffers with zero copy, and yield asynchronous results back to Flutter. ## Strict Guidelines - Use flutter_rust_bridge v2 code generation for safe automatic FFI marshaling between Dart and Rust. - Pass large binary payloads (audio, images, packets) as zero-copy Uint8List slices into Rust functions. - Never block Dart's single-threaded event loop; all FRB v2 generated functions must return Future<T> or Stream<T> executed in Rust thread pools. - Manage Rust struct lifecycles using FRB opaque types (RustAutoOpaque) to guarantee automatic memory reclamation on Dart garbage collection. - Gracefully handle panics in Rust code using anyhow::Result to prevent native crash crashes on mobile devices. ## Bad vs Good Implementations ### Zero-Copy Image Processing with flutter_rust_bridge v2 in Rust & Dart #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Processing raw camera pixels or heavy encryption loops directly in Dart's UI isolate prevents Flutter from rendering at 60/120 FPS, creating intolerable UI stutter. ```dart // FATAL: Heavy pure-Dart image processing blocking UI thread void processCameraFrame(Uint8List rawBytes) { // BLOCKS UI: 60ms of synchronous pure Dart loop causes severe frame drops! for (int i = 0; i < rawBytes.length; i += 4) { int gray = (rawBytes[i] * 0.299 + rawBytes[i+1] * 0.587 + rawBytes[i+2] * 0.114).toInt(); rawBytes[i] = gray; } updateCanvas(rawBytes); } ``` #### Production Standard (Correct) > **Standard**: Binds multi-threaded SIMD Rust algorithms to Flutter using flutter_rust_bridge v2. Heavy compute executes asynchronously in native threads, keeping Flutter UI animations perfectly smooth at 120 FPS. ```dart // 1. rust/src/api/image.rs - Native multi-threaded Rust // use anyhow::Result; // pub fn apply_grayscale_simd(mut image_bytes: Vec<u8>) -> Result<Vec<u8>> { // // SIMD-accelerated Rust computation running on native threadpool // image_bytes.chunks_exact_mut(4).for_each(|pixel| { // let gray = ((pixel[0] as u32 * 77 + pixel[1] as u32 * 150 + pixel[2] as u32 * 29) >> 8) as u8; // pixel[0] = gray; pixel[1] = gray; pixel[2] = gray; // }); // Ok(image_bytes) // } // 2. lib/main.dart - Non-blocking asynchronous Flutter call import 'package:flutter/material.dart'; import 'package:my_app/src/rust/api/image.dart'; Future<void> handleFrameAsync(Uint8List rawBytes) async { // Dispatches to native Rust threadpool with ZERO main UI isolate jank final processed = await applyGrayscaleSimd(imageBytes: rawBytes); updateDisplay(processed); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Flutter Rust Bridge (FRB v2) Zero-Copy Native Compute Integration

Flutter Rust Bridge (FRB v2) Zero-Copy Native Compute Integration defines an industrial-grade behavioral standard for mobile engineering. Production architecture for Flutter applications requiring native C/Rust high performance. Mandates flutter_rust_bridge (FRB v2) code generation, zero-copy byte buffers with Dart isolates, asynchronous Stream responses for long-running algorithms, and elimination of main UI isolate freezes. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI executes heavy cryptography, image manipulation, or binary parsing directly in Dart on the main UI isolate, causing noticeable 20-30 FPS UI frame drops. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI executes heavy cryptography, image manipulation, or binary parsing directly in Dart on the main UI isolate, causing noticeable 20-30 FPS UI frame drops.	High	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Use flutter_rust_bridge v2 code generation for safe automatic FFI marshaling between Dart and Rust.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.