blockworx_kernel/

lib.rs

//! The editor as a function.
//!
//! ```text
//! kernel(&mut Session, events, &impl TextLayout) -> View
//! ```
//!
//! `events` is everything a front end can say — the pointer, a command, an
//! action an overlay emitted, the clock, the size of the surface. There is no
//! clock argument and no viewport argument, because a tick and a resize are
//! things that happen. [`View`] is what the front end should show: the display
//! list the frame painted, the cursor, the in-place editor a tool asked for,
//! the selection's bounds on screen, the commands that are live, the window
//! title, whatever the editor had to hand back, and whether another frame is
//! owed.
//!
//! Nothing here names a UI toolkit. The three habits an immediate-mode host
//! left in the core are inputs now: time arrives as an [`Event::Tick`] and the
//! easing table is the session's, text metrics arrive as a [`TextLayout`], and
//! a repaint request comes back out in the [`View`] instead of going out to a
//! context.
//!
//! The egui shell drives the same [`Session`] through the same methods —
//! `canvas_frame`, `dispatch`, `record_history` — so there is one editor, not
//! one per surface.

pub mod bar;
pub mod camera;
pub mod chrome;
mod dispatch;
mod export;
mod frame;
mod handoff;
pub mod nav;
pub mod palette;
pub mod pointer;
pub mod session;

#[cfg(any(test, feature = "test-support"))]
pub mod driving;
#[cfg(test)]
mod tests;

use core::time::Duration;

use blockworx_geom::{Rect, Vec2};
use blockworx_paint::{
    Cursor, DrawList, EditField, Input, Interaction, Keys, Move, PointerKind, Raw, TextEvent,
    TextLayout, Tick, Vantage, Zoom,
    record::{Frame, Recording},
};
use blockworx_store::record::Camera;
use blockworx_tools::{
    commands::{Act, CommandId, CommandSet, Effect},
    names::ToolName,
    tool::{Action, ToolTrait as _},
};

pub use camera::{CameraWork, Glide, Refit};
pub use chrome::{
    Acknowledged, Crumb, Ground, Hung, Lens, Liveness, Locked, NavNode, NavTree, Notice, Notices,
    Overlay, Reading, ScopePath, Selection, TitleBlock, TopBar,
};
pub use export::Sheet;
pub use frame::Framed;
pub use handoff::Handoff;
pub use session::{Consequences, Diagnostic, FrameRate, NavPick, Session, saturation};

/// How a manifest row records `vantage` (§10.1 of `docs/log-vs-snapshot.md`):
/// the world point at the centre of `viewport`, and the zoom.
///
/// Centre-and-zoom rather than the translation, which is measured against a
/// window size the reader may no longer have. The pair lives here rather than
/// beside `Vantage` because the backend does not know the store: it knows
/// where a camera stands, not that anything writes one down.
pub fn recorded_camera(vantage: Vantage, viewport: Vec2) -> Camera {
    let centre = (viewport / 2.0 - vantage.translation) / vantage.zoom.get();
    Camera {
        x: centre.x,
        y: centre.y,
        zoom: vantage.zoom.get(),
    }
}

/// And back, against the viewport the reader has now.
pub fn vantage_of(camera: Camera, viewport: Vec2) -> Vantage {
    let zoom = Zoom::new(camera.zoom);
    Vantage {
        zoom,
        translation: viewport / 2.0 - Vec2::new(camera.x, camera.y) * zoom.get(),
    }
}

/// What a front end can say.
///
/// Taken by value rather than by reference: an [`Action`] can carry artwork
/// or a pasted payload, and saying a thing happened hands it over.
#[derive(PartialEq, serde::Serialize, serde::Deserialize)]
pub enum Event {
    /// What the pointer did, in screen space: a motion, a button edge, its
    /// leaving. What that comes to — a click, a drag, a hover — is resolved
    /// here, not by the front end.
    Pointer(Raw),
    /// The keys this frame carries beside the pointer, as the front end's
    /// focus rules read them.
    Keys(Keys),
    /// How the front end's editor ended the edit it was running: the text
    /// on a commit or a Tab, or a cancel.
    Text(TextEvent),
    /// What an overlay or a menu emitted.
    Action(Action),
    /// A command invoked by name — a toolbar press, a chord, a palette pick.
    /// Resolved through the registry, so a command the session is not offering
    /// this frame does nothing.
    Command(CommandId),
    /// What time it is. A batch with no tick in it is a batch time did not pass
    /// during, and the session keeps the last one it was given.
    Tick(Tick),
    /// The screen rect the canvas is laid out in. A batch with no resize in it
    /// keeps the last one, so a front end states this when the surface changes
    /// size rather than every call.
    Viewport(Rect),
    /// The part of the viewport the front end's own chrome leaves clear,
    /// which a framing centres in. Stated when the chrome changes.
    Safe(Rect),
    /// What the pointer did to the camera — a drag pan, a wheel notch, a
    /// pinch — in screen space. Applied before the pointer is resolved, so
    /// the frame's gestures land under the camera as it now stands.
    Move(Move),
}

/// What the front end should show.
#[derive(PartialEq, serde::Serialize, serde::Deserialize)]
pub struct View {
    /// The frame's marks, in screen space with every swatch resolved.
    pub draw_list: DrawList,
    pub cursor: Option<Cursor>,
    /// The in-place editor asked for this frame, if any: where the front
    /// end runs its own editor, what it opens on, and how it is drawn.
    pub edit_text: Option<EditField>,
    /// The selection's bounding box on screen, for the overlay that anchors
    /// to it.
    pub selection_bounds: Option<Rect>,
    /// Where the camera stands after this call — for a front end's
    /// scrollbars, a minimap, or the next call's screen↔world mapping.
    pub vantage: Vantage,
    /// The screen rect the canvas is laid out in, as the session was last
    /// told it.
    pub viewport: Rect,
    /// The colours under the diagram.
    pub ground: Ground,
    /// Whether the document may be written at all this call, and how many
    /// things are selected — what the chords a front end reads itself
    /// (paste, nudge) are gated on.
    pub writable: blockworx_store::doc::Writability,
    pub selected: usize,
    pub commands: CommandSet,
    /// The chrome model: what is drawn around the canvas, read off the
    /// session after this call's dispatch so it shows the session as it
    /// now stands.
    pub tool: ToolName,
    pub top_bar: TopBar,
    pub status: Reading,
    /// The document's history, oldest first — the panel's rows and the
    /// palette's.
    pub history: Vec<blockworx_store::history::Row>,
    pub nav_tree: NavTree,
    /// The selection bar's contents, while something is selected.
    pub overlay: Option<Overlay>,
    pub notices: Vec<Notice>,
    /// What this call wrote, where the log moved: the confirmation the
    /// status line shows for the frame.
    pub landed: Option<String>,
    pub title: String,
    /// What the editor handed back this call — the one channel out, drained
    /// rather than asked, in the order the results were left. See
    /// [`Handoff`].
    pub handoffs: Vec<Handoff>,
    /// What a command named this call turned out to be the front end's to
    /// perform: a picker, a file dialog, a document door.
    ///
    /// A front end that resolves a command against the registry itself takes
    /// the [`Effect`] there and never sees one here. One that names a command
    /// by id — which is the whole of what a control has to say — gets it back
    /// through this, because the kernel has nowhere to run one.
    pub effects: Vec<Effect>,
    /// How soon another frame is owed, or `None` if none is.
    pub repaint: Option<Duration>,
    /// Whether the front end shows its frame-rate readout.
    pub frame_rate: FrameRate,
}

/// One frame of the editor: apply what the front end said, paint, and answer
/// with what it should show.
///
/// The order is the shell's own — the registry is read before anything is
/// dispatched, the canvas runs before the actions it raises are applied, and
/// the undo stack is fed at the end — because a frame that ran them in another
/// order would be a second editor.
pub fn kernel(session: &mut Session, events: Vec<Event>, layout: &impl TextLayout) -> View {
    let interaction = observe(session, &events);
    let viewport = session.viewport();

    // The undo stack's frame: everything from here to the end of dispatch is
    // one step, whether it edits the document, moves the view, or both. A
    // rename performed between calls is its own step, taken ahead of it.
    session.account_for_rename();
    let before = {
        let _s = tracing::info_span!("state").entered();
        session.state()
    };
    // Where the log stood before any of it, so the confirmation can say what
    // landed however it landed — a dispatched action, or a tool's own
    // gesture sealing on the canvas.
    let stood = session.doc.repo().rev();
    let mut commands = {
        let _s = tracing::info_span!("commands").entered();
        let lock = session.current_lock();
        session.available_commands(lock)
    };

    // A fit owed by an earlier frame is taken before anything is painted: the
    // extent is whatever the draw passes cover, so the camera it yields is the
    // one this frame paints under.
    if session.take_refit() == Refit::Owed {
        let mut measuring = recorder(session, layout, viewport);
        if let Some(content) = session.content_bounds(&mut measuring) {
            session.fit_content(content);
        }
    }

    let mut canvas = recorder(session, layout, viewport);
    let framed = {
        let _s = tracing::info_span!("canvas_frame").entered();
        session.canvas_frame(&interaction, &mut canvas)
    };
    let recorded = canvas.finish();
    session.hand_out_assets(recorded.assets);
    session.asked_repaint(recorded.repaint);
    session.asked_editor(recorded.edit_text.as_ref());
    let edit_text = recorded.edit_text.as_ref().map(|asked| {
        let rect = session
            .vantage()
            .remap_rect(session.viewport().min, asked.position);
        EditField::of(asked, rect)
    });
    let mut draw_list = recorded.draw_list;
    draw_list.retain(|op| edit_text.as_ref().is_none_or(|field| !field.covers(op)));

    let mut effects = Vec::new();
    let mut dispatched = framed.transition.is_some();
    for act in acts(events, &mut commands) {
        match act {
            Act::Edit(action) => {
                dispatched = true;
                let _s = tracing::info_span!("dispatch").entered();
                session.dispatch(action, layout);
            }
            // A picker window, a platform dialog, a document door: the front
            // end performs its own commands, so it is handed back rather than
            // run here.
            Act::Effect(effect) => effects.push(effect),
        }
    }
    if let Some(transition) = framed.transition {
        session.dispatch(transition, layout);
    }
    effects.extend(session.owed_rename());
    // The diagram above was recorded before any of this ran, so it shows none
    // of it: a host that paints only when told something would leave a click's
    // selection undrawn until the pointer next moved.
    if dispatched || session.doc.repo().rev() != stood {
        session.asked_repaint(Some(Duration::ZERO));
    }
    {
        let _s = tracing::info_span!("record_history").entered();
        session.record_history(&before, session.now());
    }

    // Asked again rather than reused: what is available is a fact about the
    // session as it now stands, and this frame's dispatch may have changed it.
    let commands = {
        let _s = tracing::info_span!("commands").entered();
        let lock = session.current_lock();
        session.available_commands(lock)
    };
    let _s = tracing::info_span!("view").entered();
    let history = session.history_rows();
    let nav_tree = {
        let _s = tracing::info_span!("nav_tree").entered();
        session.nav_tree()
    };
    View {
        draw_list,
        cursor: recorded.cursor,
        edit_text,
        selection_bounds: framed.selection_bounds,
        vantage: session.vantage(),
        viewport: session.viewport(),
        ground: session.ground(),
        writable: session.may_write(),
        selected: session.tool.selection().map_or(0, |sel| sel.count()),
        tool: session.displayed_tool(),
        top_bar: session.top_bar(),
        status: session.reading(),
        history,
        nav_tree,
        overlay: session.overlay(framed.selection_bounds, &commands),
        notices: session.notices(),
        landed: session.landed(stood),
        commands,
        title: title(session),
        handoffs: session.take_handoffs(),
        effects,
        repaint: session.take_repaint(),
        frame_rate: session.frame_rate,
    }
}

fn title(session: &Session) -> String {
    session.window_title(None)
}

fn recorder<'a, L: TextLayout>(
    session: &Session,
    layout: &'a L,
    viewport: Rect,
) -> Recording<&'a L> {
    Recording::new(Frame {
        palette: session.palette(),
        layout,
        vantage: session.vantage(),
        viewport,
        easing: session.easing.clone(),
        tick: session.tick(),
        pointer: session.pointer_world(),
        pointer_kind: PointerKind::Mouse,
    })
}

/// What the batch says before anything is painted: the clock, the viewport,
/// the camera's moves and the pointer, taken in the order the front end said
/// them.
///
/// A batch is one frame, so a `Tick` ahead of a `Pointer` in it dates that
/// pointer — and a batch with neither runs at the clock and the size the
/// session was last told. The pointer's raw events are resolved once the
/// clock, the viewport and the moves are known, since a click is dated and
/// a position is mapped against the camera as it now stands.
fn observe(session: &mut Session, events: &[Event]) -> Interaction {
    let mut input = Input::default();
    let mut moves = Vec::new();
    for event in events {
        match event {
            Event::Tick(tick) => session.ticks(*tick),
            Event::Viewport(rect) => session.set_viewport(*rect),
            Event::Safe(rect) => session.set_safe_region(*rect),
            Event::Move(moved) => moves.push(*moved),
            Event::Pointer(raw) => input.raw.push(*raw),
            Event::Keys(keys) => input.keys = input.keys.or(*keys),
            Event::Text(text) => session.text(text),
            Event::Action(_) | Event::Command(_) => {}
        }
    }
    session.moves(&moves);
    session.resolve(&input)
}

/// What this frame asks for: the actions stated outright, and whatever a
/// command resolves to through the registry.
fn acts(events: Vec<Event>, commands: &mut CommandSet) -> Vec<Act> {
    events
        .into_iter()
        .filter_map(|event| match event {
            Event::Action(action) => Some(Act::Edit(action)),
            Event::Command(id) => commands.take(id),
            Event::Pointer(_)
            | Event::Keys(_)
            | Event::Text(_)
            | Event::Tick(_)
            | Event::Viewport(_)
            | Event::Safe(_)
            | Event::Move(_) => None,
        })
        .collect()
}