CodeNomad/dev-docs/UI_SHELL.md
Pascal André e43fbdc1d2
Some checks are pending
Download Caches / seed (ubuntu-24.04) (push) Waiting to run
Download Caches / seed (windows-2025) (push) Waiting to run
Download Caches / seed (macos-15-intel) (push) Waiting to run
Download Caches / seed (macos-26) (push) Waiting to run
Publish help / build (push) Waiting to run
Publish help / deploy (push) Blocked by required conditions
feat(ui): simplify background shell rows in Status (#1587)
I made each background shell a single row in Status. Click the command
to open its existing output window; hover, focus or long-press for
details. A separate trash button keeps stop/remove confirmations
distinct.

I tested narrow panels, right-to-left layout, keyboard and touch
interactions, and updated the help in all ten languages.
2026-11-19 04:53:45 +01:00

43 lines
24 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Application shell
## Agent conventions
- View stores read the active conversation identity from `stores/session-selection-state.ts`. Session selection actions, catalog refresh and restoration authority remain in `stores/session-state.ts`; keep those UI-effect dependencies out of the view-state import graph.
- `stores/session-surface.ts` owns the central foreground projection and gesture generation within one tab occurrence (`instanceId`). Its fixed union selects conversation, web, file or Mission. Browser targets bind explicitly to a native session; file targets retain their session/worktree lifetime; schedule and playbook readers can open without a conversation. Duplicate project tabs can consult different readers or the shared conversation. Feature stores retain browser guests/history, file bytes/drafts/editor state and Mission data/selection/tree/disclosures.
- User gestures advance the occurrence generation; async gestures adopt only if their generation is current; passive updates apply immediately and never advance it. `beginGesture(ctx)` captures the generation before awaiting and returns `current()`; `applySurface(ctx, surface, gesture?)` applies a synchronous gesture or adopts a captured one. Selection actions accept that same gesture. Adoption also checks occurrence, resource and ownership lifetimes. Never recapture authority after an await or add reciprocal cross-feature visibility effects. Browser Go, Back/Forward and Refresh admit at the gesture; location/history notifications update their feature state immediately. Removed occurrences release their foreground/resources; unavailable occurrences retain restoration data while pending activation loses authority.
- The version-one `tab-view-state` envelope supplies restored browser modes and Mission reader targets to the foreground projection. Each session owns one browser resource within the renderer; `SessionPreviewHost` keeps its guest attached in stable DOM order and follows the active `SessionPreviewSlot` bounds. Live updates preserve untouched branch and target identities; capture/restore applies validation and budgets. File targets, browsed worktrees and Files filters stay runtime-only. Restorable Mission selection/tree/disclosure state belongs to the occurrence envelope; completion acknowledgements remain per project within the window.
- Folder-scoped legacy Mission views adopt into the first restored descriptor or browser opening; explicit versioned envelopes retain authority. Reader instance references bind to recreated occurrences. Project-view sources retire after accepted persistence; legacy disclosure choices remain readable until each occurrence rewrites them.
- Passive setters (`updateMissionProjectView`, session `setActive*`/hydration setters, `retargetMissionReader` and file lifetime/status reconciliation) apply against current inventory and binding. File status requires a loaded inventory and the matching file target; session deletion reconciles the selected parent/child immediately. Mission absence clears only the matching reader. A still-current gesture resolving afterwards adopts its result over those updates. Browser resource restoration allocates under its own occurrence/session fence and preserves saved foreground mode. Schedule clicks retain their original generation through passage discovery and hydration. Guard checks live in `session-surface-passive.test.ts`, `session-deletion-reconciliation.test.ts` and `session-surface.test.ts`; full-shell races live in `session-browser-history.test.ts`.
- The selected right-panel tab and Files mode use the occurrence's restorable view envelope. The layout keys supply defaults for new occurrences; each mounted occurrence records its own selection and restores it when the panel remounts or the window restores. Panel dimensions, palette, tab order and customization retain their shared preference scope.
- Each right-panel tab owns its conditional body and lazy boundary; switching away during a pending module load leaves the new selection responsive. Only the selected tab's body mounts.
- Conversation selection and transcript scroll/follow state use the occurrence/session identity. Both occurrences receive the same native message and execution events while keeping an older reading position or latest-follow choice independently. File source/rendered choice and editor position use the target/model lifetimes in [FILES_PANEL.md](FILES_PANEL.md); the restore envelope's fields are specified in [architecture.md](architecture.md#native-profiles-windows-and-client-state).
- 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. Each shell has one clipped command button with a discreet accessible state, opening its output, and a separate trash button at the logical end confirming Stop and remove for active shells or Remove for completed entries. Busy trash controls use `aria-disabled` with guarded activation to retain focus; confirmations restore their trigger, and removal hands focus to a neighboring row or the section heading. `lib/shell-command-label.ts` recognizes conservative command envelopes for display and preserves arguments, with raw-command fallback. Recognized PowerShell script paths display their filename; the program segment clips before the separate arguments segment. Hover, focus or a long press reveals the full command, state, directory, shell, PID, exit code and available start/completion dates. Details use Kobalte's `--kb-popper-content-available-height` to fit the space beside their command within the viewport. With focus on the command, arrows, PageUp/PageDown and Home/End scroll bounded details; Escape or outside touch dismisses them. 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 share one set of actions (favorite, rename, copy ID, reload, archive/restore, delete). `useSessionRowOverflow` measures each row's title, badges, indentation and action strip: actions appear inline on hover or focus when they fit, with visible touch targets on touch devices; tighter rows use More actions (⋯). A filled star stays visible on favorites: it is the button in inline mode and an indicator in compact mode. Pending requests retain branch priority. At each depth a favorite ranks its own row within its siblings, preserving expansion. Flat search ranks matching favorites in the Activity sort and uses the chosen order in Name and Worktree. Favorites only also enables subsessions, and the hidden-match button relaxes only the two session-type switches. During a favorite write, focus follows the session's star or menu trigger across layout changes. If focus still belongs to that action on confirmation, the reordered row scrolls into view, or focus returns to Favorites only if that filter removes the row. Validate with `tests/browser/session-favorites.test.ts`.
- Favorites use the authorized workspace state route. The scoped index returns only favorite IDs; ancestor IDs stay backend-private. A successful PUT publishes its revisioned snapshot immediately. Secondary reads reconcile on invalidation and reconnect, and older responses cannot replace a newer snapshot. Bounded native absence checks retain each confirmed `SessionNotFoundError` through a scan timeout, fenced against changes to that entry or connection. A stored entry can be unpinned without a native read. The ancestry hydrator promotes off-page display roots, including exact-folder roots with external parents.
- Palette and keyboard Previous/Next follow the sidebar projection (including filters and sort). A closed drawer retains its tab’s last projected order for surviving rows and its filter controls for reopening. Back/Forward follow visit history.
- 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`. Session action handoffs also keep the target session mounted while the virtual list applies its new layout, checking the current control and row geometry before returning focus. 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](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.
- 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-plugin-row.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.
- The web client titles its browser tab `<host> — CodeNomad` from the page's `location.host` (port only when not the default), so tabs of several servers differ; on loopback hosts (`localhost`, `*.localhost`, 127/8, `[::1]`) it stays `CodeNomad`, and desktop hosts keep their own titles (`lib/web-tab-title.ts`, set in `main.tsx`).