CodeNomad/dev-docs/SETTINGS.md
Pascal André b9aa5f3b02
fix(ui): simplify high contrast to one channel curve (#1570)
I replace role-specific high-contrast rules with one sRGB channel curve
(1.3 contrast, mirrored pivots), preserving the palette's colored text
and original filled-button ink.

I keep Contrast Auto/On/Off, corrected light-palette surfaces and one
shared active-toggle tint; the result was visually approved.

I verified typechecking, 86 focused unit tests, 31 help checks across
ten languages and focused browser regressions.
2026-11-17 16:26:27 +01:00

20 KiB

Settings and Preferences

Agent conventions

  • Appearance places Contrast at the inline end of the Mode row. ui.settings.highContrast is auto (default), on or off; Auto follows prefers-contrast: more. Initial bootstrap awaits the shared authoritative preferences load and applies the resolved palette and contrast before rendering. The control applies immediately, serializes writes independently of palette edits and reconciles failed writes through an authoritative read; its i reports Auto's current state and its error stays actionable. Every input sRGB channel uses c' = clamp(pivot + (c - pivot) * 1.3, 0, 1), with mirrored pivots 0.5 - 0.3 for dark palettes and 0.5 + 0.3 for light palettes. Filled-button ink is chosen against the original accent, keeping it stable when switching contrast. See PALETTE_SOURCES.md.

  • openSettingsConfigFile(id) opens Configuration files and selects only an ID present in the editor's server catalogue. It shares openSettingsRow's short-lived same-origin hint with native Preferences on Electron and Tauri. A reopened editor preserves its dirty-discard confirmation; unavailable IDs preserve the current file. The editor consumes each target once and focuses its file selector.

  • Settings → OpenCode's logging card opens OpenCodeLogsAction in the common non-modal OutputWindow. Read once on explicit opening and on Refresh; closing, disposal and executable selection changes abort/fence the request. Global log snapshots stay in the mounted settings reader, separate from session state. The switch-to-info command/shortcut opens OpenCode settings and keeps existing key overrides. Version, executable, service actions and diagnostics share this global settings scope.

  • Reuse SettingsInfoTip for contextual help with help={{ page: "opencode", anchor: "login-start" }}. Its short localized text remains the hover/focus tooltip; click, Enter or touch opens helpUrl(locale, page, anchor) through openExternalUrl, with a localized failure alert. The span's link role, cancelled label default and stopped activation events keep containing labels, disclosures and controls unchanged. Without help, touch toggles the explanation. SettingsChoiceRow.help and behavior-registry help carry the same destination. Use only relevant published sections with matching explicit ids in every locale; dynamic diagnostics can remain tooltip-only, and actionable popovers keep SettingsInfoLink or InfoPopoverButton. Destinations and gesture/native-opener behavior are covered by lib/help-url.test.ts and tests/browser/settings-info-tip.test.ts.

  • General's Memory card owns the disabled-by-default server.memoryEnabled switch, About you/Project review, visit-stable New/Modified badges, revision-checked editing and confirmed Forget. Shared Preferences project resolution selects the authorized project memory, including its worktree; global memory belongs to the CodeNomad configuration. Flagged entries remain available for human review. Entry format, Git history, API, session instructions and badge frontiers are in AGENT_MEMORY.md.

  • General's Memory Tidy up captures the current resolved Preferences project and memory scope and confirms before sending a fixed native intent to its exact local opener. The main renderer checks fresh memory availability/writability, creates a new session at that directory, activates it and sends the fixed cleanup prompt once. Embedded browser Settings use the same main-renderer action and close after a confirmed send. Preferences owns only the review and pending confirmation; context changes revoke unsent consent. See AGENT_MEMORY.md.

  • Settings → OpenCode's OpenCodeLoginStartCard (stable row anchor #opencode-login-start) presents Launch at startup as one lone-setting switch with a one-sentence i tip saying it starts when the user session opens; the switch is its state. It reads GET /api/opencode/login-start on mount and reconnect (the latest request wins) and changes it with POST, the switch disabled until the server answers. A refused change re-reads the state and shows one fixed, localized error under the row (failed or unsupported-binary); a failed read adds Try again; unavailable disables the switch with a caption. Runtime, artifacts and stored supervision reconciliation are in OPENCODE_RUNTIME_SETUP.md. Browser regression: tests/browser/opencode-login-start.test.ts.

  • General offers autoExpandActiveSubsessions (default true): a new working/compacting/input chevron state opens visible branches belonging to the selected conversation, including its descendants at every depth (dev-docs/UI_SHELL.md). Disabling it leaves activity indicators and explicit navigation available; the preference is stored with the shared UI settings.

  • General ends its behaviors card with ui.settings.keepComputerAwake (default false), persisted through the UI config owner. Local native desktop windows and the native Preferences window show its title and an i tip. When enabled, the preference holds the existing native system-sleep lock in local application windows (including minimized windows) while allowing the display to turn off. Eligible working/compacting sessions hold the lock in local application windows and Electron remote windows. Remote windows ignore the preference; Tauri remote windows lack native wake-lock access. The Preferences window renders settings only and never requests a lock. Preference changes apply immediately.

  • Settings → Providers separates Models, Web search and Images into three shared .settings-disclosure groups (no icons): Models starts open, Web search and Images folded, and a folded group mounts nothing, so its connection metadata, configuration contract and image-model catalog are read only once opened. Models and Web search each start with a provider selector, Connect action and configured-provider list; Web search then shows its global default and project override. Images (opencode/image-settings.ts, settings/image-settings-card.tsx, styles/components/image-settings.css) edits the Global document's experimental.image_generate and experimental.media_blob. OpenCode reads image_generate per field from the highest-priority document that sets it (unset means on, with the automatic model; only false turns the image tool off), but media_blob (like subagent_depth) from the whole experimental object of the highest-priority document that has one, so writing a project block would hide inherited experimental settings. The document that decides each value is read from the native configuration entries and reported under its control when it is not the Global one. When the selected Location's own project document (the project write target) decides media_blob through its existing experimental object, the snapshot names it under mediaStorage.project instead, the box shows the effective value and saving also writes media_blob there; the edit is refused if that object has disappeared, because creating one would hide inherited settings. The Missions depth editor's Inherit removes a project object left holding only that media_blob when it equals the Global one (dev-docs/MISSIONS.md); Off is written as false, because removing the key would expose a lower-priority document that enables it. When the fresh Global write target has no experimental object while a lower-priority document has one, creating it would hide that whole object (subagent depth, todos) from every Location without its own, even when the selected Location overrides it, so the group is read-only and the backend refuses the write; never copy the inherited values into the Global document instead. Each control appears only when the connected daemon's Config.InfoEncoded declares its key, because the native experimental object rejects unknown keys; never write either key without that capability. Image models come from native GET /api/model?types=image for the selected Location. Reuse provider rows, selectors, inputs and action styles; do not add an API-key disclosure or a separate card design. Search-only integrations stay out of the Models group. Web search configuration lives entirely here. Read connection metadata while this Settings surface is visible, never credential secret values; keep API-key entry explicit and clear drafts on context changes. Use the authorized Global/Project document operations shared with plugin controls and opencode/native-setting-document.ts for targeted JSONC edits. Preserve unrelated fields, native discovery roots, WSL atomic writes and conflict/connection/deletion fences. Group/search styling lives in styles/components/websearch-settings.css; credentials use native integration methods and remain global.

  • Stats preferences explicitly aggregate the entire connected OpenCode service via opencode/service-usage.ts. Reserve the Usage label for the provider subscription panel. Native project IDs span independent clones, so never label native session.stats as physical-folder/Git-family scoped. Keep connection/workspace fences, tools: "none" and periods bounded to 366 days; never load transcripts for statistics or imply billing/quota precision. Last snapshots and period choices restore through backend-owned state.ui.serviceUsage (eight each/1 MiB, validated service/channel/folder identity), never a Preferences writer to main-window client state or a workspace-UUID cache. Native aggregation must not await optional discovery/cache reads; cached responses cannot replace fresh data. Backend authorized admission order, not completion order or client time, chooses the period across windows; optional publication is bounded and shutdown-fenced. Keep last-known-owner totals explicitly stale through disconnect/errors and revoke them on verified owner/discovery changes. Read while mounted and document-visible; hide cancels queued/trailing demand, activation revalidates once and terminal hints use the shared activity cooldown. Never treat document visibility as native minimize/occlusion detection or equate blur with hidden. See dev-docs/CACHE_REFRESH_CONVENTIONS.md for the remaining native scope. Styles live in styles/components/usage-dashboard.css.

  • Settings rows keep only a title unless a caption is essential; secondary explanations go behind components/settings/settings-info-tip.tsx (a focusable "i" with a hover/focus tooltip that a tap toggles on touch screens, a span so it never becomes a row label's control or toggles it), styled in styles/components/settings-info-tip.css. An explanation that must end with a link uses settings-info-link.tsx instead: the same "i" as a button named by its text, opening a popover named by its title (click, Enter or Space; focus moves to the link; Escape or outside interaction closes it). Links to a setting use openSettingsRow(section, row) (stores/settings-screen.ts) with the row's stable id anchor (such as #opencode-login-start), never its label, and the link's text is the setting's own title key so it follows any rename; the row (tabindex="-1") calls useSettingsRowTarget (components/settings/settings-row-target.ts) to claim the target once, focus itself and stay in view while the cards above load, and the embedded Settings dialog skips its own initial focus while the shown section holds the targeted row (settingsRowPending); closing Settings drops an unclaimed target. Hosts carry only the section to a native Preferences window, so the row travels as a 15-second same-origin localStorage hint that the window adopts for its active section on each request and on storage events (adoptSettingsRowHint). A link never reads or changes the linked setting. Behavior settings opt in with infoKey instead of subtitleKey. Folded settings groups use the one .settings-disclosure (styles/components/settings-disclosure.css; a summary may hold an inline heading that keeps the summary's look): Missions gathers every agent/model choice under "Agents and models" with the current request in its summary, and Advanced ends with the environment-variable editor folded under a single title.

  • SettingsService config reads (getOwner, getDoc) are a display cache that does not follow external edits. Config writes for every owner (mergePatchDoc, mergePatchOwner, and getDoc's normalization) start from the document as it is on disk now (YamlDocStore.reloadAuthoritative), so a stale cache is never written back; an unreadable or invalid config.yaml refuses the write with SettingsReadError (routes answer 503) instead of overwriting it. Access decisions never read the display cache: they use an authoritative read such as serverFlag(key) or readEnvironmentForAdmission().

  • Server-owner settings that widen host-only access are listed in settings/host-only-settings.ts: both config routes pass hostOnlyServerCheck(isLocalRequest(request)) to the write, which refuses with 403 a non-local write whose result changes one compared with the authoritative document it starts from (deleting the owner included), and their rows render only while localRequest() is true. Settings → SideCars ends with such a lone-setting switch, Open SideCars over HTTPS (settings/sidecars-direct-https-card.tsx, server.sidecarsOverDirectHttps, i tip linking to the SideCar help); its admission rule is in REMOTE_CONTROL.md. Browser regression: tests/browser/host-only-controls.test.ts.

  • Settings update/install actions (OpenCode and Info), OpenCode's post-update service restart, and Remote Control start/pairing-link actions use the shared .selector-button-primary accent treatment. The shared OpenCodeSetupPanel keeps those same primary actions in startup recovery. Remote Control's header refresh is an icon-only .window-icon-button, retaining its localized accessible name, tooltip, disabled state and loading spinner.

  • The native Preferences window never owns client state. Its General startup card (settings/opener-startup-state-settings-card.tsx) targets the exact local window that opened Preferences: the host records that opener and an epoch (Electron PreferencesWindowRegistry, Tauri PreferencesWindow), forwards only the fixed commands in lib/native/startup-state-command.ts to that renderer, which runs them through its own stores/client-state transitions. Mutations carry the displayed epoch and degrade to a read after the opener changes. Startup state is per window: when the opener is unknown (Preferences restored at launch) or closed, the host adopts the most recently used local window as the opener (startupStateTargetId + adoptOpener / startup_state_target + set_opener), rotating the epoch so a change prepared for another window is only a read. The card re-reads a few times while the adopted window starts and stays disabled only when no local window can answer.

  • The native Preferences window shows no session, so it never reacts to session events: stores/sessions.ts wires the session event handlers (errors, TUI toasts, permissions, session and worktree updates) only outside it. A session alert, toast or notice therefore appears in the windows showing sessions and is acknowledged once there (tests/browser/preferences-window.test.ts).

  • Native Preferences resolves its project context through settings/preferences-project-context.ts before Providers, Missions or Stats read project data. Backend workspace IDs are ephemeral: use the exact requested record while it exists; otherwise bind only one unambiguous exact-folder match from the backend's metadata-only inventory. Requests persist the opened backend-host folder as workspacePath, separate from the selected native location.directory (WSL/worktrees); keep the native directory for requests and drop any stale native workspace selector when rebinding. Requests without the backend folder match only their exact directory, never through guessed WSL translations or ancestors. A starting, missing or ambiguous project stays inactive. Read only on section demand, matching workspace lifecycle events or reconnect; never hydrate other workspaces, discover worktrees, create projects or poll. Record all deletion tombstones before filtering by the current binding so late inventory responses cannot publish deleted candidates, and revalidate when deletion resolves an ambiguity. Invalidation and newer native requests fence late reads, explicitly deleted occurrences never turn into sibling tabs, and rebinding persists through the existing Preferences request queue without resetting the section or newer scrolling. The shared renderer and request contract cover both Electron and Tauri; startup regressions live in tests/browser/preferences-startup.test.ts.

  • Settings → Info's Support CodeNomad card, between Updates and Diagnostics, holds one .selector-button-secondary action that opens helpUrl(locale, "sponsor") through openExternalUrl, like the open-sponsor palette command and the native Help menu item; a failed opening shows the localized commands.openSponsor.failed alert in the card and is never replayed. Funding channels live only on the help site (docs/help/funding.json); never put payment links or amounts in the app.

  • Settings → Info's Report a bug opens the bug_report.yml issue form with its text fields prefilled by id (BUG_REPORT_FIELDS in lib/bug-report.ts). When the template changes, keep those ids and their input/textarea types in sync: lib/bug-report.test.ts checks the repository's template. The section warms a bounded read of the form published on the default branch; the click never waits for it (WebKit drops user activation after about 1 s), using the settled assessment or else the form while a background read retries. Only a proven incompatible form (missing, unparsable, prefilled field removed or retyped) falls back to a blank issue carrying the same Markdown report; an unreachable read keeps the form. Never prefill listeners, addresses, paths, credentials or conversation data.

  • Notification icon badges mirror the existing per-window bell/history unread count, never session status or native OS notification delivery. The browser favicon uses a dot; native Electron/Tauri hosts aggregate live primary-window counts and clear contributions on reload/close, keeping preferences and preview guests outside the badge authority. On Linux, Electron sends the badge to docks implementing the LauncherEntry API (Ubuntu Dock) for its desktopName, which must stay the deb's CodeNomad.desktop; the deb check enforces it. Keep UI projection in lib/notification-icon-badge.ts and host dispatch in lib/native/notification-badge.ts; do not add discovery scans or polling.

  • Notifications have one routing table (lib/notification-routing.ts): every showToastNotification declares a category, and Settings → Notifications chooses per category On screen / History / System (components/settings/notification-routing-table.tsx, styles/components/notification-routing.css). The history, and therefore the icon badges, holds only what is routed there; errors always reach the screen and the history; transient live feedback (progress, retry countdowns, "up to date") stays on screen only. The routing table is the only system-notification control: checking a System box requests permission, and saved osNotificationsEnabled, notifyOnNeedsInput and notifyOnIdle preferences only seed the routing until it is first saved. The bell (tab bar, or title bar in the macOS desktop app) is the history, independent of system notifications. System delivery is held back only while the window has focus (visible and document.hasFocus()), unless Notify when the app is focused (osNotificationsAllowWhenVisible) is on; a window left open behind another application or on another screen still notifies (tests/browser/system-notification-focus.test.ts). Classify new notifications by what the user would want to find later, not by their source file; a warning that must be seen once by default (the incomplete-recovery warning) uses a category that shows a bubble (projects), never needsInput, whose default is System only.