Skip to content
PAM

State and lifecycle

PAM Native has a complete application-state model, not just mutable values attached to views. Components stay alive, reads are dependency-tracked, writes schedule retained renders, Rust computes minimal mutations, and Android/iOS commit them on the native frame boundary.

Choose the right owner

Section titled “Choose the right owner”
State Best owner Example
Temporary state for one component Local component state expanded card, input draft
Shared domain state Global store session, cart, settings
One subtree or flow provide() / inject() checkout or modal context
High-frequency platform interaction Native component cursor, scroll, animation
Restorable component instance Restorable editor draft, selected tab

This separation prevents a global store from becoming a dumping ground and keeps per-frame interaction away from PHP.

Local state

Section titled “Local state”
final class Counter extends Component
{
    protected function initialState(): array
    {
        return ['count' => 0];
    }


    public function increment(): void
    {
        $this->state->count++;
    }


    public function render(): Renderable
    {
        return Button::make((string) $this->state->count)
            ->onPress($this->increment(...));
    }
}

$this->state supports property reads/writes, all(), patch(), and shape-safe replace(). State accepts JSON-compatible values, ignores equal writes, and rejects undeclared keys.

Single-file components also support #[State] properties:

#[State]
public string $query = '';

Global state

Section titled “Global state”
final class AppStore extends Store
{
    protected function state(): array
    {
        return ['theme' => 1, 'online' => true, 'notifications' => 0];
    }


    public function markAllRead(): void
    {
        $this->notifications = 0;
    }
}


$app = Stores::get(AppStore::class);
$app->dispatch('markAllRead');

Stores add Vuex-style actions, computed state, transactions, selectors, subscriptions, concurrency policies, optimistic rollback, undo/redo, persistence, encryption, migrations, replication, and time-travel DevTools. Read the complete global store guide.

Lifecycle

Section titled “Lifecycle”
construct → boot → setup → mount → render → attached → resumed
          → update cycles and effects
          → paused → unmount → cleanup

Use setup() to resolve stores/services, attached() for work requiring a committed native node, effects for dependency-owned resources, and cleanup() for final teardown. The component runtime reference covers every hook, typed props, computed values, memo, watchers, refs, slots, events, context, restoration, and error boundaries.

Render and commit path

Section titled “Render and commit path”
PHP component/store write
  → dependency invalidation
  → retained Element tree
  → Rust reconcile + layout
  → bounded PNB1 mutation batch
  → one Kotlin/Swift UI commit per frame

The first frame sends a complete tree. Later frames contain numeric creates, removes, property updates, moves, and root changes. Stable 64-bit keyed identities let PAM retain unchanged native nodes.

Native-owned interaction

Section titled “Native-owned interaction”

The platform keeps high-frequency behavior local:

  • input text, cursor, selection, and IME;
  • press, long-press, pan, pinch, and rotation recognition;
  • scroll, fling, recycled-list prefetch, and refresh;
  • image fetch, decode, disk cache, and progress;
  • video/audio playback and media cache;
  • modal, drawer, navigation, and transform animations; and
  • safe-area, keyboard, dimensions, and accessibility behavior.

PHP receives semantic events. Coalesced progress/pointer events are delivered at most once per frame rather than turning every native motion sample into an application render.

Input synchronization

Section titled “Input synchronization”
Mode PHP synchronization
Native No per-keystroke synchronization
Debounced Deliver after a short quiet period
Immediate Deliver every accepted change
Blur Deliver when focus leaves
Submit Deliver on submission

Text and selection stay native while the user edits, so a slow domain action cannot make the field lose its cursor.

Performance rules

Section titled “Performance rules”
  • Give moving/repeated children stable keys.
  • Keep render() pure and bounded.
  • Read only the store/local-state values the component actually needs.
  • Put network and disk work in services or actions.
  • Use native lists for large data sets and native media/cache components for images, video, and files.
  • Use computed values and selectors for derived data.
  • Release manual subscriptions and external handles through effect cleanup.