Graft 🌱 #

Graft is a self-optimizing state management engine for Flutter: combining BLoC-style domain models, Signals-level micro-rebuild precision, and register-level CPU bitmask diffing — with strictly zero code generation.

Note

🚀 Graft v0.1.2-alpha.5 — Public Alpha Release #

Graft is currently in active public alpha across iOS, Android, Web (JS & WASM), macOS, Windows, Linux, and Embedded targets. We invite developers to take it for a spin, test its slot diffing and route-scoping capabilities across diverse architectures, and help us discover edge cases, ideas, and feedback on GitHub Issues as we march toward 1.0!

📦 Installation & Linter Setup #

1. Add Dependencies #

Add graft along with the official analyzer plugin, graft_lint:

flutter pub add graft
flutter pub add dev:custom_lint dev:graft_lint

2. Configure `analysis_options.yaml` #

Activate the plugin in your root analysis_options.yaml. To display 🔴 red error squiggles in your IDE whenever propsOf(...) is forgotten or slots are illegally nested, configure the rules under errors:

analyzer:
  plugins:
    - custom_lint
  errors:
    avoid_nested_graft_slot: error       # 🔴 Flags illegal nested slot builders
    prefer_props_in_graft_state: error   # 🔴 Flags GraftState missing propsOf(...)
    require_graft_route_observer: error  # 🔴 Flags MaterialApp missing route observer

Tip

If squiggles do not appear immediately in your IDE after saving analysis_options.yaml:

VS Code: Press Cmd + Shift + P (or Ctrl + Shift + P) and select Dart: Restart Analysis Server.
Android Studio: In the bottom Dart Analysis window, click the Restart Dart Analysis Server icon.

3. Verify in Terminal / CI #

dart run custom_lint --fatal-warnings

🛠️ Quick Start #

1. Define State & Controller #

Extend GraftState and declare domain properties in props using propsOf(...). No copyWith or code-gen needed:

class UserState extends GraftState {
  String name = 'Alice';
  String email = 'alice@example.com';
  int points = 0;

  @override
  GraftProps get props => propsOf(name, email, points);

  @override
  void onReset() {
    name = 'Alice';
    email = 'alice@example.com';
    points = 0;
  }
}

class UserGraft extends Graft<UserState> {
  UserGraft() : super(UserState());

  // Option A: Fluent cascade mutation
  void updateName(String newName) {
    state
      ..name = newName
      ..update(); // Synchronous 1-cycle bitmask diff & surgical UI dispatch
  }

  // Option B: Functional lambda mutation
  void addPoints(int amount) {
    mutate((s) => s.points += amount);
  }

  void reset() {
    state.reset(); // Restores initial baseline values via onReset() synchronously
  }
}

2. The Core Innovations: `slot`, `slots`, `builder`, & `GraftBoundary` #

Graft eliminates wasteful Flutter subtree rebuilds using 4 dedicated UI primitives:

A. Single-Child Leaf Slot (`graft.slot` or callable `graft(...)`)

Isolates individual dynamic widgets with Depth-$N$ parent rebuild insulation. Outer containers (Card, Padding, AppBar) experience 0 rebuilds:

// The Card, Padding, and outer layout NEVER rebuild!
Card(
  child: Padding(
    padding: const EdgeInsets.all(16),
    child: graft((s) => Text('Points: ${s.points}')), // 🔄 Rebuilds ONLY when points change
  ),
)

B. Multi-Child Layout Diff Engine (`graft.slots(...)`)

Universal layout diffing (Column, Row, Wrap, Stack, Flex). Each child becomes an independent diff slot. Unchanged slots, const widgets, and conditional branches evaluate with 0 rebuilds:

graft.slots(
  layout: Column(crossAxisAlignment: CrossAxisAlignment.start, children: slots),
  slots: (s) => [
    ProfileHeader(), // 0 rebuilds (even though it is not const)
    Text('Name: ${s.name}'), // 0 rebuilds when name is unchanged
    Text('Email: ${s.email}'), // 0 rebuilds when email is unchanged
    if (s.points > 100) const VipBadge(), // Dynamic branch
  ],
)

C. Virtualized Lazy Lists (`graft.builder(...)`)

100% lazy collections (ListView.builder, GridView.builder) with per-item slot isolation. Modifying one item triggers 1 rebuild only for that item, while all other items experience 0 rebuilds:

// Zero-plumbing: automatically creates an optimized ListView.builder
graft.builder<TaskItem>(
  items: (s) => s.tasks,
  itemBuilder: (task, index) => ListTile(
    title: Text(task.title),
    trailing: Checkbox(
      value: task.isDone,
      onChanged: (_) => graft.toggleTask(index),
    ),
  ),
)

D. Multi-Graft Rebuild Firewall (`GraftBoundary`)

An Element-level rebuild barrier with Ambient Auto-Discovery and Backward Adaptive Learning.

When placed inside heavy layout containers or inside graft.slots(...), it auto-discovers and listens to multiple controllers simultaneously, completely preventing expensive parent containers and sibling slots from rebuilding:

dashboardGraft.slots(
  layout: Column(children: slots),
  slots: (s) => [
    const HeaderBanner(), // 0 rebuilds (const pointer match)
    Text('Section: ${s.title}'), // Slot 1: Diffed by dashboardGraft

    // 🛡️ Heavy layout container wrapping a multi-controller GraftBoundary:
    // Parent container and sibling slots do NOT rebuild when inner boundary states update.
    HeavyContainer(
      child: GraftBoundary(
        builder: (context) {
          // Ambiently discovers and listens to userGraft & themeGraft:
          return Row(
            children: [
              Text(userGraft.state.name),
              const SizedBox(width: 8),
              Text(themeGraft.state.accentColor),
            ],
          );
        },
      ),
    ),

    const FooterBanner(), // 0 rebuilds (const pointer match)
  ],
)

🔍 Rebuild Breakdown: Why `GraftBoundary` Inside Slots is Essential

Without GraftBoundary, updating userGraft or themeGraft inside a complex slot would force the surrounding container or parent layout to rebuild. With GraftBoundary:

State Mutation Event	`HeavyContainer` (Above Boundary)	Sibling Slots (`s.title`, Header, Footer)	Inside `GraftBoundary` (`Row`)
`userGraft.state..name = 'Bob'..update()`	0 Rebuilds (Insulated)	0 Rebuilds (Diff engine bypass)	🔄 1 Rebuild
`themeGraft.state..accentColor = 'red'..update()`	0 Rebuilds (Insulated)	0 Rebuilds (Diff engine bypass)	🔄 1 Rebuild
`dashboardGraft.state..title = 'Reports'..update()`	0 Rebuilds (`GraftEquivalent`)	🔄 1 Rebuild (`s.title` slot only)	0 Rebuilds
`userGraft.state..email = 'new'..update()` (Unused)	0 Rebuilds	0 Rebuilds	0 Rebuilds (Adaptive bypass)

3. Route-Stack Lifecycle & Zero-Setup Injection (`context.use`) #

Attach GraftRouteTracker.observer to your MaterialApp in main.dart, and borrow controllers on-demand anywhere in your widget tree:

void main() {
  Graft.observer = GraftDevObserver(logRebuilds: true); // Colorized terminal logs
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorObservers: [GraftRouteTracker.observer], // or GraftRouteObserver()
      home: const UserScreen(),
    );
  }
}

class UserScreen extends StatelessWidget {
  const UserScreen({super.key});

  @override
  Widget build(BuildContext context) {
    // Resolves or inherits UserGraft across the route stack with zero boilerplate:
    final graft = context.use(UserGraft.new);

    return Scaffold(
      appBar: AppBar(
        title: graft((s) => Text(s.name)), // Surgical leaf title
      ),
      body: graft.slots(
        layout: Column(children: slots),
        slots: (s) => [
          const ProfileHeader(),
          Text('Email: ${s.email}'),
          Text('Points: ${s.points}'),
          ElevatedButton(
            onPressed: () => graft.addPoints(10),
            child: const Text('Add 10 Points'),
          ),
        ],
      ),
    );
  }
}

🏛️ The 6 Core Pillars (Philosophy) #

State management in Flutter has historically forced developers to choose between two extremes:

Architectural Cleanliness with Rebuild Overhead: Clean domain classes (BLoC/Provider) that rebuild entire widget subtrees unless wrapped in dozens of verbose BlocSelector or Selector widgets.
Rebuild Precision with Domain Fragmentation: Fine-grained reactivity (Signals/GetX/MobX) that shatters cohesive domain models into fragmented primitive wrappers (signal(), .obs, .value, rx), cluttering business logic and polluting UI code.

Graft rejects this compromise through 6 foundational pillars:

Zero-Wrapper Domain State: State models are pure Dart classes extending GraftState. No Signal<T>, no .obs, no .value, and strictly zero code generation (build_runner is never required).
Mandatory props & Recursive Snapshot Contract: Domain properties are declared via GraftProps get props => propsOf(...), an abstract compiler-enforced contract. Graft uses recursive deep snapshotting for nested GraftState sub-states and collections, eliminating forgotten fields and ensuring 100% snapshot integrity during in-place cascade mutations.
Unbounded Hardware-Aligned GraftMask: State field modifications are mapped into an unbounded, 32-bit chunked word-based bitset (GraftMask). It diffs ≤ 64 fields in CPU registers and effortlessly scales to 128, 500, or 1,000+ fields with 100% web JS compatibility and 0 GC heap allocations.
Synchronous In-Place Cascade Mutation & In-Place Reset: Direct synchronous updates via state..field = val..update() and complete baseline resets via state.reset(). Primitives, nested models, and collection items are accurately diffed without requiring immutable copyWith methods.
Two-Wrapper Architecture & Context Decoupling:
- GraftBoundary: Subtree-level rebuild barrier featuring Ambient Auto-Discovery (zero manual lists via GraftScopeTracker) and Backward Adaptive Learning with multi-field bitwise union accumulation.
- graft((s) => ...): Fine-grained surgical leaf slot with Depth-$N$ parent rebuild insulation, powered by NoSubscriptionContext to prevent Theme/MediaQuery subscription bleeding during widget diffing.
- graft.slots(...): Universal multi-child layout slot diffing with self-optimizing ignoredMask pre-flight bypass.
Automatic Route-Aware Lifecycle & PopupRoute Protection: Controllers automatically inherit down predecessor routes and cleanly self-dispose when their owning screen route pops. Transient routes (showDialog, showModalBottomSheet) borrow safely without prematurely disposing host controllers via resolveOwnerRoute.

🏆 Late-2026 Flutter State Management Benchmark Scorecard #

Empirically verified across 15+ measured runs per scenario against Riverpod, flutter_bloc / Cubit, Signals, GetX, and Provider on both Native IO and Web.

📊 For the complete statistical breakdown (Mean, Median, p95, Min, Max, StdDev, Rebuilds), see BENCHMARK_REPORT.md.

Benchmark Scenario	Metric	Native IO Winner	Native IO Graft (Rank & Gap)	Web Browser Winner	Web Browser Graft (Rank & Gap)
A1: 10,000 Synchronous Increments	Latency (ms)	🥇 Graft (0.10 ms)	—	🥇 Provider (0.62 ms)	🥉 1.21 ms (#3, +0.59ms)
A2: 100,000 Micro-State Mutations	Latency (ms)	🥇 Graft (0.66 ms)	—	🥇 Provider (4.77 ms)	🥉 13.10 ms (#3, +8.33ms)
A3: 5-Field Atomic Batch Mutation	Latency (ms)	🥇 Graft (0.12 ms)	—	🥇 Provider (0.72 ms)	4th · 3.69 ms (#4, +2.97ms)
A4: Depth-8 Nested Sub-State Mutation	Latency (ms)	🥇 Graft (0.01 ms)	—	🥇 Provider (0.11 ms)	🥈 0.13 ms (#2, +0.02ms)
B1: 10-Slot Column Layout (120 Frames)	Render (ms)	🥇 Provider (16.06 ms)	🥈 23.36 ms (#2, +7.30ms)	🥇 Riverpod (76.37 ms)	4th · 78.29 ms (#4, +1.92ms)
B2: 50-Slot Heavy Layout (120 Frames)	Render (ms)	🥇 Riverpod (24.74 ms)	🥈 24.83 ms (#2, +0.09ms)	🥇 Graft (168.55 ms)	—
C1: 5,000 Item List (300 Rapid Updates)	Throughput (ms)	🥇 Graft (28.99 ms)	—	🥇 Graft (136.11 ms)	—
C2: 20,000 Item List (300 Rapid Updates)	Throughput (ms)	🥇 Graft (31.02 ms)	—	🥇 Graft (136.29 ms)	—
C3: Random Item Insert / Delete (100x)	Latency (ms)	🥇 Graft (0.30 ms)	—	🥇 Graft (0.07 ms)	—
D1: Product Catalog & Shopping Cart	Latency (ms)	🥇 Graft (0.02 ms)	—	🥇 Graft (0.03 ms)	—
D2: Form (12 Interdependent Fields)	Latency (ms)	🥇 Graft (0.06 ms)	—	🥇 BLoC (0.06 ms)	🥈 0.07 ms (#2, +0.01ms)
D3: Navigation & Dialog State Sharing	Latency (ms)	🥇 Graft (2.54 ms)	—	🥇 Graft (8.17 ms)	—
E1: Route Stack Push / Pop Lifecycle	Latency (ms)	🥇 Graft (6.05 ms)	—	🥇 Graft (17.28 ms)	—
E2: Hot Reload Reassemble Simulation	Latency (ms)	🥇 Graft (0.92 ms)	—	🥇 Graft (3.35 ms)	—
E3: Disposed Controller Access Safety	Safety (ms)	🥇 Graft (0.00 ms)	—	🥇 Graft (0.00 ms)	—

📚 Complete Public API Reference #

Graft exposes a focused, cohesive API surface designed to remain orthogonal to Flutter's native layout engine.

A. Reactive Slots & Rebuild Boundaries (The Core Innovations) #

Extension methods on Graft<S> and isolated boundary widgets that eliminate unnecessary Flutter renders:

1. `graft((s) => Widget)` (Callable Shortcut) & `graft.slot(...)`

The signature entry point for fine-grained leaf reactions. Provides Depth-$N$ parent rebuild insulation:

// The outer Card and Padding NEVER rebuild:
Card(
  child: Padding(
    padding: const EdgeInsets.all(16),
    child: graft((s) => Text('Balance: \$${s.balance}')),
  ),
)

Or use explicit named syntax:

AppBar(
  title: graft.slot(
    builder: (s) => Text(s.title),
  ),
)

2. `graft.slots({required layout, required slots})`

The universal multi-child slot diffing engine. Evaluates child widgets against learned fieldDependenciesMask and ignoredMask, bypassing unchanged slots with 0 element rebuilds:

graft.slots(
  layout: Column(children: slots),
  slots: (s) => [
    const HeaderBanner(), // 0 rebuilds (const pointer match)
    Text('Name: ${s.name}'), // 0 rebuilds when name is unchanged
    Text('Email: ${s.email}'), // 0 rebuilds when email is unchanged
    if (s.isVerified) const VerifiedBadge(),
  ],
)

3. `GraftBoundary({required builder, key})`

An Element-level rebuild firewall that isolates multi-controller subscriptions.

Ambient Auto-Discovery: Automatically discovers and subscribes to any Graft controller whose .state is read within builder—no manual listener registration required.
Backward Adaptive Learning: Traps state mutations within the boundary. When inner controllers update, outer containers, parent widgets, and sibling slots experience 0 rebuilds.
Zero Subscription Bleed: Evaluates through NoSubscriptionContext to prevent ambient Theme or MediaQuery subscriptions from leaking into parent layouts.

// Isolates multiple controllers inside any subtree without parent rebuilds:
GraftBoundary(
  builder: (context) {
    // Ambiently discovers and listens to userGraft & themeGraft:
    return Row(
      children: [
        Text(userGraft.state.name),
        const SizedBox(width: 8),
        Icon(Icons.circle, color: themeGraft.state.accentColor),
      ],
    );
  },
)

4. `graft.compute<R>({required compute, required builder, key})`

Pre-flight derived selector computation. Checks the computed value before executing builder:

graft.compute<int>(
  compute: (s) => s.unreadMessages.length,
  builder: (unreadCount) => Badge(
    label: Text('$unreadCount'),
    child: const Icon(Icons.mail),
  ),
)

5. `graft.builder<T>({required items, required itemBuilder, layout, key})`

Virtualized lazy collections with per-item slot isolation (ListView.builder, GridView.builder):

graft.builder<TaskItem>(
  items: (s) => s.tasks,
  itemBuilder: (task, index) => TaskListTile(task: task),
)

6. `graft.async<T>({required selector, required data, required loading, required error, idle, key})`

Declarative, pattern-matched reactive slot for asynchronous domain states:

graft.async<UserProfile>(
  selector: (s) => s.profileState,
  data: (profile) => ProfileCard(profile),
  loading: () => const ShimmerCard(),
  error: (err, st) => ErrorBanner(error: err),
  idle: () => const PlaceholderCard(),
)

7. `GraftScope`

Provides localized subtree scoping for nested navigation hierarchies (GoRouter StatefulShellRoute, bottom tabs, or modal sheets):

GraftScope(
  builder: (context) => const NestedTabNavigator(),
)

8. `GraftEquivalent`

Interface allowing custom widgets to declare fine-grained content equivalence without triggering @nonVirtual operator warnings:

class UserAvatar extends StatelessWidget implements GraftEquivalent {
  final String url;
  const UserAvatar(this.url);

  @override
  bool isEquivalentTo(Widget other) => other is UserAvatar && other.url == url;

  @override
  Widget build(BuildContext context) => Image.network(url);
}

B. Domain State & Business Logic Controllers #

1. `GraftState`

The base class for domain models. Enables direct cascade mutations without immutable copyWith methods:

class CartState extends GraftState {
  final List<String> items = [];
  double discount = 0.0;

  @override
  GraftProps get props => propsOf(items, discount);

  @override
  void onReset() {
    items.clear();
    discount = 0.0;
  }
}

GraftProps get props: Mandatory abstract contract declaring properties for diffing via propsOf(...) or propsOfMany(...).
state.update(): Computes dirty bitmask against in-place baseline snapshot and triggers UI notification.
state.reset(): Calls onReset() and flushes baseline changes synchronously with 0 GC allocations.
GraftMask get dirtyMask: Read-only bitmask from the last diff evaluation.

2. `Graft<S extends GraftState>`

The business logic controller managing domain state of type S:

class CartGraft extends Graft<CartState> {
  CartGraft() : super(CartState());

  void addItem(String item) {
    state
      ..items.add(item)
      ..update();
  }

  Future<void> checkout() async {
    await runAsync<OrderConfirmation>(
      task: () => api.checkout(state.items),
      onUpdate: (asyncState) => state..confirmation = asyncState..update(),
    );
  }
}

S get state: The current state snapshot. Automatically records dependency inside GraftBoundary.
ValueListenable<S> get listenable: Direct interop with standard Flutter ValueListenableBuilder.
Future<T?> runAsync<T>({required task, required onUpdate}): Executes an asynchronous task with an internal monotonically increasing task token guard that automatically discards out-of-order stale responses.
void addError(Object error, [StackTrace? stackTrace]): Dispatches unhandled errors to GraftObserver.
void reset(): Resets state and flushes baseline synchronously.
void dispose(): Releases listeners and notifies global observer.

3. `ValueGraft<T>`

Specialized lightweight controller for single primitive or enum values without writing a state class:

class CounterGraft extends ValueGraft<int> {
  CounterGraft() : super(0);

  void increment() => value++;
  void decrement() => value--;
}

class ThemeGraft extends ValueGraft<ThemeMode> {
  ThemeGraft() : super(ThemeMode.system);

  void toggleDark() => value = ThemeMode.dark;
}

T get value / set value(T newValue): Direct read/write property. Mutating triggers slot updates.

4. `GraftAsync<T>`

Sealed algebraic data type representing asynchronous lifecycles:

// Sealed constructors:
const GraftAsync<User>.idle()
const GraftAsync<User>.loading()
const GraftAsync<User>.data(User user)
const GraftAsync<User>.error(Object error, [StackTrace? stackTrace])

// Pattern-matching with .when():
asyncValue.when(
  idle: () => const Text('Press to load'),
  loading: () => const CircularProgressIndicator(),
  data: (user) => Text('Hello, ${user.name}'),
  error: (err, st) => Text('Error: $err'),
);

Properties: isIdle, isLoading, hasData, hasError, dataOrNull, errorOrNull.

C. Route-Stack Dependency Injection (`BuildContext` Extensions) #

1. `context.use<T extends Graft>([factory])`

Resolves an active controller across the navigation stack, or creates one if not found:

Route Stack Sharing: If an ancestor route in the navigation stack created T, this screen borrows the existing instance.
Automatic Route Disposal: The first screen that calls context.use<T>() becomes the Owner. When that screen pops from the Navigator, T is automatically disposed.
Transient PopupRoute Protection: When opening dialogs (showDialog) or bottom sheets (showModalBottomSheet), Graft anchors ownership to the underlying PageRoute. Closing the popup will never prematurely dispose the controller.

class EditProfileScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Borrows existing ProfileGraft from HomeScreen in the route stack:
    final graft = context.use(ProfileGraft.new);
    return Scaffold(...);
  }
}

2. `context.create<T extends Graft>([factory])`

Force-creates a brand-new, isolated instance owned exclusively by the current screen:

// Isolated wizard or temporary comparison form:
final isolatedGraft = context.create(CheckoutGraft.new);

3. `GraftRegistry`

Central factory registry configured at application startup:

void main() {
  // 1. Route-scoped: created lazily, disposed when owner route pops:
  GraftRegistry.register(UserGraft.new);
  GraftRegistry.register(CartGraft.new);

  // 2. Global Singleton: persistent app-wide, survives route pops:
  GraftRegistry.registerSingleton(AuthGraft.new);

  // 3. Fallback to external service locator (GetIt, Kiwi, etc.):
  GraftRegistry.fallbackLocator = <T extends Object>() => GetIt.I<T>();

  runApp(const MyApp());
}

D. Observability & DevTools #

1. `GraftObserver` & `GraftDevObserver`

Global hook for monitoring lifecycle, state transitions, slot rebuilds, errors, and Flutter DevTools Timeline profiling:

void main() {
  // Colorized terminal logging + Flutter DevTools Timeline profiling:
  Graft.observer = GraftDevObserver(
    logRebuilds: true,    // Formats slot rebuild events in ANSI terminal output
    enableTimeline: true, // 👈 Emits timeline events directly into Flutter DevTools Performance trace!
  );
  runApp(const MyApp());
}

// Or implement custom analytics/error reporting:
class ProductionObserver extends GraftObserver {
  @override
  void onError(dynamic graft, Object error, StackTrace stackTrace) {
    FirebaseCrashlytics.instance.recordError(error, stackTrace);
  }
}

Zero Release Overhead: GraftDevObserver automatically disables console output and timeline emission in production release mode (kReleaseMode).
DevTools Performance Trace: When enableTimeline: true, every controller transition (Graft: MyGraft.update()) and slot rebuild (Graft: Slot #$index rebuild) appears as a named slice in Flutter DevTools.

E. Declarative Unit Testing (`graft/testing.dart`) #

1. `graftTest`

Pure Dart declarative state testing modeled after blocTest:

import 'package:flutter_test/flutter_test.dart';
import 'package:graft/graft.dart';
import 'package:graft/testing.dart';

void main() {
  group('UserGraft', () {
    graftTest<UserGraft, UserState>(
      'updates profile name and notifies listeners',
      build: () => UserGraft(),
      act: (graft) => graft.updateName('Alice'),
      expect: () => [
        isA<UserState>().having((s) => s.name, 'name', 'Alice'),
      ],
      verify: (graft) {
        expect(graft.state.name, 'Alice');
      },
    );
  });
}

🏗️ High-Performance Architecture #

Graft achieves sub-microsecond diffing and zero wasted rebuilds by decoupling state evaluation from Flutter's widget tree lifecycle.

1. Hardware-Aligned Bitmask Diff Pipeline #

┌────────────────────────────────────────────────────────────────────────┐
│                      DEVELOPER CALL (ZERO BOILERPLATE)                 │
│         state..address.city = 'Berlin'..tasks.add(item)..update()      │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                          GRAFT CORE ENGINE                             │
│                  diffChanges(): Evaluate props against _baseline       │
│                                   │                                    │
│         ┌─────────────────────────┼────────────────────────┐           │
│         ▼                         ▼                        ▼           │
│  [ Primitive Values ]   [ Nested Sub-States ]     [ Collections ]      │
│  (int, String, bool)    (GraftState in props)    (List, Set, Map)      │
│  1-Cycle Identity:      Deep Recursive Props     Recursive Elements    │
│  identical(prev, curr)  Snapshot Comparison      Snapshot Equality     │
│         │                         │                        │           │
│         └─────────────────────────┼────────────────────────┘           │
│                                   ▼                                    │
│            Compute 64-bit Integer dirtyMask in CPU registers           │
│                                   │                                    │
│                                   ▼                                    │
│                       notifyMask(dirtyMask)                            │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│              SELF-HEALING SLOT RECONCILIATION PIPELINE                 │
│                 GraftMultiChildDiffEngine / GraftBoundary              │
│                                   │                                    │
│            Does dirtyMask intersect slot's learnedDependencies?        │
│                    ┌──────────────┴──────────────┐                     │
│                   YES                            NO                    │
│                    │                             │                     │
│           [⚡ 1-CPU Fast Path]         [🔬 2-ns Fingerprint Check]     │
│           Immediate leaf rebuild       Evaluate slot hash              │
│           notifier.value = newWidget;            │                     │
│                                      ┌───────────┴───────────┐         │
│                                     MATCH                DIFFERENT     │
│                                      │                       │         │
│                                 [0 Rebuild]       [💥 SELF-HEAL MASK]  │
│                                 Bypassed clean    • Leaf rebuild!      │
│                                                   • learned |= dirty   │
└────────────────────────────────────────────────────────────────────────┘

2. Route-Stack Lifecycle & PopupRoute Protection #

Graft's dependency injection coordinates with Flutter's Navigator stack to eliminate manual service locators and memory leaks:

┌────────────────────────────────────────────────────────────┐
│                    Route A (HomeScreen)                    │
│             Calls: context.use(ProfileGraft.new)           │
│             👑 Becomes OWNER of ProfileGraft               │
└─────────────────────────────┬──────────────────────────────┘
                              │ Navigator.push()
                              ▼
┌────────────────────────────────────────────────────────────┐
│                 Route B (EditProfileScreen)                │
│             Calls: context.use(ProfileGraft.new)           │
│             🤝 BORROWS existing ProfileGraft               │
└─────────────────────────────┬──────────────────────────────┘
                              │ showDialog() / ModalBottomSheet
                              ▼
┌────────────────────────────────────────────────────────────┐
│           Transient PopupRoute (ConfirmDialog)             │
│             🛡️ Protected: Anchored to Route B              │
│      Closing dialog does NOT dispose ProfileGraft!         │
└────────────────────────────────────────────────────────────┘
                              │ Route A popped
                              ▼
┌────────────────────────────────────────────────────────────┐
│             ProfileGraft.dispose() Automatically           │
│               0 Memory Leaks • 0 Manual Hooks              │
└────────────────────────────────────────────────────────────┘

Route Stack Borrowing: Downstream screens automatically share existing controllers from predecessor routes without needing prop drilling or complex inherited widgets.
Owner-Controlled Disposal: The screen that initializes a controller owns its lifecycle. When that route pops, Graft disposes the controller automatically.
Transient Popup Protection: Dialogs, alerts, and modal bottom sheets anchor to their parent PageRoute. Popping a dialog never prematurely kills the host controller.

3. Core Engine Mechanics #

1-Cycle Bitmask Evaluation: Up to 64 state fields are tracked in 64-bit integer bitmasks, evaluated directly in CPU registers via single bitwise AND operations (dirtyMask & slotMask != 0). For models with more than 64 fields, GraftMask seamlessly scales into chunked 32-bit integer words with 100% web JavaScript compatibility.
Depth-$N$ Parent Rebuild Insulation: graft((s) => ...) leaf slots are executed inside an internal NoSubscriptionContext, preventing ambient Theme or MediaQuery subscriptions from leaking into intermediate layout parents.
Zero GC Pressure on Mutations: Synchronous in-place cascade updates (state..name = 'Alice'..update()) reuse existing domain objects. No new wrapper objects or transient copy instances are allocated during state transitions.
Pre-Flight Slot Short-Circuiting: graft.slots(...) tracks ignoredMask alongside learned dependencies. If a state mutation only modifies fields that no child slot listens to, the diff engine bypasses the entire layout build phase in 0 element rebuilds.

🧪 Test Verification & Quality Assurance #

Graft is verified against 211 passing tests with zero static analysis warnings:

flutter test
# 00:50 +211: All tests passed!

dart analyze
# No issues found!

Domain	Test Suite Files	Verification Scope
State & Collections	`test/graft_state_test.dart` `test/nested_substate_mutation_test.dart` `test/collection_mutation_test.dart` `test/graft_mask_test.dart` `test/large_state_bitmask_test.dart`	In-place baseline mutations (`List`, `Set`, `Map`), nested `GraftState` mutation diffing, 64-bit bitmasks, unbounded mask growth, and reset.
Rebuild Firewall & Diff Engine	`test/adaptive_slot_preflight_test.dart` `test/context_isolation_leak_test.dart` `test/deterministic_slot_bitmask_test.dart` `test/bitmask_preflight_test.dart` `test/safe_ast_context_test.dart` `test/depth_n_isolation_test.dart` `test/slot_engine_test.dart` `test/disordering_test.dart`	`ignoredMask` pre-flight short-circuiting, `NoSubscriptionContext` leak prevention, Depth-$N$ parent rebuild insulation, and disordered slot resolution.
Auto-Discovery & Tickers	`test/graft_boundary_test.dart` `test/multi_graft_combinator_test.dart` `test/animation_isolation_test.dart`	Multi-controller ambient auto-discovery, backward adaptive learning, and 60fps/120fps continuous animation ticker containment.
Routing & Lifecycle	`test/dialog_popup_lifecycle_test.dart` `test/graft_route_test.dart` `test/graft_route_extended_test.dart` `test/nested_route_isolation_test.dart` `test/lifecycle_test.dart`	`context.use<T>()` route-stack borrowing, transient `PopupRoute` dialog protection, parallel navigator isolation, and auto-disposal on route pop.
Async Concurrency & Slots	`test/async_concurrency_race_test.dart` `test/coalescing_test.dart` `test/graft_async_widget_test.dart`	Monotonic task token guard (`_currentAsyncTaskId`), stale response dropping, and declarative `graft.async` slots.
Stress & Scalability	`test/benchmark/*` (10 test files)	Glitch-free reactive diamond DAG propagation, deep computed chain evaluation, multi-field batching, and high-frequency frame stress testing.

📄 License #

MIT License. Free to use, modify, and distribute.

graft 0.1.2-alpha.5 graft: ^0.1.2-alpha.5 copied to clipboard

Metadata

Graft 🌱 #

🚀 Graft v0.1.2-alpha.5 — Public Alpha Release #

📑 Table of Contents #

📦 Installation & Linter Setup #

1. Add Dependencies #

2. Configure analysis_options.yaml #

3. Verify in Terminal / CI #

🛠️ Quick Start #

1. Define State & Controller #

2. The Core Innovations: slot, slots, builder, & GraftBoundary #

A. Single-Child Leaf Slot (graft.slot or callable graft(...))

B. Multi-Child Layout Diff Engine (graft.slots(...))

C. Virtualized Lazy Lists (graft.builder(...))

D. Multi-Graft Rebuild Firewall (GraftBoundary)

🔍 Rebuild Breakdown: Why GraftBoundary Inside Slots is Essential

3. Route-Stack Lifecycle & Zero-Setup Injection (context.use) #

🏛️ The 6 Core Pillars (Philosophy) #

🏆 Late-2026 Flutter State Management Benchmark Scorecard #

📚 Complete Public API Reference #

A. Reactive Slots & Rebuild Boundaries (The Core Innovations) #

1. graft((s) => Widget) (Callable Shortcut) & graft.slot(...)

2. graft.slots({required layout, required slots})

3. GraftBoundary({required builder, key})

4. graft.compute<R>({required compute, required builder, key})

5. graft.builder<T>({required items, required itemBuilder, layout, key})

6. graft.async<T>({required selector, required data, required loading, required error, idle, key})

7. GraftScope

8. GraftEquivalent

B. Domain State & Business Logic Controllers #

1. GraftState

2. Graft<S extends GraftState>

3. ValueGraft<T>

4. GraftAsync<T>

C. Route-Stack Dependency Injection (BuildContext Extensions) #

1. context.use<T extends Graft>([factory])

2. context.create<T extends Graft>([factory])

3. GraftRegistry