From 7d337abbbc9846c757e9035ce3490408abcd5b6d Mon Sep 17 00:00:00 2001 From: Simon Klee Date: Wed, 18 Nov 2026 20:48:55 +0100 Subject: [PATCH] docs(cli-rs): document plugin ownership without project history Keep the contracts governing approval, storage limits, stale replies, and focus across remounts. Drop implementation milestones, reviewer names and source coordinates from plugin and diff viewer modules. --- .../cli-rs/crates/tui/src/plugins/approve.rs | 18 +-- packages/cli-rs/crates/tui/src/plugins/btw.rs | 6 +- .../cli-rs/crates/tui/src/plugins/contain.rs | 19 +--- .../tui/src/plugins/diffs/base_branch.rs | 4 +- .../crates/tui/src/plugins/diffs/file_menu.rs | 5 +- .../crates/tui/src/plugins/diffs/help.rs | 2 +- .../crates/tui/src/plugins/diffs/keys.rs | 12 +- .../crates/tui/src/plugins/diffs/mod.rs | 13 +-- .../crates/tui/src/plugins/diffs/sources.rs | 2 +- .../crates/tui/src/plugins/diffs/tree.rs | 2 +- .../crates/tui/src/plugins/diffs/view.rs | 10 +- .../crates/tui/src/plugins/diffs/viewer.rs | 20 ++-- .../cli-rs/crates/tui/src/plugins/fallback.rs | 7 +- .../cli-rs/crates/tui/src/plugins/fetch.rs | 3 +- .../cli-rs/crates/tui/src/plugins/goal.rs | 11 +- .../crates/tui/src/plugins/home_footer.rs | 2 +- .../cli-rs/crates/tui/src/plugins/host.rs | 105 ++++++------------ .../cli-rs/crates/tui/src/plugins/keep.rs | 3 +- .../cli-rs/crates/tui/src/plugins/manager.rs | 35 ++---- .../crates/tui/src/plugins/notifications.rs | 8 +- .../cli-rs/crates/tui/src/plugins/panel.rs | 81 +++++--------- .../crates/tui/src/plugins/prompt_footer.rs | 10 +- .../crates/tui/src/plugins/sidebar_context.rs | 7 +- .../crates/tui/src/plugins/sidebar_footer.rs | 5 +- .../crates/tui/src/plugins/sidebar_limit.rs | 4 +- .../crates/tui/src/plugins/sidebar_mcp.rs | 5 +- .../crates/tui/src/plugins/sidebar_todo.rs | 10 +- .../cli-rs/crates/tui/src/plugins/stats.rs | 9 +- 28 files changed, 121 insertions(+), 297 deletions(-) diff --git a/packages/cli-rs/crates/tui/src/plugins/approve.rs b/packages/cli-rs/crates/tui/src/plugins/approve.rs index cb2c2659e9f..a1c7d4f47d5 100644 --- a/packages/cli-rs/crates/tui/src/plugins/approve.rs +++ b/packages/cli-rs/crates/tui/src/plugins/approve.rs @@ -1,17 +1,11 @@ -//! The host's question about a project plugin held back for approval (rich-plugins 3.9): a select row that toggles -//! such a plugin asks it, whichever plugin showed the row (the plugin manager's), since only the host decides what -//! runs (synthesis 3.6). +//! Ask before running a project plugin. Approval belongs to the displayed artifact, not its path alone. use opencode_plugin::loader::approval::{Artifact, Decision}; use opencode_ui::confirm::{ConfirmProps, confirm}; use crate::prelude::*; -/// Asks whether the build of the project plugin of `target` that the loader holds back now may run. The answer names -/// that build, so it records nothing when the build changed meanwhile (bigboi-1, carbon-1). Approve and Decline keep -/// the answer for this build; Escape, Ctrl+C, the header and the backdrop leave it pending (carbon-6). However the -/// question closes, `back` runs after it, once a library's answer is applied; a TypeScript plugin's tree may still be -/// hashed for its answer then. +/// Ask about the held build of `target`; record the answer only while it still identifies the same build. pub(super) fn ask(tui: &Tui, target: &str, back: impl Fn() + 'static) { let Some((held, unsaved)) = super::host::held(tui, target) else { return }; let artifact = match held { @@ -23,8 +17,7 @@ pub(super) fn ask(tui: &Tui, target: &str, back: impl Fn() + 'static) { Rc::new(move || { let Some(tui) = weak.upgrade() else { return }; let (target, artifact) = (target.clone(), artifact.clone()); - // After the confirm has closed, and before the list comes back; a TypeScript plugin's answer applies once its - // tree is hashed off the UI thread, and the list follows it then. + // Wait for the off-thread approval check before reopening the list. tui.app.defer(bind!(tui, |tui, _| { super::host::decide(&tui, &target, &artifact, decision, |tui, recorded| match recorded { Ok(true) => {} @@ -56,8 +49,7 @@ pub(super) fn ask(tui: &Tui, target: &str, back: impl Fn() + 'static) { tui.dialogs.replace(move |cx| confirm(cx, props.clone()), Some(closed), options); } -/// The question about `artifact`, found as plugin directory `target`: the library that would run, where it really is -/// when that is outside the directory, and its hash (bigboi-1, carbon-1). +/// Describe the actual library path, hash, and whether the decision can be saved. fn question(target: &str, artifact: &Artifact, unsaved: Option<&str>) -> String { let inside = artifact.script || std::fs::canonicalize(target).is_ok_and(|directory| artifact.path.starts_with(directory)); @@ -94,8 +86,6 @@ fn question(target: &str, artifact: &Artifact, unsaved: Option<&str>) -> String mod tests { use super::*; - // Expected (bigboi-1, bigboi-2, carbon-1): the question shows the library that would run and its hash, says when it - // lies outside the plugin directory, and says when the answer is not saved. #[test] fn the_question_names_the_library_and_says_what_is_not_saved() { let root = opencode_util::temp::tempdir().unwrap(); diff --git a/packages/cli-rs/crates/tui/src/plugins/btw.rs b/packages/cli-rs/crates/tui/src/plugins/btw.rs index 2a47ed5f6ff..62bd536f86a 100644 --- a/packages/cli-rs/crates/tui/src/plugins/btw.rs +++ b/packages/cli-rs/crates/tui/src/plugins/btw.rs @@ -1,8 +1,4 @@ -//! `/btw` (E.14, row F03, `feature-plugins/prompt/btw.tsx`): `session.aside` asks a one-shot side question with -//! the session's context through `session.generate`, without adding to the conversation, and shows the answer -//! in a large dialog. While answers are pending, a `/btw` spinner shows in `prompt.footer.status`. It is a plugin of -//! the one API (O-67): the spinner is a contract 2.0 surface (P6a), and the answer a dialog of the API both majors -//! share, whose body is a node of 1.x (2.0 has no keyed dialog). +//! `/btw` asks a side question with session context and shows the answer without interrupting the session. use opencode_api::client::Client; use opencode_api::generated::{SessionGenerateInput, SessionGenerateOutput}; diff --git a/packages/cli-rs/crates/tui/src/plugins/contain.rs b/packages/cli-rs/crates/tui/src/plugins/contain.rs index 9a1fc0a8112..e77fa8ac964 100644 --- a/packages/cli-rs/crates/tui/src/plugins/contain.rs +++ b/packages/cli-rs/crates/tui/src/plugins/contain.rs @@ -1,14 +1,4 @@ -//! The client's side of containment (synthesis 4.5, phase P4c). Under a parent, the client keeps its run record: the -//! parent made it, and handed over in it what the client before this one left. The client: -//! -//! - holds the build a crash named, by target and digest, in `plugin-crashes.json` in the state directory, and every -//! external plugin when the parent says safe mode, or when no parent guards it at all: their libraries are never -//! opened ([`opencode_plugin::Registry::admit`]); -//! - restores the session and the draft of the last snapshot, and shows one notice; -//! - publishes, on every path that changes them, the session on screen and the composer's exact text; -//! - on a real terminal, starts the watchdog; when a call it painted the notice for returns, says so on that line. -//! -//! The parent's half is the CLI's `contain`. +//! Report plugin calls to the supervising process and recover held builds after a crash. use std::path::{Path, PathBuf}; use std::sync::Arc; @@ -163,7 +153,7 @@ fn notice(tui: &Rc, crash: &Crash, safe: bool, dropped: bool) { Some(artifact) => { let id = if artifact.id.is_empty() { artifact.target.clone().unwrap_or_default() } else { artifact.id.clone() }; - // The held build, not a loaded plugin of the same ID (review bigboi-3). + // Use the held build's identity, not a loaded plugin with the same ID. let held = opencode_plugin::Entry::held_key(artifact.target.as_deref().unwrap_or_default()); ToastOptions::new(Variant::Error, format!("It {}.{lost}", reason(call, crash.hang))) .title(format!("Plugin failed: {id}")) @@ -191,8 +181,7 @@ pub(crate) fn enable(tui: &Rc, key: &str) { } } -/// A call whose hang notice the watchdog painted over row 1 returned: the line says so, over the notice, and goes, so -/// the row shows what the UI drew there. +/// Replace a watchdog hang notice with a brief recovery notice when the call returns. fn responded(tui: &Rc, artifact: &Artifact, took: Duration) { let theme = tui.page(); let text = format!(" plugin {} responded after {:.1} s ", artifact.id, took.as_secs_f32()); @@ -236,8 +225,6 @@ pub fn sync(tui: &Tui) { mod tests { use super::*; - // Expected (review bigboi, inherited): a change of the crash list that cannot be written says so and leaves the - // file as it was, so a release that depends on it does not happen. #[test] fn a_crash_list_that_cannot_be_written_says_so() { use std::os::unix::fs::PermissionsExt; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/base_branch.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/base_branch.rs index 68721ca0d1e..7ebefd808d4 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/base_branch.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/base_branch.rs @@ -1,6 +1,4 @@ -//! Base branch dialog (E.15b, row DLG46, `DiffBaseDialog` in `feature-plugins/system/diff-viewer.tsx`): the -//! location's local and remote branches, searched on the server as the user types (the host's query, after 150 ms). -//! The chosen branch is remembered per location and branch while the plugin is active. +//! Choose a local or remote comparison branch. use opencode_api::client::Client; use opencode_api::generated::{LocationQueryInput, VcsBranchListInput, VcsBranchListOutput}; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/file_menu.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/file_menu.rs index 69acdbfff74..eac4e9c490a 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/file_menu.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/file_menu.rs @@ -1,7 +1,4 @@ -//! Diff file menu (E.15b, row DLG49, `feature-plugins/system/diff-viewer-file-menu.tsx`): one row under a -//! right-clicked file heading or tree row that marks the file complete or incomplete. An overlay of the plugin's, -//! owned by the viewer's mount: it takes the focus, so the viewer's keys wait; Escape and a press outside close it, -//! and Enter or a click of the row runs it. +//! Context menu for a file heading or file-tree entry. use opencode_plugin::abi::interact::{Anchor, Bind, Button, Event, Handled, Interact, Layer, Overlay, PointerKind}; use opencode_plugin::abi::v2::{self, Node}; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/help.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/help.rs index c7fbf2788e6..9779eff0e54 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/help.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/help.rs @@ -1,4 +1,4 @@ -//! TypeScript: `feature-plugins/system/diff-viewer.tsx`. +//! Diff viewer keyboard help. use opencode_plugin::abi::{Dialog, Host, Layout, Node, Panel, PanelSize, Read, Span, Width}; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/keys.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/keys.rs index 3b44523e32a..7f9839a2127 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/keys.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/keys.rs @@ -1,10 +1,4 @@ -//! The `diff.*` bindings (E.15a): the viewer's commands (`diff-viewer.tsx:588-781`) and the global `diff.open` -//! (`:1311-1361`). Of the 26 `diff.*` keybinds in `config/keybind.ts`, 20 are viewer commands, `diff.open` opens it, -//! and the five deprecated tree keys (`diff.toggle`, `.expand`, `.expand_all`, `.collapse`, `.switch_focus`) are -//! kept for config only and register nothing, as in TS. -//! -//! The viewer's keys are a layer of its surface (P6c): each bind is the user's keybind of the command's name -//! ([`Bind::command`]), heard by the surface's handler while the panel has the focus or the route shows. +//! Diff commands and key bindings for route and docked views. use opencode_plugin::abi::interact::{Bind, Layer, LayerScope}; @@ -32,9 +26,7 @@ pub enum Action { Help, } -/// The viewer's commands in TS order. `app.exit` closes the viewer while it has the input; the specific bindings -/// win over its `ctrl+d`. Its `ctrl+c` is the host's: no plugin layer takes the reserved chord (P2), and the host -/// closes the plugin's menu, panel or route that has the input on it, as `app.exit` closes the viewer in TS. +/// Viewer-specific bindings take precedence over exit while the viewer owns input. pub const COMMANDS: [(&str, &str, Action); 21] = [ ("diff.close", "Close diff viewer", Action::Close), ("diff.down", "Move diff viewer down", Action::Down), diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/mod.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/mod.rs index 6e7c76e0a74..f91c2ca1ef9 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/mod.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/mod.rs @@ -1,13 +1,4 @@ -//! The diff viewer (E.15a and E.15b, row F15, `feature-plugins/system/diff-viewer.tsx`): the built-in -//! `opencode.diffs`, a plugin of contract 2.0 on both carriers (P6c, synthesis 4.9). `/diff` docks the viewer beside -//! the session as its panel, or opens it as a full-screen route outside a session. The viewer loads the VCS or -//! last-turn diff, and shows each file as a card under a sticky header, with the file tree beside the cards when the -//! screen is wide enough, split or unified hunks by width, and reviewed marks. -//! -//! What the host did for the old viewer it does for any plugin: the cards are a windowed list, the hunk cursor is a -//! step, the reading position a keep, the top edge's color a paint of `layout`, and the panel, the keys, the menu and -//! the dialogs are surfaces, a layer, an overlay and host dialogs. One viewer shows at a time: its state lives from -//! its mount's begin to its end. +//! The built-in diff viewer, shown as a route or a docked panel. use opencode_api::generated::{SessionExecutionInterruptedDataReason, V2Event}; use opencode_plugin::abi::interact::{Button, Event, Handled, OpenPanel, PointerKind}; @@ -111,7 +102,7 @@ fn setup(setup: &mut abi::Setup) -> Result<(), String> { ]; for (name, run) in commands { let ran = diffs.clone(); - // A pick closes its keyed dialog, also once no viewer is left to take it (review carbon-4). + // A pick must close its dialog even if the viewer is gone. let closes = match name { PICK_SOURCE => Some(sources::KEY), PICK_BASE => Some(base_branch::KEY), diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/sources.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/sources.rs index 4c1f7db2385..0544c8e345a 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/sources.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/sources.rs @@ -1,4 +1,4 @@ -//! TypeScript: `feature-plugins/system/diff-viewer.tsx`. +//! Select the diff source for a location. use opencode_plugin::abi::{Action, Dialog, Host, Select, SelectOption}; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/tree.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/tree.rs index 1a31be5877b..b24260fc725 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/tree.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/tree.rs @@ -1,4 +1,4 @@ -//! TypeScript: `diff-viewer-file-tree-utils.ts`, `diff-viewer-file-tree.tsx`. +//! Display and navigate the diff viewer's file tree. use std::collections::BTreeSet; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/view.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/view.rs index 194345fa555..426b8910773 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/view.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/view.rs @@ -1,7 +1,4 @@ -//! The viewer's tree: the header, the cards, the footer and the file tree, from the viewer's state. The cards are a -//! windowed list (P3): only those near the view have widgets, and a card that did not change is kept whole -//! ([`v2::View::memo`]). A card's header sticks to the top of its card, its hunks are anchors a step walks, and the -//! fixed edge above the list takes the color of the card at the top from `layout`. +//! Diff cards form a virtual list: build only cards near the viewport and retain their state across revisions. use std::rc::Rc; @@ -474,9 +471,7 @@ fn tree_pane(viewer: &Viewer, cx: &mut v2::View<'_>) -> Node { ) } -/// The fixed top edge takes the reviewed color of the card at the top, in the frame that shows it. The edge is there -/// only with the cards, so a frame without their scroll (loading, a message) paints nothing, and logs no paint of a -/// missing box (PL-10). +/// Paint the fixed edge from the top card only when the cards are visible. pub fn layout(geometry: &Geometry) -> LayoutReply { if geometry.scroll(FILES).is_none() { return LayoutReply::default(); @@ -489,7 +484,6 @@ pub fn layout(geometry: &Geometry) -> LayoutReply { mod tests { use super::*; - // Expected (PL-10): the edge is painted only in a frame that has the cards' scroll. #[test] fn the_edge_is_painted_only_with_the_cards() { assert!(layout(&Geometry::default()).paints.is_empty()); diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/viewer.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/viewer.rs index 1e88686a4e6..17d0dd1dc0d 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/viewer.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/viewer.rs @@ -118,8 +118,7 @@ pub enum Load { Ready { base: Option, files: Vec }, } -/// The plugin's memory, kept while it is active (`storage.memory("review")`): the last source and the chosen base per -/// location and branch. +/// Remember the selected source and comparison base per location and branch. #[derive(Default)] pub struct Memory { pub source: Option, @@ -144,7 +143,7 @@ pub enum Showing { pub enum Preview { Loading, Failed, - /// Bytes that the host's image decoder refuses (TS `onError`): no size and no preview to click. + /// The host cannot decode these bytes. Omit the size and preview action. Undecodable, /// The bytes, and the width and height the host decodes them to. Ready(std::rc::Rc<[u8]>, (u32, u32)), @@ -189,8 +188,7 @@ pub struct Viewer { /// Image previews by file, read once per file list. pub previews: HashMap, pub menu: Option, - /// The tree's selected row and its rows when they last scrolled it: the selection scrolls into view only when - /// they change, as TS's effect does. + /// Scroll to the selected row only when the selection or its rows change. pub tree_mark: (Option, usize), pub contents: Contents, /// The last view shows this state: a wake that changed nothing of it keeps the tree. @@ -216,7 +214,7 @@ pub struct Shown { } impl Viewer { - /// What its view shows of it now (each event changes a set by one, so the sizes tell). + /// State exposed to the current view. pub fn shown(&self) -> Shown { Shown { selected: self.selected, @@ -309,8 +307,8 @@ impl Viewer { self.docked() || self.width < FULL_LAYOUT_MIN_WIDTH } - /// Whether the viewer has the input: always full screen, else while its panel has the focus. A dialog takes the - /// focus without changing the panel's (TS `panel.focused`). + /// A fullscreen viewer owns input; a docked viewer must hold panel focus. Opening a dialog does not transfer + /// ownership of the panel. pub fn focused(&self) -> bool { !self.docked() || self.panel.is_some_and(|panel| panel.focused) } @@ -642,11 +640,7 @@ impl Viewer { self.forget(host); } - /// What a turn event says to the viewer: in `turn` mode the viewer of that session loads again when one of its - /// turns ends (TS's `createEffect` on `session.status`, running to idle), and says whether it did. It hears the - /// end itself: the status read when the UI hears of an event may already be idle again, for a turn that started - /// and ended before then (`steps/flakes-8.md`). A turn it saw start whose end the connection may have lost (a - /// reconnect, or signals the UI skipped) loads it again too (carbon's review of P6c, 6). + /// Refresh a session's turn diff when its turn ends. pub fn turn(&mut self, host: &dyn Host, diffs: &Diffs, turn: Turn<'_>) -> bool { let mine = |session: &str| self.mode == Mode::Turn && self.session() == Some(session); let ended = match turn { diff --git a/packages/cli-rs/crates/tui/src/plugins/fallback.rs b/packages/cli-rs/crates/tui/src/plugins/fallback.rs index caf1a26a44d..c411257b573 100644 --- a/packages/cli-rs/crates/tui/src/plugins/fallback.rs +++ b/packages/cli-rs/crates/tui/src/plugins/fallback.rs @@ -1,7 +1,4 @@ -//! The host's own `/plugins` while the plugin manager (`opencode.plugins`) has failed (synthesis 3.6, 4.10): the toasts -//! and the home footer still say "Run /plugins", so the host lists the TUI plugins and their errors, read only. Enter -//! on a row with an error shows it; the user's enter or click on the manager's own row enables it again, which brings -//! the manager back. Rows name registry entries by key, so a held build of the manager's ID is not the manager. +//! Host fallback for `/plugins` when the plugin manager fails. use opencode_plugin::{Entry, Source, Status}; @@ -67,7 +64,7 @@ fn show(tui: &Rc, focus: Option) { })); props.actions = vec![view_error]; props.on_select = Some(Rc::new(bind!(weak, |tui, option: &SelectOption| { - // A key or a click, not a run of the submit by name, as a plugin's `dispatch` runs it (review bigboi-1). + // Require a user key or click before toggling a plugin. let by_input = picked .upgrade() .is_some_and(|handle| handle.borrow().as_ref().is_some_and(|handle| handle.by_input())); diff --git a/packages/cli-rs/crates/tui/src/plugins/fetch.rs b/packages/cli-rs/crates/tui/src/plugins/fetch.rs index 80db84fffa5..fea6b420bf5 100644 --- a/packages/cli-rs/crates/tui/src/plugins/fetch.rs +++ b/packages/cli-rs/crates/tui/src/plugins/fetch.rs @@ -1,5 +1,4 @@ -//! The plugins' one route for I/O (O-67): a built-in builds its request with a generated `*_call` builder and turns it -//! into an [`abi::Fetch`] here; the host sends a fetch through its own client, on the transport the TUI runs on now. +//! Route built-in plugin requests through the same fetch interface as external plugins. use opencode_api::client::{Body, Call}; use opencode_plugin::abi; diff --git a/packages/cli-rs/crates/tui/src/plugins/goal.rs b/packages/cli-rs/crates/tui/src/plugins/goal.rs index ef3a5dbe464..d8ba85521cd 100644 --- a/packages/cli-rs/crates/tui/src/plugins/goal.rs +++ b/packages/cli-rs/crates/tui/src/plugins/goal.rs @@ -1,11 +1,4 @@ -//! The goal `/goal` set on a session (E.14, rows F02 and DLG45, `feature-plugins/prompt/goal.tsx`): the goal plugin's -//! RPC read, the status under the prompt, and the goal panel, for the prompt footer plugin. The panel is a dialog of -//! the API both majors share, whose body is a node of 1.x: contract 2.0 has no keyed dialog (P6a). -//! -//! [`Goals`] keeps the goal of each session a mounted footer shows. The first footer of a session reads its goal, and -//! every tracked session is read again after a reconnect, since changes published meanwhile were missed; the `changed` -//! events keep them current. A change that arrives while a read is in flight is newer than its reply, so each read and -//! change takes a turn, and a reply of an older turn is dropped. +//! Session goal status, commands, and progress panel. use opencode_api::client::Client; use opencode_api::generated::{LocationQueryInput, RpcCallInput, RpcCallOutput, SessionCommandInput, V2Event}; @@ -44,7 +37,7 @@ pub enum Status { Complete, } -/// The goals of the sessions the mounted footers show (TS `createGoal`, once per session). +/// Track goals for sessions with a mounted goal footer. #[derive(Default)] pub struct Goals { sessions: RefCell>, diff --git a/packages/cli-rs/crates/tui/src/plugins/home_footer.rs b/packages/cli-rs/crates/tui/src/plugins/home_footer.rs index 3f536fd4d27..e5bbb0dcb56 100644 --- a/packages/cli-rs/crates/tui/src/plugins/home_footer.rs +++ b/packages/cli-rs/crates/tui/src/plugins/home_footer.rs @@ -1,4 +1,4 @@ -//! TypeScript: `feature-plugins/home/footer.tsx`. +//! Built-in home footer. use opencode_plugin::abi::v2::{Node, Place, Surface}; use opencode_plugin::abi::{self, Click, Layout, Placement, Span, Width}; diff --git a/packages/cli-rs/crates/tui/src/plugins/host.rs b/packages/cli-rs/crates/tui/src/plugins/host.rs index 9c1d5d1ce8e..00914b55f79 100644 --- a/packages/cli-rs/crates/tui/src/plugins/host.rs +++ b/packages/cli-rs/crates/tui/src/plugins/host.rs @@ -33,14 +33,13 @@ pub struct Plugins { pub(crate) published: RefCell>, #[cfg(feature = "ts")] pub scripts: RefCell>>, - /// The plugins as the plugins that read them last heard of them (P6b), and whether a tell is queued. + /// Last plugin list delivered to subscribers. told: RefCell>, telling: Cell, /// The host's own `/plugins` while the plugin manager has failed. fallback: RefCell>, server_parts: RefCell>, - /// The plugins not loaded the user was told of this run, and whether the server's plugins were heard yet: the one - /// notice waits for them, so it names their TUI parts too. + /// Wait for both local and server plugins before reporting skipped entries once per run. told_skipped: RefCell>, heard_server: Cell, } @@ -108,8 +107,7 @@ impl Host for Tui { Some(serde_json::Value::Object(object)) => object.into_iter().chain(fields.clone()).collect(), _ => fields.clone(), }; - // The plugin's bound holds for the value the merge makes under the lock, which another client's writes may have - // grown since this client read it (re-review final pass, the storage bound). + // Check the merged size under the storage lock; another client can enlarge the value. queue(self, key, Some(serde_json::Value::Object(shown).to_string()), move |storage, key| { let merge = move |stored: &mut Value| match stored.as_object_mut() { Some(object) => object.extend(fields), @@ -141,8 +139,7 @@ impl Host for Tui { }; let mut options = ToastOptions::new(variant, toast.message.clone()); options.title = toast.title.clone(); - // A toast about a session offers to open it, unless the session's family is on screen. - // A plugin's toast waits behind the host's own notice of a plugin (PL-2). + // Only offer to open a session outside the visible family. Queue plugin toasts behind host failure notices. let Some(session) = toast.session.as_ref().map(|id| SessionID(id.clone())) else { return self.toasts.show_behind_kept(options); }; @@ -161,15 +158,14 @@ impl Host for Tui { } fn failed(&self, id: &str) { - // After what the failing call asked for, as in TS, where its toast showed before the error was thrown: a toast - // replaces the one on screen, so the report must come last. + // Show the failure report after the failing call's effects so an earlier toast cannot hide it. let title = format!("Plugin failed: {id}"); self.app.defer(bind!(self, |tui, _| failed_toast(&tui, title.clone(), String::new()))); self.reads.changed(self); } fn slow(&self, id: &str, cost: &str) { - // A frame that made it slow may close after the plugin failed or was turned off: then it has its own report. + // A failed or disabled plugin already has its own report. if !self.plugins.entries().iter().any(|entry| entry.id == id && entry.status == Status::Active) { return; } @@ -177,7 +173,7 @@ impl Host for Tui { .title(format!("Plugin is slow: {id}")) .keep(); tell_plugins(self); - // Disabling the manager would leave no `/plugins` (review carbon-3). + // Keep the manager available to reopen `/plugins`. if id == super::manager::ID { return self.toasts.show(options); } @@ -204,9 +200,7 @@ impl Host for Tui { // A dialog surface on screen mounts again from the registration that replaced the one that ended. let reloaded = id.to_owned(); self.app.defer(bind!(self, |tui, _| super::panel::remount(&tui, &reloaded))); - // A reload of the plugin's registrations replaced the one that ended, which has the panel too: the panel stays - // open and mounts again from the new one, as TS takes a registration without closing it (CT-29). A plugin that - // failed or ended loses it. + // Keep the panel open across registration reloads and remount its new surface. let kept = self.panels.current().is_some_and(|target| { target.plugin == id && self.plugins.has_panel(id, &target.name) @@ -366,7 +360,7 @@ impl Host for Tui { return false; } let root = |session: &str| self.data.read(|state| state.root(&SessionID(session.to_owned()))).0; - // The tabs as the call's earlier edits left them (TS `ui.tabs` acts on each in order). + // Apply tab edits in call order. let (mut open, mut current) = (self.tabs.open_ids(self), self.tabs.current(self)); for edit in staged { match edit { @@ -391,7 +385,7 @@ impl Host for Tui { } match edit { abi::TabEdit::Open { .. } | abi::TabEdit::Focus { .. } => true, - // `move` takes any session of a tab's family; `close` only the tab's own ID, as in TS. + // Move accepts any session in a tab family; close requires the tab's own ID. abi::TabEdit::Move { session, .. } => open.contains(&root(session)), abi::TabEdit::Close { session } => session.clone().or(current).is_some_and(|id| open.contains(&id)), } @@ -590,9 +584,7 @@ impl Host for Tui { } } -/// Counts each change of the host's own state (its local state and settings) in [`Host::local_revision`], once and -/// before the watchers hear it, so every view after it hears it as `local` once (review carbon-6). Called before any -/// claim mounts: listeners run in the order they subscribed. +/// Advance the shared local revision before notifying watchers, once per change. pub(crate) fn count_local(tui: &Tui) { let revision = tui.reads.revision.clone(); let local = tui.local.subscribe(move || revision.set(revision.get() + 1)); @@ -649,7 +641,7 @@ fn queue( pending.fetch_add(1, Ordering::SeqCst); let (key, proxy) = (key.to_owned(), tui.app.proxy()); let writer = tui.reads.writer.get_or_init(|| { - // A write refused under the lock leaves the disk as it was: what this client showed for it goes. + // A refused write leaves the disk unchanged; invalidate its optimistic value. let weak = tui.weak(); tui.app.on_message(move |_, _: &Refused| { if let Some(tui) = weak.upgrade() { @@ -679,7 +671,7 @@ fn queue( } } -/// Posted when a plugin storage write was refused under the lock. +/// Notification of a storage write refused under the lock. struct Refused; /// Waits until every plugin storage write queued so far is on disk. @@ -738,14 +730,11 @@ pub struct Reads { key: Cell, /// The JSON text of each storage key read or written, so a write shows at once and storage works without disk. stored: RefCell>>, - /// The one worker that writes the plugins' storage, so writes land in the order they were made. + /// Serialize plugin storage writes. writer: OnceCell, /// The writes queued and not yet on disk. pending: Arc, - /// A write was refused under the lock since the keys were last read from disk: what `stored` shows for it is no - /// file's. It stays set until a reload from disk with no write pending, so neither a correction that could not be - /// posted nor one skipped while another write was queued leaves the cache apart from the files (re-review last - /// pass). + /// Reload disk state after a refused write before trusting the cache. dirty: Arc, /// The mounted claims' pushes, which a storage write calls with `local` from the effect queue. watchers: RefCell>>, @@ -760,8 +749,7 @@ pub struct Reads { pub(super) surface: RefCell>>, /// The plugin and activation whose dialog is on screen, until it closes. pub(super) owner: RefCell>, - /// The showing `owner` was recorded for, by number, and the last number given: a close clears the owner of its own - /// showing only, whichever activation updated it since (big-boi ds-1). + /// A close clears only its own showing, even when a new activation owns the next one. pub(super) showing: Cell, pub(super) showings: Cell, /// The action the next plugin dialog runs as it closes (`abi::Dialog::Dismissable`), until that dialog takes it. @@ -1096,7 +1084,7 @@ fn set_setting(tui: &Tui, name: &str, value: Value) { }); } -/// A registry entry as a plugin reads it: without the error, which may hold another plugin's secrets (review bigboi-2). +/// Omit error text from plugin-visible entries: it may contain another plugin's secrets. fn entry(entry: opencode_plugin::Entry) -> abi::PluginEntry { let status = match entry.status { Status::Active => abi::PluginStatus::Active, @@ -1140,7 +1128,7 @@ pub fn tell_plugins(tui: &Tui) { if *tui.plugins.told.borrow() == entries { return; } - // The manager that serves `/plugins`, not a held build of its ID (review bigboi-3). + // Identify the active manager, not a held build sharing its ID. let manager = opencode_plugin::Entry::plugin_key(super::manager::ID); let failed = |entries: &[opencode_plugin::Entry]| { entries.iter().any(|entry| entry.key == manager && matches!(entry.status, Status::Failed(_))) @@ -1159,9 +1147,7 @@ pub fn tell_plugins(tui: &Tui) { pub(super) const APPROVAL: &str = "host.approval"; pub(super) const FALLBACK: &str = "host.plugins"; -/// Whether the host's approval question or its own `/plugins` is on screen: then no plugin's dialog, route or -/// navigation replaces or clears it, which would dismiss the question, or show a lookalike of it, or take the way to -/// recover from the user (review carbon-9). What plugin `id` asked for, `what`, is dropped. +/// Block plugin navigation and dialogs while the host approval question or fallback manager is visible. fn guarded(tui: &Tui, id: &str, what: &str) -> bool { let guarded = matches!(tui.dialogs.key().as_deref(), Some(APPROVAL | FALLBACK)); if guarded { @@ -1187,8 +1173,7 @@ fn status(status: opencode_store::SessionStatus) -> abi::SessionStatus { } } -/// The built-ins in TS order (`plugin/builtins.ts`), with the ones from other crates ([`crate::Deps::builtins`], -/// Mermaid and LaTeX) in their TS place after `stats`, and the diff viewer last. The storybook (F14) is excepted (Q17). +/// Register built-ins in palette order, including the renderers supplied through [`crate::Deps::builtins`]. fn builtins(external: Vec, abi: bool) -> Vec { // On the other carrier each plugin's calls cross the C ABI's byte shims ([`Builtin::Abi`]). let carried = |builtin: Builtin| match builtin { @@ -1250,8 +1235,7 @@ pub fn install(tui: &Rc) { super::contain::install(tui); tui.plugins.activate(&host(tui)); tell_plugins(tui); - // The plugins read the keymap (`keymap.pending()`, `keymap.active()`, `keymap.commands()`): the pending keys, and - // the layers and focus that decide what a key reaches, as TS's keymap selectors follow its state. + // Notify plugin keymap readers when pending keys, layers, or focus change. let keymap = tui.keymap.keymap().on_state(bind!(tui, |tui| local_changed(&tui))); tui.layers.borrow_mut().push(keymap); crate::features::events::subscribe(tui, ["plugin.updated", "server.connected"], |tui, event| { @@ -1312,13 +1296,8 @@ fn sync_server_plugins(tui: &Tui) { ); } -/// The TUI parts of the active server plugins, which TS loads from the server's list (`serverTuiPlugins`, -/// `context.tsx:96-103`, `301-305`): with the JS host the loader loads them, from the local path or the package -/// cache the server reports, holding for approval those the user's own configuration does not name (O-162); without -/// it they are listed as not loaded, unless their target is listed already, and a part the server no longer lists -/// leaves the list. A local path from a server on another machine names nothing here, and is left out. +/// Reconcile TUI entries supplied by the active server plugins. fn set_server_parts(tui: &Rc, plugins: &[PluginInfo]) { - // Only the client that loads external plugins has TS's reconcile to stand in for. let Some(loader) = tui.plugins.loader.borrow().clone() else { return }; let here = same_machine(tui.startup.args.local, tui.data.client().base_url()); let typed: Vec = plugins @@ -1368,8 +1347,7 @@ fn set_server_parts(tui: &Rc, plugins: &[PluginInfo]) { } } -/// Tells the user once a run, in the host's notice lane, which TypeScript plugins are not loaded and why: the ones not -/// told yet, grouped by reason, once the server's plugins were heard (FT-10). +/// Report each skipped TypeScript plugin once per run, grouped by reason. fn tell_skipped(tui: &Tui) { if !tui.plugins.heard_server.get() || tui.plugins.loader.borrow().is_none() { return; @@ -1411,9 +1389,7 @@ fn tell_skipped(tui: &Tui) { tui.toasts.show(options); } -/// Whether the server runs on this machine, so the paths it reports are this machine's: one the client started or the -/// service (no `--server`), or a `--server` on a loopback address. A loopback port may still be a tunnel to another -/// machine; a path it reports then needs approval like any the user's configuration does not name (O-162). +/// Trust server filesystem paths only for a local server. fn same_machine(local: bool, url: &url::Url) -> bool { local || match url.host() { @@ -1424,10 +1400,7 @@ fn same_machine(local: bool, url: &url::Url) -> bool { } } -/// The `plugins` entries of the user's own configuration as written, in the order TS applies them, removals (`-…`) -/// included (carbon recheck-1): the global opencode config's (TS `ConfigDiscovery`: `opencode.json`, then -/// `opencode.jsonc`, in the global config directory), then `cli.json`'s. Each is a package's spec, a path or a -/// selector; a file that does not parse names none. +/// Apply global config entries and removals in configuration order. fn user_plugins(tui: &Tui, config_dir: &Path) -> Vec { let global = ["opencode.json", "opencode.jsonc"] .iter() @@ -1479,8 +1452,7 @@ fn pending_toast(tui: &Tui, target: &str, message: &str) { pub struct External { pub config_dir: PathBuf, pub cwd: PathBuf, - /// Targets loaded beside the configured ones, which a config change keeps and settings never save: `plugin dev`'s - /// library (review bigboi-9). + /// Extra plugin targets that survive config reloads without being persisted, including `plugin dev`. pub dev: Vec, } @@ -1494,7 +1466,7 @@ pub type JsHost = opencode_plugin::pipe::Config; #[cfg(not(feature = "ts"))] pub enum JsHost {} -/// Whether a JS host runs the TypeScript plugins: never in a build without the `ts` feature. +/// Whether this client can run JavaScript plugins. fn js_host(tui: &Tui) -> bool { #[cfg(feature = "ts")] return tui.plugins.scripts.borrow().is_some(); @@ -1525,8 +1497,7 @@ pub fn external(tui: &Rc, external: External) { external_with(tui, external, scripts); } -/// [`external`], with the TypeScript plugins on a JS host that runs as `scripts` says (P7); without one they are listed -/// as skipped. +/// Load external plugins using the given JS host configuration. Without a host, list TypeScript plugins as skipped. pub fn external_with(tui: &Rc, external: External, scripts: Option) { let builds: Vec = external.dev.iter().map(|library| Build::new(Path::new(library).with_file_name("build.log"))).collect(); @@ -1541,7 +1512,6 @@ pub fn external_with(tui: &Rc, external: External, scripts: Option) let entries = configured(tui, tui.plugins.skipped()); let project = opencode_plugin::loader::project_root(&external.cwd); let loader = Loader::new(Rc::new(Native), external.config_dir, external.cwd, entries); - // Luau plugins (O-178): on in a build with them, unless `OPENCODE_PLUGIN_LUAU=0` turns them off. #[cfg(luau)] let loader = match opencode_plugin::luau::enabled() { true => { @@ -1612,7 +1582,7 @@ pub fn external_with(tui: &Rc, external: External, scripts: Option) tell_plugins(&tui); tell_skipped(&tui); })); - // The server's plugins may have been heard before there was a loader. + // Server entries can arrive before the loader starts. let server = tui.reads.server.borrow().1.clone(); set_server_parts(tui, &server); tell_skipped(tui); @@ -1622,12 +1592,10 @@ pub fn external_with(tui: &Rc, external: External, scripts: Option) /// author saves in an editor and looks back at the TUI later, past the 5 s of a toast's default (dx-fresh). const FAILED_BUILD: Duration = Duration::from_secs(24 * 60 * 60); -/// `plugin dev`'s `build.log` beside its library, which its builds in the background publish in the watched directory: -/// empty after a build that passed, the compiler's output after one that failed. A failed build keeps the running -/// version and said so only in the log file (PL-7). +/// Watch the development build log; an empty log means success. struct Build { log: PathBuf, - /// When the log was written last, and whether a build had failed then. + /// Last log timestamp and failure state. seen: Cell<(Option, bool)>, } @@ -1642,7 +1610,7 @@ impl Build { (meta.as_ref().and_then(|meta| meta.modified().ok()), meta.is_some_and(|meta| meta.len() > 0)) } - /// Tells a build since the last look: one that failed names its log, and the first to pass after it says so. + /// Report build failure and the first subsequent recovery. fn tell(&self, tui: &Tui) { let now = Self::read(&self.log); let (written, failed) = self.seen.replace(now); @@ -1672,7 +1640,7 @@ pub fn held(tui: &Tui, target: &str) -> Option<(Result, Option Some((loader.held(target)?, loader.unsaved())) } -/// Reconciles the external plugins with their directories now, as the watcher does after a change. +/// Reconcile external plugins against the current contents of their directories. pub fn reconcile(tui: &Rc) { let loader = tui.plugins.loader.borrow().clone(); if let Some(loader) = loader { @@ -1680,12 +1648,7 @@ pub fn reconcile(tui: &Rc) { } } -/// Records the user's `decision` on `artifact`, the build of `target` they were shown, once the build on the disk is -/// identified again, and applies it: an approved build loads at once. `done` gets `Ok(false)` when nothing was recorded -/// as the build changed since (bigboi-1), and an error when the decision cannot be saved (bigboi-7). A TypeScript -/// plugin's tree is hashed off the UI thread (FT-2), so `done` runs in a later turn; a library's, at once. An answer -/// the user gave again on `target` before the hash ended supersedes this one: it records nothing, and `done` does not -/// run (review jsnpm-5). +/// Recheck the on-disk artifact before applying the user's decision about a build. pub fn decide( tui: &Rc, target: &str, diff --git a/packages/cli-rs/crates/tui/src/plugins/keep.rs b/packages/cli-rs/crates/tui/src/plugins/keep.rs index 3a9e12eb02b..58271a9d176 100644 --- a/packages/cli-rs/crates/tui/src/plugins/keep.rs +++ b/packages/cli-rs/crates/tui/src/plugins/keep.rs @@ -1,5 +1,4 @@ -//! What a built-in's slot surface (contract 2.0, P6a) answers for 1.x's `Render::Keep` and `Render::Hide`. Its own file, -//! so a built-in's source builds as a library too (`crates/plugin/examples/home-footer`). +//! Shared retained and hidden nodes for built-in slot surfaces. use opencode_plugin::abi::v2::Node; diff --git a/packages/cli-rs/crates/tui/src/plugins/manager.rs b/packages/cli-rs/crates/tui/src/plugins/manager.rs index 22d92c3ac45..82cfece80ee 100644 --- a/packages/cli-rs/crates/tui/src/plugins/manager.rs +++ b/packages/cli-rs/crates/tui/src/plugins/manager.rs @@ -1,14 +1,4 @@ -//! The plugin manager (E.18b, `feature-plugins/system/plugins.tsx`): the built-in `opencode.plugins` with `plugins.list` -//! (`/plugins`), a plugin of the one API (P6b, synthesis 4.10) on both carriers. It reads the TUI plugins -//! ([`abi::Read::plugins`]) and hears when they change ([`abi::Setup::on_plugins`]); it never changes them. A row that -//! enables or disables a plugin, or asks to approve a project's plugin, is a toggle row, which only the host runs, on the -//! user's key or click (synthesis 3.6). The server rows come from `GET /api/plugin` of the location the manager opened -//! at; check and update are server calls too. -//! -//! Built-ins are internal and hidden until `ctrl+a`; a configured TypeScript plugin is listed as `skipped` with the -//! reason as its error (F16), and an external plugin that failed as `failed` with its error. Enter on a row that is not a -//! toggle opens its error, if any. A project plugin held back for approval (rich-plugins 3.9, not in TS) is listed -//! `pending` or `declined`. +//! Built-in manager for local and server plugins. use opencode_api::client::Client; use opencode_api::generated::{ @@ -37,8 +27,7 @@ pub fn plugin() -> abi::Plugin { struct State { opened: Cell, erring: Cell, - /// The server-list reads and checks asked for so far: only the reply to the newest one is shown, whatever order - /// they come back in (TS's resource keeps the newest). + /// Accept only the newest server list or check response. asked: Cell, directory: RefCell, server: RefCell>>, @@ -71,8 +60,7 @@ fn setup(setup: &mut abi::Setup) -> Result<(), String> { host.dialog(Dialog::Select(list(host, state, None))); state.fetch(host, Asked::List(state.opened.get(), state.next())); }); - // The list's own commands act only while it shows: run by name with no list, they open nothing (review carbon-5). - // The internal rows' switch needs no guard: an open starts it again, and only an open list shows it. + // Ignore manager actions when the list is closed. let internal = state.clone(); setup.command(hidden("opencode.plugins.internal"), move |host, _| { internal.internal.set(!internal.internal.get()); @@ -110,8 +98,7 @@ fn setup(setup: &mut abi::Setup) -> Result<(), String> { host.dialog(Dialog::Select(list(host, &back, key.map(str::to_owned)))); } }); - // After the host's question about a held build: the list on the row as it is now, and the server list read again, - // as `plugin.updated` went unheard while the question showed (review carbon-2). + // Refresh server entries after approval because list subscriptions stop while the question is open. let asked = state.clone(); setup.command(hidden("opencode.plugins.asked"), move |host, key| { if asked.opened.get() > 0 && !host.dialog_open(LIST) { @@ -211,7 +198,7 @@ impl State { } fn rows(&self, read: &dyn Read) -> Vec { - // Not the manager that runs, whose activation this is; a held build of its ID is a row (review carbon-3). + // A held build sharing the manager's ID is a separate row. let running = |entry: &PluginEntry| entry.id == ID && entry.active; let mut local: Vec = read.plugins().into_iter().filter(|entry| !running(entry)).map(Row::Tui).collect(); // A package without a server part runs nothing there; its TUI part has its own row. @@ -249,8 +236,7 @@ fn list(read: &dyn Read, state: &State, focus: Option) -> Select { }; let checking = state.checking.get(); let error = command("opencode.plugins.error", None); - // TS's order: check, then on the row view error (its own key), the host's toggle, update, and view error on enter; - // the toggle is the host's, which comes after these, and never shares a row with update or with the last. + // Keep the host's toggle distinct from plugin-supplied update and error actions. let mut actions = vec![SelectAction { title: if checking { "checking for updates" } else { "check for updates" }.to_owned(), key: Some("ctrl+r".to_owned()), @@ -260,7 +246,7 @@ fn list(read: &dyn Read, state: &State, focus: Option) -> Select { rowless: true, command: Some("dialog.plugins.check".to_owned()), disabled: checking, - // Kept with no package, so the server list's reply changes the select in place (review carbon-5). + // Keep the select mounted while waiting for the server's package list. hidden_all: !rows.iter().any(|row| row.package().is_some()), }]; actions.extend([ @@ -395,7 +381,7 @@ impl Row { } } - /// The project plugin's build waits for the user's approval, or was declined. + /// Whether the user still needs to approve this build or has declined it. fn held(&self) -> bool { matches!(self, Row::Tui(entry) if matches!(entry.status, PluginStatus::Pending | PluginStatus::Declined)) } @@ -444,7 +430,7 @@ impl Row { fn local(&self) -> bool { match self { Row::Server { plugin, .. } => matches!(plugin.source, PluginSource::Local(_)), - // TS's `path.isAbsolute`, which on Windows takes a rooted path without a drive (`/plugins/x`) too. + // On Windows a drive-less rooted path is absolute for the plugin manager. Row::Tui(entry) => entry.target.as_deref().is_some_and(|target| { target.starts_with("file://") || target.starts_with("./") @@ -513,8 +499,7 @@ impl Row { } } -/// What a slow plugin's footer says of its `report`: its costliest call kind and that kind's worst time, or its backlog. -/// The whole report goes in the row's details, so the footer leaves room for the title (PL-5). +/// Summarize the worst call or backlog in the footer; show the full report in details. fn slow_summary(report: &str) -> String { let Some(kinds) = report.strip_prefix("slow (p50/p99/worst): ") else { return "slow: backlog".to_owned() }; let worst = |kind: &str| -> Option<(String, f64)> { diff --git a/packages/cli-rs/crates/tui/src/plugins/notifications.rs b/packages/cli-rs/crates/tui/src/plugins/notifications.rs index 512a7e8e7c9..fd1dbe34483 100644 --- a/packages/cli-rs/crates/tui/src/plugins/notifications.rs +++ b/packages/cli-rs/crates/tui/src/plugins/notifications.rs @@ -1,7 +1,4 @@ -//! The notifications plugin (E.19a, row F09, `feature-plugins/system/notifications.ts`): asks for attention when -//! a session is done, a subagent is done, a form or a permission waits, or a session fails, and shows failures -//! as toasts. [`Tracker`] is the event logic; [`plugin`] feeds it the server's events. It is a plugin of the one API -//! (O-67). +//! Notify on session completion, pending requests, and failures. use std::cell::RefCell; use std::collections::HashSet; @@ -124,8 +121,7 @@ impl Tracker { self.terminal.remove(id); } V2Event::SessionExecutionSucceeded(event) => { - // A running subagent's report wakes the session again, so it isn't done yet. Subagent sounds stay - // as they were. + // A running child wakes its parent again; wait before reporting completion. let id = &event.data.session_id.0; if sessions.parent(id).is_some() || !sessions.running_child(id) { self.ended(id, sessions, &mut actions); diff --git a/packages/cli-rs/crates/tui/src/plugins/panel.rs b/packages/cli-rs/crates/tui/src/plugins/panel.rs index 28e07dd7b5c..d7d6f76f5c4 100644 --- a/packages/cli-rs/crates/tui/src/plugins/panel.rs +++ b/packages/cli-rs/crates/tui/src/plugins/panel.rs @@ -1,5 +1,4 @@ -//! The plugins' dialogs ([`abi::Dialog`]): a prompt, a list to pick from, a confirm, an alert, and a live panel, which changes in place while its key is open -//! (TS `/btw`'s `Answer`: the header, a body that scrolls, at most 60% of the screen high, and footer actions). +//! Host plugin dialogs and panels. A matching key updates a panel in place. use opencode_plugin::abi; use opencode_plugin::node::{self, Act}; @@ -51,7 +50,7 @@ fn max_rows(app: &App) -> u32 { type Owner = (String, u64); -/// Shows `dialog` of activation `generation` of plugin `id`, which owns it from now on. +/// Show `dialog` on behalf of plugin `id` at activation `generation`. pub fn show(tui: &Tui, id: &str, generation: u64, dialog: abi::Dialog) { let owner = (id.to_owned(), generation); match dialog { @@ -111,8 +110,7 @@ pub fn open(tui: &Tui, id: &str, key: &str) -> bool { mine && tui.dialogs.key() == Some(format!("{id}/{key}")) } -/// Closes the dialog plugin `id` opened, if it shows and the activation that opened it ended (4.14, deviation -/// `F16-plugin-dialog-ends-with-activation`). The dialogs replace each other, so the one on top is the only one. +/// Close a plugin dialog only when its owning activation ends. pub fn close(tui: &Tui, id: &str) { let owner = tui.reads.owner.borrow().clone(); if owner.is_some_and(|(owner, generation)| owner == id && !tui.plugins.owns(id, generation)) { @@ -156,9 +154,7 @@ fn ask(tui: &Tui, owner: Owner, asked: abi::Prompt) { tui.dialogs.clear(); run(&tui, &owner, &action, Some(value)); }); - // TS draws the description as a text of its own above the field (`{description}`), in - // OpenTUI's default text color; here in the color of the host's own prompt descriptions, over a few - // rows, so the field stays on screen. + // Use the default text color for prompt descriptions. let description = description.clone().map(|text| { Rc::new(move |cx: &DialogCx| { Text::new(&cx.app, &*text).fg(cx.theme.text.muted).max_height(DESCRIPTION_ROWS).as_any() @@ -190,8 +186,7 @@ fn bounded(text: &str) -> &str { &text[..text.floor_char_boundary(opencode_plugin::limits::get().text as usize)] } -/// The rich select on screen (synthesis 4.10): the select the plugin showed last, which a select of the same key -/// replaces in place, keeping the filter and the selected row. +/// Update a select with the same key in place so the filter and selection survive. pub struct Picker { key: String, owner: RefCell, @@ -342,7 +337,7 @@ fn list(tui: &Tui, owner: Owner, select: abi::Select, kept: Option<(String, Opti handle.move_to(&selected); } } - // The first footer was drawn before the hints could see the selection. + // Refresh hints once the first selection is available. handle.refresh_footer(); view }, else View::new(&cx.app)), @@ -359,8 +354,7 @@ fn styled(app: &App, theme: &opencode_ui::theme::Theme, span: &abi::Span) -> Tex Text::new(app, span.text.clone()).fg(fg) } -/// What a select with a query does as its filter changes (P6c): once the text has stayed the select's delay, its action -/// runs with the text, as TS's debounced `onFilter` (`createDebouncedSignal`). +/// Debounce filter changes before invoking the query action. fn query(tui: &Tui, picker: &Rc) -> Rc { let (weak, timer) = (Rc::downgrade(picker), Rc::new(Cell::new(None::))); Rc::new(bind!(tui.weak(), |tui, text: &str| { @@ -446,7 +440,7 @@ impl Picker { return; }; if let Some(plugin) = &option.toggle { - // Only the user toggles a plugin: a key or a click, never a run of the command by name (synthesis 3.6). + // Only a user key or click may toggle a plugin. let by_input = self.handle.borrow().as_ref().is_some_and(|handle| handle.by_input()); if !by_input { log::warn!("plugin {}: a row toggles a plugin only on a key or a click", owner.0); @@ -461,8 +455,7 @@ impl Picker { run(tui, &owner, action, Some(value)); } - /// Enables or disables `plugin` for the row of `value`, as the host does (synthesis 3.6): never the caller itself - /// or the plugin manager, after the key is handled, and only if the row still names that plugin then. + /// Toggle the entry selected by `value`. Refuse changes to the calling plugin or the active manager. fn toggle(self: &Rc, tui: &Tui, value: &str, plugin: &str) { let caller = self.owner.borrow().0.clone(); if toggled(tui, &caller, plugin).is_none() { @@ -485,8 +478,7 @@ impl Picker { Some((entry, Toggle::Switch(active))) => (entry, active), // The host's question, after which the list comes back on the row, unless a dialog replaced it. Some((_, Toggle::Ask(target))) => { - // The question replaces the select, which then holds the picker no more. The row's own action - // asks its plugin for the list as it is now (review bigboi-5); without one, the list as it was. + // Approval replaces the select; reopen the list through its owning plugin to get fresh rows. let (shown, value) = (picker.shown.borrow().clone(), value.clone()); let then = shown.options.iter().find(|option| option.value == value).and_then(|row| row.action.clone()); @@ -521,7 +513,7 @@ impl Picker { Some(Ok(())) => {} } tui.navigate(tui.route()); - // The hints say what the registry holds now; the rows are the plugin's, which hears of the change. + // Read hints from the current registry; the plugin supplies its own rows. if let Some(handle) = picker.handle.borrow().clone() { handle.refresh_footer(); } @@ -541,13 +533,13 @@ enum Toggle { fn toggled(tui: &Tui, caller: &str, name: &str) -> Option<(opencode_plugin::Entry, Toggle)> { let entries = tui.plugins.entries(); let plugin = opencode_plugin::Entry::plugin_key(name); - // A target names the entry it is now: a project's build keeps its target once approved (review carbon-2). + // Resolve the current entry by target across approval. let entry = entries .iter() .find(|entry| entry.key == name) .or_else(|| entries.iter().find(|entry| entry.key == plugin)) .or_else(|| entries.iter().find(|entry| entry.target.as_deref() == Some(name)))?; - // Never the caller or the manager that runs: a held build of their ID is another plugin (review carbon-3). + // Reject the active caller and manager, not unrelated held builds with the same ID. let refused = [opencode_plugin::Entry::plugin_key(caller), opencode_plugin::Entry::plugin_key(super::manager::ID)]; if refused.contains(&entry.key) { return None; @@ -615,7 +607,6 @@ fn actions(tui: &Tui, picker: &Rc) -> Vec Group::Primary, false => Group::Secondary, @@ -663,9 +654,7 @@ fn actions(tui: &Tui, picker: &Rc) -> Vec bool { let command = action .command @@ -678,8 +667,7 @@ fn usable_action(tui: &Tui, action: &abi::SelectAction) -> bool { usable } -/// Whether `key` parses as keys of the host's keymap and holds neither the reserved chord nor escape: the dialog's two -/// close keys, which a plugin's layer above them would take, keeping the user in its dialog (review carbon-5). +/// Reject Escape and the reserved chord so a plugin cannot trap the user in a dialog. fn usable_key(tui: &Tui, key: &str) -> bool { let keymap = tui.keymap.keymap(); let closing: Vec<_> = ["escape", opencode_plugin::abi::interact::RESERVED] @@ -732,7 +720,7 @@ fn detail(tui: &Tui, owner: Owner, details: abi::ErrorDetails) { run(&tui, &owner, back, None); } })); - // A TUI plugin's own error, which only the host reads (review bigboi-2). + // Only the host may read another plugin's error text. let error = details.plugin.as_deref().and_then(|key| plugin_error(&tui, key)); let props = crate::dialogs::error_details::Props { title: details.title.clone(), @@ -788,7 +776,7 @@ fn ask_yes(tui: &Tui, owner: Owner, confirm: abi::Confirm) { tui.dialogs.set_centered(centered); } -/// TS `dialog.alert`: however the alert closes, its action runs once after. +/// Run the alert action once after dismissal, regardless of how it closes. fn tell(tui: &Tui, owner: Owner, alert: abi::Alert) { let (size, centered) = (alert.size.map(dialog_size).unwrap_or_default(), alert.centered); let props = AlertProps { title: alert.title, message: alert.message, on_confirm: None }; @@ -809,9 +797,7 @@ fn tell(tui: &Tui, owner: Owner, alert: abi::Alert) { tui.dialogs.set_centered(centered); } -/// A plugin's dialog surface on screen (TS `ui.dialog.show`): the frame, with a header when it has a title, and in its -/// body the mount of the plugin's surface, which ends as the dialog closes. Built again in a new theme, it keeps its -/// widgets and the mount. +/// Host frame and mounted body for a plugin dialog surface. pub struct Body { key: String, /// The key the plugin named, which the mount's ID has. @@ -821,8 +807,7 @@ pub struct Body { title: RefCell>, frame: View, header: View, - /// The body's bounded scroll, which holds the body while it is taller than the room the screen leaves: it then - /// scrolls, and a focused node in it shows. A body that fits sits in the frame itself, laid out as TS's. + /// Scroll an oversized body within the screen and reveal its focused node. scroll: ScrollBox, /// The rows the screen leaves the body, and whether the scroll holds it. room: Cell, @@ -844,7 +829,7 @@ fn surface(tui: &Tui, owner: Owner, shown: abi::DialogSurface) { let (size, centered) = (shown.size.map(dialog_size).unwrap_or_default(), shown.centered); let open = open(tui, &owner.0, shown.shown_key()).then(|| tui.reads.surface.borrow().clone()).flatten(); if let Some(body) = open.filter(|body| body.key == key && body.surface == shown.surface) { - // A request that changes it in place and waits for its close hears it too (big-boi ds-10). + // In-place updates that wait for dismissal must receive it too. let dismissed = tui.reads.dismissed.borrow_mut().take().filter(|(of, _)| *of == owner); body.dismissed.borrow_mut().extend(dismissed); *body.owner.borrow_mut() = owner.clone(); @@ -867,7 +852,7 @@ fn surface(tui: &Tui, owner: Owner, shown: abi::DialogSurface) { } let app = &tui.app; let (header, body) = (View::new(app), View::new(app).column().focusable(true)); - // As high as the body, up to the screen's room: a taller body scrolls rather than leaving the screen (big-boi ds-9). + // Bound the scroll height to the available screen space. let scroll = ScrollBox::new(app) .scrollbar_colors(Color::rgb(0x9a, 0x9e, 0xa3), Color::rgb(0x25, 0x25, 0x27)) .min_height(0) @@ -917,8 +902,7 @@ fn surface(tui: &Tui, owner: Owner, shown: abi::DialogSurface) { if mine { tui.reads.surface.borrow_mut().take(); } - // The mount ends now, so nothing it asked for after the close goes out; its handler hears it closed, as - // the plugin's call, after the event that closed it. + // End the mount before dispatching its close callback so stale requests cannot escape. let body = closed.upgrade(); let mount = body.as_ref().and_then(|body| body.mount.borrow_mut().take()); if let Some(tell) = mount.and_then(opencode_plugin::PanelMount::close) { @@ -956,9 +940,7 @@ pub fn reveal(tui: &Tui, widget: &AnyWidget) { } } -/// A reload of plugin `id`'s registrations ended the mount of its dialog surface on screen: the dialog stays and mounts -/// again from the registration that replaced it, under the same key, so the JS host adopts what it rendered, as a -/// panel does (CT-29). Its handler hears no close. +/// Remount an open dialog against the plugin's replacement registration. pub fn remount(tui: &Rc, id: &str) { let Some(body) = tui.reads.surface.borrow().clone() else { return }; if body.owner.borrow().0 != id || !open(tui, id, &body.named) || !tui.plugins.has_dialog(id, &body.surface) { @@ -968,8 +950,7 @@ pub fn remount(tui: &Rc, id: &str) { body.body.clear(); let host = super::host::host(tui); let new = tui.plugins.dialog(&*host, id, &body.surface, &body.named, &body.body); - // What the user typed stays, with the caret: the plugin keeps its components, and an uncontrolled field's value is - // the host's (big-boi ds-2). + // Preserve the user's draft and caret when remounting an uncontrolled field. if let (Some(old), Some(new)) = (&old, &new) { old.hand_over(new); } @@ -982,8 +963,7 @@ impl Body { fn build(self: &Rc, tui: &Rc, cx: &Rc) -> View { *self.cx.borrow_mut() = Some(cx.clone()); self.draw_header(); - // Built again in a new theme, the frame is put back: the node of the body that had the focus takes it again - // (big-boi ds-6). + // Restore focus to the same body node after a theme rebuild. let frame = self.frame.id(); let focused = tui.app.focused().filter(|widget| { std::iter::successors(Some(widget.clone()), |widget| widget.parent()).any(|widget| widget.id() == frame) @@ -1162,8 +1142,7 @@ fn build(tui: &Tui, cx: &Rc, key: String, owner: Owner, panel: abi::Pa let set = |app: &App, height: u16| u32::from(height).min(u32::from(app.size().1).saturating_sub(6)).max(1); let scroll = ScrollBox::new(app).scrollbars(false).height(panel.height.map_or(1, |height| set(app, height))); let content = View::new(app).shrink(0.0); - // A bare panel is the dialog's frame and its body, which no box sizes or scrolls (TS `Dialog` around a plugin's - // own view); its header and footer are built and never shown. + // A bare panel supplies its own body sizing and scrolling. let fitted = !panel.bare; if fitted { scroll.add(&content); @@ -1176,7 +1155,7 @@ fn build(tui: &Tui, cx: &Rc, key: String, owner: Owner, panel: abi::Pa false => View::new(app).child(&scroll), }; let footer = View::new(app); - // A panel of a set height without actions has no footer row (TS `DialogLayout` without a footer). + // A fixed-height panel with no actions needs no footer. let footed = panel.height.is_none() || !panel.actions.is_empty(); let layout = match fitted { true => dialog::layout_view(cx, &header, &body, footed.then_some(&footer), DIALOG_INSET, 1), @@ -1349,7 +1328,7 @@ impl Live { &act, &mut hovers, &|text| { - // As in TS, of the plugins' Markdown only the `/btw` answer links sessions (`btw.tsx`). + // Only `/btw` answers resolve session links in plugin Markdown. if self.owner.0 != super::btw::ID { return tui.markdown(text).as_any(); } @@ -1380,9 +1359,7 @@ impl Live { } } -/// Runs `owner`'s `action` once the current event is handled; `value`, a prompt's text, is its input. An action whose -/// activation ended before then reaches nothing, not the build that replaced it (review carbon-pt-1), unless the -/// activation that replaced it goes on from it (a reload of a JS plugin's registrations, FT-4). +/// Defer the action until after the current event. Discard it if its owning activation has ended. fn run(tui: &Tui, owner: &Owner, action: &abi::Action, value: Option<&str>) { let abi::Action::Command { name, input } = action.clone(); let input = value.map(str::to_owned).or(input); diff --git a/packages/cli-rs/crates/tui/src/plugins/prompt_footer.rs b/packages/cli-rs/crates/tui/src/plugins/prompt_footer.rs index 727164ac6da..dbd630d4c31 100644 --- a/packages/cli-rs/crates/tui/src/plugins/prompt_footer.rs +++ b/packages/cli-rs/crates/tui/src/plugins/prompt_footer.rs @@ -1,12 +1,4 @@ -//! The prompt footer plugin (E.14, row F02, `feature-plugins/prompt/footer.tsx`), appended to `prompt.footer`: -//! -//! - the running subagents and shells of the session (a click opens the first child), its goal (`goal.rs`), -//! and its context use and cost, as far as they fit; -//! - otherwise the `agents` and `commands` hints, which read as disabled while the session pane does not own the input; -//! - in shell mode, `esc exit shell mode`. -//! -//! It is a plugin of the one API (O-67), on contract 2.0 (P6a). Each mount of a session's footer counts in [`Goals`], -//! which reads the goal: the surface hears its mounts begin and end ([`Event::Mount`]). +//! Prompt footer for session activity, hints, and status. use opencode_plugin::abi::interact::{Event, Handled}; use opencode_plugin::abi::v2::{Node, Place, Surface}; diff --git a/packages/cli-rs/crates/tui/src/plugins/sidebar_context.rs b/packages/cli-rs/crates/tui/src/plugins/sidebar_context.rs index 94ffe23e4c2..d96c1414ec6 100644 --- a/packages/cli-rs/crates/tui/src/plugins/sidebar_context.rs +++ b/packages/cli-rs/crates/tui/src/plugins/sidebar_context.rs @@ -1,6 +1,4 @@ -//! The sidebar's context section (E.14, row F04, `feature-plugins/sidebar/context.tsx`): the tokens of the last -//! reply, the share of the model's context they use, and the session's cost. It is a plugin of the one API (O-67), -//! on contract 2.0 (P6a). [`Last`] and [`money`] also serve the prompt footer. +//! Sidebar context usage and cost for the session family. use std::cell::RefCell; @@ -106,8 +104,7 @@ impl Last { self.models = self.location.as_ref().and_then(|location| read.models(Some(location))); } let mut stale = models || changed.list(&self.session); - // A message changed in place from the usage's source on moves the usage only if what it reads of it changed: - // each such message is read alone, so a streamed delta costs one message and not the session (P6a review). + // Re-read only changed messages that can affect usage; streamed text alone does not invalidate the total. for (session, id) in &changed.messages { if stale { break; diff --git a/packages/cli-rs/crates/tui/src/plugins/sidebar_footer.rs b/packages/cli-rs/crates/tui/src/plugins/sidebar_footer.rs index a570e19cba0..401f4bf0f89 100644 --- a/packages/cli-rs/crates/tui/src/plugins/sidebar_footer.rs +++ b/packages/cli-rs/crates/tui/src/plugins/sidebar_footer.rs @@ -1,7 +1,4 @@ -//! The sidebar footer (E.14, row F08, `feature-plugins/sidebar/footer.tsx`): the "Getting started" card while -//! no provider is connected and it was not dismissed (from 22 rows), then the location as `directory:branch`, -//! which brightens under the pointer and opens the working directory menu (E.20) on a click. It is a plugin of the -//! one API (O-67), on contract 2.0 (P6a). +//! Sidebar footer with the session location and dismissible getting-started card. use opencode_plugin::abi::v2::{Node, Place, Surface}; use opencode_plugin::abi::{self, Click, Command, Justify, Layout, Placement, Span, Wrap}; diff --git a/packages/cli-rs/crates/tui/src/plugins/sidebar_limit.rs b/packages/cli-rs/crates/tui/src/plugins/sidebar_limit.rs index e3b7817c3ad..6ef6decc0de 100644 --- a/packages/cli-rs/crates/tui/src/plugins/sidebar_limit.rs +++ b/packages/cli-rs/crates/tui/src/plugins/sidebar_limit.rs @@ -1,6 +1,4 @@ -//! The sidebar's limit section (E.14, row F05, `feature-plugins/sidebar/limit.tsx`): what the OpenCode Console -//! workspace's limits leave for the selected model, in the error color when it is out or reached. Hidden when -//! no limit applies to the model. It is a plugin of the one API (O-67), on contract 2.0 (P6a). +//! Sidebar warning for the selected model's remaining workspace allowance. use opencode_plugin::abi::v2::{Node, Place, Surface}; use opencode_plugin::abi::{self, Placement, Span}; diff --git a/packages/cli-rs/crates/tui/src/plugins/sidebar_mcp.rs b/packages/cli-rs/crates/tui/src/plugins/sidebar_mcp.rs index 8c54518f896..47ca9d86813 100644 --- a/packages/cli-rs/crates/tui/src/plugins/sidebar_mcp.rs +++ b/packages/cli-rs/crates/tui/src/plugins/sidebar_mcp.rs @@ -1,7 +1,4 @@ -//! The sidebar's MCP section (E.14, row F06, `feature-plugins/sidebar/mcp.tsx`): each server of the session's -//! location with its status. Above two servers the header folds the list, and the folded header counts the -//! active servers and the errors. A click on a server opens the MCP dialog on it, and on its error when it failed -//! (`mcp.list` with the server's name). It is a plugin of the one API (O-67), on contract 2.0 (P6a). +//! Foldable MCP status list for the session's location. use opencode_api::generated::McpServer; use opencode_plugin::abi::v2::{Node, Place, Surface}; diff --git a/packages/cli-rs/crates/tui/src/plugins/sidebar_todo.rs b/packages/cli-rs/crates/tui/src/plugins/sidebar_todo.rs index cfbdeae86a6..7cc5973f9c1 100644 --- a/packages/cli-rs/crates/tui/src/plugins/sidebar_todo.rs +++ b/packages/cli-rs/crates/tui/src/plugins/sidebar_todo.rs @@ -1,6 +1,4 @@ -//! The sidebar's todo section (E.14, row F07, `feature-plugins/sidebar/todo.tsx`): the list of the latest -//! completed `todowrite` call before the revert boundary. Above two items the header folds the list, and the -//! folded header counts what remains. It is a plugin of the one API (O-67), on contract 2.0 (P6a). +//! Show the most recent completed todo list before the revert boundary. use opencode_api::generated::{SessionMessageAssistantContentItem, SessionMessageAssistantToolState}; use opencode_plugin::abi::v2::{Node, Place, Surface}; @@ -61,8 +59,7 @@ struct Last { } impl Last { - /// Reads what `changed` may have changed; whether the list it shows changed. A streamed delta that leaves the - /// latest `todowrite` call as it was allocates nothing. + /// Refresh the displayed list only when a relevant message or boundary changes. fn update(&mut self, read: &dyn abi::Read, changed: &Changed, fresh: bool) -> bool { let info = fresh || changed.session(&self.session); if info { @@ -70,8 +67,7 @@ impl Last { read.session(&self.session).and_then(|session| session.info.revert).map(|revert| revert.message_id.0); } let mut messages = info || changed.list(&self.session); - // A message changed in place can change the list only if it holds a `todowrite` call or held the one the list - // came from: each is read alone, so a streamed delta costs one message and not the session (P6a review). + // Inspect changed messages individually; unrelated deltas must not rescan the transcript. for (session, id) in &changed.messages { if messages { break; diff --git a/packages/cli-rs/crates/tui/src/plugins/stats.rs b/packages/cli-rs/crates/tui/src/plugins/stats.rs index 22c7403f4bc..24ec5dc1c78 100644 --- a/packages/cli-rs/crates/tui/src/plugins/stats.rs +++ b/packages/cli-rs/crates/tui/src/plugins/stats.rs @@ -1,4 +1,4 @@ -//! TypeScript: `feature-plugins/system/stats.tsx`, `stats-data.ts`. +//! Session statistics poster. use opencode_api::client::Client; use opencode_api::generated::{ExperimentalSessionStatsInput, ExperimentalSessionStatsInputTools, SessionStatsInfo}; @@ -45,11 +45,10 @@ fn setup(setup: &mut abi::Setup) -> Result<(), String> { Some(Err(_)) => Node::text([Span::new("Could not load stats. Reopen /stats to try again.")]) .fg("text.feedback.error.base"), }; - // The terminal's height, as the poster reads it: on a resize the host's watch calls the view before a layout - // gives the route its new room, so the input's is the last frame's (review carbon-1). + // Use the terminal height during resize; the view notification precedes layout of the new route size. page(node, cx.read.info().size.1) }); - // As TS's `StatsPage` resource: each mount asks afresh, and a reply after the route went is dropped. + // Fetch on each mount and discard replies after unmount. let mounted = state.clone(); // The calendar and the logo compute their colors from the theme's, so a theme change calls the view (the 1.x route // rendered again on one). @@ -124,7 +123,7 @@ const DIGITS: [(char, [&str; 5]); 15] = [ ('T', ["111", "010", "010", "010", "010"]), ]; -/// The page's scroll, which keeps where it was scrolled while the route shows. +/// Stable key for the page's scroll offset. const PAGE: &str = "page"; fn page(content: Node, height: u16) -> Node {