CodeNomad/dev-docs/UI_SHELL.md
Pascal André a349a59204
Some checks are pending
Publish help / build (push) Waiting to run
Publish help / deploy (push) Blocked by required conditions
feat(ui): consolidate diagnostics in non-modal output windows (#1467)
Group session navigation beside the panel toggle, centre Sessions, and retain New session/Search at the trailing edge. Remove the duplicate Info view and keep global OpenCode diagnostics in Settings > OpenCode.

Read the selected execution host's fixed opencode.log through the CLI's documented log directory, using bounded 128 KiB snapshots, strict selector validation, no-store responses and source-change/cancellation fences. Share the movable, non-modal output frame with native background-shell output while keeping log bytes separate from messages and model requests.

Restore saved Info selections only after native parent hydration without claiming user-selection authority. Keep output open across unrelated settings changes, and update all ten locales and affected help pages.

Validation: 76 browser tests, 6 backend tests, 15 restoration tests and 31 help tests passed, along with server/UI typechecks, production UI build and whitespace checks. Independent gatekeeper review of exact head 8ccbfeb236e17ba02c3232a8a038c122c47976e8 reported zero actionable findings; a COMMENT review records the evidence.

CI state at administrative merge: help build and completed authorization/compatibility checks passed; the remaining platform, native and browser jobs were still in progress, with no reported failing check. Those in-progress jobs are not represented as passed. The unrelated existing Missions help-anchor assertion is documented in the PR.

Closes #1465.
2026-11-11 16:24:26 +01:00

17 KiB

Application shell

Panel toggles, floating drawers, project/right-panel tabs, the session sidebar and native application menus.

Agent conventions

  • Status is the first right-panel tab by default (core-plugin.tsx); saved tab orders take precedence. In RightPanelCustomizationPopover, its always-available row has a chevron in place of a visibility checkbox. That chevron folds only the customization's section checkboxes, preserving the sections' visibility and order; it starts expanded each time the customization opens.

  • Status Background Shells lists running shells whose IDs occur in OpenCode's experimental.job.list shell inventory, through the owned /api/workspaces/:id/background-shells route. The selected Location's shell.list supplies metadata; session ownership authorizes tool shells independently of their working directory. Read only while the section is visible and expanded, refreshing on Shell lifecycle, tool completion (which follows background admission) and reconnect. Inventory returns its native directory for event matching alongside the host-side demand alias, including WSL projects without a selected conversation; events during the initial unresolved read schedule one coalesced follow-up. Keep each command on one clipped row with its two icon actions; shell/cwd/PID/status are in the row's tooltip. Output preserves the native cursor and renders plain text and ANSI HTML in distinct elements. Cover source selection, ownership, output, stop, narrow and RTL geometry with the shell store/proxy suites and tests/browser/background-shells.test.ts.

  • The right panel's tab scroller (RightPanel.tsx) is position: relative, so it contains every absolutely positioned descendant of a tab: content of any tab, an extension's included, never grows the shell's overflow (which would scroll the whole window under the project tabs). A tab that scrolls itself is also its own containing block (Missions: dev-docs/MISSIONS.md).

  • Docked panel resize handles follow the composer's Pointer Events design: capture the pointer on the handle and keep its .is-resizing highlight until pointer up/cancel, capture loss or the active handle's cleanup. Scope each handle's cleanup to its own side so resizing continues when the opposite panel closes. Keep event handlers local in useDrawerResize.ts and styles in styles/panels/session-layout.css; validate both sides, RTL and touch with tests/browser/panel-resize.test.ts.

  • Session rows keep actions inline until their measured title, badges, and controls no longer fit. Keep responsive action styles in styles/components/session-row-actions.css; hidden inline controls remain measurable but inert, and an open overflow menu stays mounted until dismissal.

  • SessionList, MissionRows and virtual task rows share lib/preserve-list-focus.ts for keyed DOM moves. Restore the last still-connected focused control only when an actual removal/reinsertion left focus on the document body, using preventScroll. Later focus, Tab and outside-pointer intent take precedence; hidden, inert and unfocused documents retain their own focus policy. Keep native wheel scrolling independent of focus restoration and validate connected row moves with the real list components.

  • A parent's own expander chevron, expanded or collapsed, carries its descendants' most urgent visible state (input steady, working/compacting pulsing, idle steady green) with counted states in its label (session-child-activity.ts); idle follows the existing badge visibility, unseen-subagent preference and seen/fade lifecycle, and excludes interrupted sessions by recovery state regardless of acknowledgement. The chevron always toggles expansion and preserves descendant badges; never add a separate badge. Its context menu (components/session-expander.tsx, Kobalte ContextMenu with the shared overflow-menu items; right click, the Menu key or Shift+F10) offers Mark as read, which clears the Idle and Interrupted badges of the row and every descendant exactly as clicking each badge does, never touching work or pending input; it is disabled while nothing in the hierarchy shows such a badge. General's autoExpandActiveSubsessions preference defaults on: when a visible collapsed row is selected or has the selected conversation as an ancestor and its descendant activity changes to working, compacting or permission/form input, SessionList reveals the paths to active descendants through revealSubsession. This applies recursively to visible subsessions at every depth. Check the row against the scroll viewport, including Virtua's offscreen buffer. Observe activity kind independently of expansion and preferences; scrolling a busy row into view, collapsing it or enabling the setting alone leaves its current expansion intact. Activity in other families stays represented by the chevron. Manual and activity-driven expansions share the same restorable state and local restoration authority. Styles live in styles/components/session-child-activity.css; validate with tests/browser/session-child-activity.test.ts and stores/session-subsession-activity.test.ts.

  • Idle and Interrupted badges are keyboard-activatable Clear buttons beside the session-selection button. Clicking or sweeping across them clears Idle through markSessionIdleSeen and acknowledges Interrupted through markSessionInterruptionSeen; work, retry and pending input/permission remain visible. Viewing a conversation clears only Idle; Interrupted requires an explicit clear gesture. Row badges share the one-way toggleSweepClear group in lib/toggle-sweep.ts, preserving mouse/pen sampling, release suppression and touch scrolling. Keep the message-reload action unchanged. Validate with tests/browser/session-status-clear.test.ts.

  • Conversation header actions (inline and in their overflow menu) offer the web preview on every platform, with Full screen added on mobile. Remote Control clients hide the preview entry while their host keeps web previews off: /api/meta then reports previewsUnavailable (previewsUnavailable() in lib/server-meta.ts). Validate with tests/browser/header-windows.test.ts.

  • Session hierarchy geometry lives in styles/components/session-tree.css; connector axes follow the parent expander at every depth, including selection mode, RTL and touch layouts.

  • Session search/filter mode uses flat per-session results with an optional subsession switch; filters, sorting, worktree badges and selection use each result's own identity. Normal browsing retains the session hierarchy.

  • Session archive actions use native session.update({ archived }), serialized with other session actions, followed by an authoritative inventory refresh and flag verification. Native events project time.archived; stale metadata reads retain newer event authority. Normal browsing and list-cycling hide idle archived branches, keeping selected conversations and running/pending-request paths reachable. Children retain their own flags and remain independently discoverable in flat search/filter mode. The archive selector is local to that search surface (Unarchived / Archived / All), with the native flag badge and Restore action; never persist a separate archive state or treat archive as interruption/deletion. Validate session-archive.test.ts, session-tree.test.ts, browser session-archives.test.ts and scripts/test-session-archive-native.mjs.

  • Project and right-panel tabs share components/tab-scroll.tsx and styles/components/tab-scroll.css. Keep their native scrollbar above upright content without mirrored transforms, negative border overlaps or permanent compositing hints. Validate shared scrollbar styling and adjoining edges at fractional zoom in the browser and isolated Electron renderer fixtures (tests/browser/tab-chrome.test.ts).

  • The Status tab starts with the shown session's goal line (components/session/session-goal-line.tsx, styles/panels/status-goal.css) only while that session has a /goal: one row above the sections with the status badge (.session-goal-badge in styles/components/badges.css), the objective truncated with its full text and the reason in its tooltip (the reason is also the row's accessible description), the rounds, one Pause/Resume button that keeps focus as the status flips, and Clear. While a command runs its actions are aria-disabled and ignore activation, never disabled, so the focused button keeps keyboard focus. Never add it to CORE_STATUS_SECTION_ITEMS or the right-panel customization, and never show a hint, empty state or gap without a goal. Contract, commands and freshness: OPENCODE_COMPATIBILITY.md (Session goal). Validate with tests/browser/session-goal.test.ts.

  • Built-in right-panel tabs are constructed directly in right-panel/core-runtime.tsx (never add a first-party plugin loader for them); external sandboxed panels keep their independent consent/loading path.

  • Integration Status sections are registered by right-panel/integration-status-module.tsx under stable integration:<id> IDs, in catalog order after Plugins. Saved order and hidden IDs retain absent sections; dragging moves only the source, and Up/Down in customization uses the same ordering for every section. Stable section objects preserve focused DOM across refreshes. Expected-action changes expand once, respecting subsequent user collapse. One attachment owner and one grouped polite live region belong to each Status tab; disappearing focused sections hand focus to the Plugins accordion trigger. Conversation attachment controls and binding labels live exclusively in these sections.

  • Embedded floating session drawers use instance/shell/HostedDrawer.tsx so their SUID modal roots are direct children of the existing geometry host. A Solid Portal wrapper must not become an ARIA-hidden ancestor of visible controls. Preserve SUID's modal stacking, sibling isolation, focus policy, Escape/backdrop handling and scroll restoration; validate with tests/browser/drawer-accessibility.test.ts rather than overriding ARIA or disabling modal enforcement.

  • Floating-panel outside-pointer and Escape dismissal leave ARIA menus, listboxes and dialogs to their own selection/dismissal handlers (shell/drawer-events.ts). Their portals are outside the drawer DOM, and closing the drawer on pointerdown destroys a menu before touch pointerup selects its action. Both the shell's capture listener and SUID's Escape policy defer to nested surfaces; focus and isolation stay with SUID. Keep this guard shared in the shell, not in individual menu actions; validate the real session Delete confirmation with tests/browser/session-delete.test.ts and Status menus with tests/browser/integration-attachment.test.ts.

  • Each side panel has exactly one open/close control: instance/shell/ShellPanelToggle.tsx (PanelLeft/PanelRight, .icon-toggle with aria-expanded/aria-controls), absolutely placed at the shell's outer header corners (--space-xs from the window edge) in .session-shell-frame, outside the drawer host so modal sibling isolation never hides it, and above floating drawers. The frame is an isolated stacking context: toggles stay above in-frame drawers but below body-portaled dialogs, scrims and utility windows. Both toggles precede the shell content in tab order and use the fixed View-menu labels (window.menu.leftPanel/rightPanel) with aria-expanded, never an Open/Close label flip. They are strictly fixed: no horizontal or vertical movement between docked, floating and closed states in any layout; the sidebar header, right-panel tab bar (both edges when floating) and the conversation header (data-{left,right}-toggle-reserve) reserve their footprint instead. Every header's action row (session list header row, right-panel .tab-strip-shortcuts, conversation side groups and status indicators, with or without the title row) and the toggles centre on one shared line, --panel-header-action-center in styles/tokens.css; never measure per-state offsets. The session list header holds a single action row; never add a keyboard-shortcut footer below the session list. Opening one floating drawer closes the other; the outside-pointer handler ignores the toggles. Styles live in styles/panels/shell-panel-toggles.css; validate with tests/browser/shell-navigation.test.ts.

  • Each side panel keeps whether the user wants it (opened, or closed while docked) and docks while the window has its room, in a fixed order: the session panel first, the right panel only beside it (instance/shell/useDrawerChrome.ts, drawer-layout.ts). Narrowing shrinks the conversation to its minimum, then the right panel to its minimum, where it hides, then the left panel to its minimum, where it hides: each panel hides at the end of its own compression, so the other never changes width at that moment and only the conversation takes the room. A hidden wanted panel returns with the room, so the layout follows the window width alone, narrowing and widening alike (a minimizing window's tiny viewport included). A panel opened without room floats over the conversation; dismissing it keeps the docked choice, and it docks once it has room. On touch tablets each orientation remembers the wanted panels. A panel hidden by the layout hands focus to its toggle when it last held focus, even when the focused control already left the DOM. Choosing from the floating session panel's list closes that panel, the shown session included; Back/Forward keep it open. Validate with tests/browser/shell-navigation.test.ts, whose narrowing/widening sweep requires panels never to grow back or reappear while narrowing and widening to retrace the same layouts.

  • The session sidebar header groups Back/Forward beside the leading fixed panel toggle, centres Sessions between navigation and trailing New session/Search, and truncates the title at narrow widths. Back/Forward (ArrowLeft/ArrowRight, mirrored in RTL; history wording "Back"/"Forward" with conversation tooltips, distinct from the palette's Previous/Next Session list cycling) use a browser-like in-memory history per project tab and window (stores/session-navigation-history.ts, instance/shell/useSessionNavigationHistory.ts, at most 50 entries). It records every displayed conversation whatever selected it; the no-session draft stays outside the history (Back first returns to the cursor entry). Navigating moves the cursor and selects through the ordinary handleSessionSelect path without pushing; a new selection truncates the forward stack; unavailable/deleted sessions are skipped and determine the disabled states. Do not add keyboard shortcuts or persistence to this history.

  • Native Electron/Tauri application menus follow the UI locale: renderers translate NATIVE_MENU_LABEL_KEYS (lib/native/menu-labels.ts) and send them with the View menu state. Hosts keep English until a renderer reports labels, keep the last locale for windows without one, and escape & outside macOS. Electron takes its defaults from lib/native/menu-labels-en.ts; Tauri's menu_labels.rs defaults are checked against the English messages by menu-labels.test.ts. Tauri retitles retained items in place; Electron rebuilds its menu on a label change. Local application and Preferences windows draw their own title bar (components/native-titlebar.tsx). On Windows and Linux they are frameless: the main window's title bar presents the menus, and both carry the window controls. On macOS the menus stay in the global menu bar and the hosts keep the native traffic lights at their standard place over the title bar's left end (Tauri overlay title bar in title_bar.rs, Electron titleBarStyle: "hidden"); the title bar takes the native 28 px title bar height so they stay centred, undoes the host's page zoom because the traffic lights never zoom (CSS --host-page-zoom/--host-page-unzoom on the document: Tauri's host publishes them after each load and zoom change through title_bar::publish_page_zoom, since WebKit hides the zoom from the page; Electron's renderer sets them from the preload's getZoomFactor(), re-read on resize), and holds the brand or title, the drag region and, in the main window, the app actions (Settings, notification history and Remote Access, components/app-actions.tsx), which the project tab bar holds on the other platforms and in browsers (appActionsInTitlebar). Never move the traffic lights through the hosts' position options: Tauri loses its position once the window is shown and resized. Tauri keeps the native menu bar of local application and Preferences windows attached for its accelerators but hidden through menu_bar::hide (menu_bar.rs), which on Linux also excludes the GTK bar from show_all (run when a window appears) and lets its accelerators fire while hidden. Remote windows keep their native decorations and menu bar. About CodeNomad runs the open-about command (Settings → Info), falling back to a native panel only when no application window can receive it. The Help menu lists CodeNomad Help, Support CodeNomad, Get Updates and About in both hosts (both Tauri branches); Support CodeNomad runs the open-sponsor command, which opens the sponsor help page in the UI locale, and the host opens the English page when no application window can receive it.