App Shell

Use this when touching settings, preferences, command palette, sidebar, shortcuts, global navigation, modals, overlays, dockable panels, favorites, saved views, app-shell persistence, or visual shell tests.

Core Contracts

Read:

1. AGENTS.md
2. frontend/AGENTS.md
3. docs/frontend/component-structure.md
4. docs/frontend/keyboard.md
5. docs/frontend/modals.md
6. docs/frontend/tabs.md
7. docs/frontend/dockable-panels.md
8. docs/architecture/data-access.md for app state and persisted reads
9. docs/architecture/application-lifecycle.md for native shell and process UI ownership

Settings-specific contract:

• Persisted app preferences and runtime-enforced settings are backend-owned and owned by PreferencesService and described by readAppSettingsSchema.
• frontend/src/core/settings/appPreferences.ts owns the frontend schema metadata cache and typed metadata helpers. Settings UI sections should consume defaults, bounds, enum values, validation hints, and runtime flags through those helpers instead of duplicating backend constants.
• Fallback metadata belongs only inside appPreferences.ts for first paint, Wails-unavailable tests, or schema-load failure; it is not a second settings contract.
• Settings components should not fetch backend schema directly. Add or reuse a typed helper in core/settings when UI needs preference metadata.
• Frontend preference setters should use the shared optimistic update path that calls UpdateAppPreferences, then roll back cache, emitted events, and any appearance localStorage mirrors on failure.
• UpdateAppPreferences returns normalized settings and changed keys. Do not change that response shape unless a workflow genuinely needs schema metadata in the mutation response.
• Runtime-effect flags are metadata for diagnostics and future UI decisions. Do not add user-facing runtime-effect copy unless the workflow calls for it.
• Settings effects run only after successful persistence and lock release, through the owner-shaped sinks documented in docs/architecture/data-access.md; settings UI must not add a direct runtime owner call.
• Frontend-only or bootstrap state stays local when it is transient or needed before Wails is available. Do not move local UI state into the backend just because it appears in Settings.
• Object panel position and layout defaults are persisted preferences with backend-normalized defaults.

Entry Points

• frontend/src/ui/settings
• frontend/src/core/settings
• frontend/src/core/app-state-access
• backend/preferences_service.go
• backend/preferences_settings.go
• backend/runtime_setting_policies.go
• backend/data_management_coordinator.go
• backend/desktop_shell.go
• backend/favorites_service.go
• backend/ui_state_store.go
• frontend/src/ui/command-palette
• frontend/src/ui/shortcuts
• frontend/src/ui/navigation
• frontend/src/ui/layout
• frontend/src/ui/dockable
• frontend/src/ui/modals
• frontend/src/ui/favorites
• frontend/src/shared/components/modals
• frontend/src/shared/components/tabs

Checklist

• User-facing labels, icons, categories, and command-palette entries stay aligned across surfaces.
• Settings and persistence keys are scoped correctly, including cluster or namespace identity when the state is cluster data.
• Persisted preferences hydrate from backend schema metadata instead of duplicating defaults and bounds in UI code.
• Backend-owned Settings controls read min/max/default/current values from schema metadata helpers in core/settings; keep fallback constants local to the metadata layer only.
• Backend schema coverage includes every preference accepted by UpdateAppPreferences, without adding non-preference settings like selected kubeconfigs or saved themes to the preference schema.
• Regenerate Wails bindings when backend settings DTOs, schema fields, or response shapes change.
• Preference mutations use UpdateAppPreferences semantics: atomic validation, persistence before runtime side effects, and rollback on failure.
• Local-only Settings state and first-paint bootstrap caches remain frontend-owned.
• Keyboard shortcuts respect focus ownership and text-input behavior.
• Modals preserve focus trap, drag regions, and keyboard dismissal behavior.
• Dockable panel and tab changes preserve selection, close, drag/drop, and cluster/object identity behavior.
• Visual changes reuse existing CSS/tokens and avoid inline styles.
• Tests cover persistence, keyboard/focus, and changed UI state.

Validation

Use focused checks while iterating:

mise exec -- npm run typecheck --prefix frontend
mise exec -- npm run test --prefix frontend -- settings command-palette shortcuts modals dockable favorites

Use browser or Storybook validation for visual behavior, then follow the root final validation gate.