Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

feat(desktop): open General Settings in place and drop web top bars in the shell (#2163)

Maxa72dddf9d380
diff --git a/desktop/README.md b/desktop/README.md
index 87b7cc272..5e051fc61 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -205,7 +205,7 @@ Packaged installations register `avibe://` for native, single-window navigation:
| --- | --- |
| `avibe://session/<id>` | `/chat/<id>` |
| `avibe://show/<id>` | `/apps/show/<id>` |
-| `avibe://settings` | `/admin/settings/service` |
+| `avibe://settings` | `/settings/general` |
| `avibe://vaults/request/<id>` | `/vaults?request_id=<id>` |
IDs use literal ASCII letters, digits, `.`, `_`, and `-`, up to 128 bytes;
diff --git a/desktop/runtime-host/src/deep_link.rs b/desktop/runtime-host/src/deep_link.rs
index a203ccacf..d07a82e27 100644
--- a/desktop/runtime-host/src/deep_link.rs
+++ b/desktop/runtime-host/src/deep_link.rs
@@ -48,7 +48,7 @@ pub fn parse_deep_link(raw: &str) -> Option<DeepLinkTarget> {
};
format!("{prefix}/{identifier}")
}
- ("settings", "") => "/admin/settings/service".to_owned(),
+ ("settings", "") => "/settings/general".to_owned(),
("vaults", path) => {
let identifier = path.strip_prefix("/request/")?;
if !valid_identifier(identifier) {
@@ -162,7 +162,7 @@ mod tests {
const MAPPINGS: &[(&str, &str)] = &[
("avibe://session/ses.A_b-9", "/chat/ses.A_b-9"),
("avibe://show/ses.A_b-9", "/apps/show/ses.A_b-9"),
- ("avibe://settings", "/admin/settings/service"),
+ ("avibe://settings", "/settings/general"),
("avibe://vaults/request/req.A_b-9", "/vaults?request_id=req.A_b-9"),
];
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index da64299fd..b1a809950 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -71,9 +71,14 @@ const STOP_MENU_ID: &str = "stop-runtime";
const QUIT_MENU_ID: &str = "quit-avibe";
const LOGIN_MENU_ID: &str = "start-at-login";
const SETTINGS_MENU_ID: &str = "open-settings";
-/// What Settings opens: the Workbench deep link, whose destination
-/// `parse_deep_link` owns, delivered the way an external link is.
+/// Where Settings leads: the Workbench deep link, whose destination
+/// `parse_deep_link` owns. It is delivered as a page load only when the window
+/// has no Workbench able to open Settings in place.
const SETTINGS_DEEP_LINK: &str = "avibe://settings";
+/// The in-page request to open Settings, read by `ui/src/lib/desktopShell.ts`.
+/// A Workbench that handles it cancels it; an uncancelled one falls back to
+/// loading the deep link's destination.
+const OPEN_SETTINGS_EVENT: &str = "avibe:desktop-open-settings";
#[cfg(feature = "bundled-runtime")]
const ACTIVITY_UNINSTALL: u8 = 3;
@@ -375,17 +380,47 @@ fn settings_is_available(activity: u8, workbench_origin: bool) -> bool {
activity == ACTIVITY_MONITOR && workbench_origin
}
+/// Settings opens inside the Workbench already on screen, through the same
+/// navigation its own Settings control takes, so leaving Settings returns to the
+/// surface it covered — project, session and unsent draft included. A page load
+/// would discard all of that. Only a window that shows no Workbench goes through
+/// the deep-link path instead, which waits for one.
fn open_workbench_settings(app: &AppHandle) {
let Some(shell) = app.try_state::<Shell>() else {
return;
};
- let workbench_origin = shell.active_origin.lock().is_ok_and(|origin| origin.is_some());
- if !settings_is_available(shell.activity.load(Ordering::SeqCst), workbench_origin) {
+ let Some(origin) = shell.active_origin.lock().ok().and_then(|origin| origin.clone()) else {
+ return;
+ };
+ if !settings_is_available(shell.activity.load(Ordering::SeqCst), true) {
return;
}
+ let shown = app
+ .get_webview_window(MAIN_WINDOW)
+ .filter(|window| window.url().is_ok_and(|url| origin.matches_url_origin(&url)));
+ if let Some(window) = shown {
+ focus_or_restore_main_window(app);
+ if window.eval(open_settings_script()).is_ok() {
+ return;
+ }
+ }
receive_native_deep_link(app, [SETTINGS_DEEP_LINK]);
}
+/// Asks the page to open Settings, and loads the deep link's destination when
+/// nothing in the page takes the request: an older Workbench, or a route outside
+/// the app shell. The destination is a same-origin path, so the load stays on the
+/// adopted Runtime.
+fn open_settings_script() -> String {
+ let path = avibe_runtime_host::deep_link::parse_deep_link(SETTINGS_DEEP_LINK)
+ .expect("the Settings deep link is part of the frozen grammar")
+ .path()
+ .to_owned();
+ format!(
+ "if (window.dispatchEvent(new Event('{OPEN_SETTINGS_EVENT}', {{ cancelable: true }}))) window.location.assign('{path}');"
+ )
+}
+
fn refresh_runtime_tray(app: &AppHandle, state: TrayRuntimeState) {
refresh_native_controls(app, Some(state));
}
@@ -1691,6 +1726,15 @@ mod tests {
assert!(avibe_runtime_host::deep_link::parse_deep_link(SETTINGS_DEEP_LINK).is_some());
}
+ #[test]
+ fn the_settings_request_falls_back_to_the_deep_link_destination() {
+ assert_eq!(
+ open_settings_script(),
+ "if (window.dispatchEvent(new Event('avibe:desktop-open-settings', { cancelable: true }))) \
+ window.location.assign('/settings/general');"
+ );
+ }
+
#[test]
fn a_control_refresh_without_a_status_keeps_the_status_already_shown() {
let unreachable = TrayRuntimeState::Unreachable;
diff --git a/desktop/src-tauri/tests/shell_boundaries.rs b/desktop/src-tauri/tests/shell_boundaries.rs
index 0693476ec..06c8a9254 100644
--- a/desktop/src-tauri/tests/shell_boundaries.rs
+++ b/desktop/src-tauri/tests/shell_boundaries.rs
@@ -226,7 +226,11 @@ fn deep_links_have_native_entry_points_without_a_workbench_callable_command() {
assert!(source.contains(required), "native deep-link path is missing {required}");
}
assert!(!build.contains("deep_link") && !build.contains("window_state"));
- assert!(!source.contains("on_open_url") && !source.contains(".eval("));
+ assert!(!source.contains("on_open_url"));
+ // The one script the shell runs in the Workbench is its constant Settings
+ // request; nothing page-supplied is ever evaluated.
+ assert_eq!(source.matches(".eval(").count(), 1);
+ assert!(source.contains("window.eval(open_settings_script())"));
assert!(!source.contains("RunEvent::Opened"));
let receiver = source
.split("fn receive_native_deep_link(")
@@ -790,7 +794,7 @@ fn native_tray_copy_has_locale_and_placeholder_parity() {
}
#[test]
-fn settings_open_through_the_deep_link_path_only_while_a_workbench_is_shown() {
+fn settings_open_in_the_shown_workbench_and_only_while_one_is_shown() {
let source = shipping_source("src/lib.rs");
let body = |name: &str| -> String {
source
@@ -837,12 +841,31 @@ fn settings_open_through_the_deep_link_path_only_while_a_workbench_is_shown() {
let gate = handler
.find("if !settings_is_available(")
.expect("the handler refuses without a Workbench");
+ // In place first, so the Workbench keeps the surface Settings covers.
+ let in_place = handler
+ .find("window.eval(open_settings_script())")
+ .expect("Settings opens inside the Workbench on screen");
+ let shown = handler
+ .find("origin.matches_url_origin(&url)")
+ .expect("only a window showing the adopted Workbench is asked");
let delivery = handler
.find("receive_native_deep_link(app, [SETTINGS_DEEP_LINK]);")
- .expect("Settings is delivered as a deep link");
- assert!(gate < delivery, "the handler must refuse before delivering");
+ .expect("a window without a Workbench still gets the deep link");
+ assert!(gate < shown && shown < in_place && in_place < delivery);
assert!(!handler.contains(".navigate("), "the deep-link path owns navigation");
assert!(source.contains("const SETTINGS_DEEP_LINK: &str = \"avibe://settings\";"));
+ let event = source
+ .split("const OPEN_SETTINGS_EVENT: &str = \"")
+ .nth(1)
+ .expect("the in-page Settings request")
+ .split('"')
+ .next()
+ .expect("event literal");
+ let reader = read_to_string(&crate_dir().join("../../ui/src/lib/desktopShell.ts"));
+ assert!(
+ reader.contains(&format!("'{event}'")),
+ "the Workbench must listen for the request the shell sends"
+ );
}
#[test]
diff --git a/docs/plans/desktop-deep-links.md b/docs/plans/desktop-deep-links.md
index 1ecc458ac..dc501fe8f 100644
--- a/docs/plans/desktop-deep-links.md
+++ b/docs/plans/desktop-deep-links.md
@@ -39,7 +39,7 @@ spelling (`avibe:session/...`); one form only.
| --------------------------------- | -------------------------------------------- |
| `avibe://session/<session_id>` | `/chat/<session_id>` |
| `avibe://show/<session_id>` | `/apps/show/<session_id>` |
-| `avibe://settings` | `/admin/settings/service` |
+| `avibe://settings` | `/settings/general` |
| `avibe://vaults/request/<request_id>` | `/vaults?request_id=<request_id>` |
Parse as a URL. Accept only when `scheme == avibe`, `host` is one of
@@ -107,6 +107,20 @@ capability, no `remote` grant**. A Workbench page still cannot invoke
bootstrap IPC; the shell pushing a same-origin path into its own
WebView is not an IPC grant.
+One narrow exception keeps an in-app gesture from costing the user
+their place: the native **Settings…** item (menu, tray, `CmdOrCtrl+,`)
+opens General Settings over whatever the Workbench is showing, so
+closing Settings returns to that session, project, or draft. While the
+window shows the adopted origin, the shell evaluates one constant
+script that dispatches the cancelable `avibe:desktop-open-settings`
+event; the SPA cancels it and opens its Settings overlay in place. An
+uncancelled event (an older Workbench) falls back to
+`location.assign('/settings/general')`, and a window not showing the
+Workbench, or a failed evaluation, falls back to delivering
+`avibe://settings` through this path. The script is shell-owned and
+carries no page data; the page gains no command and no capability.
+External `avibe://settings` links keep the ordinary navigation.
+
If the Runtime is not yet ready (bootstrap screen still up), the
stashed target waits. Bootstrap failure discards it and stays on the
bootstrap screen — a deep link must not override a failed Runtime
diff --git a/tests/scenarios/auth_setup/catalog.yaml b/tests/scenarios/auth_setup/catalog.yaml
index 887e3d815..26ddef9c0 100644
--- a/tests/scenarios/auth_setup/catalog.yaml
+++ b/tests/scenarios/auth_setup/catalog.yaml
@@ -403,4 +403,25 @@ scenarios:
- tests/test_model_hub_source_identity.py
- ui/src/components/settings/models/SourceRow.test.tsx
- ui/e2e/model-provider/provider.spec.ts
+ - id: AUTH-SETUP-125
+ name: Settings opened over an unfinished setup keeps the wizard and its step
+ status: partial
+ kind: happy_path
+ layer: scenario
+ missing_layer: ui-e2e
+ backend: web
+ reason: >-
+ the rule is a browser routing rule with no server boundary: while setup is
+ required, General Settings (and Model Hub) opened over /setup stay the same
+ setup visit, so the guard neither re-validates nor remounts the wizard, and
+ the Settings menu opened there offers only those sections. The desktop shell
+ depends on it because its setup screens leave the language control to General
+ Settings. A pytest node would drive no browser and assert nothing about it;
+ the browser tests below drive the real guard, overlay boundary and Settings
+ menu against controlled responses.
+ owning_layer: L4 integrated acceptance (packaged desktop shell against a live instance)
+ supporting_tests:
+ - ui/src/App.remoteAuth.test.tsx
+ - ui/src/components/settings/SettingsLayout.test.tsx
+ - ui/src/components/DesktopSettingsCommand.test.tsx
next_priority: []
diff --git a/ui/src/App.remoteAuth.test.tsx b/ui/src/App.remoteAuth.test.tsx
index 061f8cb64..e76c2f783 100644
--- a/ui/src/App.remoteAuth.test.tsx
+++ b/ui/src/App.remoteAuth.test.tsx
@@ -2,9 +2,9 @@
import { act, cleanup, render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
-import { useLayoutEffect } from 'react';
+import { useEffect, useLayoutEffect } from 'react';
import { afterEach, describe, expect, it, vi } from 'vitest';
-import { MemoryRouter, Navigate, Route, Routes } from 'react-router-dom';
+import { MemoryRouter, Navigate, Route, Routes, useLocation } from 'react-router-dom';
import { AuthGuard } from './App';
import { Summary } from './components/steps/Summary';
@@ -12,6 +12,9 @@ import { useInstanceAuthorization } from './context/InstanceAuthorizationContext
import { DENIED_INSTANCE_CAPABILITIES, OWNER_INSTANCE_CAPABILITIES } from './lib/sessionInfo';
import { isOwnerOnlyPath } from './lib/adminNavigation';
import { reportRemoteAuthorizationState, REMOTE_AUTH_STATE_EVENT } from './lib/remoteAuth';
+import { DESKTOP_OPEN_SETTINGS_EVENT } from './lib/desktopShell';
+import { DesktopSettingsCommand } from './components/DesktopSettingsCommand';
+import { SettingsOverlayNavigationBoundary } from './components/settings/SettingsOverlayNavigationBoundary';
vi.hoisted(() => {
vi.stubGlobal('matchMedia', vi.fn().mockImplementation((query: string) => ({
@@ -226,6 +229,50 @@ describe('AuthGuard setup-bypass authorization', () => {
});
});
+describe('AuthGuard General Settings over setup', () => {
+ // AUTH-SETUP-125
+ it('opens the desktop Settings request over the wizard without leaving it', async () => {
+ api.getAuthSession.mockResolvedValue({
+ remote: false,
+ instance_kind: 'personal',
+ instance_role: 'owner',
+ capabilities: OWNER_INSTANCE_CAPABILITIES,
+ });
+ api.getConfig.mockResolvedValue({ mode: 'v2', setup_state: { needs_setup: true } });
+ Object.defineProperty(window, '__AVIBE_DESKTOP_SHELL__', { value: true, configurable: true });
+ const mounts = { count: 0 };
+ const SetupSurface = () => {
+ const { pathname } = useLocation();
+ useEffect(() => { mounts.count += 1; }, []);
+ return <div>at {pathname}</div>;
+ };
+
+ try {
+ render(
+ <MemoryRouter initialEntries={['/setup']}>
+ <AuthGuard>
+ <SettingsOverlayNavigationBoundary desktop>
+ <DesktopSettingsCommand />
+ <SetupSurface />
+ </SettingsOverlayNavigationBoundary>
+ </AuthGuard>
+ </MemoryRouter>,
+ );
+ expect(await screen.findByText('at /setup')).toBeTruthy();
+
+ act(() => {
+ window.dispatchEvent(new Event(DESKTOP_OPEN_SETTINGS_EVENT, { cancelable: true }));
+ });
+
+ expect(await screen.findByText('at /settings/general')).toBeTruthy();
+ expect(mounts.count).toBe(1);
+ expect(api.getConfig).toHaveBeenCalledOnce();
+ } finally {
+ Reflect.deleteProperty(window, '__AVIBE_DESKTOP_SHELL__');
+ }
+ });
+});
+
describe('AuthGuard setup access parity (AUTH-SETUP-405)', () => {
const managers = [
{ remote: false, instance_kind: 'personal', instance_role: 'owner' },
diff --git a/ui/src/App.tsx b/ui/src/App.tsx
index ac21c6bbb..151dbe9f9 100644
--- a/ui/src/App.tsx
+++ b/ui/src/App.tsx
@@ -92,7 +92,7 @@ const SettingsModelsPage = lazy(() =>
);
import { ModelHubCapabilityGate } from './components/settings/models/ModelHubCapabilityGate';
import { MODEL_HUB_SETTINGS_PATH } from './components/settings/models/modelHubRoutes';
-import { settingsOverlayOriginFromState } from './lib/settingsOverlay';
+import { settingsOverlayOriginFromState, SETUP_VISIT_SETTINGS_PATHS } from './lib/settingsOverlay';
import { hasConfiguredPlatformCredentials } from './lib/platforms';
import { isIosDevice, isStandalonePwa } from './lib/platform';
import {
@@ -304,11 +304,12 @@ export const AuthGuard = ({ children }: { children: ReactNode }) => {
// off /setup; that pathname flip re-runs the effect so the stale
// `needs-setup` status refreshes to `ready` instead of bouncing the
// user straight back to /setup.
- // Model Hub opened over the wizard is still the same setup visit. Keep the
- // wizard mounted so closing Settings returns to its current step.
- const isSetupRoute = location.pathname === '/setup'
- || (location.pathname === MODEL_HUB_SETTINGS_PATH
- && settingsOverlayOriginFromState(location.state)?.location.pathname === '/setup');
+ // A setup-visit Settings section opened over the wizard is still the same
+ // setup visit. Keep the wizard mounted so closing Settings returns to its
+ // current step.
+ const settingsOverSetup = SETUP_VISIT_SETTINGS_PATHS.has(location.pathname)
+ && settingsOverlayOriginFromState(location.state)?.location.pathname === '/setup';
+ const isSetupRoute = location.pathname === '/setup' || settingsOverSetup;
const previousIsSetupRouteRef = useRef(isSetupRoute);
useEffect(() => {
@@ -512,7 +513,9 @@ export const AuthGuard = ({ children }: { children: ReactNode }) => {
return <AccessBlocked code={blockedCode} />;
}
if (guardStatus === 'needs-setup' && !bypassSetupGuard) {
+ // Model Hub keeps its own grant; General needs only the wizard beneath it.
if (authorizationSession && (location.pathname === '/setup'
+ || (settingsOverSetup && location.pathname !== MODEL_HUB_SETTINGS_PATH)
|| (location.pathname === MODEL_HUB_SETTINGS_PATH && setupModelHubAllowed))) {
return <InstanceAuthorizationProvider session={authorizationSession}>{children}</InstanceAuthorizationProvider>;
}
diff --git a/ui/src/components/AppShell.tsx b/ui/src/components/AppShell.tsx
index 424cb8957..fced69d31 100644
--- a/ui/src/components/AppShell.tsx
+++ b/ui/src/components/AppShell.tsx
@@ -42,6 +42,7 @@ import {
} from '../lib/settingsOverlay';
import { isStandaloneSettingsMenu, useSettingsMenuPlacement } from '../lib/settingsMenuPlacement';
import { SettingsOverlayNavigationBoundary } from './settings/SettingsOverlayNavigationBoundary';
+import { DesktopSettingsCommand } from './DesktopSettingsCommand';
type ShellNavItem = {
to?: string;
@@ -377,6 +378,7 @@ export const AppShell: React.FC = () => {
<ShellSidebarContext.Provider value={shellDrawsSidebar}>
<ConfigRecoveryNotice config={config} />
<SettingsOverlayNavigationBoundary desktop={isDesktop}>
+ <DesktopSettingsCommand />
<Outlet />
</SettingsOverlayNavigationBoundary>
</ShellSidebarContext.Provider>
@@ -432,6 +434,7 @@ export const AppShell: React.FC = () => {
// Desktop: normal document flow.
<ShellSidebarContext.Provider value={shellDrawsSidebar}>
<SettingsOverlayNavigationBoundary desktop={isDesktop}>
+ <DesktopSettingsCommand />
<SettingsFocusHandoffContext.Provider value={settingsFocusHandoffRef}>
<WindowManagerProvider standalone={standaloneAppTab} onWindowForeground={leaveSettingsForWindow}>
<StandaloneAppTabContext.Provider value={standaloneAppTab}>
diff --git a/ui/src/components/DesktopSettingsCommand.test.tsx b/ui/src/components/DesktopSettingsCommand.test.tsx
new file mode 100644
index 000000000..433689833
--- /dev/null
+++ b/ui/src/components/DesktopSettingsCommand.test.tsx
@@ -0,0 +1,83 @@
+/* @vitest-environment jsdom */
+
+import { act, cleanup, render } from '@testing-library/react';
+import { useEffect } from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { MemoryRouter, useLocation, useNavigate } from 'react-router-dom';
+import type { Location, NavigateFunction } from 'react-router-dom';
+
+import { DESKTOP_OPEN_SETTINGS_EVENT } from '@/lib/desktopShell';
+import { closeSettingsOverlay, settingsOverlayOriginFromState } from '@/lib/settingsOverlay';
+import { DesktopSettingsCommand } from './DesktopSettingsCommand';
+import { SettingsOverlayNavigationBoundary } from './settings/SettingsOverlayNavigationBoundary';
+
+const DESKTOP_SHELL_FLAG = '__AVIBE_DESKTOP_SHELL__';
+
+const probe: { current: { location: Location; navigate: NavigateFunction } | null } = { current: null };
+
+const Probe = () => {
+ const location = useLocation();
+ const navigate = useNavigate();
+ useEffect(() => {
+ probe.current = { location, navigate };
+ });
+ return null;
+};
+
+const renderShell = (entry: string) => render(
+ <MemoryRouter initialEntries={[entry]}>
+ <SettingsOverlayNavigationBoundary desktop>
+ <DesktopSettingsCommand />
+ <Probe />
+ </SettingsOverlayNavigationBoundary>
+ </MemoryRouter>,
+);
+
+// What the shell's Settings… item runs: the request first, a page load only
+// when nothing in the page took it.
+const requestSettings = (): boolean => {
+ let taken = false;
+ act(() => {
+ taken = !window.dispatchEvent(new Event(DESKTOP_OPEN_SETTINGS_EVENT, { cancelable: true }));
+ });
+ return taken;
+};
+
+afterEach(() => {
+ cleanup();
+ probe.current = null;
+ Reflect.deleteProperty(window, DESKTOP_SHELL_FLAG);
+});
+
+describe('DesktopSettingsCommand', () => {
+ it('opens General Settings over the current surface and returns to it', () => {
+ Object.defineProperty(window, DESKTOP_SHELL_FLAG, { value: true, configurable: true });
+ renderShell('/chat/ses_7?message=m1');
+
+ expect(requestSettings()).toBe(true);
+ expect(probe.current?.location.pathname).toBe('/settings/general');
+
+ const origin = settingsOverlayOriginFromState(probe.current?.location.state);
+ expect(origin?.location.pathname).toBe('/chat/ses_7');
+ expect(origin?.location.search).toBe('?message=m1');
+ act(() => closeSettingsOverlay(probe.current!.navigate, origin!));
+ expect(`${probe.current?.location.pathname}${probe.current?.location.search}`).toBe('/chat/ses_7?message=m1');
+ });
+
+ it('keeps the origin when Settings is already open on another section', () => {
+ Object.defineProperty(window, DESKTOP_SHELL_FLAG, { value: true, configurable: true });
+ renderShell('/chat/ses_7');
+ act(() => probe.current!.navigate('/settings/service'));
+
+ expect(requestSettings()).toBe(true);
+ expect(probe.current?.location.pathname).toBe('/settings/general');
+ expect(settingsOverlayOriginFromState(probe.current?.location.state)?.location.pathname).toBe('/chat/ses_7');
+ });
+
+ it('leaves the request untaken outside the desktop shell', () => {
+ renderShell('/chat/ses_7');
+
+ expect(requestSettings()).toBe(false);
+ expect(probe.current?.location.pathname).toBe('/chat/ses_7');
+ });
+});
diff --git a/ui/src/components/DesktopSettingsCommand.tsx b/ui/src/components/DesktopSettingsCommand.tsx
new file mode 100644
index 000000000..69396bfc2
--- /dev/null
+++ b/ui/src/components/DesktopSettingsCommand.tsx
@@ -0,0 +1,28 @@
+import { useEffect } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+
+import { SETTINGS_LANDING_PATH } from '@/lib/adminNavigation';
+import { DESKTOP_OPEN_SETTINGS_EVENT, isDesktopShell } from '@/lib/desktopShell';
+
+/**
+ * Answers the desktop shell's Settings… menu item. It navigates like the
+ * sidebar's own Settings control, so the Settings overlay boundary it renders
+ * under records the covered surface and leaving Settings returns to it. Mount it
+ * inside `SettingsOverlayNavigationBoundary`.
+ */
+export const DesktopSettingsCommand = () => {
+ const navigate = useNavigate();
+ const { pathname } = useLocation();
+
+ useEffect(() => {
+ if (!isDesktopShell()) return undefined;
+ const open = (event: Event) => {
+ event.preventDefault();
+ if (pathname !== SETTINGS_LANDING_PATH) navigate(SETTINGS_LANDING_PATH);
+ };
+ window.addEventListener(DESKTOP_OPEN_SETTINGS_EVENT, open);
+ return () => window.removeEventListener(DESKTOP_OPEN_SETTINGS_EVENT, open);
+ }, [navigate, pathname]);
+
+ return null;
+};
diff --git a/ui/src/components/Wizard.tsx b/ui/src/components/Wizard.tsx
index 13aa02b9b..2a2c74b4b 100644
--- a/ui/src/components/Wizard.tsx
+++ b/ui/src/components/Wizard.tsx
@@ -25,6 +25,7 @@ import {
} from './onboarding/providers/gatewayBootstrap';
import logoImg from '@/assets/logo.png';
import { LanguageSwitcher } from './LanguageSwitcher';
+import { isDesktopShell } from '../lib/desktopShell';
import { useApi } from '../context/ApiContext';
import { useStatus } from '../context/StatusContext';
import { setConfigField } from '../lib/configMutations';
@@ -37,9 +38,13 @@ import { admitEntry, chooseEntryDefault, readEntryEvidence, type EntryGateDeps,
* the logo asset, which already carries its white tile, beside the two-line wordmark —
* at the window's own gutter, and the shared language switcher wearing its round
* trigger opposite it.
+ *
+ * The desktop shell leaves it out, and its height with it: the window's title bar
+ * names the app, and language lives in General Settings behind the native menu.
*/
function SetupHeader() {
const { t } = useTranslation();
+ if (isDesktopShell()) return null;
return (
<header>
<div className="onboarding-brand">
diff --git a/ui/src/components/settings/SettingsLayout.test.tsx b/ui/src/components/settings/SettingsLayout.test.tsx
index 23f1c6979..56558d661 100644
--- a/ui/src/components/settings/SettingsLayout.test.tsx
+++ b/ui/src/components/settings/SettingsLayout.test.tsx
@@ -177,6 +177,31 @@ describe('SettingsLayout', () => {
expect(await screen.findByText('chat-body')).toBeTruthy();
});
+ it('leaves the top bar to the desktop shell and keeps the rail way out', async () => {
+ media.matches = true;
+ Object.defineProperty(window, '__AVIBE_DESKTOP_SHELL__', { value: true, configurable: true });
+ try {
+ const user = userEvent.setup();
+ renderLayout({
+ pathname: '/settings/general',
+ state: settingsOverlayOpenState({
+ pathname: '/chat/ses_7',
+ search: '',
+ hash: '',
+ state: null,
+ key: 'chat-origin',
+ }),
+ });
+
+ expect(screen.queryByRole('banner')).toBeNull();
+ expect(screen.queryByRole('button', { name: 'settings.close' })).toBeNull();
+ await user.click(screen.getByRole('button', { name: 'settings.backToApp' }));
+ expect(await screen.findByText('chat-body')).toBeTruthy();
+ } finally {
+ Reflect.deleteProperty(window, '__AVIBE_DESKTOP_SHELL__');
+ }
+ });
+
it('keeps the settings rail fixed while the route pane owns vertical scrolling', () => {
renderLayout('/settings/replies');
@@ -281,6 +306,26 @@ describe('SettingsLayout', () => {
});
});
+ // AUTH-SETUP-125: Settings opened over the wizard offers only the sections the
+ // setup visit keeps, so no row leads out of the setup and loses its step.
+ it('offers only the setup visit sections over the wizard', async () => {
+ const setup: Location = { pathname: '/setup', search: '', hash: '', state: null, key: 'setup' };
+ renderLayout(
+ { pathname: '/settings/general', state: settingsOverlayOpenState(setup, null) },
+ { shellHasSidebar: false },
+ );
+
+ expect(screen.getByText('general-body')).toBeTruthy();
+ expect(screen.getByRole('link', { name: 'settings.sections.general' })).toBeTruthy();
+ await waitFor(() => {
+ expect(screen.getByRole('link', { name: 'settings.sections.models' })).toBeTruthy();
+ });
+ const rail = screen.getByRole('navigation', { name: 'settings.navigationLabel' });
+ expect(rail.querySelectorAll('a[href^="/settings/"]')).toHaveLength(2);
+ expect(screen.queryByRole('link', { name: 'settings.sections.replies' })).toBeNull();
+ expect(screen.queryByRole('button', { name: 'nav.messagingPlatforms' })).toBeNull();
+ });
+
it('opens Messaging Platforms by default and still allows manual collapse', async () => {
const user = userEvent.setup();
renderLayout('/settings/service');
diff --git a/ui/src/components/settings/SettingsLayout.tsx b/ui/src/components/settings/SettingsLayout.tsx
index 9735ff88c..34b1885c2 100644
--- a/ui/src/components/settings/SettingsLayout.tsx
+++ b/ui/src/components/settings/SettingsLayout.tsx
@@ -30,9 +30,11 @@ import { SETTINGS_LANDING_PATH } from '@/lib/adminNavigation';
import { settingsResumePath, writeLastSettingsSection } from '@/lib/settingsSectionMemory';
import { getEnabledPlatforms, platformSupportsChannels } from '@/lib/platforms';
import { useIsDesktop } from '@/lib/useIsDesktop';
+import { isDesktopShell } from '@/lib/desktopShell';
import {
closeSettingsOverlay,
isChromelessShellPath,
+ SETUP_VISIT_SETTINGS_PATHS,
useSettingsOverlayContext,
} from '@/lib/settingsOverlay';
import { useStandaloneSettingsMenu } from '@/lib/settingsMenuPlacement';
@@ -235,6 +237,7 @@ export const SettingsLayout: React.FC = () => {
const location = useLocation();
const navigate = useNavigate();
const isDesktop = useIsDesktop();
+ const desktopShell = isDesktopShell();
// Specifically the setup wizard, and only for the mobile back affordance
// below: coming from the wizard makes Back mean Back. That is a different
// question from whether a sidebar is on screen, which the rail reads from the
@@ -287,6 +290,9 @@ export const SettingsLayout: React.FC = () => {
() => SETTINGS_GROUPS.map((group) => ({
...group,
items: group.items.flatMap((item) => {
+ // Over the wizard, only the sections the setup visit keeps: any other
+ // row would leave the setup and lose the step it is on.
+ if (setupOrigin && !SETUP_VISIT_SETTINGS_PATHS.has(item.path)) return [];
if (item.ownerOnly && !capabilities.can_manage_instance) return [];
if (item.feature === 'models' && !modelHubVisible) return [];
return [{
@@ -296,7 +302,7 @@ export const SettingsLayout: React.FC = () => {
}];
}),
})).filter((group) => group.items.length > 0),
- [capabilities.can_manage_instance, channelSettingsVisible, modelHubVisible],
+ [capabilities.can_manage_instance, channelSettingsVisible, modelHubVisible, setupOrigin],
);
const activeTrail = (() => {
@@ -361,6 +367,10 @@ export const SettingsLayout: React.FC = () => {
return (
<div className="flex h-full min-h-0 flex-col overflow-hidden bg-background md:h-[var(--app-shell-h)]">
+ {/* The desktop shell's title bar stands in for this one. Its window never
+ gets narrower than the rail breakpoint, so the rail's own Back to Avibe
+ row is always on screen to leave by. */}
+ {!desktopShell && (
<header className="flex h-[calc(3.5rem+env(safe-area-inset-top))] shrink-0 items-center justify-between border-b border-border bg-surface px-4 pt-[env(safe-area-inset-top)] md:h-14 md:pt-0">
<div className="flex min-w-0 items-center gap-2 text-[13px] font-semibold text-foreground">
{/* Leaving Settings for the Workbench is the same action whichever
@@ -408,6 +418,7 @@ export const SettingsLayout: React.FC = () => {
</ReturnToApp>
</div>
</header>
+ )}
<div className="flex min-h-0 flex-1">
{/* Standalone Settings replaces the app sidebar, so this rail has to be
diff --git a/ui/src/lib/desktopShell.ts b/ui/src/lib/desktopShell.ts
index 3222c7ba1..3a0404ad4 100644
--- a/ui/src/lib/desktopShell.ts
+++ b/ui/src/lib/desktopShell.ts
@@ -9,7 +9,17 @@ declare global {
* True when this document is the Avibe desktop shell's own window rather than a
* browser tab or an installed PWA. This is the host, not the viewport size: see
* `useIsDesktop` for the layout breakpoint.
+ *
+ * The shell draws the window's title bar and owns the native Settings… menu, so
+ * the page leaves out the top bars a browser tab needs for the same job.
*/
export function isDesktopShell(): boolean {
return typeof window !== 'undefined' && window.__AVIBE_DESKTOP_SHELL__ === true;
}
+
+/**
+ * The native Settings… item (⌘,) dispatches this cancelable event on `window`.
+ * A listener that opens Settings in place cancels it; left uncancelled, the
+ * shell loads Settings as a page instead.
+ */
+export const DESKTOP_OPEN_SETTINGS_EVENT = 'avibe:desktop-open-settings';
diff --git a/ui/src/lib/settingsOverlay.ts b/ui/src/lib/settingsOverlay.ts
index 4cca66f12..e05c693f2 100644
--- a/ui/src/lib/settingsOverlay.ts
+++ b/ui/src/lib/settingsOverlay.ts
@@ -1,6 +1,8 @@
import { createContext, useContext } from 'react';
import type { Location, NavigateFunction } from 'react-router-dom';
+import { MODEL_HUB_SETTINGS_PATH } from '../components/settings/models/modelHubRoutes';
+import { SETTINGS_LANDING_PATH } from './adminNavigation';
import { inAppHistoryIndex } from './navigationHistory';
import { isLegacySettingsEntryPath } from './settingsRoutes';
@@ -53,6 +55,18 @@ export const isSettingsEntryPath = (pathname: string): boolean =>
*/
export const isChromelessShellPath = (pathname: string): boolean => pathname === '/setup';
+/**
+ * The Settings sections a setup visit opens over the wizard without leaving it:
+ * General, which holds the interface language the desktop shell's setup screens
+ * leave to it, and Model Hub, the setup's own repair route. The route guard keeps
+ * the wizard mounted behind exactly these, and a Settings menu opened from the
+ * wizard offers exactly these, so nothing on screen leads out of the setup.
+ */
+export const SETUP_VISIT_SETTINGS_PATHS: ReadonlySet<string> = new Set([
+ SETTINGS_LANDING_PATH,
+ MODEL_HUB_SETTINGS_PATH,
+]);
+
export const settingsOverlayOriginFromState = (state: unknown): SettingsOverlayOrigin | null => {
if (!state || typeof state !== 'object') return null;
const candidate = (state as SettingsOverlayState)[SETTINGS_BACKGROUND_KEY];