Skip to content

Latest commit

 

History

History
421 lines (376 loc) · 30.3 KB

ui.md

File metadata and controls

421 lines (376 loc) · 30.3 KB

UI layer

Part of the architecture overview.

UI crates are shared by every feature and depend only on each other, the domain, service and the foundation: nocterm-ui, nocterm-workspace and nocterm-keymap. The workspace's seams are how features meet without depending on each other (ADR 0006).

The shared SessionOptionsEditor returns SessionOptionsInputError, retaining numeric parse sources and domain override validation. Callers format it when presenting a form error; malformed numeric text never becomes a saved override.

Theme, icons and notices

nocterm-ui projects tokens/settings into the standard GPUI Kit theme and accepts an explicitly installed SettingsHandle and returns its retained UiReady witness; it provides shared icons, terminal styling, standalone drag previews and operational notices. One retained ThemeUi owns catalog, settings and Design paint subscriptions. Catalog changes resolve effective tokens; published settings resolve and paint directly when tokens remain unchanged. Design observation paints only, preserving the one-way projection. Appearance callbacks apply the same supplied settings owner. UI initialization paints initial supplied policy; live changes require retaining ThemeUi. Terminal styling and form surfaces use supplied TerminalSettings plus the current paint tokens/theme. Optional toolkit button metrics are projected from design tokens once; views retain standard component variants. Notices use the toolkit's window-local notification list with stable operation keys and recovery actions, published by operation events rather than rendering. Drag previews capture painted source bounds and inherited typography because GPUI renders them outside the application root. Passive source renderers preserve Connections and Explorer row appearance; drag payloads remain independent of the visual snapshot, including multi-selection. Connections draw quiet insertion overlays and explicit append targets after every expanded group's last row. The toolkit shares tab/title presentation with passive previews and reports the actual source size and pointer offset to dock drop geometry. Terminal elements reuse the emulator snapshot until output, presentation state, size or palette changes. Selection, scrolling and search advance a presentation revision before event subscribers run. Input at an unchanged live screen waits for shell echo; cursor timing and IME overlays redraw only when their presentation changes. VT scroll boundaries preserve selection and avoid unnecessary output notifications, including selection recomputation in vi mode.

Settings controls

SettingsTextField owns native input, a 600 ms debounce, checked admission and the latest original receipt. Feature-provided typed bindings read and validate actual settings candidates; UI keeps no feature validators or document cache. SettingsTextField::section builds those typed bindings, preserving the caller's validation cause and publishing only a successful section candidate. Stateless form controls and checked-field rows share their presentation; pages keep their labels, callbacks, validation policy, field membership and teardown. Each distinct flush immediately enters the existing bounded settings queue, including while an older write is pending. Same waiting literal is deduplicated only at an unchanged published semantic revision; a later publication admits a fresh intention before delayed UI completion. Settled dedup uses the current confirmed value. The field retains one latest waiter; dropping an older waiter never revokes accepted service work. Matching completion reconciles canonical text and diagnostics; a newer literal remains intact. Publication failures remain visible and the same literal can be retried with Enter. Returning to a prior value is admitted behind a different pending candidate.

Published settings observations retain the original weak field/window. Forms own narrow redraw subscriptions with each field's membership, so an asynchronous failure updates the surrounding error even without a settings publication. Removing a field retires its handle and form observation together. Hosts flush before close/deactivation; shutdown captures already accepted edits through the existing service. A draft never flushed before native quit is not an accepted snapshot. No coordinator phase or quit handler is added (ADR 0054).

Plugin settings form

PluginSettingsForm draws the settings schema of one plugin (nocterm-plugin-model) with one control per field kind: a switch, a row of buttons or a searchable list for a choice, a checkbox per option, a stepper for a bounded number and a single-line input for text. FormScope selects the whole plugin or the groups of one contribution, and FormFrame draws it as part of a host page or labelled with a plugin's name. An empty scope says "This item has no settings".

The form never computes a number or a list from its own copy. Each control sends a FieldEdit to a PluginSettingsSource, a port named for the form's need: a switch and a choice send the value shown, while an option toggle, a step and text are applied by the source to the value current at write time. The source reports a typed PluginSettingsError; the form shows its text under the field and shows what the source holds, including changes made elsewhere. Text is sent once per 600 ms pause, on Enter or blur, and on flush, and is never overwritten while it waits to be sent. Text values are displayed literally in an ordinary unmasked input.

SectionBinding<S> is the system source: the owner supplies read and write functions over its own SettingsSection, and every write runs inside the store's checked update, so it is ordered with the owner's own writes and a refused edit changes nothing. PluginSettingsDirectory maps a system plugin to its schema and source. The test-support feature supplies FakePluginSettings (ADR 0085).

Rendering

Windows incremental painting stays inside the vendored GPUI renderer. Exact scene comparisons identify conservative damage; a retained image is cleared and recomposed only within that region, then copied completely to the swap chain. Terminal and workspace features do not manage GPU textures or dirty rectangles. Resize, device recovery, atlas content changes and unsupported content force a full frame. Unsupported partial-clear devices and retained-allocation failures keep the full-render path. The renderer patch notes describe the resource lifecycle and pixel-equivalence tests.

Linux uses original full rendering by default. Experimental incremental painting requires NOCTERM_EXPERIMENTAL_LINUX_RETAINED_RENDERER=1 and stays inside the pinned WGPU renderer. Supported surfaces receive a complete copy of a same-format retained image on every presentation, including unchanged scenes. Partial updates overwrite the damaged rectangle without blending and replay intersecting batches in order; reopened path passes restore the scissor. Atlas content revisions and renderer lifecycle changes invalidate the image. Capability, allocation and bounded-memory fallbacks preserve the original full renderer, which remains the pixel oracle. Two bounded snapshots reuse storage; an exact record-pair memo resets for each comparison. Snapshots rotate only after successful submission with an unchanged atlas revision, and invalidation releases their storage. The WGPU patch notes record the Linux scope, provenance and tests. Linux scroll-copy is not enabled. Measured retained scrolling still increased CPU per event by about 3.3–3.8% on the tested Radeon/Vulkan system, so it is not enabled by default. The shared GPUI Div scroll handler uses the same snapped and rounded bounds as prepaint to clamp a wheel offset before comparing and notifying. Events keep bubbling; fitting containers and scroll boundaries avoid transient invalidation. Variable-height virtual lists route wheel input separately from absolute scrollbar positioning. They traverse measured spans using sum-tree seeks and measure missing crossed rows during layout. At most 128 extra crossed-row measurements run in one pass; a coalesced distance and an explicit next-frame request continue larger movements. Ordinary visible/overdraw layout retains its own work. Explicit uniform-height hints retain their approximate jump policy. Navigation, reset, thumb dragging and removal of the anchored row cancel deferred wheel movement.

Workspace

Workspace coordinates eight private owners besides its focus handle: WindowSurfaces, Chrome, PanelGroups, body, ShellLayout, installed ports, registered actions and the registrations of the plugin catalog. Chrome owns window menus, the new-tab popover and the status bar; PanelGroups owns the navigation and assistant groups: their visibility, selected panel, attention, expansion and panel subscriptions (ADR 0081). The members of a group and their order come from the resolved layout; a panel the layout leaves in the tray stays openable by id but is outside next-panel and the toggle numbering. Panels and widgets register under the ids of the plugin catalog carried by Deps: the workspace checks the id and its kind, creates the view from the owner's factory (which may read the workspace) and places it by the descriptor (ADR 0082). nocterm-ui maps a descriptor's Icon and WidthClass onto its icon names and column widths. ShellLayout also follows [plugins]: it re-resolves the layout against the plugins that are off, and each window creates a plugin's panels and widgets only while it is enabled and drops them when it is switched off (ADR 0086). ShellLayout reads the [layouts] settings through the SettingsHandle in Deps, keeps the document it last saw and resolves the selected layout against the catalog; each window observes the handle and, by the transition of the two documents, either re-sides its groups and opens the panels a switched-to layout names, or only rearranges (ADR 0084). The StatusBar keeps widget factories and creates a widget's view when the layout first places it. A group's side comes from its zone, a pinned widget the layout omits goes to the end of the right zone, and an omitted panel that asks for attention is drawn at the inner end of the right zone (ADR 0083). A right click on the footer opens a context menu (status_bar/menu.rs): Hide for the item under the pointer, unless it is pinned, Customize Status Bar… (OpenLayoutSettings, naming the item) and a Layouts submenu. Hide is the same checked edit (edit_layouts, RemoveToTray) the editor uses, and a refused write is shown as a notice (ADR 0087). The Clock plugin (clock::PLUGIN, widget clock.time, right zone, auto: Tray) is declared here beside the shell: Deps::with_clock supplies a WallClock, Workspace::new registers the widget when one is given, and ClockView re-reads it when its text can change (each second with seconds on, else at the minute boundary and at least every five seconds, so a suspend or a time-zone change shows within seconds) only while a layout places the widget and the plugin is enabled. The plugin owns the [clock] section (ClockSettings: 24/12-hour, seconds, short date) and its schema; clock::plugin_settings binds them for the Plugins page and the editor, and every window's view follows a change (ADR 0088). Immutable observations expose tab identities and native pane order without giving callers mutable native entities. Transitions commit membership and subscriptions before the shell emits events or changes focus (ADR 0026).

WindowSurfaces retains the outer connection dock. Each workspace is an outer ProjectView Item containing its own ProjectSurface with ordinary terminal tabs, splits and background sessions. Both docks use the existing tab engine. Window settings, sidebar and right-panel visibility keep their window owners (ADR 0067).

The active outer Item supplies the visible chat ContextId; switching inner tabs keeps the same workspace history. Source receipts identify the original native window, outer Item and inner surface. SurfaceSelection owns source and selection receipts plus presentation lifecycle; SurfaceState owns initial terminal issuance, the starting folder and monitoring identity. Selection generations prevent a delayed menu or focus callback from acting after switching tabs. Hidden sessions keep running and their events update their original surface.

nocterm-workspace-ports::ProjectTerminalOpen captures the connected parent once. Its private terminal provider retains the complete resolved location, original SessionSpec and installation. Opening an inner tab uses the normal local/SSH terminal lifecycle; ordinary folders change the initial directory and container locations adapt the launch and execution capabilities. Shell options, credentials, proxy and ordered jump hosts stay on that source. New tabs and reconnect work independently of the original parent tab.

The project terminal contracts and typed context refusals live in workspace-ports without workspace reexports. A private ProjectTerminalPlacement retains original surface authority; the typed validation/admission bridge keeps native selection and Item cleanup in the shell. Providers validate before creating terminal Items (ADR0079).

ExplorerSource exposes ordinary session file access and the workspace's initial folder. Local folders use the existing local pane; SSH folders use the remote pane. Navigation and file operations follow normal host permissions. Container and unavailable provider locations do not expose a host folder through this projection. The neutral terminal resolver dispatches explicitly registered provider IDs, binds the resource before opening and refuses missing providers (ADR 0071).

Shared directory controls in nocterm-ui receive read-only directory contracts from nocterm-explorer. Explorer and workspace creation share native input, completion and navigation controls while keeping their own listing acceptance and view lifetimes. Source and request generations reject stale results (ADR 0072).

Saved workspace lookup includes ordinary central, local and background terminals. When no matching connected parent exists, ProjectTerminalResolve supplies an ordinary terminal provider from saved server metadata. Profile destination and ordered jump route must still match. Authentication happens inside the workspace's first terminal; no separate server tab or parent-connection waiter is created. Opening callbacks check the current definition and surface membership. Hidden workspaces do not steal focus. The header and sidebar identify the server using its configured name and icon, while the outer tab identifies the workspace (ADR 0070).

Chat attachment menus and tool resolution use the same original terminal seat. Saved-server metadata is available in both General and workspace chats; active terminals remain limited to that seat's surface. ChatConnectionOpen opens an explicitly selected server in the original surface through the app's ordinary terminal composition. It checks the live source before creating a terminal, retains the saved credentials and ordered jump route, and does not select a hidden workspace. Closed surfaces and foreign windows refuse the operation.

nocterm-workspace owns window layout, tabs and sidebar switches through native DockArea/DockSkin instances. The toolkit owns one pane tree per retained surface and drag previews; an adapter exposes Items as dock Panels. Presentation aliases are separate from Item/session titles. Shared actions operate the same dock for keyboard split/reorder/focus. Tab context-menu closures capture the original surface/selection and clicked Item, reject stale selections and resolve that surface's current pane order at execution; closing adjacent/other tabs cannot cross pane boundaries. The full-width workspace footer is drawn from the resolved layout (ADR 0083): panel toggles, the notice bar, the local terminal toggle and status widgets in three zones. A bar with an empty centre is one flat row, with the right zone pushed to the end. A bar with a centre is three slots: the outer two share the width the centre leaves, so the centre stays at the window's midpoint (up to layout.status_bar_center_max) while nothing is cut. Toggles and separators never shrink, and an outer slot never gives up the room they need: the centre and the notice line truncate first, and only then does the right slot clip, from its outer end, so a toggle that asks for the user stays visible. Widgets keep their size like toggles: one that does not fit moves whole into the menu. Where the row would still be too wide, the entries that do not fit move into a » menu at the end of the bar (status_bar/overflow.rs), widgets first, then the local terminal toggle, then panel toggles (the open ones last); the notice line and a toggle that asks for attention are never moved. BarOverflow keeps the widths the row measured, shared by the row, the inputs of each frame and the click handlers, and a pure planner (overflow/plan.rs) chooses what to hide, so the bar is drawn whole until it has been measured and settles one frame after its width or its entries change. The menu rows are the toggles' own actions and the widgets' own views; a popup a widget opens from its row (the host monitor's details) is drawn outside the menu's box, and the menu stays open while that popup has the focus, so a press inside it does not close the menu under it. A widget registered with WidgetRegistration::zone_aware implements ZoneAware and is told the zone that places it, on creation and when a layout moves it, so its popover can open toward the inside of the window (nocterm_ui::zone_anchor); the notice list does the same through NoticeBar::anchor. Removing the last bottom Item also removes its Dock instead of merely emptying the tab list. Hiding the local dock uses native dock visibility, preserving its pane tree, sizes, tab order, selections, groups and running processes. Within a surface every tab shares one Item registry and the same close, split, grouping, rename and keyboard operations. Close scopes resolve the clicked tab's current native pane; Close All affects its dock placement. LocalTerminal directory synchronization returns LocalDirectoryError, distinguishing missing or disconnected shells, unsafe paths, unsupported integration, busy prompts, charset encoding causes and input queue rejection. Consumers format errors at notice presentation; the workspace retains the selected target on refusal. Local shell capability is an optional Item contract, so mixed panes and moved local tabs retain identical ownership. Local focus preserves the last central remote context for Explorer; native group selection owns the local cwd target. Header add controls pass an explicit LocalTerminalTarget::Beside(EntityId) to the opener, resolving the live anchor pane when the new shell registers, including moves to Center. A stale anchor closes only the new shell; registered Items are never closed by a rejected registration. Native pane queries and empty-region cleanup belong to the Tabs owner and its DockTopology capability. DockItem adapts presentation; each tab entry owns its feature handle, cached session and focus/event subscriptions. LocalDockState owns selection and remembered height, not a second placement tree. Zoom permits tab reordering and grouping: same-group reorders retain zoom, while accepted topology changes clear it to reveal their result. Hiding Bottom leaves local tabs moved to Center visible. A region's last tab can be dragged to another open visible region; the final visible tab of a surface and explicit locks remain protected. Empty noncentral regions disappear after moves without closing Items. An Item supplies tab content, focus and an optional SessionContext; a Panel supplies sidebar content. Features register actions rather than making the shell depend on them. SessionSpec and a session opener connect requests from the connections feature to the terminal feature. Cached session contexts avoid reading an Item reentrantly during its own render; matching connected contexts also support transfer retry while a utility tab is active.

The narrow terminal ports, SessionContext and ConnectionSummary are declared by the nocterm-workspace-ports service crate and re-exported by the workspace, so services can consume them without depending on the window shell (ADR 0062). They return TerminalError, retaining charset sources and concrete capability, prompt, ownership and queue refusals. open_on_host returns OpenOnHostError, retaining launch validation and identifying a missing connected session. Consumers format these causes at notices or agent transcript boundaries.

The Item supplies an immutable TerminalCapabilities record with a required state port and independent optional operations, among them TerminalFiles, which returns the filesystem of a terminal's exact current connection (Local, or Remote with its host and RemoteFs) or refuses a stale, disconnected, prompting or filesystem-less terminal. ExpectedSession binds calls to the workspace Item and connection epoch. UserPromptToken also binds the exact secret prompt. Unsupported operations refuse explicitly; replacement sessions cannot inherit queued approvals, grants or prompt answers. Reconnect returns its accepted epoch so every waiter can reject an unrelated subsequent replacement.

Tab groups

Tabs can be grouped. Groups are workspace state the dock knows nothing of: tab_groups holds membership and colors, and after every layout change TabGroups::gather finds the member the user moved and brings the rest of its group beside it in their previous order, so dragging any member drags the group, and a tab dropped among a group is moved out of it. Each tab's group color reaches the tab bar through the vendored gpui_kit::component::dock::Panel::tab_accent. A program opened from a session on the same host joins that session's group; splitting a tab off takes it out of its group, and a group left with one tab ends.

Sessions without a tab

Workspace also keeps sessions without a tab. open_background_session asks an installed background opener (Terminal's) for an Item it holds outside the dock; such sessions appear in terminals() marked background, can be moved into a tab with show_background_session, and end with close_background_session. The agent opens them for attached saved servers that have no session; a chat closes those it opened when it closes or no longer attaches the server.

The active host

Features that run programs on the active host share the workspace's host module: Host::resolve picks the session's own connection when it can run programs and this computer otherwise, and follow_active_session reports tab switches and reconnects.

The resource monitor uses a separate consumer projection, MonitorSource, because outer connection tabs do not identify a selected workspace's inner environment. The original surface entity owns inert checked target metadata; its live inner session supplies authority. Workspace::monitor_source distinguishes selected, unavailable and genuinely local contexts. Monitoring never resolves an unavailable project through another surface or the local runner. Shared Host::resolve and ordinary active-session consumers keep their existing semantics (ADR 0077).

Command palette

The command palette (workspace::command_palette, Ctrl+Shift+P, Cmd+Shift+P on macOS) lists no commands of its own. When it opens it asks GPUI for the actions available where focus is — the focused view's, its ancestors' and application handlers — keeps nocterm's namespaces (workspace, terminal, connections, files, agent, vault), names them from the action (workspace::OpenSettings → "Workspace: Open Settings"), searches their actions! documentation as well and shows the shortcut. The chosen action is dispatched from the view that had focus, exactly as its shortcut would be, so a feature makes a command available in the palette by declaring and handling an action, nothing more.

Layout memory

Widths the user drags resizable columns to, and layout choices, are kept by an explicitly injected nocterm_ui::LayoutHandle, keyed by name and saved to layout.json in the state directory. Its private nocterm_store::Persisted entity keeps changes immediately visible and coalesces pending snapshots into the latest arrangement. Bootstrap retains that same handle in the workspace dependencies for every new window. Agent presentation receives the same handle through its supplied Installed. observe_size projects only changes to one normalized visible scalar; caller-owned subscriptions exclude unrelated keys, flags and persistence-only notifications. Shared history split updates are applied at the next native group rebuild, preserving its existing entity and subscriptions without another persistence write. LayoutMemory is an initialization namespace returning the explicit handle. It keeps the existing application quit hook in its initializer and has no global state or fallback arrangement. Clones share the original persistence participant. The explicitly injected ShutdownCoordinator captures layout before background drain and shares one deadline across its registered participants (ADR 0013). Settings also uses nocterm-store, with durable publication rather than optimistic layout projection. Bootstrap registers both settings and layout with the same coordinator alongside snippets, connection state, agent documents and output recording. The workspace body lays out one column per shown panel group and the tabs — navigation, tabs, assistant, or mirrored by the Swapped layout; the columns follow the order of their groups in the bar, and a panel that stands alone is a column of its own (ADR 0094) — with one resize state per arrangement, and remembers widths per width class rather than per position: a hidden column kept in the resizable group would hold its stale width and stop its neighbours from growing. Expanded chat replaces central content while visible navigation retains its side and width. Hidden, docked and expanded panel presentations have separate resize states; expanded measurements never overwrite remembered docked widths. Navigation controls preserve expansion, and closing navigation focuses the visible chat. An expandable panel learns its side through ExpandablePanel::set_side; the agent panel puts its history column on the outer side and remembers that column's width. A side panel that opens a column of its own asks the workspace to widen it with PanelRequest::Widen. Panels are shown and hidden by their feature's action (files::ToggleExplorer, connections::ToggleServers, containers::ToggleContainers) through Workspace::toggle_panel with the contribution's id, so the workspace binds no feature's panel. ToggleRightPanel is the remaining legacy action; it acts on the assistant group.

Key bindings

Key bindings are data. nocterm-keymap (UI layer) owns the keymap format, the merge of the application's defaults (assets/keymap.toml) with the user's keymap.toml, which lists only differences ("none" unbinds), and installs the merge in GPUI. Its bindings carry a metadata mark, so a change replaces exactly them without a restart and leaves the component library's own bindings alone. Edit APIs return KeymapError, preserving native keystroke and persistence causes. A failed save leaves the desired binding installed and reports the failure; a later successful edit persists the current desired keymap. The composition root retains a cloneable KeymapHandle around the private owner and passes it to each page and window. Named edits install owned marked bindings after releasing the entity borrow, then notify observers, including persistence failure. The typed shared PersistError is the same original cause returned to the caller; invalid keystrokes leave the previous state and diagnostic intact. Native loading and synchronous keymap persistence remain existing UI-layer migration debt. See ADR0051. It also names actions for people (humanize) and decides which are user commands (offered), for the command palette and the keymap page alike. nocterm-keymap-ui is the Keymap settings page, a guest page like the vault's: a searchable table that records new shortcuts through a keystroke interceptor (so even bound keys are captured) and edits only through nocterm-keymap.

TerminalStyle::with_settings projects an explicitly supplied terminal section through the current design and theme rules. Terminal views use their installed SettingsHandle; dialogs and settings surfaces capture their original supplied owner. Their backgrounds retain the same terminal colour and alpha conversion.

Shared UI does not register or read the AI policy schema. Agent runtime registers its own supplied settings section; standalone settings-page compositions register that section explicitly before constructing AI controls.

Shared settings presentation

SettingsTextField owns native text, checked immutable admissions and the original store receipt. FieldPresentation retains that field and its weak redraw observation with the page membership. The small shared syntax helpers parse numbers and JSON; agent resolution and credential policy remain in the AI domain and Agent page. SettingsPageSpec supports the same plain lazy guest factories and contextual builtin factories. The latter receive only their original SettingsHandle and per-Item save feedback. The additive flush operation leaves existing guest lifecycle contracts intact. SettingsPage::reveal(anchor, window, cx) lets a page bring forward the part an anchor names (a plugin id on the Plugins page, layout/<id> for an item in the editor of Appearance); the default returns false and the host SettingsPageHandle::reveal forwards it to a constructed page (ADR 0086).