Trait InstanceNode 

pub trait InstanceNode {
    // Required methods
    fn base(&self) -> &BaseInstance;
    fn instantiate(args: InstantiationArgs) -> Rc<Self>
       where Self: Sized;
    fn resolve_debug(
        &self,
        f: &mut Formatter<'_>,
        expanded_node: Option<&ExpandedNode>,
    ) -> Result<(), Error>;

    // Provided methods
    fn supports_alpha_source_render(&self) -> bool { ... }
    fn requires_non_reactive_update(
        &self,
        _expanded_node: &ExpandedNode,
    ) -> bool { ... }
    fn has_scene_lighting(&self) -> bool { ... }
    fn resolve_scene_light(
        &self,
        _expanded_node: &ExpandedNode,
        _context: &RuntimeContext,
    ) -> Option<SceneLight> { ... }
    fn resolve_scene_ambient_light(
        &self,
        _expanded_node: &ExpandedNode,
        _context: &RuntimeContext,
    ) -> Option<SceneAmbientLight> { ... }
    fn establishes_light_frame(&self) -> bool { ... }
    fn update(
        self: Rc<Self>,
        _expanded_node: &Rc<ExpandedNode>,
        _context: &Rc<RuntimeContext>,
    ) { ... }
    fn handle_pre_render(
        &self,
        expanded_node: &ExpandedNode,
        context: &Rc<RuntimeContext>,
        rcs: &mut dyn RenderContext,
    ) { ... }
    fn prepare_canvas_geometry(&self, _node: &ExpandedNode) -> CanvasGeometry { ... }
    fn render(
        &self,
        expanded_node: &ExpandedNode,
        context: &Rc<RuntimeContext>,
        rcs: &mut dyn RenderContext,
    ) { ... }
    fn handle_post_render(
        &self,
        expanded_node: &ExpandedNode,
        context: &Rc<RuntimeContext>,
        rcs: &mut dyn RenderContext,
    ) { ... }
    fn handle_mount(
        self: Rc<Self>,
        expanded_node: &Rc<ExpandedNode>,
        context: &Rc<RuntimeContext>,
    ) { ... }
    fn handle_unmount(
        &self,
        expanded_node: &Rc<ExpandedNode>,
        context: &Rc<RuntimeContext>,
    ) { ... }
    fn handle_scroll(&self, args_scroll: Scroll) { ... }
    fn get_template(&self) -> Option<&RefCell<Vec<Rc<dyn InstanceNode>>>> { ... }
    fn clips_content(&self, _expanded_node: &ExpandedNode) -> bool { ... }
    fn ray_cast_test(
        &self,
        expanded_node: &ExpandedNode,
        ray: Point2<Window>,
    ) -> bool { ... }
    fn scrolls_content(&self, _expanded_node: &ExpandedNode) -> bool { ... }
    fn property_requires_occlusion_recompute(
        &self,
        _property_name: &str,
    ) -> bool { ... }
    fn materializes_native_surface(&self, _expanded_node: &ExpandedNode) -> bool { ... }
    fn materializes_native_surface_before_children(
        &self,
        _expanded_node: &ExpandedNode,
    ) -> bool { ... }
    fn resolve_scroll_offset(
        &self,
        _expanded_node: &ExpandedNode,
    ) -> Option<(f64, f64)> { ... }
    fn received_children_source(&self) -> ReceivedChildrenSource { ... }
    fn handle_native_interrupt(
        &self,
        _expanded_node: &Rc<ExpandedNode>,
        _interrupt: &NativeInterrupt,
    ) { ... }
    fn handle_control_flow_node_expansion(
        self: Rc<Self>,
        _expanded_node: &Rc<ExpandedNode>,
        _context: &Rc<RuntimeContext>,
    ) { ... }
    fn handle_setup_projected_children(
        self: Rc<Self>,
        _expanded_node: &Rc<ExpandedNode>,
        _context: &Rc<RuntimeContext>,
    ) { ... }
    fn resolve_coverage_path(
        &self,
        _expanded_node: &ExpandedNode,
    ) -> Option<BezPath> { ... }
    fn resolve_alpha_mask_paints(
        &self,
        _expanded_node: &ExpandedNode,
    ) -> Vec<AlphaMaskPaint> { ... }
    fn resolve_occlusion_path(
        &self,
        expanded_node: &ExpandedNode,
    ) -> Option<BezPath> { ... }
    fn resolve_coverage_opacity(&self, expanded_node: &ExpandedNode) -> f64 { ... }
    fn resolve_effect_clip_path(
        &self,
        _expanded_node: &ExpandedNode,
    ) -> Option<BezPath> { ... }
}

Central runtime representation of a properties-computable and renderable node. InstanceNodes are conceptually stateless, and rely on ExpandedNodes for stateful representations.

An InstanceNode sits in between a pax_compiler::TemplateNodeDefinition, the compile-time definition analogue to this instance, and ExpandedNode.

There is a 1:1 relationship between pax_compiler::TemplateNodeDefinitions and InstanceNodes. There is a one-to-many relationship between one InstanceNode and possibly many variant ExpandedNodes, due to duplication via for.

InstanceNodes are architecturally “type-aware” — they can perform type-specific operations e.g. on the state stored in ExpandedNode, while ExpandedNodes are “type-blind”. The latter store polymorphic data but cannot operate on it without the type-aware assistance of their linked InstanceNode.

(See RepeatInstance::expand_node where we visit a singular InstanceNode several times, producing multiple ExpandedNodes.)

Required Methods

fn base(&self) -> &BaseInstance

Retrieves the base instance, containing common functionality that all instances share

fn instantiate(args: InstantiationArgs) -> Rc<Self>

where Self: Sized,

fn resolve_debug( &self, f: &mut Formatter<'_>, expanded_node: Option<&ExpandedNode>, ) -> Result<(), Error>

Provided Methods

fn supports_alpha_source_render(&self) -> bool

Whether ordinary render hooks are valid inside a detached vector alpha source. Native surfaces and cross-surface containers require separate capture support.

fn requires_non_reactive_update(&self, _expanded_node: &ExpandedNode) -> bool

Whether this instance has per-frame update work that cannot be driven entirely through reactive property effects.

fn has_scene_lighting(&self) -> bool

Whether this primitive can contribute direct or ambient scene lighting.

Lighting primitives must return true even while disabled. The runtime uses this stable capability at mount/replacement to register contributors without polling every scene node during rendering.

fn resolve_scene_light( &self, _expanded_node: &ExpandedNode, _context: &RuntimeContext, ) -> Option<SceneLight>

Returns a resolved light contribution for a primitive with has_scene_lighting().

fn resolve_scene_ambient_light( &self, _expanded_node: &ExpandedNode, _context: &RuntimeContext, ) -> Option<SceneAmbientLight>

Returns a resolved ambient contribution for a primitive with has_scene_lighting().

fn establishes_light_frame(&self) -> bool

Whether this node establishes a lexical boundary for descendant lights.

fn update( self: Rc<Self>, _expanded_node: &Rc<ExpandedNode>, _context: &Rc<RuntimeContext>, )

Updates the expanded node, recomputing its properties and possibly updating its children.

fn handle_pre_render( &self, expanded_node: &ExpandedNode, context: &Rc<RuntimeContext>, rcs: &mut dyn RenderContext, )

Second lifecycle method during each render loop, occurs after properties have been computed, but before rendering Example use-case: perform side-effects to the drawing contexts. This is how Frame performs clipping, for example. Occurs in a pre-order traversal of the render tree.

fn prepare_canvas_geometry(&self, _node: &ExpandedNode) -> CanvasGeometry

Prepare primitive-local paint geometry independently of drawing or surface readiness.

The default is conservatively unbounded. Bounded primitives should return their actual local coverage; the runtime shares its transformed result with replay selection. This must be a side-effect-free read of settled properties. Results are retained until RuntimeContext::mark_canvas_node_dirty invalidates the node, so a primitive’s reactive drawing dependencies must include every input used here. Surface replay reuses the prepared record without invoking this method again.

fn render( &self, expanded_node: &ExpandedNode, context: &Rc<RuntimeContext>, rcs: &mut dyn RenderContext, )

Third lifecycle method during each render loop, occurs after all descendents have been rendered. Occurs in a post-order traversal of the render tree. Most primitives are expected to draw their contents to the rendering context during this event.

fn handle_post_render( &self, expanded_node: &ExpandedNode, context: &Rc<RuntimeContext>, rcs: &mut dyn RenderContext, )

Fourth and final lifecycle method during each render loop, occurs after all descendents have been rendered AND the current node has been rendered. Useful for clean-up, e.g. this is where Frame cleans up the drawing contexts to stop clipping. Occurs in a post-order traversal of the render tree.

fn handle_mount( self: Rc<Self>, expanded_node: &Rc<ExpandedNode>, context: &Rc<RuntimeContext>, )

Fires during the tick when a node is first attached to the render tree. For example, this event fires by all nodes on the global first tick, and by all nodes in a subtree when a Conditional subsequently turns on a subtree (i.e. when the Conditionals criterion becomes true after being false through the end of at least 1 frame.) A use-case: send a message to native renderers that a Text element should be rendered and tracked

fn handle_unmount( &self, expanded_node: &Rc<ExpandedNode>, context: &Rc<RuntimeContext>, )

Fires during element unmount, when an element is about to be removed from the render tree (e.g. by a Conditional) A use-case: send a message to native renderers that a Text element should be removed

fn handle_scroll(&self, args_scroll: Scroll)

Invoked by event interrupts to pass scroll information to render node

fn get_template(&self) -> Option<&RefCell<Vec<Rc<dyn InstanceNode>>>>

fn clips_content(&self, _expanded_node: &ExpandedNode) -> bool

Used by frame to control content clipping

fn ray_cast_test( &self, expanded_node: &ExpandedNode, ray: Point2<Window>, ) -> bool

Override when a primitive needs a more precise hit region than its layout bounds.

fn scrolls_content(&self, _expanded_node: &ExpandedNode) -> bool

Used by scroller-like primitives to allocate a browser-owned presentation layer.

fn property_requires_occlusion_recompute(&self, _property_name: &str) -> bool

Returns whether changes to a named typed property invalidate native compositing. Leaf changes update indexed coverage; changes to clipping or layer ownership reconcile the inherited structure.

Common geometry, transform, opacity, and child-list dependencies are tracked separately for every node. Override this for typed properties that only affect local content or native patches and cannot change occlusion coverage, clipping, z-order, or layer ownership.

fn materializes_native_surface(&self, _expanded_node: &ExpandedNode) -> bool

True when an otherwise layout-only primitive currently materializes a native surface.

fn materializes_native_surface_before_children( &self, _expanded_node: &ExpandedNode, ) -> bool

True when a materialized native surface should be projected before descendants.

Most renderables are post-order so their own pixels sit above descendants in logical tree order. Native backing surfaces, such as liquid-glass Groups, need the opposite: the chassis should create/project the native surface before descendant content while still including the surface in native occlusion and vector-mask computation.

fn resolve_scroll_offset( &self, _expanded_node: &ExpandedNode, ) -> Option<(f64, f64)>

Returns the current browser-owned scroll offset in local scroller coordinates.

fn received_children_source(&self) -> ReceivedChildrenSource

Selects which engine child family should be normalized into received_children for semantic container-style consumers.

This hook is about provenance, not semantics:

• Owned means the node’s active child tree is already its received payload
• Projected means the node receives payload from its caller and the runtime delivers that payload through projection so slot(...) can consume it

The default remains heuristic for now: components normalize projected children, while other nodes normalize owned children.

fn handle_native_interrupt( &self, _expanded_node: &Rc<ExpandedNode>, _interrupt: &NativeInterrupt, )

fn handle_control_flow_node_expansion( self: Rc<Self>, _expanded_node: &Rc<ExpandedNode>, _context: &Rc<RuntimeContext>, )

fn handle_setup_projected_children( self: Rc<Self>, _expanded_node: &Rc<ExpandedNode>, _context: &Rc<RuntimeContext>, )

fn resolve_coverage_path( &self, _expanded_node: &ExpandedNode, ) -> Option<BezPath>

fn resolve_alpha_mask_paints( &self, _expanded_node: &ExpandedNode, ) -> Vec<AlphaMaskPaint>

Resolves vector paint for an alpha-mask source without rendering or mutating the source’s retained canvas state. Paint-local coverage without common node/ancestor opacity. The Mask consumer applies the source subtree’s opacity factors relative to its own boundary.

fn resolve_occlusion_path( &self, expanded_node: &ExpandedNode, ) -> Option<BezPath>

Returns coverage used by the occlusion/native-mask/layer-partition pass.

The default uses the same coverage path as masks and hit-style geometry, but primitives with render-side animation may return a conservative stable path here so animation-only properties do not force the occlusion pass to rebuild expensive geometry every frame.

fn resolve_coverage_opacity(&self, expanded_node: &ExpandedNode) -> f64

fn resolve_effect_clip_path( &self, _expanded_node: &ExpandedNode, ) -> Option<BezPath>

Trait Implementations

impl Debug for dyn InstanceNode

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl InstanceNode for ComponentInstance

impl InstanceNode for ConditionalInstance

impl InstanceNode for RepeatInstance

impl InstanceNode for RouterInstance

impl InstanceNode for SlotInstance