api

Structs

NodeContext

This runtime owner stays on the UI thread. Transfer properties or delivery handles to workers instead.

fn requires_send<T: Send>() {}
requires_send::<pax_runtime::api::NodeContext>();

Runtime context passed into user component lifecycle methods and event handlers.

For an inline binding, Rust self belongs to the component that authored the binding, while this context describes the child receiving the call. Bounds, expression stack access, subscriptions, and async lifetime remain target-local. Component-level bindings receive their own component's state and context.

Child-related fields intentionally separate semantic payload from engine transport:

  • projected_children is the raw transport family used by Slot
  • received_children is the normalized semantic payload that this node should treat as content from its caller
  • retained_received_children are former received children kept alive only so @out transitions can finish

A node's own private template or primitive-assembled structure is intentionally not surfaced here as a first-class "child family" for container consumers.

Properties

expanded_node

Type: Weak<ExpandedNode>

slot_index

Type: LocalProperty<Option<usize>>

slot index of this node in its container

expression_stack

Type: Rc<RuntimePropertiesStackFrame>

containing_component

Type: Weak<ExpandedNode>

Reference to the ExpandedNode of the component containing this node

elapsed_frames

Type: LocalProperty<u64>

The current global engine frame count.

elapsed_millis

Type: LocalProperty<u64>

The current global engine wall-clock time in milliseconds.

gyro

Type: LocalProperty<Gyro>

Current device orientation sensor reading.

accel

Type: LocalProperty<Accel>

Current device accelerometer reading.

bounds_parent

Type: LocalProperty<(f64, f64)>

The bounds of this element's immediate container (parent) in px

bounds_self

Type: LocalProperty<(f64, f64)>

The bounds of this element in px

measured_size

Type: LocalProperty<Option<(f64, f64)>>

Measured bounds resolved by the chassis or container layout for this node.

subtree_layout_hull

Type: LocalProperty<LayoutHull>

Node-local subtree layout hull published by the engine for container measurement.

platform

Type: Platform

Current platform (Web/Native) this app is running on

os

Type: OS

Current os (Android/Windows/Mac/Linux) this app is running on

target

Type: LocalProperty<TargetInfo>

Derived target facts for platform/OS checks.

viewport

Type: LocalProperty<Viewport>

Derived viewport facts for size and orientation checks.

projected_children_count

Type: LocalProperty<usize>

The number of projected children available to this node.

This is the raw transport count used by slot-driven implementations. Container-style consumers usually want received_children_count instead.

node_transform_and_bounds

Type: TransformAndBounds<NodeLocal, Window>

The transform of this node in the global coordinate space

projected_children

Type: LocalProperty<Vec<Rc<ExpandedNode>>>

Children projected into this node from the containing component.

Projection is an engine transport mechanism. Consumers that want the semantic payload owned by this node should prefer received_children.

projected_children_changed

Type: LocalProperty<()>

A structural invalidation signal for projected children.

received_children

Type: LocalProperty<Vec<Rc<ExpandedNode>>>

Semantic payload children received by this node from its caller.

This is the canonical "content" view for container-style logic. It excludes private encapsulated implementation children and also excludes exit-retained payload nodes, which instead appear in retained_received_children.

received_children_count

Type: LocalProperty<usize>

Convenience count derived from received_children.

received_children_changed

Type: LocalProperty<()>

A structural invalidation signal for received_children.

Prefer this or received_children itself for structural subscriptions that must react to reorders as well as insertions and removals.

retained_received_children

Type: LocalProperty<Vec<Rc<ExpandedNode>>>

Received children retained only so exit transitions can finish.

These are no longer part of the active semantic payload, but some containers still need to place them as ghosts or overlays while their @out transitions run.

retained_received_children_changed

Type: LocalProperty<()>

A structural invalidation signal for retained_received_children.

Implementations

application
pub fn application(&self) -> AppContext

Access the owning application lifetime, cancellation and error reporting.

async_scope
pub fn async_scope(&self) -> Result<AsyncScope, AsyncError>

Lifetime of this exact context node, ending at actual unmount. Retain a component mount scope when later handlers receive child-control contexts. A saved context cannot acquire the scope of a later mount of that node.

clear_subscriptions
pub fn clear_subscriptions(&self)

Remove all subscriptions registered on this node.

dispatch_event
pub fn dispatch_event(&self, identifier: &'static str) -> Result<(), String>

Queue a named custom event from this component for dispatch at the end of the tick.

elapsed_time_millis
pub fn elapsed_time_millis(&self) -> u128

Milliseconds elapsed according to the chassis-provided clock.

get_node_interface
pub fn get_node_interface(&self) -> Option<NodeInterface>

Return the interface for this node's containing component, when present.

get_screenshot_map
pub fn get_screenshot_map(&self) -> Rc<RefCell<HashMap<u32, ScreenshotData>>>

Shared map where completed screenshot captures are published by id.

local_point
pub fn local_point(&self, p: Point2<Window>) -> Point2<NodeLocal>

Convert a window-space point into this node's local coordinate space, including any presentation offsets inherited from ancestor scrollers.

pub fn navigate_to(&self, url: &str, target: NavigationTarget)

Ask the chassis to navigate to a URL.

On web targets, same-origin navigation in the current tab can be handled through the browser History API and routed back into Pax without a full page reload. Cargo metadata's [package.metadata.pax.web].server_owned_prefixes delegates matching paths to ordinary browser navigation before changing application history. Other targets use the active chassis navigation behavior.

screenshot
pub fn screenshot(&self, id: u32)

Request a screenshot capture from the chassis, keyed by caller-provided id.

set_cursor
pub fn set_cursor(&self, cursor: CursorStyle)

Ask the chassis to display the requested cursor over the app surface.

subscribe
pub fn subscribe(&self, dependencies: &[UntypedProperty], f: impl Fn() + 'static)

Attach a dependency subscription whose callback runs when any dependency dirties.

provide_store
pub fn provide_store<T: Store>(&self, store: T) -> Result<(), StoreError>

Publish a store on this context's mounted node, keyed by its concrete Rust type.

Register in the component's own mount handler to give each component instance an independent provider. In an inline descendant handler, the context identifies that descendant even when Rust self is its authoring component. The context's node, not self, owns the registration.

The owner and its logical descendants can find the value with with_store. This includes private template children and caller-supplied children; private wrappers around a slot do not change projected content's ancestry. Siblings and ancestors cannot discover this registration.

Providing the same type again on the same owner replaces its entry for future lookups. Previously cloned handles keep their original state; the registry is not reactive. Prefer updating properties in a stable store. Providers are cleared at final unmount, after unmount handlers run.

Returns StoreError::ExpiredScope for an unmounted or stale context, or StoreError::BorrowConflict if the entry being replaced is borrowed.

with_store
pub fn with_store<T: Store, V>(&self, f: impl FnOnce(&mut T) -> V) -> Result<V, StoreError>

Borrow the nearest provider of T, starting with this context's node.

Lookup follows logical template ancestry, independently of expression scope and render parents. A nearer same-type provider shadows an outer one; unrelated types remain visible. It never searches siblings or descendants. Two consumers share state when they resolve the same provider.

The closure exclusively borrows that store for its duration. Clone a needed Property handle inside the closure, then read or update it after the borrow ends. This avoids conflicts if subsequent work looks up the same store. The returned value can be a handle or an owned snapshot, but cannot borrow from the store.

Returns StoreError::Missing when no provider exists, StoreError::ExpiredScope when the context or an ancestor's mount has ended, and StoreError::BorrowConflict when the nearest provider is already borrowed. A conflict or expired scope never falls back to an outer provider. Saved contexts cannot discover a later mount's stores.