tilo_app/framework/

root.rs

//! The root widget of a framework app: keeps the resource state current,
//! publishes the resource and its actions, forwards edits to the host, and
//! indexes the resource for search.

use std::collections::HashSet;
use std::rc::Rc;
use std::sync::Arc;
use tilo_actions::ResourceSpec;
use ui_core::widget::{AppModel, ModelPath};

use crate::runner::with_native_presentations;
use tilo_resource::{Resource, SearchEntry};
use ui_core::PresencePayload;
use ui_core::application_view::{
    ApplicationFocusRestore, ApplicationLocalView, ApplicationViewState,
};
use ui_core::automerge::AutoCommit;
use ui_core::permissions::{LivePermissions, PermissionScope};
use ui_core::presence::{PresenceCtx, PresenceKey};
use ui_core::record::RecordSaveStatus;
use ui_core::search::SearchProvider;
use ui_core::text_render::TextRenderer;
use ui_core::vello::Scene;
use ui_core::vello::kurbo::Affine;
use ui_core::view::ThawError;
use ui_core::widget::capability::{capability, capability_mut};
use ui_core::widget::{AppKind, AppWidget, Decorator, Element, IconDescriptor, Widget};
use ui_core::{LocalState, Theme};

use super::dispatch::DispatchCore;
use super::rows::{find, join, merge, outside_document};
use super::scenario::Run;
use super::stage::Stages;
use super::surface::SurfacePublication;
use super::view::ViewCx;

mod controls;
mod facts;
mod live_head;
mod read;
mod search;
mod shared_tree;
mod shown_item;
mod typed;
mod widget;
use live_head::LiveHead;
pub(crate) use read::READ_TYPE;
use read::{offer_document_reads, offer_item_reads, read, read_spec};
pub(crate) use search::{
    BodyText, IndexedEntries, LiveSearch, ResourceSearch, field_weight, index_entry,
};
use shared_tree::{
    DocumentChildren, ItemChildren, NestedViews, PublishedChildren, RecordChildren, RowChildren,
    SharedTreeCache, mark_document_jobs,
};
use typed::TypedRoot;
pub(crate) use typed::{ResourceType, Typed};
pub(crate) use widget::{RootApp, RootModel, RootPublishes, RootSearch, RootWidget};

pub(crate) struct ResourceRoot {
    title: &'static str,
    icon: IconDescriptor,
    label: String,
    /// The resource type the root shows, and what it says of itself.
    resource: ResourceType,
    /// What depends on the resource type: its live state, the views'
    /// updaters and bound edits, the dispatcher and the effects. Everything
    /// else here is compiled once in the shared runtime.
    typed: Box<dyn TypedRoot>,
    /// What bound controls look up ([`super::controls::Actions`]).
    action_bindings: super::controls::ActionTable,
    /// The live revision bound controls last followed.
    followed: std::cell::Cell<u64>,
    _alive: Rc<()>,
    pub(crate) dispatch: DispatchCore,
    saved: LocalState<RecordSaveStatus>,
    /// The window's save status over the view: the record's durability and
    /// the app's own saves, silent unless a save stalls or fails.
    save: super::saves::SaveIndicator,
    /// The reactions to the record, in the window's bar, where the record
    /// takes them.
    reactions: super::reactions::ReactionsIndicator,
    /// The participant's permissions, re-checked every sync so a role change
    /// while the app runs takes effect at once. `None` for a read-only view
    /// of a past version.
    permissions: Option<LivePermissions>,
    write: Option<PermissionScope>,
    stages: Stages,
    feeds: super::history::HistoryFeeds,
    /// What the view was built for, and the fixtures a capture's views read.
    pub(crate) run: Run,
    /// The settings the view follows, re-read when their document changes.
    pub(crate) storage: Rc<super::settings::ViewStorage>,
    /// The app's view: the custom surface itself when the view is one.
    pub(crate) content: Element,
    /// What is shown instead of the view while the record does not read as
    /// the resource, and why.
    unreadable: Option<(String, Element)>,
    /// The view was swapped for the unreadable state or back since layout.
    swapped: bool,
    /// What keeps the bindings of the app's view alive once it stands in
    /// the place of the window's arrival ([`Self::settle_arrival`]).
    arrived: Option<Rc<()>>,
    /// View and effect operations of the app's presentation, attached to the
    /// published resource. Document specs are dropped.
    presentation: Vec<tilo_actions::ActionSpec>,
    /// The resource's and its surfaces' search entries, indexed.
    search: Rc<std::cell::RefCell<SearchCache>>,
    /// The document-owned tree at one live and translation revision, shared
    /// with the last one wherever the change left it as it was. Surface
    /// bindings, local rows and effect availability are decorated afresh
    /// for every caller.
    publication_tree: std::cell::RefCell<Option<SharedTreeCache>>,
    /// The item children last published, kept so the next tree builds only
    /// the items whose label changed.
    item_children: std::cell::RefCell<Option<ItemChildren>>,
    /// The document children as the shared publication last carried them.
    published_children: std::cell::RefCell<Option<PublishedChildren>>,
    /// The children with the records kept beside the resource, as the shared
    /// publication last carried them.
    record_children: std::cell::RefCell<Option<RecordChildren>>,
    /// The children with the surfaces' live rows merged in, as the shared
    /// publication last carried them.
    row_children: std::cell::RefCell<Option<RowChildren>>,
    /// The head bound controls were last refreshed from, kept between syncs
    /// for a resource whose publication may be reused
    /// ([`Resource::publication_cache_epoch`]).
    binding_head: std::cell::RefCell<Option<BindingHead>>,
    /// What bound controls share of the publication at one head: built
    /// once per head, never copied per refresh.
    binding_base: std::cell::RefCell<Option<Rc<BindingBase>>>,
    /// The head of the live state and what it was published from.
    live_head: std::cell::RefCell<Option<LiveHead>>,
    /// The document children of the live state as last published, kept
    /// while they are unchanged.
    document_children: std::cell::RefCell<Option<DocumentChildren>>,
    /// The view operation types of the nested resources at one live revision.
    nested_views: std::cell::RefCell<Option<NestedViews>>,
    /// Whether the resource keeps document state History shows.
    history: bool,
    /// Whether the window stands on the framework's ground: every window but
    /// one shown over other apps' content — a sheet over the desktop
    /// ([`WindowRole::Sheet`]), or the on-screen keyboard over the app it
    /// types into ([`WindowRole::InputSurface`]).
    ///
    /// [`WindowRole::Sheet`]: ui_core::application::WindowRole::Sheet
    /// [`WindowRole::InputSurface`]: ui_core::application::WindowRole::InputSurface
    ground: bool,
    /// Platform presentation actions; the browser implementation has no state.
    native_presentation: crate::runner::Presentation,
    /// The links `share-link` is minting.
    share: super::share_link::ShareLinks,
    /// Where the resource's state comes from and where its edits go: the
    /// document the host lends each pass, or the session over the app's one
    /// connection ([`super::Source`]).
    source: super::Source,
}

impl ResourceRoot {
    /// Adopt the session's newest reading of the resource, when it moved:
    /// what the view binds follows it as any change does.
    fn sync_remote_state(&self) {
        let (Some(resource), Some(connection)) =
            (self.source.remote_resource(), self.source.connection())
        else {
            return;
        };
        let Some(reading) = connection.reading(resource) else {
            // Nothing publishes it yet, or the person may not read it:
            // denial is absence (`apps.md` §6), and the last state stands.
            return;
        };
        if let Err(error) = self.typed.adopt(&reading) {
            tracing::warn!(%error, kind = self.resource.kind, "the session's reading is not this resource's state");
        }
    }

    fn sync_over(&mut self, state: &AutoCommit, path: &automerge::ObjId) {
        self.refresh_access();
        if self.dispatch.take_represent() {
            self.typed.represent();
        }
        let head = self.refresh(state);
        for (action, reason) in self.dispatch.opener.take_refusals() {
            self.dispatch.refuse(&action, reason);
        }
        self.follow_readability();
        self.storage.refresh();
        self.typed
            .poll_window_jobs(effect_view(&mut self.unreadable, &mut self.content));
        {
            let _profile = tilo_resource::profiling::Phase::start("framework.content_sync");
            self.content.sync(state, path);
        }
        self.reveal_launched();
        self.settle_arrival();
        self.follow_search();
        // What the view's sync changed (its bound edits, its availability)
        // reaches the bindings; the document-owned head is rebuilt only when
        // the sync moved the state.
        let head = self.refresh_bindings(Some(head));
        *self.binding_head.borrow_mut() = Some(head);
        // The save status says itself in the window's bar.
        self.save.sync(ui_core::time::now());
        self.sync_reactions();
    }
}

impl ui_core::component_lifecycle::WindowActivation for ResourceRoot {
    /// Asked through the root's own door, or by the app's view: a view whose app runs
    /// elsewhere (a tilolang host's instance) hears the request there.
    fn take_window_activation_intent(&self) -> bool {
        let own = self.native_presentation.take_window_activation_intent();
        let view = app_view_in(self.content.as_ref())
            .is_some_and(ui_core::component_lifecycle::take_window_activation_intent);
        own || view
    }
}

/// The operation type of the framework's `open` view: show the item at an
/// anchor, as picking a search hit does.
pub(crate) const OPEN_TYPE: &str = tilo_actions::remote::APPLICATION_OPEN_TYPE;

/// The parameter of `open` naming what to show.
const OPEN_ANCHOR: &str = "anchor";

/// `open`: show the item at an anchor (a search entry's anchor). Published
/// when a view shows items ([`ViewCx::on_open`](super::ViewCx::on_open)), so
/// an agent opens the app where a person's search hit would.
fn open_spec() -> tilo_actions::ActionSpec {
    tilo_actions::ActionSpec::typed_operation(
        "open",
        "Open",
        "Item to open",
        tilo_actions::OperationKind::View,
        OPEN_TYPE,
        vec![tilo_actions::ActionParam::required(
            OPEN_ANCHOR,
            tilo_actions::ParamType::Text,
            "Item to open: the anchor of a search hit",
        )],
        |args| {
            tilo_actions::EncodedAction::encode_operation(
                OPEN_TYPE,
                &serde_json::json!({ OPEN_ANCHOR: args.text(OPEN_ANCHOR) }),
            )
            .unwrap_or_else(|_| tilo_actions::EncodedAction {
                type_id: OPEN_TYPE.into(),
                payload: Vec::new(),
            })
        },
    )
    .of_kind(tilo_actions::ActionKind::Read)
    .with_description("Open the app at one item: the anchor of a search hit.")
}

/// The label of the item view the framework gives an item resource that
/// presents no view of its own.
const ITEM_VIEW_LABEL: &str = "Item";

/// `open` on one item resource: show that item, as its search hit would.
fn item_open_spec(anchor: &str) -> tilo_actions::ActionSpec {
    let encoded = tilo_actions::EncodedAction::encode_operation(
        OPEN_TYPE,
        &serde_json::json!({ OPEN_ANCHOR: anchor }),
    )
    .unwrap_or_else(|_| tilo_actions::EncodedAction {
        type_id: OPEN_TYPE.into(),
        payload: Vec::new(),
    });
    tilo_actions::ActionSpec::typed_operation(
        "open",
        "Open",
        "Open",
        tilo_actions::OperationKind::View,
        OPEN_TYPE,
        Vec::new(),
        move |_| encoded.clone(),
    )
    .of_kind(tilo_actions::ActionKind::Read)
    .with_description("Show this item.")
}

/// Offer `open` on every item resource under `resource` (an item of the
/// collections of the resource `item_of` knows the items of), bound to that
/// item.
fn offer_item_open(item_of: fn(&str) -> bool, resource: &mut ResourceSpec) {
    if item_of(resource.id.as_str())
        && !resource
            .actions
            .iter()
            .any(|existing| existing.id == "open")
    {
        resource.actions.push(item_open_spec(resource.id.as_str()));
        // The opener is also a presentation binding, not just a verb in the
        // catalogue. Keep an app's explicit views; otherwise advertise the
        // item view that this exact bound opener actually shows. The view
        // names what it shows, the item, and not which item: the item's own
        // label is the resource's, published once with it. Every item's
        // `open` is then one catalogue entry however many items there are,
        // where a copy of the item's label made each item's `open`, and its
        // whole action template, an entry of its own.
        if resource.views.is_empty() {
            resource.views.push(
                tilo_actions::ResourceViewSpec::new("item", ITEM_VIEW_LABEL, "open")
                    .with_primary(true),
            );
        }
    }
    for child in &mut resource.children {
        offer_item_open(item_of, child);
    }
}

/// The ids of the actions the framework publishes on every app's resource
/// beside the app's own: the generic `apply`, `group` and `field-edit`, the
/// views `open`, `read` and `facts`, history, and the presentation operations. An app
/// verb, effect or view under one of these ids shadows the framework's or is
/// shadowed by it, so `tilo-app check` refuses it.
#[must_use]
pub fn reserved_action_ids() -> Vec<String> {
    let mut ids: Vec<String> = [
        tilo_resource::APPLY,
        tilo_resource::GROUP,
        tilo_resource::FIELD_EDIT,
    ]
    .into_iter()
    .map(str::to_owned)
    .collect();
    ids.push(open_spec().id.clone());
    ids.push(read_spec().id.clone());
    ids.push(facts::FACTS.to_owned());
    ids.push(tilo_resource::share::SHARE_LINK.to_owned());
    ids.push(tilo_resource::share::SHARE_INVITE_LINK.to_owned());
    ids.extend(super::history::specs().iter().map(|spec| spec.id.clone()));
    ids.extend(
        with_native_presentations(ResourceSpec::new("", "", ""))
            .actions
            .iter()
            .map(|spec| spec.id.clone()),
    );
    ids.sort();
    ids.dedup();
    ids
}

/// The window's arrival: the app's view, shown once the workspace's holdings
/// arrived ([`super::app`]'s `build_root`).
type WorkspaceArrival = ui_core::widget::ArrivingView;

/// The app's view in `content`, once it shows: `content` itself, or the
/// view standing in the window's arrival once that arrived. The arrival
/// answers for nothing of the view (a traversal meets the view as its
/// descendant, once), so what the root asks of the app's view it asks here.
fn app_view_in(content: &dyn Widget) -> Option<&dyn Widget> {
    let Some(arrival) = content
        .as_any()
        .and_then(|any| any.downcast_ref::<WorkspaceArrival>())
    else {
        return Some(content);
    };
    let switch = arrival
        .answer()?
        .as_any()?
        .downcast_ref::<super::switch::Switch>()?;
    Some(switch.part())
}

/// `visit` the app's view in `content` ([`app_view_in`]); `content` itself
/// while the view is on its way, where nothing of it answers.
fn with_app_view_mut<R>(content: &mut Element, visit: impl FnOnce(&mut dyn Widget) -> R) -> R {
    let arrived = content
        .as_any_mut()
        .and_then(|any| any.downcast_mut::<WorkspaceArrival>())
        .and_then(WorkspaceArrival::answer_mut)
        .and_then(|answer| answer.as_any_mut()?.downcast_mut::<super::switch::Switch>());
    match arrived {
        Some(switch) => visit(switch.part_mut()),
        None => visit(content.as_mut()),
    }
}

/// The view effects answer on: the app's `content`, or what stands in for
/// it while the resource is `unreadable`.
fn effect_view<'a>(
    unreadable: &'a mut Option<(String, Element)>,
    content: &'a mut Element,
) -> &'a mut dyn Widget {
    match unreadable {
        Some((_, shown)) => shown.as_mut(),
        None => content.as_mut(),
    }
}

impl ResourceRoot {
    /// Once the window's arrival settled (the app's view shows, its
    /// cross-fade over), the view stands in the arrival's place: the root
    /// is the app's view plus what the framework adds again, and nothing of
    /// the arrival stays between them.
    fn settle_arrival(&mut self) {
        let Some(arrival) = self
            .content
            .as_any_mut()
            .and_then(|any| any.downcast_mut::<WorkspaceArrival>())
        else {
            return;
        };
        let Some(mut answer) = arrival.take_answer(ui_core::motion::frame_now()) else {
            return;
        };
        let empty = || -> Element { Box::new(ui_core::widget::Spacer::fixed(0.0)) };
        self.content = match answer
            .as_any_mut()
            .and_then(|any| any.downcast_mut::<super::switch::Switch>())
        {
            Some(switch) => {
                let (view, alive) = switch.take_part(empty());
                self.arrived = Some(alive);
                view
            }
            None => answer,
        };
        self.swapped = true;
    }

    /// The app's view: what the root asks the view for ([`app_view_in`]).
    pub(crate) fn app_view(&self) -> &dyn Widget {
        app_view_in(self.content.as_ref()).unwrap_or_else(|| self.content.as_ref())
    }

    /// The window ground is the framework's: an app never fills it, and one
    /// that paints nothing still stands on it. A sheet over the desktop
    /// stands on nothing ([`Self::without_ground`]).
    fn paint_ground(
        &mut self,
        scene: &mut Scene,
        transform: Affine,
        theme: &Theme,
        presence: &PresenceCtx,
    ) {
        self.native_presentation.track_theme(theme);
        if self.ground {
            scene.fill(
                ui_core::vello::peniko::Fill::NonZero,
                transform,
                theme.tokens.colors.surfaces.content,
                None,
                &self.content.get_rect(),
            );
        }
        self.run.people.follow(presence);
    }

    /// A root over `content`, the view built in `cx`, whose handles the root
    /// keeps; `alive` is the scope `cx`'s bindings are tied to. Only this
    /// constructor knows `R`.
    pub(crate) fn new<R: Resource>(
        title: &'static str,
        icon: IconDescriptor,
        label: String,
        cx: ViewCx<R>,
        alive: Rc<()>,
        content: Element,
    ) -> Self {
        let native_presentation = crate::runner::Presentation::new(&cx);
        cx.dispatch.name_resource(&label);
        let ViewCx {
            env,
            updaters,
            action_bindings,
            stages,
            feeds,
            bindings,
            ..
        } = cx;
        let dispatch = env.dispatch.core().clone();
        let typed = Typed {
            live: env.live,
            reading: std::cell::RefCell::new(None),
            updaters,
            dispatch: env.dispatch,
            bindings,
            effects: env.effects,
        };
        Self::assemble(
            (title, icon, label),
            ResourceType::of::<R>(),
            Box::new(typed),
            action_bindings.table(),
            Parts {
                alive,
                dispatch,
                saved: env.saved,
                saves: env.saves,
                stages,
                feeds,
                run: env.run,
                storage: env.storage,
                content,
                native_presentation,
            },
        )
    }

    /// [`Self::new`] past what names the resource type.
    fn assemble(
        (title, icon, label): (&'static str, IconDescriptor, String),
        resource: ResourceType,
        typed: Box<dyn TypedRoot>,
        action_bindings: super::controls::ActionTable,
        parts: Parts,
    ) -> Self {
        let Parts {
            alive,
            dispatch,
            saved,
            saves,
            stages,
            feeds,
            run,
            storage,
            content,
            native_presentation,
        } = parts;
        Self {
            title,
            icon,
            label,
            resource,
            typed,
            action_bindings,
            followed: std::cell::Cell::new(0),
            _alive: alive,
            dispatch,
            saved,
            save: super::saves::SaveIndicator::new(saves, title),
            reactions: super::reactions::ReactionsIndicator::default(),
            permissions: None,
            write: None,
            stages,
            feeds,
            run,
            storage,
            content,
            unreadable: None,
            swapped: false,
            arrived: None,
            presentation: Vec::new(),
            search: Rc::default(),
            publication_tree: std::cell::RefCell::new(None),
            item_children: std::cell::RefCell::new(None),
            published_children: std::cell::RefCell::new(None),
            record_children: std::cell::RefCell::new(None),
            row_children: std::cell::RefCell::new(None),
            binding_head: std::cell::RefCell::new(None),
            binding_base: std::cell::RefCell::new(None),
            live_head: std::cell::RefCell::new(None),
            document_children: std::cell::RefCell::new(None),
            nested_views: std::cell::RefCell::new(None),
            history: true,
            ground: true,
            native_presentation,
            share: super::share_link::ShareLinks::default(),
            source: super::Source::Document,
        }
    }

    /// Take the source the dispatcher submits over as the root's too, so the
    /// view syncs from the reading the session publishes when the record is
    /// the session's ([`super::Source::Connection`]).
    pub(crate) fn reading_from_source(mut self) -> Self {
        self.source = self.dispatch.source().clone();
        self
    }

    /// A root whose resource keeps no document state: it publishes no
    /// History actions and its window offers no History.
    pub(crate) fn without_history(mut self) -> Self {
        self.history = false;
        self
    }

    /// Stand on nothing: what the view does not paint shows what is under
    /// the window, in the live window and in the picture a host draws from
    /// it alike.
    pub(crate) fn without_ground(mut self) -> Self {
        self.ground = false;
        self.native_presentation.without_ground();
        self
    }

    #[cfg(not(target_family = "wasm"))]
    pub(crate) fn drawing_past(mut self, past: crate::runner::DrawPast) -> Self {
        self.native_presentation.drawing_past(past);
        self
    }

    pub(crate) fn with_presentation(mut self, operations: Vec<tilo_actions::ActionSpec>) -> Self {
        self.presentation = operations;
        self
    }

    /// Stage a screenshot scenario's view state: every view's
    /// [`on_stage`](super::ViewCx::on_stage) callback runs now, and every
    /// hosted surface stages on its next sync.
    /// Stage the views' state for `scenario`, and answer the collaborators
    /// the capture shows as the presence frames their windows would send.
    pub(crate) fn stage(
        &self,
        scenario: Option<&str>,
    ) -> Vec<(String, PresenceKey, PresencePayload)> {
        self.stages.run(scenario);
        self.run
            .collaborators()
            .iter()
            .map(|(name, at)| {
                let (key, payload) = at.presence_of(self.resource.kind, self.dispatch.app_id());
                (name.clone(), key, payload)
            })
            .collect()
    }

    /// Settle the window's save status for a capture
    /// ([`SaveIndicator::settle_for_capture`](super::saves::SaveIndicator::settle_for_capture)).
    pub(crate) fn settle_saves_for_capture(&mut self) {
        self.save.settle_for_capture(ui_core::time::now());
    }

    /// Follow `permissions`: the resource is editable while they grant
    /// `write`.
    pub(crate) fn following(
        mut self,
        permissions: Option<LivePermissions>,
        write: PermissionScope,
    ) -> Self {
        if let Some(permissions) = &permissions {
            self.dispatch.follow(permissions.clone());
        }
        self.permissions = permissions;
        self.write = Some(write);
        self
    }

    /// Show the record's reactions in the window's bar, and run those
    /// pressed there ([`super::reactions`]). Nothing while the record does
    /// not read as the resource: its last state is not what it holds.
    fn sync_reactions(&mut self) {
        let state = self.typed.state();
        let readable = self.unreadable.is_none();
        self.reactions.sync(&super::reactions::ReactionsInput {
            table: self.resource.record_table.filter(|_| readable),
            state: state.as_ref(),
            dispatch: &self.dispatch,
            people: &self.run.people,
            private: self.run.private,
        });
    }

    /// Show the item the launch asked for once a view that opens items is
    /// up. An item the record does not hold yet (it is still arriving) is
    /// asked for again at the next sync.
    fn reveal_launched(&self) {
        let mut reveal = self.run.launched.reveal.borrow_mut();
        if let Some(anchor) = reveal.as_deref()
            && self.stages.opens()
            && self.stages.open(anchor).is_ok()
        {
            *reveal = None;
        }
    }

    /// Apply a permission change made while the app runs: dispatchers stop
    /// (or resume) submitting, bound state and surfaces see the new value.
    fn refresh_access(&self) {
        let _profile = tilo_resource::profiling::Phase::start("framework.access_refresh");
        if let (Some(permissions), Some(write)) = (&self.permissions, &self.write) {
            let read_only = !permissions.check(write) && !self.may_change_shown_item(permissions);
            self.dispatch.set_read_only(read_only);
            // Its person sees, in the window's bar, that they may only look.
            ui_core::window_toolbar::show_view_only(read_only);
        }
        self.dispatch.refresh_permission_states();
    }

    /// The root as the widget a host mounts.
    pub(crate) fn into_widget(self) -> Box<dyn AppWidget> {
        RootWidget::boxed(Box::new(self))
    }

    /// The root as the widget a past version's preview draws. Boxed here,
    /// not where the resource's type is known, so its widget table is
    /// compiled once for every app.
    pub(crate) fn into_root_widget(self) -> Box<dyn Widget> {
        Box::new(RootWidget::new(Box::new(self)))
    }

    /// The handles of the root that name its resource type, when it is `R`.
    pub(crate) fn typed<R: Resource>(&self) -> Option<&Typed<R>> {
        self.typed.as_any().downcast_ref::<Typed<R>>()
    }

    /// What the launch that opened the window named.
    pub(crate) fn launch(&self) -> super::launch::LaunchInput<'_> {
        self.run.launch()
    }

    /// Every hosted surface of this resource in the view, in tree order.
    fn surfaces(&self, visit: &mut dyn FnMut(&dyn SurfacePublication)) {
        fn walk(
            widget: &dyn Widget,
            resource: std::any::TypeId,
            visit: &mut dyn FnMut(&dyn SurfacePublication),
        ) {
            if let Some(surface) =
                ui_core::widget::capability::capability::<dyn SurfacePublication>(widget)
                && surface.resource() == resource
            {
                visit(surface);
            }
            widget.for_each_child(&mut |child| walk(child, resource, visit));
        }
        walk(self.content.as_ref(), self.resource.id, visit);
    }

    /// Bind the edits views offer on the rows `rows` name
    /// ([`Publishes::row_edits`](super::Publishes::row_edits)).
    ///
    /// One walk of the view asks every surface about every row, so binding
    /// costs the view plus surfaces × rows, never the view once per row. Each
    /// row binds its edits in tree order of the surfaces offering them.
    #[inline(never)]
    fn bind_row_declarations(&self, rows: &mut [ResourceSpec]) {
        // Every row, nested ones too (a playlist's tracks), asked of the
        // surfaces in one walk.
        fn ids(rows: &[ResourceSpec], out: &mut Vec<String>) {
            for row in rows {
                out.push(row.id.as_str().to_owned());
                ids(&row.children, out);
            }
        }
        fn bind(
            typed: &dyn TypedRoot,
            rows: &mut [ResourceSpec],
            offered: &mut std::collections::HashMap<String, Box<dyn std::any::Any>>,
        ) {
            for row in rows {
                if let Some(decls) = offered.remove(row.id.as_str()) {
                    let bound = std::mem::replace(row, ResourceSpec::new("", "", ""));
                    *row = typed.bind(bound, decls);
                }
                bind(typed, &mut row.children, offered);
            }
        }
        if rows.is_empty() {
            return;
        }
        let mut all = Vec::new();
        ids(rows, &mut all);
        let mut offered: std::collections::HashMap<String, Box<dyn std::any::Any>> =
            std::collections::HashMap::new();
        let mut spare: Option<Box<dyn std::any::Any>> = None;
        self.surfaces(&mut |surface| {
            for id in &all {
                if let Some(decls) = offered.get_mut(id.as_str()) {
                    surface.row_declarations(id, decls.as_mut());
                    continue;
                }
                let decls = spare.get_or_insert_with(|| self.typed.no_declarations());
                if surface.row_declarations(id, decls.as_mut())
                    && let Some(decls) = spare.take()
                {
                    offered.insert(id.clone(), decls);
                }
            }
        });
        bind(self.typed.as_ref(), rows, &mut offered);
    }

    /// The resource as published: its own actions and children, the edits
    /// views bound to where the user is, the live rows views and surfaces
    /// show, and the framework's operations every app answers.
    #[inline(never)]
    fn publication(&self) -> ResourceSpec {
        let _profile = tilo_resource::profiling::Phase::start("framework.publication");
        let state = self.typed.state();
        let mut tree = self.shared_document_tree(&*state).to_resource();
        if let Some(reason) = self.typed.unreadable() {
            // Read out of the last state that did read: the record publishes
            // why its document actions do not apply, never that state as the
            // one it holds.
            tilo_resource::withhold_document_actions(&mut tree, &reason);
        }
        self.decorate_publication(&*state, tree, Decoration::Tree)
    }

    /// What the live state holds: its revision and how much of the document
    /// it read ([`super::Live::loads`]).
    fn version(&self) -> (u64, u64) {
        (self.typed.revision(), self.typed.loads())
    }

    /// The document-owned part of what controls bind to: the live
    /// resource's identity and own actions, without its children, published
    /// without building a child, so it costs the same however many items
    /// the resource holds.
    #[inline(never)]
    fn binding_head(&self) -> BindingHead {
        let state = self.typed.state();
        let version = (self.version(), ui_core::i18n::I18nManager::revision());
        let epoch = self.typed.cache_epoch(&*state);
        let resource = if let Some(reason) = &self.typed.unreadable() {
            // The state is the last that read, not what the document holds,
            // so even the fields bound controls were bound to are no longer
            // offered: every document action says why it does not apply.
            let mut head = self
                .typed
                .head(self.dispatch.resource_id(), &self.label, &*state);
            tilo_resource::withhold_document_actions(&mut head, reason);
            head.actions
                .retain(|spec| spec.id != tilo_resource::FIELD_EDIT);
            Rc::new(head)
        } else if let Some(epoch) = &epoch {
            self.live_head(&*state, epoch)
        } else {
            let _profile = tilo_resource::profiling::Phase::start("framework.resource_head");
            Rc::new(
                self.typed
                    .head(self.dispatch.resource_id(), &self.label, &*state),
            )
        };
        BindingHead {
            version,
            epoch,
            resource,
        }
    }

    /// The head bound controls were last refreshed from, while it still
    /// holds: the resource may reuse its publication
    /// ([`Resource::publication_cache_epoch`]) and nothing it depends on
    /// moved since. A resource that may not is published afresh each sync.
    fn retained_head(&self) -> Option<BindingHead> {
        let head = self.binding_head.borrow_mut().take()?;
        let current = self.typed.cache_epoch(&*self.typed.state());
        (head.epoch.is_some() && head.epoch == current).then_some(head)
    }

    /// What bound controls look up ([`super::controls::Actions`]), as one
    /// resource: the published resource's identity and actions over `head`,
    /// exactly as [`Self::publication`] publishes them, without building or
    /// decorating its children.
    #[cfg(test)]
    fn binding_publication(&self, head: &BindingHead) -> ResourceSpec {
        let base = self.binding_base(head);
        let overlay = self.binding_overlay(&base);
        let mut resource = (*base.resource).clone();
        for spec in overlay {
            match resource.actions.iter_mut().find(|own| own.id == spec.id) {
                Some(own) => *own = spec,
                None => resource.actions.push(spec),
            }
        }
        resource
    }

    /// The part of what bound controls look up that only `head` and the
    /// framework decide: the head with the presentation's, the framework's
    /// and History's actions, as [`Self::decorate_publication`] adds them.
    /// Built once per head and kept, so a refresh shares it.
    fn binding_base(&self, head: &BindingHead) -> Rc<BindingBase> {
        let key = BaseKey {
            head: Rc::clone(&head.resource),
            locale: head.version.1,
            epoch: head.epoch.clone(),
            causal: self.typed.has_causal_drains(),
            unreadable: self.typed.unreadable(),
        };
        if let Some(base) = self
            .binding_base
            .borrow()
            .as_ref()
            .filter(|base| base.key == key)
        {
            return Rc::clone(base);
        }
        let mut resource = (*head.resource).clone();
        let head_len = resource.actions.len();
        resource = self.with_presentation_specs(resource);
        let shadow_len = resource.actions.len();
        resource = self.with_framework_specs(resource);
        if key.causal {
            mark_document_jobs(&mut resource);
        }
        if let Some(unreadable) = &key.unreadable {
            tilo_resource::withhold_document_actions(&mut resource, unreadable);
        }
        let base = Rc::new(BindingBase {
            key,
            resource: Rc::new(resource),
            head_len,
            shadow_len,
        });
        *self.binding_base.borrow_mut() = Some(Rc::clone(&base));
        base
    }

    /// What the views add over `base` now, as
    /// [`Self::decorate_publication`] adds it: the edits they bound, their
    /// availability, and the app's effects. Few actions, built per refresh.
    fn binding_overlay(&self, base: &BindingBase) -> Vec<tilo_actions::ActionSpec> {
        let state = self.typed.state();
        let bound = {
            let _profile = tilo_resource::profiling::Phase::start("framework.bound_declarations");
            self.typed.declarations(&*state)
        };
        let mut availability = Vec::new();
        self.surfaces(&mut |surface| {
            let _profile = tilo_resource::profiling::Phase::start("framework.surface_publication");
            availability.extend(surface.availability());
        });
        let own = base
            .resource
            .actions
            .get(..base.head_len)
            .unwrap_or_default();
        let shadows = base
            .resource
            .actions
            .get(..base.shadow_len)
            .unwrap_or_default();
        // The head's actions the edits bind over, refined where they say so.
        let ids = self.typed.declaration_ids(&*bound);
        let mut overlay = ResourceSpec::new("", "", "");
        overlay.actions = own
            .iter()
            .filter(|spec| ids.contains(&spec.id.as_str()))
            .cloned()
            .collect();
        overlay = self.typed.bind(overlay, bound);
        for status in &availability {
            if !overlay.actions.iter().any(|spec| spec.id == status.id())
                && let Some(spec) = own.iter().find(|spec| spec.id == status.id())
            {
                overlay.actions.push(spec.clone());
            }
            for spec in overlay
                .actions
                .iter_mut()
                .filter(|spec| spec.id == status.id())
            {
                status.overlay(spec);
            }
        }
        let effects = {
            let _profile = tilo_resource::profiling::Phase::start("framework.effect_specs");
            self.typed.effect_specs()
        };
        for spec in effects {
            let shadowed = shadows
                .iter()
                .chain(&overlay.actions)
                .any(|existing| existing.id == spec.id);
            debug_assert!(!shadowed, "effect `{}` shadows an action", spec.id);
            if shadowed {
                tracing::warn!(effect = spec.id, "effect shadows an action; not published");
                continue;
            }
            overlay.actions.push(spec);
        }
        if base.key.causal {
            mark_document_jobs(&mut overlay);
        }
        if let Some(unreadable) = &base.key.unreadable {
            tilo_resource::withhold_document_actions(&mut overlay, unreadable);
        }
        overlay.actions
    }

    /// Refresh the actions bound controls look up, reusing `head` while the
    /// live state and locale are those it was built at. Answers the head
    /// they were refreshed from.
    #[inline(never)]
    fn refresh_bindings(&self, head: Option<BindingHead>) -> BindingHead {
        let _profile = tilo_resource::profiling::Phase::start("framework.action_bindings");
        let version = (self.version(), ui_core::i18n::I18nManager::revision());
        let head = match head {
            Some(head) if head.version == version => head,
            _ => self.binding_head(),
        };
        let base = self.binding_base(&head);
        let overlay = self.binding_overlay(&base);
        // Read while the document did not: the fields these edits were bound
        // to are of the last state that read, not what it holds now.
        let overlay = if self.typed.unreadable().is_some() {
            overlay
                .into_iter()
                .filter(|spec| spec.id != tilo_resource::FIELD_EDIT)
                .collect()
        } else {
            overlay
        };
        self.action_bindings
            .update_shared(Rc::clone(&base.resource), overlay);
        head
    }

    /// [`Self::publication`] of the resource as `doc` holds it now, which a
    /// change from another window or participant may have moved past what
    /// this view last synced.
    #[inline(never)]
    fn current_publication(&self, doc: &AutoCommit) -> ResourceSpec {
        // The session keeps the record: there is no document here to read
        // the resource from, so what it publishes is the state the view
        // syncs from the reading (`one-app-model.md` §4).
        if !self.source.is_connection()
            && !self.typed.follows(doc)
            && let Ok(current) = self.typed.read(doc)
        {
            // Publication can run after an edit and before the view syncs.
            // Validate its nested views against this same state, rather than
            // withdrawing the new resource tree using the previous frame's
            // handler table. The next live revision replaces this cache.
            self.pin_nested_views(&*current);
            let reason = self.typed.unreadable();
            let mut tree = self.publication_of(&*current);
            if let Some(reason) = reason {
                tilo_resource::withhold_document_actions(&mut tree, &reason);
            }
            return tree;
        }
        self.publication()
    }

    #[inline(never)]
    fn publication_of(&self, state: &dyn std::any::Any) -> ResourceSpec {
        let _profile = tilo_resource::profiling::Phase::start("framework.publication");
        let tree = self.shared_document_tree(state).to_resource();
        self.decorate_publication(state, tree, Decoration::Tree)
    }

    /// Add to `resource`, the document-owned tree, what the view and the
    /// framework publish on it. [`Decoration::Actions`] decorates only the
    /// resource's own actions; its children stay as they are.
    #[inline(never)]
    fn decorate_publication(
        &self,
        state: &dyn std::any::Any,
        mut resource: ResourceSpec,
        decoration: Decoration,
    ) -> ResourceSpec {
        let children = decoration == Decoration::Tree;
        let bound = {
            let _profile = tilo_resource::profiling::Phase::start("framework.bound_declarations");
            self.typed.declarations(state)
        };
        let mut rows = Vec::new();
        let mut availability = Vec::new();
        self.surfaces(&mut |surface| {
            let _profile = tilo_resource::profiling::Phase::start("framework.surface_publication");
            availability.extend(surface.availability());
            if children {
                rows.extend(
                    surface
                        .live_rows()
                        .into_iter()
                        .map(super::LiveRow::into_resource),
                );
            }
        });
        resource = self.typed.bind(resource, bound);
        for status in &availability {
            for spec in resource
                .actions
                .iter_mut()
                .filter(|spec| spec.id == status.id())
            {
                status.overlay(spec);
            }
        }
        if children {
            merge(&mut resource.children, rows);
            let _profile = tilo_resource::profiling::Phase::start("framework.row_declarations");
            self.bind_row_declarations(&mut resource.children);
        }
        resource = self.with_presentation_specs(resource);
        // The app's own effects come before the framework's history and
        // render operations: an app answering `diff` its own way is asked.
        let effects = {
            let _profile = tilo_resource::profiling::Phase::start("framework.effect_specs");
            self.typed.effect_specs()
        };
        for spec in effects {
            let shadowed = resource
                .actions
                .iter()
                .any(|existing| existing.id == spec.id);
            debug_assert!(!shadowed, "effect `{}` shadows an action", spec.id);
            if shadowed {
                tracing::warn!(effect = spec.id, "effect shadows an action; not published");
                continue;
            }
            resource = resource.with_action(spec);
        }
        resource = self.with_framework_specs(resource);
        if self.typed.has_causal_drains() {
            mark_document_jobs(&mut resource);
        }
        if let Some(unreadable) = self.typed.unreadable() {
            tilo_resource::withhold_document_actions(&mut resource, &unreadable);
        }
        if children {
            // A record a view asked for and could not open is published
            // with its declared actions unavailable for why: nothing is
            // shown of it, so nothing but those is answered.
            resource.children.extend(self.storage.record_resources());
            resource.children.extend(self.storage.unavailable_records());
        }
        resource
    }

    /// `resource` with the view and effect operations of the app's
    /// presentation it does not offer itself.
    fn with_presentation_specs(&self, mut resource: ResourceSpec) -> ResourceSpec {
        for spec in &self.presentation {
            if spec.kind == tilo_actions::OperationKind::Document {
                continue;
            }
            if resource
                .actions
                .iter()
                .any(|existing| existing.id == spec.id)
            {
                continue;
            }
            resource = resource.with_action(spec.clone());
        }
        resource
    }

    /// `resource` with the framework's render, `read` and History actions it
    /// does not offer itself.
    fn with_framework_specs(&self, mut resource: ResourceSpec) -> ResourceSpec {
        let specs = framework_specs();
        let read = self.resource.readable.then_some(&specs.read);
        let facts = self.resource.facts.then_some(&specs.facts);
        let history = specs.history.iter().filter(|_| self.history);
        for spec in specs.native.iter().chain(read).chain(facts).chain(history) {
            if !resource
                .actions
                .iter()
                .any(|existing| existing.id == spec.id)
            {
                resource = resource.with_action(spec.clone());
            }
        }
        resource
    }

    /// Show why the record does not read as the resource instead of the
    /// view while it does not, never the last state as if it were current,
    /// and refuse submissions with the same reason.
    #[inline(never)]
    fn follow_readability(&mut self) {
        let reason = self.typed.unreadable();
        if self.unreadable.as_ref().map(|(shown, _)| shown) == reason.as_ref() {
            return;
        }
        self.dispatch.set_unreadable(reason.clone());
        self.unreadable = reason.map(|reason| {
            let shown: Element = Box::new(unreadable_state(&reason));
            (reason, shown)
        });
        self.swapped = true;
    }

    /// Follow the document when it moved — a local action, a
    /// collaborator's change, an undo or a restore — reading only what the
    /// change touched.
    ///
    /// Answers the document-owned head the bindings were refreshed from, for
    /// the refresh after the view synced to reuse.
    fn refresh(&self, doc: &AutoCommit) -> BindingHead {
        // The session keeps the record: the state follows the reading
        // (`sync_remote_state`), never a document this process lent an empty
        // pass (`one-app-model.md` §4).
        if !self.source.is_connection()
            && let Err(error) = self.typed.sync(doc)
        {
            tracing::warn!(%error, kind = self.resource.kind, "resource unreadable");
        }
        // Refresh the same declarations the host publishes before rebuilt
        // controls look up their bindings. Retained surface handles share it.
        let head = self.refresh_bindings(self.retained_head());
        self.typed.follow_change(doc, &self.followed);
        self.feeds.refresh(doc);
        self.typed.drain(self.typed.revision());
        head
    }
}

/// What [`ResourceRoot::new`] hands [`ResourceRoot::assemble`] of the view
/// it was built in.
struct Parts {
    alive: Rc<()>,
    dispatch: DispatchCore,
    saved: LocalState<RecordSaveStatus>,
    saves: super::saves::Saves,
    stages: Stages,
    feeds: super::history::HistoryFeeds,
    run: Run,
    storage: Rc<super::settings::ViewStorage>,
    content: Element,
    native_presentation: crate::runner::Presentation,
}

/// `widget`'s hosted surface, when it is one of the resource type
/// `resource`.
fn surface_mut(
    widget: &mut dyn Widget,
    resource: std::any::TypeId,
) -> Option<&mut (dyn SurfacePublication + 'static)> {
    capability_mut::<dyn SurfacePublication>(widget)
        .filter(|surface| surface.resource() == resource)
}

/// What [`ResourceRoot::binding_base`] is built from.
#[derive(Clone)]
struct BaseKey {
    head: Rc<ResourceSpec>,
    locale: u64,
    epoch: Option<String>,
    causal: bool,
    unreadable: Option<String>,
}

impl PartialEq for BaseKey {
    fn eq(&self, other: &Self) -> bool {
        Rc::ptr_eq(&self.head, &other.head)
            && self.locale == other.locale
            && self.epoch == other.epoch
            && self.causal == other.causal
            && self.unreadable == other.unreadable
    }
}

/// The shared part of what bound controls look up, at one [`BaseKey`].
struct BindingBase {
    key: BaseKey,
    resource: Rc<ResourceSpec>,
    /// How many of its actions are the head's own.
    head_len: usize,
    /// How many are the head's and the presentation's: what an effect of
    /// the same id would shadow.
    shadow_len: usize,
}

/// The framework's actions every app's resource offers unless it offers
/// them itself, at one locale.
struct FrameworkSpecs {
    native: Vec<tilo_actions::ActionSpec>,
    read: tilo_actions::ActionSpec,
    facts: tilo_actions::ActionSpec,
    history: Vec<tilo_actions::ActionSpec>,
}

thread_local! {
    static FRAMEWORK_SPECS: std::cell::RefCell<Option<(u64, Rc<FrameworkSpecs>)>> =
        const { std::cell::RefCell::new(None) };
}

/// [`FrameworkSpecs`] at the current locale, built once per locale on
/// each thread rather than on every publication.
fn framework_specs() -> Rc<FrameworkSpecs> {
    let locale = ui_core::i18n::I18nManager::revision();
    FRAMEWORK_SPECS.with_borrow_mut(|kept| {
        if let Some((at, specs)) = kept.as_ref()
            && *at == locale
        {
            return Rc::clone(specs);
        }
        let specs = Rc::new(FrameworkSpecs {
            native: with_native_presentations(ResourceSpec::new("", "", "")).actions,
            read: read_spec(),
            facts: facts::facts_spec(),
            history: super::history::specs(),
        });
        *kept = Some((locale, Rc::clone(&specs)));
        specs
    })
}

/// How much of a publication [`ResourceRoot::decorate_publication`] adds.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Decoration {
    /// The whole published tree: the resource's actions and its children.
    Tree,
    /// Only the resource's identity and own actions, which is all bound
    /// controls read.
    Actions,
}

/// The document-owned head of the publication, at the live version and
/// locale it was taken at.
#[derive(Clone)]
struct BindingHead {
    version: ((u64, u64), u64),
    /// [`Resource::publication_cache_epoch`] at the time.
    epoch: Option<String>,
    resource: Rc<ResourceSpec>,
}

/// `resource` without its children, cloning nothing of them.
#[cfg(all(test, not(target_arch = "wasm32")))]
fn without_children(resource: &ResourceSpec) -> ResourceSpec {
    let ResourceSpec {
        id,
        kind,
        label,
        presentation,
        semantic_identity,
        app_id,
        children: _,
        actions,
        views,
        readers,
        resource_type,
    } = resource;
    ResourceSpec {
        id: id.clone(),
        kind: kind.clone(),
        label: label.clone(),
        presentation: presentation.clone(),
        semantic_identity: semantic_identity.clone(),
        app_id: app_id.clone(),
        children: Vec::new(),
        actions: actions.clone(),
        views: views.clone(),
        readers: *readers,
        resource_type: resource_type.clone(),
    }
}

/// Visit the surface of type `S` the root of a resource app of `R` shows: for
/// a test, or a host that mounted the app, reaching the surface between
/// frames (`App::with_component_root` lends the root of a mounted one).
/// `None` when `root` is not such a root or shows no `S`.
pub fn with_surface<R: Resource, S: 'static, T>(
    root: &mut dyn std::any::Any,
    visit: impl FnOnce(&mut S) -> T,
) -> Option<T> {
    fn find<S: 'static>(widget: &mut dyn ui_core::widget::Widget) -> Option<&mut S> {
        if widget.as_any_mut().is_some_and(|any| any.is::<S>()) {
            return widget.as_any_mut()?.downcast_mut::<S>();
        }
        widget.children_mut().into_iter().find_map(find::<S>)
    }
    let root = root.downcast_mut::<ResourceRoot>()?;
    find::<S>(root.view_mut()).map(visit)
}

impl ui_core::widget::document_effects::DocumentEffects for ResourceRoot {
    fn start_document_effects(
        &mut self,
        operation: &ui_core::host_operation::ResourceOperation<'_>,
        applied: &ui_core::widget::document_effects::AppliedDocument<'_>,
    ) -> Result<Option<ui_core::host_operation::ResourceOperationStart>, String> {
        self.typed.start_document_effects(operation, applied)
    }
}

/// How many search entries are indexed away from the UI thread rather than
/// in the frame that asks for them.
const OFF_THREAD_ENTRIES: usize = 1024;

/// Whether `entries` are indexed away from the frame that asks for them.
///
/// Natively, a few short entries index in that frame: tantivy costs tens of
/// microseconds, and a build that landed at once saves the search a look
/// again. A page moves every build off the frame — its one thread runs the
/// toolkit's background queue between frames, so a build in the frame holds
/// the palette's first paint until it finishes. A set large enough to be
/// slow, or one carrying prose bodies, moves off the frame on either host.
fn indexes_off_frame(entries: &[SearchEntry]) -> bool {
    // Tests drive both rules on the host they run on.
    #[cfg(test)]
    if let Some(forced) = FORCE_OFF_FRAME.with(std::cell::Cell::get) {
        return forced;
    }
    crate::runner::IN_A_PAGE
        || entries.len() >= OFF_THREAD_ENTRIES
        || entries.iter().any(|entry| entry.body.is_some())
}

#[cfg(test)]
thread_local! {
    /// Tests set whether every build moves off the frame, as a page's does.
    pub(crate) static FORCE_OFF_FRAME: std::cell::Cell<Option<bool>> = const { std::cell::Cell::new(None) };
}

/// What the resource's search entries are of: a revision of the resource
/// and the entries its surfaces show.
#[derive(PartialEq)]
struct SearchState {
    revision: (u64, u64),
    shown: Vec<SearchEntry>,
}

/// An index search answers from, and the state it is of: none for the empty
/// index answering before the first one arrives.
struct AnsweringIndex {
    of: Option<SearchState>,
    indexed: Arc<IndexedEntries>,
}

/// An index being built away from the UI thread.
struct BuildingIndex {
    of: SearchState,
    generation: u64,
    arriving: std::sync::mpsc::Receiver<IndexedEntries>,
}

/// The resource's search index, built only when someone searches and at
/// most one at a time.
///
/// Every state is given its index's generation when first seen, before
/// anything is built: the action directory names that generation on every
/// frame, and the index a later search builds carries it.
#[derive(Default)]
pub(crate) struct SearchCache {
    answering: Option<AnsweringIndex>,
    building: Option<BuildingIndex>,
    /// The newest state nothing is built of yet, and its generation: built
    /// when the next search asks once no build is in flight.
    wanted: Option<(SearchState, u64)>,
    /// Entries a showing search waits on, and their state and generation:
    /// indexed once the build in flight lands.
    queued: Option<(SearchState, u64, Vec<SearchEntry>)>,
    /// A search is showing that waits on its surfaces' answers.
    watching: bool,
    /// The generation that holds the surfaces' answers to the latest query:
    /// the waiting search shows what an index this new or newer finds.
    answered: Option<u64>,
    next_generation: u64,
    /// How many indexes of entries have been started.
    #[cfg(test)]
    builds: usize,
}

impl SearchCache {
    fn reserve_generation(&mut self) -> u64 {
        let generation = self.next_generation;
        self.next_generation = generation.wrapping_add(1);
        generation
    }

    /// Answer from an index that finished building since last asked, and
    /// start the one a waiting search wants once nothing is in flight.
    fn receive(&mut self) {
        self.land();
        if self.building.is_none()
            && let Some((state, generation, entries)) = self.queued.take()
        {
            self.build(state, generation, entries);
        }
    }

    fn land(&mut self) {
        let Some(building) = self.building.take() else {
            return;
        };
        match building.arriving.try_recv() {
            Ok(indexed) => {
                self.answering = Some(AnsweringIndex {
                    of: Some(building.of),
                    indexed: Arc::new(indexed),
                });
            }
            Err(std::sync::mpsc::TryRecvError::Empty) => self.building = Some(building),
            // A lost build: its state is wanted afresh when next asked.
            Err(std::sync::mpsc::TryRecvError::Disconnected) => {}
        }
    }

    /// The generation of the index that answers for `state`, given now if
    /// `state` is new. Builds nothing.
    fn generation_for(&mut self, state: SearchState) -> u64 {
        self.receive();
        if let Some(answering) = &self.answering
            && answering.of.as_ref() == Some(&state)
        {
            return answering.indexed.generation;
        }
        if let Some(building) = &self.building
            && building.of == state
        {
            return building.generation;
        }
        if let Some((wanted, generation)) = &self.wanted
            && *wanted == state
        {
            return *generation;
        }
        let generation = self.reserve_generation();
        self.wanted = Some((state, generation));
        generation
    }

    /// Index `entries`, of `state`: in this frame when they are few, else
    /// away from the UI thread. The index search answers from now.
    ///
    /// A page never indexes in the frame that asks for it, however few the
    /// entries. Its one thread runs the toolkit's
    /// [`background`](ui_core::background) queue between frames, so a build
    /// in the frame holds the palette's first paint until it finishes, and
    /// indexing a window's content into tantivy there is what the page
    /// desk measured as the 14–57 s between typing and the first row, per
    /// app, moving with whichever window was opened last. A background job
    /// runs after the frame returns, so the ready rows paint at once and the
    /// content's rows join them when the index is built
    /// ([`SearchCache::building`], which the search showing polls for).
    fn build(
        &mut self,
        state: SearchState,
        generation: u64,
        entries: Vec<SearchEntry>,
    ) -> Arc<IndexedEntries> {
        #[cfg(test)]
        {
            self.builds = self.builds.saturating_add(1);
        }
        if indexes_off_frame(&entries) {
            let (send, arriving) = std::sync::mpsc::channel();
            let building = entries.clone();
            let spawned = ui_core::background::Background::current().spawn(
                "resource-search-index",
                move || {
                    let _ = send.send(IndexedEntries::built(building, generation));
                },
            );
            if spawned.is_ok() {
                self.building = Some(BuildingIndex {
                    of: state,
                    generation,
                    arriving,
                });
                return self.answering();
            }
        }
        let indexed = Arc::new(IndexedEntries::built(entries, generation));
        self.answering = Some(AnsweringIndex {
            of: Some(state),
            indexed: Arc::clone(&indexed),
        });
        indexed
    }

    /// Whether an index is being built off the frame for a state this cache
    /// was asked for: the search showing looks again shortly, so the rows the
    /// build finds are drawn when it lands.
    pub(crate) fn building(&mut self) -> bool {
        self.receive();
        self.building.is_some()
    }

    /// The index holding the surfaces' answers to the waiting search, once
    /// it is in.
    fn answer(&mut self) -> Option<Arc<IndexedEntries>> {
        self.receive();
        let wanted = self.answered?;
        self.answering
            .as_ref()
            .filter(|answering| answering.of.is_some() && answering.indexed.generation >= wanted)
            .map(|answering| Arc::clone(&answering.indexed))
    }

    /// The index search answers from now: the empty one until a first
    /// arrives.
    fn answering(&mut self) -> Arc<IndexedEntries> {
        if let Some(answering) = &self.answering {
            return Arc::clone(&answering.indexed);
        }
        let generation = self.reserve_generation();
        let indexed = Arc::new(IndexedEntries::built(Vec::new(), generation));
        self.answering = Some(AnsweringIndex {
            of: None,
            indexed: Arc::clone(&indexed),
        });
        indexed
    }
}

// The root is the app's view plus what the framework adds: it keeps the
// state current, publishes the resource, forwards edits and indexes search.
// Everything else — layout, input, traversal, operation admission — is the
// view's own, forwarded by the decorator.
impl RootModel for ResourceRoot {
    ui_core::provides!(dyn ui_core::undo::CommittedActions, dyn ui_core::history_mode::capability::DocumentHistory, dyn ui_core::widget::document_effects::DocumentEffects, dyn ui_core::widget::Collaborative, #[cfg(not(target_family = "wasm"))] dyn ui_core::component_lifecycle::WindowActivation; inner = content);

    fn view(&self) -> &(dyn Widget + 'static) {
        match &self.unreadable {
            Some((_, shown)) => shown.as_ref(),
            None => self.content.as_ref(),
        }
    }

    fn view_mut(&mut self) -> &mut (dyn Widget + 'static) {
        match &mut self.unreadable {
            Some((_, shown)) => shown.as_mut(),
            None => self.content.as_mut(),
        }
    }

    fn paints_ground(&self) -> bool {
        self.ground
    }

    fn take_structure_dirty(&mut self) -> bool {
        let swapped = std::mem::take(&mut self.swapped);
        self.view_mut().take_structure_dirty() || swapped
    }

    // Input is forwarded unchanged; model, storage and policy wakes remain
    // owned by the runner and still request their normal synchronization.
    fn view_only_scroll(&self, event: &ui_core::winit::event::WindowEvent) -> bool {
        self.content.view_only_scroll(event)
    }

    // The root adds no structure of its own beyond swapping its view for
    // the unreadable state: a change its view can describe stays described.
    fn take_structure_change(&mut self) -> ui_core::widget::StructureChange {
        let change = self.view_mut().take_structure_change();
        if std::mem::take(&mut self.swapped) {
            ui_core::widget::StructureChange::Rebuild
        } else {
            change
        }
    }

    fn record_owners(&self) -> Vec<ui_core::history_mode::HistoryOwner> {
        let mut owners = self.storage.person_owners();
        owners.extend(self.content.record_owners());
        owners
    }

    fn sync(&mut self, state: &AppModel, path: &ModelPath) {
        if self.source.is_connection() {
            // The session keeps the record: the view syncs from the reading
            // it publishes, and the document the host lends this pass holds
            // nothing of it (`one-app-model.md` §4). Everything the view
            // binds is still synced, over the state this root now holds.
            self.sync_remote_state();
            let empty = AutoCommit::new();
            self.sync_over(&empty, &automerge::ROOT);
            return;
        }
        let (state, path) = ui_core::doc::document_ref(state, path);
        self.sync_over(state, path);
    }

    fn settle(&mut self, edits: &mut ui_core::widget::Edits<'_>, path: &ui_core::automerge::ObjId) {
        self.typed.apply_settlements(edits);
        self.content.settle(edits, path);
        self.storage.settle();
    }

    fn draw(
        &mut self,
        scene: &mut Scene,
        transform: Affine,
        text: &mut TextRenderer,
        theme: &Theme,
        presence: &PresenceCtx,
    ) {
        self.paint_ground(scene, transform, theme, presence);
        self.content.draw(scene, transform, text, theme, presence);
        // The window drew: what its bar says of the save is seen.
        self.save.seen();
    }

    fn needs_redraw(&self) -> bool {
        self.native_presentation.needs_redraw()
            || self.content.needs_redraw()
            || self.save.needs_redraw(ui_core::time::now())
    }

    fn save_indicator(&self) -> &super::saves::SaveIndicator {
        &self.save
    }

    #[cfg(test)]
    fn save_indicator_mut(&mut self) -> &mut super::saves::SaveIndicator {
        &mut self.save
    }

    // A screenshot harness reaches the root to stage a scenario's view state
    // (`framework::stage`).
    fn as_any_mut(&mut self) -> &mut dyn std::any::Any {
        self
    }

    // The resource is the same for every participant (an agent task sees and
    // invokes the same actions); only the content's tree is per participant.

    // The undo boundary of a surface's immediate actions this event; the
    // host records one step per event and author.

    // A surface's step stays open for the actions that continue it (the
    // letters of a word), which report no boundary of their own.

    /// Resource and app presentation doors publish effect/view actions; their
    /// operation types must be in the retained handler table or publication
    /// withdraws the whole component surface.
    fn resource_operation_handlers(&self) -> HashSet<String> {
        let mut handlers = ui_core::host_operation::resource_operation_handlers(self.view());
        handlers.extend(
            crate::runner::operation_types()
                .iter()
                .map(|op| (*op).to_owned()),
        );
        handlers.insert(super::history::VIEW_TYPE.to_owned());
        handlers.insert(super::person::HISTORY_TYPE.to_owned());
        handlers.insert(super::record::RECORD_ACTION_TYPE.to_owned());
        handlers.insert(super::chain::CHAIN_ACTION_TYPE.to_owned());
        handlers.insert(tilo_resource::share::SHARE_TYPE.to_owned());
        handlers.insert(tilo_resource::share::SHARE_INVITE_TYPE.to_owned());
        if self.stages.opens() {
            handlers.insert(OPEN_TYPE.to_owned());
        }
        // Opening another app is routed by the host to the workspace
        // broker, whichever resource offers it.
        handlers.insert(tilo_actions::remote::ApplicationLaunch::TYPE.to_owned());
        // A resource reads itself when it says it does, and its items from
        // its record's table when it does not (`offer_item_reads`): the read
        // it publishes is always one it answers.
        if self.resource.readable || self.resource.record_table.is_some() {
            handlers.insert(READ_TYPE.to_owned());
        }
        if self.resource.facts {
            handlers.insert(facts::FACTS_TYPE.to_owned());
        }
        handlers.extend(
            self.typed
                .effect_operations()
                .into_iter()
                .map(str::to_owned),
        );
        for spec in (self.resource.local_operations)()
            .into_iter()
            .chain(self.presentation.iter().cloned())
        {
            if let Some(type_id) = &spec.operation_type {
                handlers.insert(type_id.clone());
            }
        }
        handlers.extend(self.nested_views().iter().cloned());
        handlers
    }

    fn poll_resource_operation(
        &mut self,
        invocation: tilo_actions::InvocationId,
        cancellation_requested: bool,
        doc: &AutoCommit,
        path: &ui_core::automerge::ObjId,
    ) -> Option<tilo_actions::InvocationUpdate> {
        if let Some((update, copied)) = self.share.poll(invocation, cancellation_requested) {
            if copied && let tilo_actions::InvocationUpdate::Succeeded { output, .. } = &update {
                self.dispatch
                    .note_landed(tilo_resource::share::SHARE_LINK, output);
            }
            return Some(update);
        }
        self.typed
            .poll_effect(
                invocation,
                cancellation_requested,
                effect_view(&mut self.unreadable, &mut self.content),
            )
            .or_else(|| {
                with_app_view_mut(&mut self.content, |view| {
                    ui_core::host_operation::poll_resource_operation(
                        view,
                        invocation,
                        cancellation_requested,
                        doc,
                        path,
                    )
                })
            })
    }

    fn start_operation(
        &mut self,
        op: &ui_core::host_operation::ResourceOperation<'_>,
        doc: &mut ui_core::widget::Edits<'_>,
        path: &ui_core::automerge::ObjId,
    ) -> Result<Option<ui_core::host_operation::ResourceOperationStart>, String> {
        // A view of a resource the system asked for: show that item first, so
        // the picture is of the item and not of whatever the window happened
        // to show. `render` is the app's answer to "show me this resource".
        if let Some(request) = op.unscoped()
            && request.type_id == crate::runner::RENDER_TYPE
            && !request.payload.is_empty()
            && let Some(anchor) = crate::runner::rendered_anchor(request.payload)
        {
            self.stages.open(&anchor)?;
        }
        if let Some(output) = with_app_view_mut(&mut self.content, |view| {
            self.native_presentation.start_operation(op, doc, view)
        })? {
            return Ok(Some(
                ui_core::host_operation::ResourceOperationStart::Completed(output),
            ));
        }
        if (self.resource.readable || self.resource.record_table.is_some())
            && let Some(request) = op.unscoped()
            && request.type_id == READ_TYPE
        {
            let output = read(
                self.typed.as_ref(),
                &self.resource,
                &*self.typed.state(),
                doc,
                request.payload,
            )?;
            return Ok(Some(
                ui_core::host_operation::ResourceOperationStart::Completed(output),
            ));
        }
        if self.resource.facts
            && let Some(request) = op.unscoped()
            && request.type_id == facts::FACTS_TYPE
        {
            let output = facts::answer(
                self.typed.as_ref(),
                &*self.typed.state(),
                doc,
                request.payload,
            )?;
            return Ok(Some(
                ui_core::host_operation::ResourceOperationStart::Completed(output),
            ));
        }
        if let Some(request) = op.unscoped()
            && super::share_link::handles(request.type_id)
        {
            return self.start_share(request.invocation, request.payload);
        }
        if let Some(request) = op.unscoped()
            && request.type_id == OPEN_TYPE
        {
            let args: serde_json::Value =
                tilo_actions::decode_json(request.payload).map_err(|error| error.to_string())?;
            let anchor = args
                .get(OPEN_ANCHOR)
                .and_then(serde_json::Value::as_str)
                .ok_or_else(|| "open needs the anchor of an item".to_owned())?;
            self.stages.open(anchor)?;
            return Ok(Some(
                ui_core::host_operation::ResourceOperationStart::Completed(
                    tilo_actions::ActionOutput::default(),
                ),
            ));
        }
        if let Some(output) = self.start_record_operation(op, doc)? {
            return Ok(Some(
                ui_core::host_operation::ResourceOperationStart::Completed(output),
            ));
        }
        // An effect reads the resource as the document stands, though no
        // frame has run since a collaborator's change arrived.
        if let Err(error) = self.typed.sync(doc) {
            tracing::warn!(%error, kind = self.resource.kind, "resource unreadable");
        }
        if let Some(started) = self.typed.start_effect(
            op,
            doc.doc(),
            effect_view(&mut self.unreadable, &mut self.content),
        )? {
            return Ok(Some(started));
        }
        if let Some(started) =
            ui_core::host_operation::start_operation(self.view_mut(), op, doc, path)?
        {
            return Ok(Some(started));
        }
        Ok(self.start_catalogue_view(op))
    }
}

impl ResourceRoot {
    /// The record-level requests every framework app answers the same way:
    /// its history at a version, an operation on one of its records or its
    /// chain of parts, and the person's own record history.
    fn start_record_operation(
        &self,
        op: &ui_core::host_operation::ResourceOperation<'_>,
        doc: &mut ui_core::widget::Edits<'_>,
    ) -> Result<Option<tilo_actions::ActionOutput>, String> {
        let Some(request) = op.unscoped() else {
            return Ok(None);
        };
        let output = if request.type_id == super::history::VIEW_TYPE {
            super::history::answer(doc, request.payload)?
        } else if request.type_id == super::record::RECORD_ACTION_TYPE {
            self.storage
                .record_action(self.dispatch.me(), request.payload)?
        } else if request.type_id == super::chain::CHAIN_ACTION_TYPE {
            self.storage
                .chain_action(self.dispatch.me(), request.payload, doc)?
        } else if request.type_id == super::person::HISTORY_TYPE {
            self.storage.person_history(request.payload)?
        } else {
            return Ok(None);
        };
        Ok(Some(output))
    }

    /// What the resource's search entries are of now, and the surfaces'
    /// query sinks. What the surfaces show (a page's text, live rows)
    /// changes on its own, beside the resource's revision.
    fn search_state(&self) -> (SearchState, Vec<super::publishing::SearchQueries>) {
        let mut shown = Vec::new();
        let mut queries = Vec::new();
        self.surfaces(&mut |surface| {
            shown.extend(surface.search_entries());
            queries.extend(surface.search_queries());
        });
        let state = SearchState {
            revision: self.version(),
            shown,
        };
        (state, queries)
    }

    /// The index search answers `state` from, building it if nothing is. A
    /// large set of entries (a browsing history, a store catalogue) or one
    /// with prose bodies (whole books) is indexed away from the UI thread,
    /// one build at a time: until the index of `state` arrives, search
    /// answers from the one before it, and states that come and go while a
    /// build is in flight cost only the newest one's build after it.
    fn current_search_index(&self, state: SearchState) -> Arc<IndexedEntries> {
        let mut cache = self.search.borrow_mut();
        let generation = cache.generation_for(state);
        if let Some(answering) = &cache.answering
            && answering.of.is_some()
            && answering.indexed.generation == generation
        {
            return Arc::clone(&answering.indexed);
        }
        if cache.building.is_some() {
            return cache.answering();
        }
        let Some((state, generation)) = cache.wanted.take() else {
            return cache.answering();
        };
        let entries = self.entries_of(&state);
        cache.build(state, generation, entries)
    }

    /// Whether the surfaces' secrets are unlocked: locked when any surface
    /// says so, unlocked when one says so and none disagrees, else unsaid.
    fn secrets_unlocked(&self) -> Option<bool> {
        let mut said = None;
        self.surfaces(&mut |surface| match surface.secrets_unlocked() {
            Some(false) => said = Some(false),
            Some(true) if said.is_none() => said = Some(true),
            _ => {}
        });
        said
    }

    /// Everything search finds in `state`: the resource's entries and what
    /// its surfaces show.
    fn entries_of(&self, state: &SearchState) -> Vec<SearchEntry> {
        let mut entries = self.typed.search(&*self.typed.state());
        entries.extend(state.shown.iter().cloned());
        entries
    }

    /// A search that waits on its surfaces' answers (a server still
    /// looking) gets an index of what they show once every one of them has
    /// answered the latest query.
    fn follow_search(&self) {
        if !self.search.borrow().watching {
            return;
        }
        let mut answering = false;
        self.surfaces(&mut |surface| {
            answering |= surface
                .search_queries()
                .is_some_and(|queries| queries.answering());
        });
        if answering {
            return;
        }
        let (state, _) = self.search_state();
        let mut cache = self.search.borrow_mut();
        cache.watching = false;
        let generation = cache.generation_for(state);
        cache.answered = Some(generation);
        if cache.building.is_some() {
            // Indexed once the build in flight lands.
            if let Some((state, wanted)) = cache.wanted.take() {
                let entries = self.entries_of(&state);
                cache.queued = Some((state, wanted, entries));
            }
            return;
        }
        if let Some((state, wanted)) = cache.wanted.take() {
            let entries = self.entries_of(&state);
            cache.build(state, wanted, entries);
        }
    }
}

impl ResourceRoot {
    fn start_catalogue_view(
        &self,
        op: &ui_core::host_operation::ResourceOperation<'_>,
    ) -> Option<ui_core::host_operation::ResourceOperationStart> {
        // View openers from the resource/presentation catalogue and from its
        // nested resources (e.g. a rich-text body's `tilo.rich-text.view`
        // editor/compact) are already mounted; accept them so agents and
        // Ctrl+K can switch without a missing-handler fault.
        let request = op.unscoped()?;
        if request.kind != tilo_actions::OperationKind::View {
            return None;
        }
        let known = (self.resource.local_operations)()
            .into_iter()
            .chain(self.presentation.iter().cloned())
            .any(|spec| spec.operation_type.as_deref() == Some(request.type_id))
            || self.nested_views().contains(request.type_id);
        known.then(|| {
            ui_core::host_operation::ResourceOperationStart::Completed(
                tilo_actions::ActionOutput::default(),
            )
        })
    }

    /// Start minting a link to one of the resources this root publishes.
    fn start_share(
        &mut self,
        invocation: tilo_actions::InvocationId,
        payload: &[u8],
    ) -> Result<Option<ui_core::host_operation::ResourceOperationStart>, String> {
        let record = self
            .run
            .launched
            .record
            .as_ref()
            .map(|record| record.as_str().to_owned());
        let publisher = super::share_link::Publisher {
            app: self.dispatch.app_id(),
            record: record.as_deref(),
            root: self.dispatch.resource_id(),
        };
        let may_invite = self.dispatch.may_invite();
        let started = self
            .share
            .start(invocation, payload, &publisher, may_invite)?;
        Ok(Some(match started {
            Some(minted) => {
                if minted.copied {
                    self.dispatch
                        .note_landed(tilo_resource::share::SHARE_LINK, &minted.output);
                }
                ui_core::host_operation::ResourceOperationStart::Completed(minted.output)
            }
            None => ui_core::host_operation::ResourceOperationStart::Accepted,
        }))
    }
}

// The root's own clients for the action door (minting links, opening
// references) share the app's collaboration connection with whatever the
// view keeps there.
impl ui_core::widget::Collaborative for ResourceRoot {
    fn take_collab_requests(&mut self) -> Vec<ui_core::collaboration::CollabRequest> {
        let mut requests =
            ui_core::widget::Collaborative::take_collab_requests(self.share.remote_mut());
        if let Some(mut door) = self.dispatch.opener.door() {
            requests.extend(ui_core::widget::Collaborative::take_collab_requests(
                &mut door,
            ));
        }
        with_app_view_mut(&mut self.content, |view| {
            if let Some(content) = capability_mut::<dyn ui_core::widget::Collaborative>(view) {
                requests.extend(content.take_collab_requests());
            }
        });
        requests
    }

    fn handle_collab_event(&mut self, event: &ui_core::collaboration::CollabEvent) {
        ui_core::widget::Collaborative::handle_collab_event(self.share.remote_mut(), event);
        if let Some(mut door) = self.dispatch.opener.door() {
            ui_core::widget::Collaborative::handle_collab_event(&mut door, event);
        }
        with_app_view_mut(&mut self.content, |view| {
            if let Some(content) = capability_mut::<dyn ui_core::widget::Collaborative>(view) {
                content.handle_collab_event(event);
            }
        });
    }
}

impl RootSearch for ResourceRoot {
    fn search_providers(&self) -> Vec<Box<dyn SearchProvider>> {
        // The index is rebuilt only when the resource or what its surfaces
        // show moved since the last one.
        let (state, queries) = self.search_state();
        let indexed = self.current_search_index(state);
        // The app's one search source: what its content widgets show beside
        // the resource reaches it as their surfaces' entries, never as a
        // provider of their own.
        let mut source = ResourceSearch::new(self.resource.label, self.dispatch.app_id(), indexed);
        source.scopes = self.typed.search_scopes(&*self.typed.state());
        source.queries = queries;
        // A person who may not read the record is found nothing of it.
        source.readable = self.dispatch.may_read();
        source.live = Some(LiveSearch {
            cache: Rc::clone(&self.search),
            answered: std::cell::RefCell::new(None),
        });
        source.opens = self
            .stages
            .opens()
            .then(|| tilo_actions::ActionAddress::new(self.dispatch.resource_id(), "open"));
        vec![Box::new(source)]
    }

    /// The one source [`Self::search_providers`] makes, named with the
    /// generation its index has or will have once someone searches: the
    /// action directory reads this on every frame, and indexing whole books
    /// per keystroke for a search nobody runs is what it must not cost.
    fn search_provider_descriptors(
        &self,
    ) -> Vec<ui_core::search::capability::SearchProviderDescriptor> {
        let (state, _) = self.search_state();
        let generation = self.search.borrow_mut().generation_for(state);
        vec![ui_core::search::capability::SearchProviderDescriptor::new(
            self.resource.label,
            Some(generation),
            // `ResourceSearch` keeps the provider default.
            ui_core::widget::ActionDirectoryInvocationDomain::Unsupported,
        )]
    }

    /// The resource's entries and what its surfaces show, as of the same
    /// generation the action directory names, with whether the surfaces'
    /// secrets are unlocked.
    fn search_index_state(&self) -> Option<ui_core::search::index_publication::IndexState> {
        let (state, _) = self.search_state();
        let generation = self.search.borrow_mut().generation_for(state);
        Some(ui_core::search::index_publication::IndexState {
            generation,
            secrets_unlocked: self.secrets_unlocked(),
        })
    }

    /// Every entry a hit can open, as the session's persistent index keeps
    /// it: short metadata only, never a prose body. A view that keeps its
    /// entries out of the index
    /// ([`Publishes::search_entries_while_running`](super::Publishes::search_entries_while_running))
    /// contributes none.
    fn search_index_entries(&self) -> Vec<ui_core::search::index_publication::IndexEntry> {
        let mut entries = self.typed.search(&*self.typed.state());
        self.surfaces(&mut |surface| {
            if surface.kept_in_search_index() {
                entries.extend(surface.search_entries());
            }
        });
        entries.iter().filter_map(index_entry).collect()
    }

    /// A picked hit opens the app at its anchor: the views registered with
    /// `on_open` show it, then any hit the content provided reaches it.
    fn activate_search_result(
        &mut self,
        action_id: &str,
        doc: &mut ui_core::widget::Edits<'_>,
        path: &ModelPath,
    ) {
        if self.stages.open(action_id).is_err() {
            with_app_view_mut(&mut self.content, |view| {
                ui_core::search::capability::activate_search_result(view, action_id, doc, path);
            });
        }
    }
}

impl RootPublishes for ResourceRoot {
    fn resources(&self, doc: &AutoCommit) -> Vec<ResourceSpec> {
        RootPublishes::resources_for(self, None, doc)
    }
    fn shared_resources_for(
        &self,
        participant: Option<&tilo_actions::ParticipantId>,
        doc: &AutoCommit,
    ) -> Option<Vec<ui_core::published::SharedResource>> {
        self.shared_resources(participant, doc)
    }
    fn resources_for(
        &self,
        participant: Option<&tilo_actions::ParticipantId>,
        doc: &AutoCommit,
    ) -> Vec<ResourceSpec> {
        // What surfaces bind to where someone is, they bind to this
        // participant's view.
        let _viewer = participant
            .cloned()
            .map(ui_core::invocation_scope::ViewerScope::enter);
        let mut resource = self.current_publication(doc);
        // The content may add live external entities beside the resource,
        // never a document action: those are the resource's own. One naming
        // the resource joins it rather than publishing it twice.
        let mut extras = Vec::new();
        for extra in ui_core::resources::resources_for(self.app_view(), participant, doc) {
            let extra = outside_document(extra);
            if extra.id == resource.id {
                join(&mut resource, extra);
            } else {
                extras.push(extra);
            }
        }
        if self.stages.opens()
            && !resource
                .actions
                .iter()
                .any(|existing| existing.id == "open")
        {
            resource = resource.with_action(open_spec());
        }
        if self.stages.opens() {
            offer_item_open(self.resource.opens_as_item, &mut resource);
        }
        if let Some(table) = self.resource.record_table {
            offer_item_reads(&mut resource, table, self.resource.kind);
        }
        let mut resources = vec![resource];
        resources.append(&mut extras);
        resources
    }
    fn resource(&self, doc: &AutoCommit, id: &str) -> Option<ResourceSpec> {
        RootPublishes::resource_for(self, None, doc, id)
    }
    /// A live row a surface is still reading.
    fn resource_pending(&self, id: &str) -> bool {
        let mut pending = false;
        self.surfaces(&mut |surface| pending = pending || surface.live_row_pending(id));
        pending
    }
    /// Resource `id` in the published tree, or one the tree leaves out: a
    /// child the resource resolves by id, or a live row a surface resolves.
    fn resource_for(
        &self,
        participant: Option<&tilo_actions::ParticipantId>,
        doc: &AutoCommit,
        id: &str,
    ) -> Option<ResourceSpec> {
        let _viewer = participant
            .cloned()
            .map(ui_core::invocation_scope::ViewerScope::enter);
        // A change from another window or participant may not have reached
        // this view yet: an item it removed is gone, one it made is there.
        if let Some(published) = find(&[self.current_publication(doc)], id) {
            return Some(published);
        }
        let current = if self.typed.follows(doc) {
            None
        } else {
            self.typed.read(doc).ok()
        };
        let state = current.unwrap_or_else(|| self.typed.state());
        let mut child = self.typed.child(&*state, doc, id);
        if self.resource.readable
            && let Some(child) = &mut child
        {
            offer_document_reads(child, &|id| self.typed.document_child(&*state, id));
        }
        let mut row = None;
        self.surfaces(&mut |surface| {
            if row.is_none() {
                row = surface.live_row(id).map(super::LiveRow::into_resource);
            }
        });
        // An item past the published page is resolved on its own, and the row
        // a surface shows for it joins it as it does in the page.
        let resolved = match (child, row) {
            (Some(mut child), Some(row)) => {
                join(&mut child, row);
                Some(child)
            }
            (child, row) => child.or(row),
        };
        if let Some(mut resolved) = resolved {
            self.bind_row_declarations(std::slice::from_mut(&mut resolved));
            if self.stages.opens() {
                offer_item_open(self.resource.opens_as_item, &mut resolved);
            }
            return Some(resolved);
        }
        // Last, what the content resolves by id beyond what it publishes (a
        // place, a record past the published page), without a document
        // action: those are the resource's own.
        ui_core::resources::resource_for(self.app_view(), None, doc, id)
            .map(super::rows::resolved_outside_document)
    }
    fn document_action_result(
        &self,
        doc: &AutoCommit,
        address: &tilo_actions::ActionAddress,
        changes: &[ui_core::automerge::Patch],
    ) -> Option<serde_json::Value> {
        // The record's own actions, and its verbs bound on its items.
        if address.resource == self.dispatch.resource_id()
            || (self.resource.item_of)(address.resource.as_str())
        {
            if super::history::is_edit(&address.action) {
                return super::history::result(&address.action, doc, changes);
            }
            // What the action minted rides beside its own answer, the
            // resource's or else its surface's. An answer that is not an
            // object (an editor's summary naming the blocks it made) already
            // says what it made and is kept as it is.
            let minted = tilo_resource::take_minted();
            let answer = self
                .typed
                .answer(doc, &address.action, changes)
                .or_else(|| {
                    ui_core::resources::document_action_result(
                        self.app_view(),
                        doc,
                        address,
                        changes,
                    )
                });
            return match answer {
                _ if minted.is_empty() => answer,
                Some(serde_json::Value::Object(mut fields)) => {
                    fields.insert("minted".into(), minted.into());
                    Some(serde_json::Value::Object(fields))
                }
                Some(other) => Some(other),
                None => Some(serde_json::json!({ "minted": minted })),
            };
        }
        ui_core::resources::document_action_result(self.app_view(), doc, address, changes)
    }
}

// The root owns the file whose history it shows beside the resource's (the
// runner checks the source it registered is this root's); everything else
// about History is its content's, as before.
impl ui_core::history_mode::capability::DocumentHistory for ResourceRoot {
    fn history_registration(
        &self,
    ) -> Result<
        Option<ui_core::history_mode::HistoryRegistration>,
        ui_core::history_mode::HistoryRegistrationError,
    > {
        match &self.run.file_history {
            Some((source, definition)) => {
                let scopes = definition.scopes.iter().map(|scope| {
                    ui_core::history_mode::HistorySourceRegistration::CheckedFiles {
                        scope: scope.key,
                        source: source.clone(),
                    }
                });
                ui_core::history_mode::HistoryRegistration::new(definition, scopes.collect())
                    .map(Some)
            }
            None => ui_core::history_mode::capability::history_registration(self.app_view()),
        }
    }

    fn history_restore_readiness(&self, scope: &str) -> Result<(), String> {
        ui_core::widget::capability::capability::<
            dyn ui_core::history_mode::capability::DocumentHistory,
        >(self.app_view())
        .map_or(Ok(()), |content| content.history_restore_readiness(scope))
    }

    fn document_history_definition(
        &self,
    ) -> Option<&'static ui_core::history_mode::HistoryDefinition> {
        ui_core::history_mode::capability::document_history_definition(self.app_view())
    }

    fn physical_text_policy(
        &self,
        previous: Option<&tilo_actions::EncodedAction>,
        next: &tilo_actions::EncodedAction,
    ) -> (bool, bool) {
        self.typed.text_policy(previous, next)
    }

    fn document_action_applied(
        &mut self,
        action: &tilo_actions::EncodedAction,
        before: &[ui_core::automerge::ChangeHash],
        doc: &ui_core::automerge::AutoCommit,
        path: &ui_core::automerge::ObjId,
    ) {
        // An action a participant took (an agent's verb) leaves them where
        // the resource says it lands, once the state follows it.
        if let Some(participant) = ui_core::invocation_scope::current_participant() {
            self.typed.note_applied(&participant, action);
        }
        with_app_view_mut(&mut self.content, |view| {
            if let Some(content) = ui_core::widget::capability::capability_mut::<
                dyn ui_core::history_mode::capability::DocumentHistory,
            >(view)
            {
                content.document_action_applied(action, before, doc, path);
            }
        });
    }
}

impl ui_core::undo::CommittedActions for ResourceRoot {
    fn take_committed_action(&mut self) -> Option<Vec<ui_core::automerge::ChangeHash>> {
        self.dispatch.take_committed()
    }
    fn keeps_undo_step_open(&self) -> bool {
        self.dispatch.keeps_step_open()
    }
}

impl RootApp for ResourceRoot {
    fn app_kind(&self) -> AppKind {
        AppKind::Editor
    }

    fn app_title(&self) -> &str {
        self.title
    }

    fn app_icon(&self) -> IconDescriptor {
        self.icon.clone()
    }

    fn device_shell_operation(
        &mut self,
        operation: &ui_core::floating_surface::DeviceShellOperation,
    ) -> Result<serde_json::Value, String> {
        fn perform(
            widget: &mut dyn Widget,
            resource: std::any::TypeId,
            operation: &ui_core::floating_surface::DeviceShellOperation,
        ) -> Option<Result<serde_json::Value, String>> {
            if let Some(surface) = surface_mut(widget, resource)
                && surface.supports_device_shell()
            {
                return Some(surface.device_shell_operation(operation));
            }
            widget
                .children_mut()
                .into_iter()
                .find_map(|child| perform(child, resource, operation))
        }
        perform(self.content.as_mut(), self.resource.id, operation)
            .unwrap_or_else(|| Err("Terminal is not available".into()))
    }

    fn request_device_shell(&mut self) -> bool {
        fn request(widget: &mut dyn Widget, resource: std::any::TypeId) -> bool {
            if let Some(surface) = surface_mut(widget, resource)
                && surface.request_device_shell()
            {
                return true;
            }
            widget
                .children_mut()
                .into_iter()
                .any(|child| request(child, resource))
        }
        request(self.content.as_mut(), self.resource.id)
    }

    fn take_host_intent(&mut self) -> Option<ui_core::widget::AppHostIntent> {
        fn take(
            widget: &mut dyn Widget,
            resource: std::any::TypeId,
        ) -> Option<ui_core::widget::AppHostIntent> {
            if let Some(surface) = surface_mut(widget, resource)
                && let Some(intent) = surface.take_host_intent()
            {
                return Some(intent);
            }
            // A view whose app runs elsewhere asks through its own door.
            if let Some(intent) = ui_core::component_lifecycle::take_host_intent(widget) {
                return Some(intent);
            }
            widget
                .children_mut()
                .into_iter()
                .find_map(|child| take(child, resource))
        }
        take(self.content.as_mut(), self.resource.id)
    }

    fn take_save_retry(&mut self) -> bool {
        self.save.take_record_retry()
    }

    fn record_save_status(&mut self, status: RecordSaveStatus) {
        self.save.record(&status, ui_core::time::now());
        self.saved.set(status);
    }

    // The workspace refused what this record sent, and the record withdrew it:
    // the view shows the stored state again, and the action reads as
    // refused, as one this device refused does.
    fn record_refused(&mut self, refusal: &ui_core::record::RecordRefusal) {
        self.dispatch.refuse_by_workspace(refusal);
        self.typed.represent();
    }

    fn take_notices(&mut self) -> Vec<String> {
        self.dispatch.take_notices()
    }

    fn record_said(&mut self, text: &str) {
        self.dispatch.kept(text);
    }

    // A surface that keeps presentation of its own across restarts (the
    // open item, the caret) saves it as the window's.
    fn capture_application_view(&self) -> Result<Option<ApplicationLocalView>, ThawError> {
        capability::<dyn ApplicationViewState>(self.app_view())
            .map_or(Ok(None), ApplicationViewState::capture_application_view)
    }

    fn restore_application_view(
        &mut self,
        local: &ApplicationLocalView,
        doc: &AutoCommit,
    ) -> Result<ApplicationFocusRestore, ThawError> {
        with_app_view_mut(&mut self.content, |view| {
            match capability_mut::<dyn ApplicationViewState>(view) {
                Some(view) => view.restore_application_view(local, doc),
                None => Err(ThawError::State(
                    "application-local restoration unsupported".into(),
                )),
            }
        })
    }

    fn finish_application_view_restore(&mut self) -> Result<(), ThawError> {
        with_app_view_mut(&mut self.content, |view| {
            capability_mut::<dyn ApplicationViewState>(view).map_or(
                Ok(()),
                ApplicationViewState::finish_application_view_restore,
            )
        })
    }
}

#[cfg(test)]
mod index_entry_tests;

#[cfg(test)]
#[cfg(not(target_arch = "wasm32"))]
mod search_tests;

/// What a window shows instead of the app's view while its record does not
/// read as the resource: what happened and what to do, in the person's
/// words, with the reason the record was refused (a path and a missing
/// value) behind the state's "Details".
fn unreadable_state(reason: &str) -> ui_core::widget::EmptyState {
    ui_core::widget::EmptyState::new(ui_core::i18n::I18nManager::lookup_plain(
        "framework-unreadable",
    ))
    .with_icon(ui_core::icons::Icon::CircleAlert)
    .with_message(ui_core::i18n::I18nManager::lookup_plain(
        "framework-unreadable-hint",
    ))
    .with_details(reason)
}

/// The window of a record that did not read as the resource when it was
/// opened: why, instead of the app's view, and the resource's actions
/// published as unavailable for that reason.
pub(crate) struct Unopened {
    title: &'static str,
    icon: IconDescriptor,
    /// What it publishes: the resource's declared actions, every document
    /// one unavailable for the reason.
    resource: ResourceSpec,
    shown: ui_core::widget::EmptyState,
}

impl Unopened {
    /// The window of a record that does not read as the resource of
    /// `kind` and `label`, whose actions are `declarations`.
    pub(crate) fn new(
        title: &'static str,
        icon: IconDescriptor,
        (kind, label): (&'static str, &'static str),
        declarations: &[tilo_resource::Declaration],
        reason: &str,
    ) -> Self {
        let mut resource =
            ResourceSpec::new(kind, kind, tilo_resource::label::localized(kind, label));
        for decl in declarations {
            resource = resource.with_action(tilo_resource::declaration_spec(decl));
        }
        tilo_resource::withhold_document_actions(&mut resource, reason);
        Self {
            title,
            icon,
            shown: unreadable_state(reason),
            resource,
        }
    }
}

impl Unopened {
    /// The window as a host mounts it, its widget table compiled once for
    /// every app.
    pub(crate) fn boxed(self) -> Box<dyn AppWidget> {
        Box::new(self)
    }
}

impl Decorator for Unopened {
    ui_core::provides!(dyn ui_core::resources::PublishesResources);

    type Inner = ui_core::widget::EmptyState;

    fn inner(&self) -> &ui_core::widget::EmptyState {
        &self.shown
    }

    fn inner_mut(&mut self) -> &mut ui_core::widget::EmptyState {
        &mut self.shown
    }
}

impl ui_core::resources::PublishesResources for Unopened {
    fn resources(&self, _doc: &AutoCommit) -> Vec<ResourceSpec> {
        vec![self.resource.clone()]
    }
}

impl AppWidget for Unopened {
    fn app_kind(&self) -> AppKind {
        AppKind::Editor
    }

    fn app_title(&self) -> &str {
        self.title
    }

    fn app_icon(&self) -> IconDescriptor {
        self.icon.clone()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use ui_core::search::{DEFAULT_SEARCH_RESULT_LIMIT, SearchQuery};

    #[test]
    fn child_document_reads_are_bound_to_their_own_resource() {
        let mut child = ResourceSpec::new("book/page/body", "text", "Body");
        child.children.push(ResourceSpec::new(
            "private-child",
            "account",
            "Secret account",
        ));
        offer_document_reads(&mut child, &|id| id == "book/page/body");
        assert!(
            child.children[0].actions.is_empty(),
            "eligibility is not inherited"
        );
        let read = &child.actions[0];
        assert!(read.contract.reads_document());
        let encoded = read.build_json(&serde_json::Map::new()).unwrap();
        assert_eq!(encoded.type_id, READ_TYPE);
        let payload: serde_json::Value = tilo_actions::decode_json(&encoded.payload).unwrap();
        assert_eq!(payload["item"], "book/page/body");
        assert!(
            read.build_json(
                serde_json::json!({"item": "another/book"})
                    .as_object()
                    .unwrap()
            )
            .is_err()
        );
        let encoded = read
            .build_json(serde_json::json!({"version": "past"}).as_object().unwrap())
            .unwrap();
        let payload: serde_json::Value = tilo_actions::decode_json(&encoded.payload).unwrap();
        assert_eq!(payload["item"], "book/page/body");
        assert_eq!(payload["version"], "past");
    }

    /// The ids the framework keeps are the ones it publishes on every
    /// app: the generic actions, `open`, `read`, history and presentation.
    #[test]
    fn the_reserved_ids_are_what_the_framework_publishes() {
        let reserved = reserved_action_ids();
        for id in [
            "apply",
            "group",
            "field-edit",
            "open",
            "read",
            "undo",
            "redo",
            "restore",
            "restore-reviewed",
            "review-restore",
            "checkpoint",
            "history",
            "diff",
            "render",
        ] {
            assert!(
                reserved.iter().any(|kept| kept == id),
                "{id} in {reserved:?}"
            );
        }
        assert!(
            !reserved.iter().any(|kept| kept == "rename"),
            "an app's own verb name is not kept"
        );
    }

    #[test]
    fn a_search_entry_naming_an_action_is_a_hit_that_invokes_it() {
        let open = tilo_actions::ActionAddress::new("notes.page:1", "open");
        let search = ResourceSearch {
            name: "Notes",
            app: "so.tilo.notes",
            indexed: Arc::new(IndexedEntries::built(
                vec![
                    SearchEntry::new("Groceries", "milk and eggs").invoking(open.clone()),
                    SearchEntry::new("Garden", "roses").anchored("page:2"),
                ],
                0,
            )),
            scopes: Vec::new(),
            queries: Vec::new(),
            readable: true,
            live: None,
            opens: None,
        };
        let groceries = search.search("groceries");
        assert_eq!(groceries.len(), 1);
        assert_eq!(groceries[0].action_address(), Some(open));
        let garden = search.search("garden");
        assert_eq!(garden.len(), 1);
        assert_eq!(garden[0].action_address(), None);
        assert_eq!(garden[0].action_id, "page:2");
    }

    #[test]
    fn a_search_entry_reads_as_its_group_subtitle_and_icon() {
        let reveal = tilo_actions::ActionAddress::new("video.marker:1", "reveal");
        let search = ResourceSearch {
            name: "Project",
            app: "so.tilo.project",
            indexed: Arc::new(IndexedEntries::built(
                vec![
                    SearchEntry::new("Sunset", "the last light")
                        .invoking(reveal)
                        .grouped("Timeline markers")
                        .subtitled("0:21 · Drone")
                        .with_icon("star")
                        .boosted(5),
                    SearchEntry::new("Sunset take", ""),
                ],
                0,
            )),
            scopes: Vec::new(),
            queries: Vec::new(),
            readable: true,
            live: None,
            opens: None,
        };
        let hits = search.search("sunset");
        let marker = hits
            .iter()
            .find(|hit| hit.title == "Sunset")
            .expect("the marker is found");
        assert_eq!(marker.kind, "Timeline markers");
        assert_eq!(marker.subtitle.as_deref(), Some("0:21 · Drone"));
        assert_eq!(marker.icon, Some(ui_core::icons::Icon::Star));
        let plain = hits
            .iter()
            .find(|hit| hit.title == "Sunset take")
            .expect("the plain entry is found");
        assert_eq!(plain.kind, "Project", "an ungrouped hit is the resource's");
        assert!(plain.preview.is_none(), "no text, no preview");
        // Subtitles are searched too: a marker is found by the shot it is on.
        assert!(
            search
                .search("drone")
                .iter()
                .any(|hit| hit.title == "Sunset")
        );
    }

    #[test]
    fn every_entry_stays_findable_page_by_page() {
        let search = ResourceSearch::new(
            "Tracks",
            "so.tilo.test",
            Arc::new(IndexedEntries::built(
                (0..257)
                    .map(|n| SearchEntry::new(format!("Common track {n}"), ""))
                    .collect(),
                0,
            )),
        );
        let mut cursor = None;
        let mut seen = std::collections::HashSet::new();
        loop {
            let page = search.search_page(&SearchQuery::new("common"), cursor.as_ref(), 17, 5);
            assert!(page.results.len() <= 5);
            for hit in &page.results {
                assert!(seen.insert(hit.title.clone()), "{} came twice", hit.title);
            }
            let Some(next) = page.next else { break };
            assert!(search.action_directory_cursor_is_current(&next));
            cursor = Some(next);
        }
        assert_eq!(seen.len(), 257, "every match is reachable");
    }

    #[test]
    fn no_caller_materialises_more_than_one_page_at_once() {
        let search = ResourceSearch::new(
            "Tables",
            "so.tilo.test",
            Arc::new(IndexedEntries::built(
                (0..300)
                    .map(|n| SearchEntry::new(format!("table {n}"), ""))
                    .collect(),
                0,
            )),
        );
        assert_eq!(
            search.search_limited("", usize::MAX).len(),
            DEFAULT_SEARCH_RESULT_LIMIT
        );
        assert_eq!(
            search
                .search_page(&SearchQuery::new(""), None, usize::MAX, usize::MAX)
                .results
                .len(),
            DEFAULT_SEARCH_RESULT_LIMIT
        );
    }

    /// A chapter of a book: one paragraph per segment, each opening the
    /// book where it is.
    struct Chapter(Vec<&'static str>);

    impl tilo_resource::SearchText for Chapter {
        fn segment_count(&self) -> usize {
            self.0.len()
        }

        fn piece_count(&self, segment: usize) -> usize {
            usize::from(segment < self.0.len())
        }

        fn piece(&self, segment: usize, piece: usize) -> Option<tilo_resource::SearchPiece<'_>> {
            let text = self.0.get(segment)?;
            (piece == 0).then_some(tilo_resource::SearchPiece {
                text,
                space_before: segment > 0,
            })
        }

        fn locates(&self, _segment: usize) -> bool {
            true
        }

        fn location(&self, segment: usize) -> Option<SearchEntry> {
            Some(
                SearchEntry::new(format!("Paragraph {}", segment.saturating_add(1)), "").invoking(
                    tilo_actions::ActionAddress::new(format!("book.location:{segment}"), "open"),
                ),
            )
        }
    }

    #[test]
    fn a_match_in_a_body_is_the_place_it_is_in() {
        let body = tilo_resource::SearchBody::new(Arc::new(Chapter(vec![
            "It was a dark and stormy night.",
            "The lighthouse keeper counted the waves.",
        ])));
        let search = ResourceSearch::new(
            "Library",
            "so.tilo.test",
            Arc::new(IndexedEntries::built(
                vec![
                    SearchEntry::new("Storm Tales", "")
                        .invoking(tilo_actions::ActionAddress::new("book:1", "open"))
                        .grouped("Books")
                        .with_body(body.clone()),
                ],
                0,
            )),
        );
        let hits = search.search("lighthouse keeper");
        let place = hits
            .iter()
            .find(|hit| hit.title == "Paragraph 2")
            .expect("the paragraph the words are in is a hit");
        assert_eq!(
            place.action_address(),
            Some(tilo_actions::ActionAddress::new("book.location:1", "open"))
        );
        assert_eq!(place.kind, "Books", "a location is listed with its book");
        assert!(
            search
                .search("storm tales")
                .iter()
                .any(|hit| hit.title == "Storm Tales"),
            "the book itself is found by its title"
        );
        assert_eq!(body, body.clone(), "a body is the text it shares");
    }

    #[test]
    fn a_field_ranks_by_its_own_weight() {
        use tilo_resource::SearchWeight;
        let search = ResourceSearch::new(
            "Mail",
            "so.tilo.test",
            Arc::new(IndexedEntries::built(
                vec![
                    SearchEntry::new("Lunch plans", "")
                        .field("[email protected]", SearchWeight::Metadata),
                    SearchEntry::new("Quarterly report", "")
                        .field("[email protected]", SearchWeight::Identity),
                ],
                0,
            )),
        );
        let hits = search.search("[email protected]");
        assert_eq!(hits.len(), 2, "both are found by the address");
        assert_eq!(
            hits[0].title, "Quarterly report",
            "a match in an identity outranks one in metadata"
        );
    }
}

// Compiled only into native tests: the file's own `cfg` says so.
mod publication_tests;