Struct RouteOutlet 

pub struct RouteOutlet { /* private fields */ }

Mounts one Navigator as presentation-aware stack content.

The outlet owns the integration state the navigator cannot: per-route mount tags feeding the focus ownership oracle, a RouteFocusState driven across transitions, and one RouteTaskBinding per live route (lifetime-owned, including unmounted-but-alive routes). Use one outlet per navigator; nested navigators get nested outlets and stay isolated through disjoint tags and states.

Dropping the outlet releases the integration: focus records, bindings, and tags go with it (bound scopes then follow ordinary TaskScope ownership, detached from later removals).

State inventory (owner → invariant): navigator (cloned handle — identity and lifetimes live in navigation); focus, bindings, tags (outlet — pruned to live routes on every reconcile); nested/parent (attachment graph — weak both ways, single-parent, acyclic); driver (driving runtime — claimed on drive, released on detach or runtime drop); task_parent (host scope — never mutated); presented/pending (transition bookkeeping — advance only on commit); epoch (attempt context — one per driven frame); composing/consumed (composition record — receipted mounting builders only, promoted on success only); signaled (schedule memo — edge-triggered per revision); namespace/root_key (immutable construction identity); tag_sequence (monotonic, never reused); revision (invalidation generation — doubles as the drive counter); mount (attached element — cleared when it vanishes).

Implementations

impl RouteOutlet

pub fn new(navigator: &Navigator, task_parent: &TaskScope) -> Self

Hosts navigator, parenting route task scopes under task_parent (typically the window scope, so close still cancels through existing ownership).

pub fn attach_nested( outlet: &Rc<RefCell<Self>>, nested: &Rc<RefCell<Self>>, ) -> Result<(), OutletAttachError>

Registers a directly nested outlet whose content mounts inside this outlet’s routes. Nested elements resolve to the nested outlet, so inner navigation can neither overwrite outer saved focus nor be restored over by it. Sibling outlets sharing only an ancestor need nothing: disjoint subtrees never attribute across. Transitivity follows containment — register each outlet with its direct parent.

Topology is enforced before any mutation, borrowing the back-dispatch lesson without coupling to it: self-attachment and cycles are rejected (cascade driving must terminate), and each outlet has at most one live parent (cascade driving visits every registered child, so a shared child would drive twice per frame). Re-registering with the same parent is an idempotent no-op; moving parents requires Self::detach_nested first. Registration holds weakly: dropping the nested outlet releases it, and dead entries prune on every present, so repeated replacement never grows metadata.

pub fn detach_nested(outlet: &Rc<RefCell<Self>>, nested: &Rc<RefCell<Self>>)

Detaches a nested outlet. The child keeps its own records, bindings, and tags, but the parent’s cascade no longer drives it: a detached outlet receives no frame work even while application code retains its handle. Detach also releases the child’s driver claim, so ownership transfers cleanly — reattaching elsewhere (or driving it standalone, including under another runtime) claims anew. Detaching a non-child is a no-op.

pub fn frame_drive_count(&self) -> u64

Frames driven through this outlet, cascade included. Each Self::present_frame on the driving root advances every participating outlet by exactly one. Reads the invalidation generation, which advances once per driven frame and needs no separate counter.

pub fn nested_widget(nested: &Rc<RefCell<Self>>) -> Widget

Mounts a nested outlet’s widget with the required builder identity: a stable keyed boundary driven by the nested revision, so ancestor rebuilds retain the slot instead of remounting it. Hosts compose this inside outer route content instead of assembling stateful builders by hand; no nested attach is needed on top. Presenting the outer outlet drives the whole tree in one frame — nested outlets never need their own present_frame calls.

pub fn attached_nested_count(&self) -> usize

Number of live nested attachments. Dead handles prune on every present; useful for hosts composing nested outlets dynamically.

pub fn set_modal_route_scopes(&mut self, enabled: bool)

Returns the navigator this outlet hosts. Publishes each route’s ModalRoute to its content, so ModalRoute::of works inside routes. Off by default: the scope is an inherited (lazily built) node, so route content then validates when it mounts rather than before the outlet commits a rebuild, and a malformed route reports InvalidGeneratedChild instead of failing the rebuild atomically.

pub fn modal_route_scopes(&self) -> bool

pub fn navigator(&self) -> &Navigator

pub fn id(&self) -> OutletId

Returns this outlet’s identity, for error data and host bookkeeping.

pub fn needs_frame(&self) -> bool

Whether navigation arrived that no composition consumed yet — for this outlet or any nested outlet. True before the first composition with a non-empty stack, and after navigation newer than the last consumed snapshot (including navigation during a build, whose paint lags one frame behind the bookkeeping). False once composition consumes current state. Diagnostics and custom drivers only: ordinary hosts must not poll this for mandatory work — the scheduler flag from present_frame carries that. It does not report failed frames (their error return does that).

pub fn attach( outlet: &Rc<RefCell<RouteOutlet>>, runtime: &mut Runtime, ) -> Result<(), OutletError>

Attaches the outlet to its mounted widget so Self::present_frame rebuilds outlet content every frame. Call once after mounting Self::widget: the mount element is located through the outlet root tag. Re-attaching replaces the previous builder harmlessly.

Attachment claims the outlet for runtime’s driver domain: an outlet nested under a live parent, or claimed by another live runtime, is rejected before mutation. Detach (nested) or drop the owning runtime (teardown releases) before attaching elsewhere.

use std::{cell::RefCell, rc::Rc};
use incular_config::Constraints;
use incular_core::{Color, Size};
use incular_navigation::{Navigator, Page};
use incular_runtime::{RouteOutlet, Runtime};
use incular_widgets::{Column, Widget};

let navigator = Navigator::new();
let mut runtime =
    Runtime::new(Column::new(Vec::<Widget>::new()).into()).unwrap();
let parent = runtime.spawner().scope();
let outlet = Rc::new(RefCell::new(RouteOutlet::new(&navigator, &parent)));
// One-time setup: mount the outlet widget, then attach its builder.
let root = runtime.tree().root().expect("root");
let outlet_for_build = outlet.clone();
runtime
    .register_builder(root, move || {
        Column::new(vec![outlet_for_build.borrow().widget()]).into()
    })
    .unwrap();
runtime
    .run_frame(Constraints::tight(Size::new(200., 200.)))
    .unwrap();
RouteOutlet::attach(&outlet, &mut runtime).unwrap();
navigator.push_page(Page::new("a", Widget::box_(Size::new(40., 40.), Color::WHITE)));
// The single recurring operation: rebuild, frame, reconcile.
let _frame =
    RouteOutlet::present_frame(&outlet, &mut runtime, Constraints::tight(Size::new(200., 200.)))
        .unwrap();
assert!(navigator.current().is_some());

pub fn widget(&self) -> Widget

Builds the outlet widget: mounted routes in stack order with each route’s veil as a direct sibling preceding its content, so barrier semantics block every earlier route while the veiled route itself stays visible. The visible suffix paints from the top down to the first opaque page inclusive; retained but covered routes stay Builds the outlet widget for mounting, without touching any bookkeeping: safe to call speculatively and discard. Only the mounting builders (registered by attach, and nested slots) acknowledge what they accept. Covered routes without retention unmount (disposal); retained ones stay mounted inert while invisible; overlay entries are left for their portal host.

pub fn route_task_scope(&self, route: RouteId) -> Option<TaskScope>

Returns the route task scope for spawning route-bound work, if the route is currently mounted and bound.

pub fn present_frame( outlet: &Rc<RefCell<Self>>, runtime: &mut Runtime, constraints: Constraints, ) -> Result<(DisplayList, FrameStats), OutletError>

Presents one production frame through the outlet: validates the tree, captures any pending transition, rebuilds outlet content, runs layout, then commits the transition against the mounted tree. This is the supported recurring operation: the save runs before the frame reconciles (rebuilding may unmount covered content and the drain clears dead focus), while the restore runs after layout when targets are eligible.

Takes the outlet shared (rather than &mut self) because the attached builder reenters it immutably while the frame runs; short borrows never span the frame. Driving claims the whole tree for runtime: presenting a nested child directly, or through a second live runtime, fails before any mutation. A rebuild or frame failure keeps the pending capture for a safe retry instead of consuming the activation, and navigation mid-frame abandons the stale capture without touching committed records.