hooks library

Optional flutter_hooks integration for cell_flutter.

Status: Experimental, paired with cell_flutter 0.6.0 (hardening — see the cell_flutter library docs and README.md Status for what is and is not claimed).

This library is the Hooks Layer of the binding: a set of use* functions that express the same reactive contracts as the widget counterparts (CellBuilder, CellSelector, CellAsyncBuilder, CellListener) but compose with flutter_hooks primitives. It is opt-in — application code that does not use HookWidget should import package:cell_flutter/cell_flutter.dart instead.

Import this library from any widget that extends HookWidget (or uses HookBuilder):

import 'package:cell_flutter/hooks.dart';

Rules inherited from flutter_hooks

Every hook in this library must be called:

  1. Unconditionally — not inside an if, loop, or short-circuit.
  2. At the top of HookWidget.build (before any early return that precedes another hook).
  3. In the same order on every build.

Violations trigger flutter_hooks' own assertion. The contract is not relaxed here — the hooks are thin wrappers around flutter_hooks primitives and inherit its lifecycle model verbatim.

Requirements

flutter_hooks must be in your pubspec.yaml. It is a regular dependency of cell_flutter, so it resolves automatically; pinning its version explicitly is recommended for stability, since this library is coupled to flutter_hooks' hook API.

Inherited caveats (please read)

useCellAsync inherits the per-source error-pulse behavior and the concurrent-asyncMap caveat documented in CellAsyncBuilder. In short: only Cell.fromFuture emits error pulses today; fromStream and asyncMap do not. A useCellAsync over an asyncMap source with concurrency > 0 inherits the concurrent-effect-attribution caveat. The hooks' own observation is correct; the caveats concern the source's replay fidelity and the per-source error surface.

What this library exports

  • useCell — the selector hook (equivalent of CellSelector).
  • useCellValue — the full-value shortcut for useCell.
  • useCellNotifier — the CellNotifier hook for composing with flutter_hooks primitives or ValueListenableBuilder.
  • useCellListener — the side-effect hook (equivalent of CellListener).
  • useCellAsync — the async-snapshot hook (equivalent of CellAsyncBuilder).

It also re-exports cell_flutter and flutter_hooks, so a single import suffices in a HookWidget.

See Also:

  • cell_flutter — the widget-layer binding this library builds on.
  • flutter_hooks — the hook primitives and rules this library obeys.
  • CellBuilder, CellSelector, CellAsyncBuilder, CellListener — the widget equivalents each hook mirrors.

Classes

ApplyAccepted<R>
The command was authorized, safety-checked, and successfully executed.
ApplyCommandRunner
A helper class used to set up and execute an action on a cell.
ApplyLedger
The framework's internal Record Keeper and receipt generator.
ApplyOutcome<R>
The official, auditable result of submitting an ApplyCommand.
ApplyRejected<R>
The command was denied by the framework's safety rules (the Integrity Gate).
ApplyStaged
The command was accepted and placed into a transaction to be run later.
ApplyTransactionScope
Handle for a staged command transaction — the mechanism behind Cell.txApply.
ApplyVeto
A special signal used by a function to cancel its own operation.
Async<C>
A foundational marker interface and architectural contract representing an Asynchronous Proxy or Controller for a core component C.
AsyncPriorityQueue<E>
AsyncQueueList<E>
AsyncSynapses<P extends Pulse, L extends Cell>
An Asynchronous Projection of a Synapses instance for non‑blocking signal distribution.
Box<T>
A specialized, lightweight container used to provide a mutable state anchor within the framework's immutable Record architecture.
Cell
A reactive node: holds state (or relays signals), validates every incoming change against a policy, and broadcasts accepted changes to whatever else is listening.
CellAsyncBuilder<V>
A widget that renders the asynchronous state of any Cell as an AsyncSnapshot<V>.
CellBase
The foundational abstract implementation of the Cell interface.
CellBuilder<V>
A widget that rebuilds its builder whenever cell's value changes.
CellEditingController
A TextEditingController bound two-way to a ValueCell<String>.
CellErrorBoundary
Renders a fallback instead of Flutter's error screen when a cell-driven error is thrown while building the subtree below it.
CellErrorBoundaryState
The state behind CellErrorBoundary.
CellFlutterDevTools
The in-app Cell Inspector.
CellFormField<T>
A FormField whose value is bound two-way to a ValueCell<T>.
CellGraph
A registered cell graph: the unit of identity and replay in the framework.
CellGraphBuilder
The entry point for constructing a CellGraph.
CellGraphRegistry
Public read-only access to the cell id registry.
CellGraphSnapshot
A serialisable snapshot of an entire cell graph.
CellInspectorOverlay
A floating in-app Cell Inspector panel.
CellListener<V>
A widget that invokes onPulse for every pulse emitted by cell, without rebuilding its subtree.
CellListView<T>
A virtualized list whose item collection is bound to a Cell.
CellNotifier<V>
Adapts a ValueCell to Flutter's ValueNotifier contract as a read-only bridge.
CellPulseRecord
One recorded pulse, display-formatted.
CellRegistry
The live registry behind CellFlutterDevTools.
CellRegistryEntry
One registered cell and its journal.
CellRestorationScope
Provides a RestorationBucket to descendant RestorableCells and registers them automatically with Flutter's restoration protocol.
CellRestorationScopeState
The stateful, mixin-bearing half of CellRestorationScope.
CellScope
An InheritedWidget that provides a small set of app-level cells to the subtree below it, addressed by Symbol.
CellSelector<V, S>
A widget that rebuilds its builder only when a selected slice of cell's value changes.
CellSnapshot
A serialisable projection of one cell's identity and current value.
CellTextField
A TextFormField whose value is bound two-way to a ValueCell<String>.
CellValueBuilder<V>
A widget that rebuilds its builder whenever any Cell emits a new value.
ClockEffect
A read of the system clock. Records the epoch millis.
CollectivePulse<P>
A Collective Pulse — a flat bundle of independent pulses travelling together as a single atomic wave.
CollectivePulseBase<P>
The abstract base class for CollectivePulse implementations.
CompensationFailure
Describes a single failed compensation attempt.
Context
Metadata describing a Cell's tier, domain, and operational boundaries — used by TestCell rules to make context-aware decisions.
ContextBase
The foundational implementation of the Operational Environment, providing the core logic for Prototype-based Inheritance and Ontological Resolution.
ContextTranslator
Bridges a DeputyContext across mandate schema versions.
ContextTranslatorRegistry
A simple registry of translators keyed by (from, to).
CycleChecker
A specialized Traversal Guard and Topology Validator, responsible for preventing infinite recursion and ensuring the reactive graph remains a Directed Acyclic Graph (DAG) during signal propagation.
DefaultValue
DefaultValue is a metadata annotation primarily used by the code generation framework (such as build_model) to define a fallback or initial value for fields in a model class.
DeputyContext
Represents the Formal Mandate and declaration of intention for a Deputy.
DivergenceReport
A single point at which a replay diverged from its recording.
EffectJournal
The boundary between a receptor and the outside world.
EffectRecord
A single recorded non-deterministic observation.
EmailPattern
EmailPattern is a specialized EntryPattern metadata annotation designed to validate whether a string conforms to a standard email address format.
EntryPattern
EntryPattern is a specialized TestRule metadata annotation that validates whether a string input matches a specific Regular Expression (RegExp).
EphemeralPolicy<C extends Cell>
Defines the Lifecycle Governance for transient reactive nodes.
EvolvedPulse<P>
An immutable signal derived from a previous pulse through a transformation step — a causal link in the signal's journey.
EvolvedPulseBase<P>
The abstract base class for EvolvedPulse implementations.
FilterRule<P extends Pulse>
A filter that can transform, redact, or suppress a Pulse before it is broadcast to downstream observers.
FinalBox<T>
A specialized, write-once container providing a thread-safe, immutable anchor for state that is initialized after construction.
ForkHandle
A forked history.
ForkLedgerStore
A LedgerStore wrapper that injects a synthetic ForkRecord entry at seq 0.
ForkRecord
The genesis record of a fork ledger.
FunctionObject
Simple wrapper for functions or records containing function information. Used to pass function metadata through the system.
FunctionTypeObject<T>
Lazy-evaluated version of TypeObject that executes a function to get the value. Useful for deferred initialization or expensive object creation.
Governance<V>
The foundational Authority Protocol for defining structural and behavioral guardrails within the framework's Mandate ontology.
GovernanceEntry<G extends Governance<V>, V>
A strongly-typed key-value pair that represents a single dimension of governance within the framework's Scene-Driven Ontology.
HashChain
The rolling hash chain that binds ledger entries.
Hook<R>
Hook is similar to a StatelessWidget, but is not associated to an Element.
HookBuilder
A HookWidget that delegates its build to a callback.
HookState<R, T extends Hook<R>>
The logic and internal state for a HookWidget
HookWidget
A Widget that can use a Hook.
Identity
A utility for materializing unique identities within the somatic graph.
Inheritable
InMemoryLedgerStore
An in-memory LedgerStore, suitable for tests and for ephemeral graphs whose ledger does not need to survive the process.
Instruction<C extends Cell, I extends Pulse, O extends Pulse>
A discrete logic unit that defines how a Receptor reacts to a Pulse.
InstructionBase<C extends Cell, I extends Pulse, O extends Pulse>
The foundational implementation and architectural base for all Instruction variants.
InstructionChain<C extends Cell, I extends Pulse, O extends Pulse>
A composite Instruction that orchestrates a sequence of processing units.
IoEffect
A single I/O call (network, disk, database). Records the label, the request digest, and the response digest; the raw response is held only if the caller supplied rawOutput. For replay, rawOutput is required — the digest alone cannot reconstruct the response.
JournalScope
The task-local stack of active journals.
Ledger
The durable, hash-chained record of every state transition.
LedgerEntry
A single, immutable row in the ledger.
LedgerScope
The graph-scoped ambient that coordinates state capture and ledger append.
LedgerScopeImpl
The per-graph implementation of the scope.
LedgerStore
The persistence backend for a Ledger.
Lock
A mutual-exclusion lock: serializes access to a shared resource across asynchronous code, similar to Java's synchronized.
MaxLength
MaxLength is a specialized TestRule metadata annotation used primarily by the code generation framework (such as build_model) to enforce structural and data-integrity constraints on model fields.
Modifiable
A specialized architectural marker and base interface for objects that support controlled mutation through the framework's dynamic command pattern.
ModifiableAsync<C extends Cell>
Provides asynchronous execution of operations on a Cell.
MultiLock
A Lock that atomically acquires several other locks together.
Nucleolus
A specialized, terminal implementation of the Nucleus contract representing the framework's "zero-state" and Ontological Root.
Nucleus
The immutable blueprint underlying every Cell — its receptor, testRule, context, synapses, and lifecycle policy, stored separately from the live cell instance.
NucleusBase
The foundational base implementation of the Nucleus contract, providing a memory-optimized storage engine for reactive cell properties.
NullJournal
The "no journal in scope" sentinel. Every effectful operation fails loudly.
ObjectRef<T>
A class that stores a single value.
OpenCell
A specialized, interactive Cell that serves as a Reactive Bridge for external stimulus injection and dynamic topology management.
OpenCellAsync
Represents the Asynchronous Governance Interface for an OpenCell.
PolicyReplay
Policy-tick journaling for EphemeralPolicy.
PolicyTickEffect
A single tick of an EphemeralPolicy.
PriorityQueue<E>
A collection of elements that maintains a Deterministic Priority Order, serving as a specialized Ranked Execution Buffer for the reactive fabric.
PropagationPolicy
A declarative blueprint defining the Temporal Dynamics and Operational Governance of pulse propagation.
Pulse<P>
A reactive signal — the fundamental unit of communication in the framework.
PulseBase<P>
The foundational blueprint for all nervous signals within the reactive graph.
PulseCodec
Canonical serialiser for Pulse.
PulseContext
Represents the Causal Identity and ontological Provenance of a Pulse.
PulseContextCodec
Serialises and deserialises PulseContext, preserving the full parent chain.
PulseEphemeralPolicy
A governance policy that defines the Lifecycle Constraints and Termination Logic for a Pulse as it traverses the reactive graph.
PulseReconstructor
Reconstructs the input Pulse that produced a LedgerEntry.
PulseShell<P, R extends Receptor<Cell>>
A specialized Shell providing a Perceptual Projection of a Pulse to facilitate pre-execution validation and security gating.
QueueList<E>
Receptor<C extends Cell>
The transformation pipeline that decides how a Cell responds to an incoming Pulse.
ReceptorAsync<C extends Cell>
An asynchronous execution handle for a Receptor that facilitates non‑blocking pulse processing and lifecycle synchronization.
ReceptorBase<C extends Cell>
The foundational base implementation of Receptor that provides the core synchronization and pulse propagation engine.
RecordingJournal
The recording side of the journal.
RegisteredCell
A thin wrapper that pairs a Cell with its graph-scoped name.
ReplayEngine
The replay engine.
ReplayJournal
The replay side of the journal.
ReplayOptions
Strictness flags that control the replay engine's behaviour when the replayed state diverges from the recorded state.
ReplayResult
The result of a ReplayEngine.replay call.
RestorableCell<V>
A ValueCell whose value participates in Flutter's state restoration.
RestorableCellDelegate<V>
The internal RestorableProperty that bridges a RestorableCell to Flutter's restoration protocol.
Shell<T>
A specialized Defensive Perimeter and Projection Layer representing a formal contract for Bidirectional Mutual Authorization.
StateDelta
A single cell's state change within a ledger entry.
StatefulHookWidget
A StatefulWidget that can use a Hook.
Store<StateT, ActionT>
A store of mutable state that allows mutations by dispatching actions.
StreamEffect
A stream event. Records the event's stream label, the digest of the value, and optionally the raw value.
Synapses<P extends Pulse, L extends Cell>
The distribution fabric for a Cell's outgoing signals—defining how, when, and to whom a pulse is delivered.
SynapsesBase<P extends Pulse, C extends Cell>
The foundational base implementation for Synapses, serving as the Transmission Engine of the cell.core reactive framework.
SyncBox<T>
A synchronized variant of Box providing Thread-Safe Access and facilitating Atomic State Transitions across concurrent execution boundaries.
SyncCycleChecker
A thread-safe, Synchronized Circular Dependency Guard for asynchronous reactive flows.
SyncQueue<E>
A thread-safe implementation of a PriorityQueue, providing Synchronized Access for prioritized collection-based state.
SyncSet<E>
A thread-safe implementation of a Set, providing Synchronized Access for collection-based state.
SynthesisCell
Represents a Synthesis Cell—a specialized structural node that aggregates signals from multiple source cells into a single unified stream.
TestActionRule<C extends Cell>
A specialized behavioral guard for validating imperative logic and functional action execution within the reactive graph.
TestCell<C extends Cell>
The central validation gate for a Cell – it decides what's allowed.
TestCellReplay
Purity-aware invocation of a TestCell.
TestLinkRule<C extends Cell>
A specialized behavioral guard for validating Topological Synapses and graph formation within the reactive framework.
TestPasses
A sentinel implementation of TestCell that always authorises every operation.
TestPulseRule<C extends Cell>
A rule that validates incoming Pulse signals before they reach a cell.
TestRule<C>
A fundamental architectural component representing an Integrity Gate or Validation Guard, responsible for enforcing structural and business invariants across the reactive graph.
TimerEffect
A timer firing. Records the scheduled duration and the actual fire time; the pair is what makes debounce/throttle replayable.
TransactionBegun
Emitted when a transaction begins.
TransactionCommitted
Emitted when a transaction commits successfully.
TransactionEvent
Base class for all transaction lifecycle events.
TransactionOptions
Configuration options for a Cell.transaction.
TransactionRolledBack
Emitted when a transaction is rolled back.
TransactionTimedOut
Emitted when a transaction times out.
TransactionUpdated
Emitted when a cell is updated during a transaction.
TxApplyBegun
Emitted once, immediately after ApplyTransactionScope.begin succeeds.
TxApplyCommitted
Emitted after a successful ApplyTransactionScope.commit.
TxApplyCompensationFailed
Emitted each time a compensation attempt fails.
TxApplyCompensationRetry
Emitted before each retry of a compensation function.
TxApplyEvent
Base class for all lifecycle events emitted by an ApplyTransactionScope.
TxApplyOptions
Configuration for Cell.txApply.
TxApplyRejected
Emitted when a staged command is refused.
TxApplyRolledBack
Emitted after a rollback (full or savepoint-scoped).
TxApplyStaged
Emitted once per successful ApplyTransactionScope.enqueueCommand.
TypeObject<T>
Wrapper class for holding typed objects. Provides type safety when working with generic containers.
Unmodifiable
A specialized Marker Interface and architectural anchor used to identify reactive nodes and data structures that have been restricted to Read-Only access.
UnmodifiableCollectivePulse<P>
UnmodifiableEvolvedPulse<P>
UnmodifiablePulse<P>
A read‑only projection of a pulse that enforces structural finality.
UnmodifiablePulseBase<P>
UnmodifiableValueCell<V>
A specialized read‑only proxy of a ValueCell that enforces immutability.
UuidEffect
A UUID generation. Records the generated UUID.
ValidationFailure
Represents a validation failure for a specific cell.
ValueCell<V>
A state‑bearing reactive node – the primary way to manage persistent state in the Cell Framework.
ValueCellAsync<V>
A specialized asynchronous controller for ValueCell, providing a thread‑safe and non‑blocking interface for state interaction.
ValueNucleus<V>
A specialized Nucleus blueprint designed to manage and propagate a discrete, persistent state value of type V.
ValueRange
ValueRange is a specialized TestRule metadata annotation designed to validate whether a numeric input falls within a specific inclusive boundary.
Values
Values is a specialized TestRule that validates whether a given input is present within a predefined collection of allowed values.
VerdictEffect
The decision reached by an effectful TestCell.
VersionRegistry
Maps (cellId, version) to the receptor and test rule that implemented that version.
WebsiteUrlPattern
WebsiteUrlPattern is a specialized EntryPattern metadata annotation designed to validate whether a string conforms to a standard web URL format.

Enums

AuditLevel
Defines the Observability Granularity and XAI Verbosity required for a Deputy's operations.
Clearance
Defines the Sovereign Physical Laws and structural boundaries of reactive operations within the framework.
CompensationErrorPolicy
Determines how the transaction scope behaves when a compensation attempt fails.
ForkPolicy
How a fork handles the parent graph's state.
HubRouting
Defines how a Cell.hub decides which spoke (child cell) should receive an incoming signal.
Isolation
Defines the Architectural Boundary & State Visibility of a Deputy.
IsolationLevel
Defines the consistency and visibility guarantees for a transaction.
LineageArgument
Defines the specific data field to be extracted when traversing a Pulse's Causal History via the lineage method.
LockOrdering
Defines the order in which locks are acquired during commit.
Mandate<V>
Defines the Capability Profile and Authorization Scope for a Deputy.
Ontology<V>
Defines the Structural Taxonomy, Static Identity, and Architectural Shape of a Cell.
PriorityTier
Defines the Semantic Urgency Tiers for signal execution.
PropagationStrategy
Defines the tactical execution models for Pulse Propagation within the Cell framework's reactive graph.
Provenance<V>
Defines the Causal Accountability, Audit Trail, and Operational Intent of a Pulse.
Purity
Classifies a Receptor or TestCell by its effect footprint.
ReasoningStrategy
Defines the Logical Pedigree and algorithmic origin of a Pulse.
Sensitivity
Defines the Information Classification and data-privacy tier of a Pulse.
Sovereignty
Defines the Commitment Authority and Escalation Protocol assigned to a Deputy.

Mixins

Deputy<C extends Cell>
The mixin implementing proxy behavior for Cell.deputy — you don't use this directly.
Effectful
The declarative marker for effectful receptors and rules.
EffectfulReadOnly
A variant of Effectful for receptors that read the outside world but do not mutate it (clocks, environment variables, read-only database lookups). Reports Purity.readOnlyExternal.
GovernanceMixin<G extends Governance<V>, V>
A convenient mixin that provides default implementations for the Governance interface methods.
HookElement
An Element that uses a HookWidget as its configuration.
InstructionChainMixin<C extends Cell, I extends Pulse, O extends Pulse>
A mixin that provides the core execution engine for composite instructions.
OpenReceptorMixin
A mixin that implements the Manual Control Interface for the reactive network.
OpenSynapsesMixin
A mixin that implements the Reactive Topology Interface for OpenCell architectures.

Extensions

ApplyCommandDSL on Cell
A "fluent" shortcut that makes it easier to create and run commands on a cell.
CellAsStream on Cell
Bridges a Cell to a Dart Stream<V?>.
CellAsValue on Cell
An extension that mirrors any Cell into a fresh ValueCell.
CellGraphFork on CellGraph
Forking extensions for CellGraph.
CellGraphTranslators on CellGraph
The graph-scoped translator registry.
CellGraphVersions on CellGraph
The graph-scoped version registry (see VersionRegistry).
CellGraphVisualise on CellGraph
Visualisation for CellGraph and Ledger.
CellRestoration on Cell
Static factory access for RestorableCell.
ForkParentLookup on Ledger
The parent ledger's hash at a given sequence.
ForkVerify on ForkHandle
Fork-aware verification. A fork's verify requires the parent ledger's verify() to pass.
LedgerVisualise on Ledger
Visualisation for a Ledger's entries (also used by the CLI).
PulseExtension on Pulse<P>
Provides a fluent, functional API for operating on individual Pulse instances.
PulseIterableExtension on Iterable<Pulse>
Fluent extensions for collections of Pulse objects.
PulseJson on Pulse<P>
Encodes this pulse to its canonical JSON wire form via encodePulse.
ReplayEngineFork on ReplayEngine
Fork-aware replay: replays a parent ledger into a fork handle, applying a Mutation to each entry.
TekartikLockExtension on Lock
Extension on Lock providing synchronous execution when possible, for synchronous computations that don't need to always go through a Future.
ValueCellBuilder on ValueCell<V>
Fluent constructor for a CellBuilder over a ValueCell.

Constants

pulseNullPayload → const Object
Explicitly override payload to null in Pulse.fromJson.
pulseNullPolicy → const Object
Explicitly override policy to null in Pulse.fromJson.
pulseNullSource → const Object
Explicitly override source to null in Pulse.fromJson.
pulseNullStep → const Object
Explicitly override step to null in Pulse.fromJson.
pulseNullType → const Object
Explicitly override type to null in Pulse.fromJson.
useTextEditingController → const _TextEditingControllerHookCreator
Creates a TextEditingController, either via an initial text or an initial TextEditingValue.

Properties

debugHotReloadHooksEnabled ↔ bool
Whether to behave like in release mode or allow hot-reload for hooks.
getter/setter pair

Functions

canonicalJsonDecode(String source) → Object?
Decodes a canonical JSON string into a JSON-encodable object tree.
canonicalJsonEncode(Object? value, {bool omitNulls = false}) → String
Encodes value into deterministic, canonical JSON.
cellEditingController(ValueCell<String> cell) → CellEditingController
Creates a CellEditingController bound to cell.
decodePulse(Map<String, dynamic> json, {Cell? resolver(String id)?, bool lenient = false, void onSkipped(List<String> skipped)?}) → PulseBase
Decodes a pulse from the canonical JSON produced by encodePulse.
encodePulse(PulseBase pulse, {bool lenient = false}) → Map<String, dynamic>
Encodes pulse to its canonical JSON wire form.
fingerprint(Object? value) → String
Computes the SHA-256 fingerprint of value's canonical JSON form, hex-encoded.
get<T>(Function fn, {Function? fallback, T? orElse}) → T
A robust functional utility for safely executing operations of type T with multi-stage recovery logic and hierarchical fallbacks.
mapMerge<K, V>(Map<String, dynamic> map, Map<String, dynamic> other) → Map<String, dynamic>
restorableState<V>({required String restorationId, V? initial, V? fromPrimitives(Object? data)?, Object? toPrimitives(V? value)?}) → RestorableCell<V>
The unqualified alias for CellRestoration.restorableState.
snapshotForCell<V>(Cell cell) → AsyncSnapshot<V>?
Returns the AsyncSnapshot the widget should show for cell's currently retained pulse, or null when nothing usable is retained.
snapshotForPulse<V>(Pulse<Object?> pulse) → AsyncSnapshot<V>
Projects a single Pulse into an AsyncSnapshot for a CellAsyncBuilder.
use<R>(Hook<R> hook) → R
Registers a Hook and returns its value.
useAnimation<T>(Animation<T> animation) → T
Subscribes to an Animation and returns its value.
useAnimationController({Duration? duration, Duration? reverseDuration, String? debugLabel, double initialValue = 0, double lowerBound = 0, double upperBound = 1, TickerProvider? vsync, AnimationBehavior animationBehavior = AnimationBehavior.normal, List<Object?>? keys}) → AnimationController
Creates an AnimationController and automatically disposes it when necessary.
useAppLifecycleState() → AppLifecycleState?
Returns the current AppLifecycleState value and rebuilds the widget when it changes.
useAutomaticKeepAlive({bool wantKeepAlive = true}) → void
Mark a widget using this hook as needing to stay alive even when it's in a lazy list that would otherwise remove it.
useCallback<T extends Function>(T callback, [List<Object?> keys = const <Object>[]]) → T
Cache a function across rebuilds based on a list of keys.
useCarouselController({int initialItem = 0, List<Object?>? keys}) → CarouselController
Creates a CarouselController that will be disposed automatically.
useCell<V, S>({required ValueCell<V> cell, required S select(V? value), bool equals(S previous, S next)?}) → S
Reads the slice of cell produced by select, rebuilding only when that slice changes.
useCellAsync<V>(Cell cell, {AsyncSnapshot<V>? initialSnapshot}) → AsyncSnapshot<V>
Returns the async state of cell as an AsyncSnapshot, updating on every pulse.
useCellListener<V>({required Cell cell, required void onPulse(BuildContext context, Pulse<V> pulse)}) → void
Invokes onPulse for every pulse emitted by cell, without rebuilding the widget.
useCellNotifier<V>(ValueCell<V> cell) → CellNotifier<V>
Returns a CellNotifier bound to cell, disposed on unmount.
useCellValue<V>(ValueCell<V> cell) → V?
A convenience wrapper for "rebuild on every value change".
useContext() → BuildContext
Obtains the BuildContext of the building HookWidget.
useCupertinoTabController({int initialIndex = 0, List<Object?>? keys}) → CupertinoTabController
Creates a CupertinoTabController that will be disposed automatically.
useDebounced<T>(T toDebounce, Duration timeout) → T?
Returns a debounced version of the provided value toDebounce, triggering widget updates accordingly after a specified timeout duration.
useDraggableScrollableController({List<Object?>? keys}) → DraggableScrollableController
Creates a DraggableScrollableController that will be disposed automatically.
useEffect(Dispose? effect(), [List<Object?>? keys]) → void
Useful for side-effects and optionally canceling them.
useExpansibleController({List<Object?>? keys}) → ExpansibleController
Creates a ExpansibleController that will be disposed automatically.
useExpansionTileController({List<Object?>? keys}) → ExpansionTileController
Creates a ExpansionTileController that will be disposed automatically.
useFixedExtentScrollController({int initialItem = 0, ScrollControllerCallback? onAttach, ScrollControllerCallback? onDetach, List<Object?>? keys}) → FixedExtentScrollController
Creates FixedExtentScrollController that will be disposed automatically.
useFocusNode({String? debugLabel, FocusOnKeyEventCallback? onKeyEvent, bool skipTraversal = false, bool canRequestFocus = true, bool descendantsAreFocusable = true, bool descendantsAreTraversable = true}) → FocusNode
Creates an automatically disposed FocusNode.
useFocusScopeNode({String? debugLabel, FocusOnKeyEventCallback? onKeyEvent, bool skipTraversal = false, bool canRequestFocus = true}) → FocusScopeNode
Creates an automatically disposed FocusScopeNode.
useFuture<T>(Future<T>? future, {T? initialData, bool preserveState = true}) → AsyncSnapshot<T>
Subscribes to a Future and returns its current state as an AsyncSnapshot.
useIsMounted() → IsMounted
Returns an IsMounted object that you can use to check if the State is mounted.
useListenable<T extends Listenable?>(T listenable) → T
Subscribes to a Listenable and marks the widget as needing build whenever the listener is called.
useListenableSelector<R>(Listenable? listenable, R selector()) → R
Rebuild only when there is a change in the selector result.
useMemoized<T>(T valueBuilder(), [List<Object?> keys = const <Object>[]]) → T
Caches the instance of a complex object.
useOnAppLifecycleStateChange(LifecycleCallback? onStateChanged) → void
Listens to the AppLifecycleState.
useOnListenableChange(Listenable? listenable, VoidCallback listener) → void
Adds a given listener to a Listenable and removes it when the hook is disposed.
useOnPlatformBrightnessChange(BrightnessCallback onBrightnessChange) → void
Listens to the platform Brightness.
useOnStreamChange<T>(Stream<T>? stream, {void onData(T event)?, void onError(Object error, StackTrace stackTrace)?, void onDone()?, bool? cancelOnError}) → StreamSubscription<T>?
Subscribes to a Stream and calls the Stream.listen to register the onData, onError, and onDone.
useOverlayPortalController({List<Object?>? keys}) → OverlayPortalController
Creates a OverlayPortalController that will be disposed automatically.
usePageController({int initialPage = 0, bool keepPage = true, double viewportFraction = 1.0, ScrollControllerCallback? onAttach, ScrollControllerCallback? onDetach, List<Object?>? keys}) → PageController
Creates a PageController that will be disposed automatically.
usePlatformBrightness() → Brightness
Returns the current platform Brightness value and rebuilds the widget when it changes.
usePrevious<T>(T val) → T?
Returns the previous value passed to usePrevious (from the previous widget build).
useReassemble(VoidCallback callback) → void
Runs the callback on every hot reload, similar to reassemble in the stateful widgets.
useReducer<StateT, ActionT>(Reducer<StateT, ActionT> reducer, {required StateT initialState, required ActionT initialAction}) → Store<StateT, ActionT>
An alternative to useState for more complex states.
useRef<T>(T initialValue) → ObjectRef<T>
Creates an object that contains a single mutable property.
useScrollController({double initialScrollOffset = 0.0, bool keepScrollOffset = true, String? debugLabel, ScrollControllerCallback? onAttach, ScrollControllerCallback? onDetach, List<Object?>? keys}) → ScrollController
Creates ScrollController that will be disposed automatically.
useSearchController({List<Object?>? keys}) → SearchController
Creates a SearchController that will be disposed automatically.
useSingleTickerProvider({List<Object?>? keys}) → TickerProvider
Creates a single usage TickerProvider.
useSnapshotController({bool allowSnapshotting = false}) → SnapshotController
Creates and disposes a SnapshotController.
useState<T>(T initialData) → ValueNotifier<T>
Creates a variable and subscribes to it.
useStream<T>(Stream<T>? stream, {T? initialData, bool preserveState = true}) → AsyncSnapshot<T>
Subscribes to a Stream and returns its current state as an AsyncSnapshot.
useStreamController<T>({bool sync = false, VoidCallback? onListen, VoidCallback? onCancel, List<Object?>? keys}) → StreamController<T>
Creates a StreamController which is automatically disposed when necessary.
useTabController({required int initialLength, Duration? animationDuration = kTabScrollDuration, TickerProvider? vsync, int initialIndex = 0, List<Object?>? keys}) → TabController
Creates a TabController that will be disposed automatically.
useTransformationController({Matrix4? initialValue, List<Object?>? keys}) → TransformationController
Creates and disposes a TransformationController.
useTreeSliverController() → TreeSliverController
Creates a TreeSliverController that will be disposed automatically.
useValueChanged<T, R>(T value, R? valueChange(T oldValue, R? oldResult)) → R?
Watches a value and triggers a callback whenever the value changed.
useValueListenable<T>(ValueListenable<T> valueListenable) → T
Subscribes to a ValueListenable and returns its value.
useValueNotifier<T>(T initialData, [List<Object?>? keys]) → ValueNotifier<T>
Creates a ValueNotifier that is automatically disposed.
useWidgetStatesController({Set<WidgetState>? values, List<Object?>? keys}) → WidgetStatesController
Creates a WidgetStatesController that will be disposed automatically.
withCellLocks<T>(Iterable<Cell> cells, Future<T> body(), {int order(Cell a, Cell b)?}) → Future<T>
Acquires the locks of cells in a deterministic total order.
withLocks<T>(Iterable<Lock?> locks, Future<T> body()) → Future<T>
Creates a cell that emits the values of a Dart Stream.

Typedefs

ApplyArguments = ({Map<Symbol, Object?>? namedArguments, List<Object?>? positionalArguments})
A structured container for function arguments that allows for auditing and reversals.
ApplyCommand = ({ApplyArguments arguments, ApplyCompensation? compensation, Function function})
A complete request to perform an action or change state within a cell.
ApplyCompensation = ({ApplyArguments arguments, Cell? cell, Function function})
A set of instructions used to undo or "roll back" a change if it fails.
ApplyReceipt = ({ApplyArguments arguments, Cell cell, String? contextVersion, Function function, String id, int? ledgerSeq, String? pulseDigest, String? receptorVersion, String? ruleVersion, DateTime timestamp, int? txSequence, bool vetted})
The permanent, official record of a specific action taken by a cell.
Arguments = ({Map<Symbol, dynamic>? namedArguments, List? positionalArguments})
Represents a tuple of positional and named arguments for function calls. Used when validating or processing function applications in cells.
BrightnessCallback = FutureOr<void> Function(Brightness previous, Brightness current)
A callback triggered when the platform brightness changes.
Dispose = void Function()
A function called when the state of a widget is destroyed.
EgressHandle<S extends Pulse> = ({Cell cell, void Function() start, void Function() stop})
A management handle for an Output Terminal, providing a controlled interface to manage an external side-effect listener.
FunctionType<R> = R Function()
Generic function type that takes no parameters and returns RNA. Used in FunctionTypeObject for lazy evaluation.
HubHandle = ({Pulse? Function(Pulse pulse) emit, Future<Pulse?> Function(Pulse pulse) emitAsync, Future<void> Function(Pulse pulse, {bool serializedCompletion}) ingest, Cell root, Iterable<Cell> spokes})
A management handle for a Signal Distribution Hub, providing a unified interface to control a multi-destination routing cluster.
IngressHandle<I> = ({Cell cell, bool Function(I input) emit, Future<bool> Function(I input) emitAsync, Future<void> Function(Pulse<I> pulse, {bool serializedCompletion}) ingest})
A management handle for an Input Gateway, providing a controlled interface for injecting external imperative stimuli into the reactive graph.
InheritableHandle = ({Cell? bind, Context context, EphemeralPolicy<Cell>? ephemeralPolicy, Receptor<Cell> receptor, TestCell<Cell> testRule})
A structured grouping of the Governance & Logic properties that define a node's operational identity and can be cascaded through the inheritance chain.
IsMounted = bool Function()
Used by useIsMounted to allow widgets to determine if the Widget is still in the widget tree or not.
LifecycleCallback = FutureOr<void> Function(AppLifecycleState? previous, AppLifecycleState current)
A callback triggered when the app life cycle changes.
MirroredCell<V> = ({ValueCell<V> cell, void Function() dispose})
The paired result of CellAsValue.asValueCell: a mirror cell and the callback that releases it.
Mutation = Pulse? Function(LedgerEntry entry, Pulse pulse)
A what-if mutation hook.
NucleusSimplest = Nucleolus
A semantic type alias representing the framework's Zero-Overhead Root and the terminal ancestor of all reactive blueprints.
OpenCellBase = _OpenCell
Base class for all OpenCell types.
PulseResolver = Cell? Function(String id)
Resolves a Cell.id to a live Cell.
Reducer<State, Action> = State Function(State state, Action action)
Composes an Action and a State to create a new State.
SpokeRegistration = ({DeputyContext? context, Pulse? Function(Cell cell, Pulse pulse, {dynamic user})? handler, String key, bool Function(String? type)? match, int priority, Receptor<Cell>? receptor})
A configuration record for an individual Spoke (Destination) within a Cell.hub.
StateHandle<V> = ({ValueCell<V> cell, Future<void> Function(Pulse<V> pulse, {bool serializedCompletion}) ingest, bool Function(V? value) update, Future<bool> Function(V? value) updateAsync})
A management record that bundles a ValueCell with its imperative update functions — the standard way to create and interact with a state atom.
SynthesisHandle = ({bool Function(Cell cell) add, void Function(Iterable<Cell> cells) addAll, SynthesisCell cell, bool Function() clear, bool Function() isEmpty, bool Function(Cell cell) remove, void Function(Iterable<Cell> cells) removeAll, void Function() start, void Function() stop, List<Cell> Function() toList})
An Administrative Record providing a control interface for dynamic SynthesisCell topographies.
TransactionScope = ({Future<void> Function(Iterable<Cell> cells) begin, Future<void> Function() commit, dynamic Function(Cell cell) pending, dynamic Function(Cell cell) read, Future<void> Function({Object? savepoint}) rollback, Object Function() savepoint, void Function(Cell cell, dynamic value) update})
A handle for coordinating atomic, multi‑cell transactions.

Exceptions / Errors

ForkIntegrityException
Thrown by ForkVerify.verify when a fork's parent ledger, fork ledger, or genesis binding is invalid.
LedgerIntegrityException
Thrown by Ledger.verify when an entry's hash, sequence, or predecessor chain does not match.
PulseDecodeError
A pulse JSON record cannot be decoded.
PulseNotSerializable
A pulse cannot be serialised because it carries a field that has no honest wire representation.
ReplayDivergenceException
Thrown when a replay diverges from the recording.
TransactionConflictException
Thrown when an isolation conflict is detected during commit.
TransactionTimeoutException
Thrown when a transaction exceeds its timeout duration.
TransactionValidationException
Thrown when validation of buffered writes fails during commit.
TxApplyCompensationException
Raised when one or more compensations fail under CompensationErrorPolicy.collectThenThrow or CompensationErrorPolicy.failFast.
TxApplyException
Raised for control-flow problems in a ApplyTransactionScope: wrong phase (e.g. commit before begin), non-modifiable function, non- participant cell, or a rejected command at commit time.