Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Fix Settings routing from the project navigator (#4443)

mike-inkeep23ba44961eed
diff --git a/.changeset/navigator-settings.md b/.changeset/navigator-settings.md
new file mode 100644
index 000000000..9ded16900
--- /dev/null
+++ b/.changeset/navigator-settings.md
@@ -0,0 +1,8 @@
+---
+"@inkeep/open-knowledge": patch
+"@inkeep/open-knowledge-desktop": patch
+---
+
+Open Settings from the project navigator in supported desktop installations to customize your theme and, when available, terminal access and connections to your AI tools. Reopening setup shows a customization heading while first launch keeps its welcome heading.
+
+Settings commands now share window routing across native menus, in-app menus, and deep links. Editor windows, including single-file editors, open full settings. On supported desktop installations, invoking Settings from a menu with no windows opens the navigator and its customization dialog. External Settings links open editor settings or the navigator without forcing the integration consent dialog. Unsupported installations direct you to use Settings from a project window.
diff --git a/docs/content/get-started/quickstart.mdx b/docs/content/get-started/quickstart.mdx
index 6de207526..98b995dac 100644
--- a/docs/content/get-started/quickstart.mdx
+++ b/docs/content/get-started/quickstart.mdx
@@ -31,7 +31,7 @@ Download the installer for your platform:
### Create a new project
-- Open the OpenKnowledge app. On first launch, approve the **Connect your AI tools to OpenKnowledge** dialog — it wires up your AI editors and makes sure the `ok` command is available in your terminal. If you skip it, re-open it later from **File → Set up OpenKnowledge integrations…**.
+- Open the OpenKnowledge app. On first launch, approve the **Connect your AI tools to OpenKnowledge** dialog — it wires up your AI editors and makes sure the `ok` command is available in your terminal. If you skip it, re-open it later from **File → Set up OpenKnowledge integrations…**. On supported desktop installations, **Settings…** from the project navigator also opens this customization dialog; [Settings in an editor](/docs/reference/configuration) opens the full settings pane.
- You'll then land on the launcher. To follow this guide, choose **Create new project** — or pick a starter pack from the **or use a starter pack** line beneath the cards (for example **Knowledge base**) to scaffold ready-made folders and templates up front and skip the Initialize step below. The count at the end of that line opens the full set of packs.
- Type a name for your project (for example, *Team Wiki*).
- Optionally click **Browse** to change where the project is saved, then click **Create**.
diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdx
index 7482a9b4e..9c57e36c2 100644
--- a/docs/content/reference/configuration.mdx
+++ b/docs/content/reference/configuration.mdx
@@ -20,6 +20,8 @@ You can inspect and edit config three ways:
Edits made anywhere reflect everywhere; an open Settings pane refreshes live.
+In the desktop app, Settings follows the focused window. An editor opens the full Settings pane. From the project navigator, Settings opens a customization dialog for your theme and, when available, terminal access and connections to your AI tools; on macOS it also opens that dialog when all windows are closed and the app is still running. This customization shortcut requires a supported packaged installation (macOS, Windows, or Linux deb/rpm). Dev and AppImage builds direct you to use Settings from a project window instead. Open a project for Account, Sync, Plugins, and Skills Studio settings. See the [quickstart](/docs/get-started/quickstart) for first-launch setup.
+
## Schema
The **Scope** column says which file a setting belongs in:
diff --git a/packages/app/src/components/McpConsentDialog.dom.test.tsx b/packages/app/src/components/McpConsentDialog.dom.test.tsx
index 3f2c8006e..4a253ff5f 100644
--- a/packages/app/src/components/McpConsentDialog.dom.test.tsx
+++ b/packages/app/src/components/McpConsentDialog.dom.test.tsx
@@ -785,6 +785,28 @@ describe('McpConsentDialog surface by origin', () => {
pending.resolve({ ok: true });
});
+ test('a user-opened one is titled as customization, not as a welcome', async () => {
+ await renderDialog(reconfigureHarness());
+
+ expect(
+ screen.getByRole('dialog', { name: /Customize your OpenKnowledge experience/ }),
+ ).toBeTruthy();
+ expect(screen.queryByText(/Welcome to OpenKnowledge/)).toBeNull();
+ expect(screen.queryByText(/Let's get set up/)).toBeNull();
+ expect(screen.getByRole('dialog').getAttribute('aria-describedby')).toBeNull();
+ });
+
+ test('first-run keeps the welcome title', async () => {
+ await renderDialog();
+
+ expect(screen.getByRole('alertdialog', { name: /Let's get set up/ })).toBeTruthy();
+ expect(screen.getByText(/Welcome to OpenKnowledge/)).toBeTruthy();
+ const descriptionId = screen.getByRole('alertdialog').getAttribute('aria-describedby');
+ expect(document.getElementById(descriptionId ?? '')?.textContent).toBe(
+ 'Customize your OpenKnowledge experience.',
+ );
+ });
+
test('a user-opened one still offers Finish setup', async () => {
const harness = await renderDialog(reconfigureHarness());
diff --git a/packages/app/src/components/McpConsentDialogBody.tsx b/packages/app/src/components/McpConsentDialogBody.tsx
index 2f90422b9..bc0c6d5cc 100644
--- a/packages/app/src/components/McpConsentDialogBody.tsx
+++ b/packages/app/src/components/McpConsentDialogBody.tsx
@@ -60,7 +60,12 @@ interface ConsentSurface {
onOpenChange: (open: boolean) => void;
children: ReactNode;
}>;
- Content: ComponentType<{ className?: string; 'aria-busy'?: boolean; children: ReactNode }>;
+ Content: ComponentType<{
+ className?: string;
+ 'aria-busy'?: boolean;
+ 'aria-describedby'?: string;
+ children: ReactNode;
+ }>;
Header: ComponentType<{ children: ReactNode }>;
Title: ComponentType<{ className?: string; children: ReactNode }>;
Description: ComponentType<{ className?: string; children: ReactNode }>;
@@ -216,22 +221,31 @@ function McpConsentDialogForm({ payload, store, toast }: McpConsentDialogFormPro
'[&_[data-slot=dialog-close]]:pointer-events-none [&_[data-slot=dialog-close]]:opacity-50',
)}
aria-busy={busy}
+ {...(firstRun ? {} : { 'aria-describedby': undefined })}
>
<Surface.Header>
<Surface.Title className="flex flex-col gap-8 text-2xl tracking-tighter">
{}
<OkIcon className="size-10 shrink-0" aria-hidden />
{}
- <span className="flex flex-col gap-1.5">
- <span className="uppercase font-mono font-normal text-2xs text-muted-foreground tracking-widest">
- <Trans>Welcome to OpenKnowledge</Trans>
+ {firstRun ? (
+ <span className="flex flex-col gap-1.5">
+ <span className="uppercase font-mono font-normal text-2xs text-muted-foreground tracking-widest">
+ <Trans>Welcome to OpenKnowledge</Trans>
+ </span>
+ <Trans>Let's get set up.</Trans>
+ </span>
+ ) : (
+ <span>
+ <Trans>Customize your OpenKnowledge experience.</Trans>
</span>
- <Trans>Let's get set up.</Trans>
- </span>
+ )}
</Surface.Title>
- <Surface.Description className="sr-only">
- <Trans>Customize your OpenKnowledge experience.</Trans>
- </Surface.Description>
+ {firstRun && (
+ <Surface.Description className="sr-only">
+ <Trans>Customize your OpenKnowledge experience.</Trans>
+ </Surface.Description>
+ )}
</Surface.Header>
<Surface.Body className="flex flex-col gap-6 min-h-0">
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 0d1277df4..79ca31252 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -408,6 +408,13 @@ import { handleRevealExternal } from './reveal-external.ts';
import { attachServerExitObserver } from './server-exit-observer.ts';
import { createServerExitRecorder, type ServerExitRecorder } from './server-exit-record.ts';
import { breakServerLockHeldBy } from './server-lock-break.ts';
+import {
+ openSettingsSurface,
+ resolveSettingsWindowKind,
+ type SettingsSurfaceOptions,
+ type SettingsWindowKind,
+ settingsHashScript,
+} from './settings-surface.ts';
import { startFirstRunHandshake } from './share-handoff.ts';
import { checkOutboundUrl, handleShellOpenExternal } from './shell-allowlist.ts';
import { applyHarvestedAuthSock, harvestShellAuthSock } from './shell-env.ts';
@@ -1539,7 +1546,8 @@ function ensureWindowManager() {
function openNavigator(pendingPayload?: ShareNavigatorPayload) {
if (navigatorWindow) {
getLogger('navigator').debug({}, 'already open, focusing');
- (navigatorWindow as unknown as { focus: () => void }).focus();
+ if (navigatorWindow.isMinimized?.()) navigatorWindow.restore?.();
+ navigatorWindow.focus();
if (pendingPayload) {
const wc = (navigatorWindow as unknown as { webContents: Electron.WebContents }).webContents;
if (wc.isLoading()) {
@@ -2333,14 +2341,7 @@ async function runMenuDispatchCommand(
refreshApplicationMenu();
return;
case 'open-settings': {
- const target =
- BrowserWindow.fromWebContents(sender) ??
- BrowserWindow.getFocusedWindow() ??
- BrowserWindow.getAllWindows()[0];
- if (!target) return;
- target.webContents
- .executeJavaScript("window.location.hash = '#settings'; undefined")
- .catch(() => {});
+ openSettings(BrowserWindow.fromWebContents(sender));
return;
}
case 'check-for-updates':
@@ -2351,7 +2352,7 @@ async function runMenuDispatchCommand(
});
return;
case 'reconfigure-mcp-wiring':
- reconfigureMcpWiringNow();
+ reconfigureMcpWiringNow(pickLoadedRendererForMcpDialog());
return;
case 'open-github':
void shell.openExternal('https://github.com/inkeep/open-knowledge');
@@ -2452,7 +2453,7 @@ async function runApplicationMenuRefresh(): Promise<void> {
reconfigureMcpWiring:
app.isPackaged && supportedPackagedInstall()
? () => {
- reconfigureMcpWiringNow();
+ reconfigureMcpWiringNow(pickLoadedRendererForMcpDialog());
}
: undefined,
openInstallSkillDialog: () => {
@@ -2462,13 +2463,7 @@ async function runApplicationMenuRefresh(): Promise<void> {
"window.location.hash = '#install-claude-desktop'; undefined",
);
},
- openSettings: () => {
- const target = BrowserWindow.getFocusedWindow() ?? BrowserWindow.getAllWindows()[0];
- if (!target) return;
- target.webContents
- .executeJavaScript("window.location.hash = '#settings'; undefined")
- .catch(() => {});
- },
+ openSettings: () => openSettings(),
onReportBug: () => sendMenuAction('report-bug'),
onSendFeedback: () => sendMenuAction('send-feedback'),
onCheckForUpdates: autoUpdaterHandle
@@ -3531,14 +3526,86 @@ function armMcpWiring(opts: ArmMcpWiringOpts = {}): RunMcpWiringHandle {
return runMcpWiringOnFirstLaunch(createMcpWiringOpts(opts));
}
-function reconfigureMcpWiringNow(): boolean {
+function settingsWindowKind(win: BrowserWindow): SettingsWindowKind {
+ return resolveSettingsWindowKind(win, {
+ isDestroyed: (target) => target.isDestroyed(),
+ isNavigator: (target) => target === navigatorWindow,
+ getEditorContext: (target) =>
+ wm?.getContextForBrowserWindow(target as unknown as BrowserWindowLike),
+ getNoteContext: (target) => getNoteWindowContext(target.id),
+ getTerminalContext: (target) => getTerminalWindowContext(target.id),
+ });
+}
+
+function openSettings(
+ explicit: BrowserWindow | null = null,
+ options: SettingsSurfaceOptions = {},
+): void {
+ openSettingsSurface(
+ explicit,
+ {
+ kindOf: settingsWindowKind,
+ getFocusedWindow: () => BrowserWindow.getFocusedWindow(),
+ getAllWindows: () => BrowserWindow.getAllWindows(),
+ showEditor: (win, section) => {
+ if (win.isMinimized()) win.restore();
+ win.focus();
+ void win.webContents.executeJavaScript(settingsHashScript(section)).catch((err) => {
+ getLogger('settings').warn({ err }, 'failed to open editor settings');
+ });
+ },
+ showNavigator: (win) => {
+ if (win?.isMinimized()) win.restore();
+ win?.focus();
+ if (!(app.isPackaged && supportedPackagedInstall())) {
+ getLogger('settings').warn(
+ { packaged: app.isPackaged, supported: supportedPackagedInstall() },
+ 'navigator settings unavailable on this install',
+ );
+ const options: MessageBoxOptions = {
+ type: 'info',
+ buttons: ['OK'],
+ defaultId: 0,
+ cancelId: 0,
+ title: 'Settings unavailable',
+ message:
+ 'Settings from the navigator is unavailable in this build. Open Settings from a project window instead.',
+ };
+ void (win ? dialog.showMessageBox(win, options) : dialog.showMessageBox(options));
+ return false;
+ }
+ return reconfigureMcpWiringNow(
+ win && !win.webContents.isLoading() ? win.webContents : undefined,
+ );
+ },
+ openNavigator,
+ onEditorRequired: (win) => {
+ getLogger('settings').info({}, 'account settings require an open project');
+ const options: MessageBoxOptions = {
+ type: 'info',
+ buttons: ['OK'],
+ defaultId: 0,
+ cancelId: 0,
+ title: 'Open a project',
+ message: 'Open a project to connect your account in Settings.',
+ };
+ void (win && !win.isDestroyed()
+ ? dialog.showMessageBox(win, options)
+ : dialog.showMessageBox(options));
+ },
+ },
+ options,
+ );
+}
+
+function reconfigureMcpWiringNow(target: McpWiringDispatchTarget | undefined): boolean {
if (!(app.isPackaged && supportedPackagedInstall())) return false;
mcpWiringHandle?.destroy();
mcpWiringHandle = null;
try {
mcpWiringHandle = armMcpWiring({
forceShow: true,
- immediateDispatchTarget: pickLoadedRendererForMcpDialog(),
+ immediateDispatchTarget: target,
});
return true;
} catch (err) {
@@ -3712,7 +3779,10 @@ const RECENT_GIT_ROOTS_CAP = 256;
function registerIpcHandlers() {
const handle = createHandler(ipcMain);
- handle('ok:mcp-wiring:reconfigure', async (): Promise<boolean> => reconfigureMcpWiringNow());
+ handle(
+ 'ok:mcp-wiring:reconfigure',
+ async (): Promise<boolean> => reconfigureMcpWiringNow(pickLoadedRendererForMcpDialog()),
+ );
handle('ok:spellcheck:toggle', async (): Promise<boolean> => {
setSpellCheckEnabledAppWide(!appState.spellCheckEnabled);
@@ -5996,13 +6066,7 @@ function bootPrimaryInstance(): void {
? await dialog.showMessageBox(parentWindow, messageBoxOptions)
: await dialog.showMessageBox(messageBoxOptions);
if (response === 0) {
- if (parentWindow) {
- (parentWindow as BrowserWindowLike).webContents.executeJavaScript(
- "window.location.hash = '#settings/account'; undefined",
- );
- } else {
- openNavigator();
- }
+ openSettings(parentWindow ?? null, { section: 'account', editorOnly: true });
return 'connect';
}
if (BrowserWindow.getAllWindows().length === 0) {
@@ -6029,14 +6093,22 @@ function bootPrimaryInstance(): void {
openNavigator(payload);
},
openScreen: (win, screen) => {
+ if (screen === 'settings') {
+ openSettings(win as BrowserWindow | null, { origin: 'deep-link' });
+ return;
+ }
+ if (!win) return;
const w = win as BrowserWindowLike;
- const hashByScreen: Record<ScreenTarget, string> = {
- settings: '#settings',
+ const hashByScreen: Record<Exclude<ScreenTarget, 'settings'>, string> = {
'install-claude': '#install-claude-desktop',
};
- w.webContents.executeJavaScript(
- `window.location.hash = '${hashByScreen[screen]}'; undefined`,
- );
+ void w.webContents
+ .executeJavaScript(
+ `window.location.hash = ${JSON.stringify(hashByScreen[screen])}; undefined`,
+ )
+ .catch((err) => {
+ getLogger('url-scheme').warn({ err, screen }, 'failed to open screen deep link');
+ });
},
getFocusedWindow: () => {
const focused = BrowserWindow.getFocusedWindow();
diff --git a/packages/desktop/src/main/settings-surface.test.ts b/packages/desktop/src/main/settings-surface.test.ts
new file mode 100644
index 000000000..d37b2eeda
--- /dev/null
+++ b/packages/desktop/src/main/settings-surface.test.ts
@@ -0,0 +1,313 @@
+import { describe, expect, test, vi } from 'vitest';
+
+import {
+ openSettingsSurface,
+ resolveSettingsSurface,
+ resolveSettingsWindowKind,
+ type SettingsSurfaceDeps,
+ type SettingsWindowKind,
+ settingsHash,
+ settingsHashScript,
+} from './settings-surface.ts';
+
+interface FakeWindow {
+ id: number;
+ kind: SettingsWindowKind;
+}
+
+function win(id: number, kind: SettingsWindowKind): FakeWindow {
+ return { id, kind };
+}
+
+function depsFor(
+ focused: FakeWindow | null,
+ all: readonly FakeWindow[],
+): SettingsSurfaceDeps<FakeWindow> {
+ return {
+ kindOf: (w) => w.kind,
+ getFocusedWindow: () => focused,
+ getAllWindows: () => all,
+ };
+}
+
+describe('resolveSettingsWindowKind', () => {
+ const project = { ephemeral: false };
+ const singleFile = { ephemeral: true };
+ const navigator = { id: 1 };
+ const editor = { id: 2 };
+ const singleFileEditor = { id: 3 };
+ const note = { id: 4 };
+ const terminal = { id: 5 };
+ const other = { id: 6 };
+ const destroyed = { id: 7 };
+ const editors = new Map([
+ [editor.id, project],
+ [singleFileEditor.id, singleFile],
+ [destroyed.id, project],
+ ]);
+ const notes = new Map([[note.id, {}]]);
+ const terminals = new Map([[terminal.id, {}]]);
+ const deps = {
+ isDestroyed: (target: { id: number }) => target === destroyed,
+ isNavigator: (target: { id: number }) => target === navigator,
+ getEditorContext: (target: { id: number }) => editors.get(target.id),
+ getNoteContext: (target: { id: number }) => notes.get(target.id),
+ getTerminalContext: (target: { id: number }) => terminals.get(target.id),
+ };
+
+ test.each([
+ [navigator, 'navigator'],
+ [editor, 'editor'],
+ [singleFileEditor, 'editor'],
+ [note, 'note'],
+ [terminal, 'terminal'],
+ [other, 'other'],
+ [destroyed, 'other'],
+ ] as const)('classifies window %j as %s from its registry', (target, expected) => {
+ expect(resolveSettingsWindowKind(target, deps)).toBe(expected);
+ });
+
+ test('keeps Settings in a single-file editor with another project behind it', () => {
+ expect(
+ resolveSettingsSurface(singleFileEditor, {
+ kindOf: (target) => resolveSettingsWindowKind(target, deps),
+ getFocusedWindow: () => singleFileEditor,
+ getAllWindows: () => [editor, singleFileEditor, navigator],
+ }),
+ ).toEqual({ kind: 'editor', window: singleFileEditor });
+ });
+});
+
+describe('resolveSettingsSurface', () => {
+ test('an explicit editor window wins over a focused navigator', () => {
+ const editor = win(1, 'editor');
+ const navigator = win(2, 'navigator');
+ expect(resolveSettingsSurface(editor, depsFor(navigator, [navigator, editor]))).toEqual({
+ kind: 'editor',
+ window: editor,
+ });
+ });
+
+ test('an explicit navigator window hosts the navigator surface', () => {
+ const navigator = win(2, 'navigator');
+ expect(resolveSettingsSurface(navigator, depsFor(null, [navigator]))).toEqual({
+ kind: 'navigator',
+ window: navigator,
+ });
+ });
+
+ test('an explicit window that cannot host settings falls through to focus', () => {
+ const note = win(3, 'note');
+ const editor = win(1, 'editor');
+ expect(resolveSettingsSurface(note, depsFor(editor, [note, editor]))).toEqual({
+ kind: 'editor',
+ window: editor,
+ });
+ });
+
+ test('the focused editor window is the target', () => {
+ const editor = win(1, 'editor');
+ const navigator = win(2, 'navigator');
+ expect(resolveSettingsSurface(null, depsFor(editor, [navigator, editor]))).toEqual({
+ kind: 'editor',
+ window: editor,
+ });
+ });
+
+ test('a focused navigator is the target even when an editor window is open behind it', () => {
+ const editor = win(1, 'editor');
+ const navigator = win(2, 'navigator');
+ expect(resolveSettingsSurface(null, depsFor(navigator, [editor, navigator]))).toEqual({
+ kind: 'navigator',
+ window: navigator,
+ });
+ });
+
+ test('a focused terminal window defers to an open editor window', () => {
+ const terminal = win(4, 'terminal');
+ const editor = win(1, 'editor');
+ const navigator = win(2, 'navigator');
+ expect(resolveSettingsSurface(null, depsFor(terminal, [navigator, terminal, editor]))).toEqual({
+ kind: 'editor',
+ window: editor,
+ });
+ });
+
+ test('a focused note window with only the navigator open lands on the navigator', () => {
+ const note = win(3, 'note');
+ const navigator = win(2, 'navigator');
+ expect(resolveSettingsSurface(null, depsFor(note, [note, navigator]))).toEqual({
+ kind: 'navigator',
+ window: navigator,
+ });
+ });
+
+ test('no windows at all resolves to none', () => {
+ expect(resolveSettingsSurface(null, depsFor(null, []))).toEqual({ kind: 'none' });
+ });
+
+ test('windows of unknown kind never host settings', () => {
+ const other = win(9, 'other');
+ expect(resolveSettingsSurface(other, depsFor(other, [other]))).toEqual({ kind: 'none' });
+ });
+
+ describe('editorOnly', () => {
+ test('skips a focused navigator when an editor window exists', () => {
+ const editor = win(1, 'editor');
+ const navigator = win(2, 'navigator');
+ expect(
+ resolveSettingsSurface(null, depsFor(navigator, [navigator, editor]), {
+ editorOnly: true,
+ }),
+ ).toEqual({ kind: 'editor', window: editor });
+ });
+
+ test('resolves to none when only the navigator is open', () => {
+ const navigator = win(2, 'navigator');
+ expect(
+ resolveSettingsSurface(navigator, depsFor(navigator, [navigator]), { editorOnly: true }),
+ ).toEqual({ kind: 'none' });
+ });
+ });
+});
+
+describe('openSettingsSurface', () => {
+ function harness(focused: FakeWindow | null, all: readonly FakeWindow[]) {
+ return {
+ ...depsFor(focused, all),
+ showEditor: vi.fn(),
+ showNavigator: vi.fn(() => true),
+ openNavigator: vi.fn(),
+ onEditorRequired: vi.fn(),
+ };
+ }
+
+ test('opens customization in the focused navigator while a project is open', () => {
+ const navigator = win(1, 'navigator');
+ const deps = harness(navigator, [win(2, 'editor'), navigator]);
+
+ openSettingsSurface(null, deps);
+
+ expect(deps.showNavigator).toHaveBeenCalledExactlyOnceWith(navigator);
+ expect(deps.showEditor).not.toHaveBeenCalled();
+ expect(deps.openNavigator).not.toHaveBeenCalled();
+ });
+
+ test('opens full settings in the requesting editor even after focus has changed', () => {
+ const editor = win(1, 'editor');
+ const navigator = win(2, 'navigator');
+ const deps = harness(navigator, [editor, navigator]);
+
+ openSettingsSurface(editor, deps);
+
+ expect(deps.showEditor).toHaveBeenCalledExactlyOnceWith(editor, undefined);
+ expect(deps.showNavigator).not.toHaveBeenCalled();
+ });
+
+ test('arms customization before creating the first navigator', () => {
+ const deps = harness(null, []);
+ deps.openNavigator.mockImplementation(() => {
+ expect(deps.showNavigator).toHaveBeenCalledExactlyOnceWith(null);
+ });
+
+ openSettingsSurface(null, deps);
+
+ expect(deps.openNavigator).toHaveBeenCalledOnce();
+ expect(deps.showEditor).not.toHaveBeenCalled();
+ });
+
+ test('a terminal-only session creates a navigator to host customization', () => {
+ const terminal = win(1, 'terminal');
+ const deps = harness(terminal, [terminal]);
+
+ openSettingsSurface(terminal, deps);
+
+ expect(deps.showNavigator).toHaveBeenCalledExactlyOnceWith(null);
+ expect(deps.openNavigator).toHaveBeenCalledOnce();
+ });
+
+ test('account settings target an editor even when the navigator is focused', () => {
+ const editor = win(1, 'editor');
+ const navigator = win(2, 'navigator');
+ const deps = harness(navigator, [navigator, editor]);
+
+ openSettingsSurface(navigator, deps, { editorOnly: true, section: 'account' });
+
+ expect(deps.showEditor).toHaveBeenCalledExactlyOnceWith(editor, 'account');
+ expect(deps.showNavigator).not.toHaveBeenCalled();
+ });
+
+ test('account settings without an editor open the project picker', () => {
+ const deps = harness(null, []);
+
+ openSettingsSurface(null, deps, { editorOnly: true, section: 'account' });
+
+ expect(deps.openNavigator).toHaveBeenCalledOnce();
+ expect(deps.showEditor).not.toHaveBeenCalled();
+ expect(deps.showNavigator).not.toHaveBeenCalled();
+ expect(deps.onEditorRequired).toHaveBeenCalledExactlyOnceWith(null);
+ });
+
+ test.each(['terminal', 'note', 'navigator'] as const)(
+ 'account settings explain the project requirement when only a %s is open',
+ (kind) => {
+ const focused = win(1, kind);
+ const deps = harness(focused, [focused]);
+
+ openSettingsSurface(focused, deps, { editorOnly: true, section: 'account' });
+
+ expect(deps.openNavigator).toHaveBeenCalledOnce();
+ expect(deps.onEditorRequired).toHaveBeenCalledExactlyOnceWith(focused);
+ expect(deps.showNavigator).not.toHaveBeenCalled();
+ expect(deps.showEditor).not.toHaveBeenCalled();
+ },
+ );
+
+ test('does not create an empty navigator when customization cannot be armed', () => {
+ const deps = harness(null, []);
+ deps.showNavigator.mockReturnValue(false);
+
+ openSettingsSurface(null, deps);
+
+ expect(deps.showNavigator).toHaveBeenCalledExactlyOnceWith(null);
+ expect(deps.openNavigator).not.toHaveBeenCalled();
+ });
+
+ test.each([null, win(1, 'navigator'), win(2, 'terminal')] as const)(
+ 'a deep link with %j focused opens the navigator without forcing consent',
+ (focused) => {
+ const deps = harness(focused, focused ? [focused] : []);
+
+ openSettingsSurface(focused, deps, { origin: 'deep-link' });
+
+ expect(deps.openNavigator).toHaveBeenCalledOnce();
+ expect(deps.showNavigator).not.toHaveBeenCalled();
+ expect(deps.onEditorRequired).not.toHaveBeenCalled();
+ },
+ );
+
+ test('a deep link still opens full settings in an existing editor', () => {
+ const editor = win(1, 'editor');
+ const deps = harness(editor, [editor]);
+
+ openSettingsSurface(editor, deps, { origin: 'deep-link' });
+
+ expect(deps.showEditor).toHaveBeenCalledExactlyOnceWith(editor, undefined);
+ expect(deps.showNavigator).not.toHaveBeenCalled();
+ expect(deps.openNavigator).not.toHaveBeenCalled();
+ });
+});
+
+describe('settingsHash', () => {
+ test('defaults to the bare settings hash', () => {
+ expect(settingsHash()).toBe('#settings');
+ expect(settingsHashScript()).toBe('window.location.hash = "#settings"; undefined');
+ });
+
+ test('appends a section id', () => {
+ expect(settingsHash('account')).toBe('#settings/account');
+ expect(settingsHashScript('account')).toBe(
+ 'window.location.hash = "#settings/account"; undefined',
+ );
+ });
+});
diff --git a/packages/desktop/src/main/settings-surface.ts b/packages/desktop/src/main/settings-surface.ts
new file mode 100644
index 000000000..ef2cf2e23
--- /dev/null
+++ b/packages/desktop/src/main/settings-surface.ts
@@ -0,0 +1,98 @@
+export type SettingsWindowKind = 'editor' | 'navigator' | 'note' | 'terminal' | 'other';
+
+export function resolveSettingsWindowKind<TWindow>(
+ win: TWindow,
+ deps: {
+ isDestroyed: (win: TWindow) => boolean;
+ isNavigator: (win: TWindow) => boolean;
+ getEditorContext: (win: TWindow) => object | null | undefined;
+ getNoteContext: (win: TWindow) => object | undefined;
+ getTerminalContext: (win: TWindow) => object | undefined;
+ },
+): SettingsWindowKind {
+ if (deps.isDestroyed(win)) return 'other';
+ if (deps.isNavigator(win)) return 'navigator';
+ if (deps.getTerminalContext(win)) return 'terminal';
+ if (deps.getNoteContext(win)) return 'note';
+ return deps.getEditorContext(win) ? 'editor' : 'other';
+}
+
+export interface SettingsSurfaceDeps<TWindow> {
+ kindOf: (win: TWindow) => SettingsWindowKind;
+ getFocusedWindow: () => TWindow | null;
+ getAllWindows: () => readonly TWindow[];
+}
+
+export type SettingsSection = 'account';
+
+export type SettingsSurfaceOptions =
+ | { origin?: 'user' | 'deep-link'; editorOnly?: false; section?: never }
+ | { origin?: 'user'; editorOnly: true; section?: SettingsSection };
+
+export interface OpenSettingsSurfaceDeps<TWindow> extends SettingsSurfaceDeps<TWindow> {
+ showEditor: (win: TWindow, section?: SettingsSection) => void;
+ showNavigator: (win: TWindow | null) => boolean;
+ openNavigator: () => void;
+ onEditorRequired: (win: TWindow | null) => void;
+}
+
+export type SettingsSurfaceTarget<TWindow> =
+ | { kind: 'editor'; window: TWindow }
+ | { kind: 'navigator'; window: TWindow }
+ | { kind: 'none' };
+
+export function resolveSettingsSurface<TWindow>(
+ explicit: TWindow | null,
+ deps: SettingsSurfaceDeps<TWindow>,
+ options: SettingsSurfaceOptions = {},
+): SettingsSurfaceTarget<TWindow> {
+ const editorOnly = options.editorOnly === true;
+ const asHost = (win: TWindow | null): SettingsSurfaceTarget<TWindow> | null => {
+ if (win == null) return null;
+ const kind = deps.kindOf(win);
+ if (kind === 'editor') return { kind, window: win };
+ if (kind === 'navigator' && !editorOnly) return { kind, window: win };
+ return null;
+ };
+
+ const direct = asHost(explicit) ?? asHost(deps.getFocusedWindow());
+ if (direct) return direct;
+
+ const all = deps.getAllWindows();
+ const editor = all.find((win) => deps.kindOf(win) === 'editor');
+ if (editor !== undefined) return { kind: 'editor', window: editor };
+ if (!editorOnly) {
+ const navigator = all.find((win) => deps.kindOf(win) === 'navigator');
+ if (navigator !== undefined) return { kind: 'navigator', window: navigator };
+ }
+ return { kind: 'none' };
+}
+
+export function openSettingsSurface<TWindow>(
+ explicit: TWindow | null,
+ deps: OpenSettingsSurfaceDeps<TWindow>,
+ options: SettingsSurfaceOptions = {},
+): void {
+ const target = resolveSettingsSurface(explicit, deps, options);
+ if (target.kind === 'editor') {
+ deps.showEditor(target.window, options.section);
+ } else if (options.origin === 'deep-link') {
+ deps.openNavigator();
+ } else if (target.kind === 'navigator') {
+ deps.showNavigator(target.window);
+ } else if (options.editorOnly) {
+ deps.openNavigator();
+ deps.onEditorRequired(explicit ?? deps.getFocusedWindow());
+ } else if (deps.showNavigator(null)) {
+ deps.openNavigator();
+ }
+}
+
+export function settingsHash(section?: SettingsSection): string {
+ if (section === undefined) return '#settings';
+ return `#settings/${section}`;
+}
+
+export function settingsHashScript(section?: SettingsSection): string {
+ return `window.location.hash = ${JSON.stringify(settingsHash(section))}; undefined`;
+}
diff --git a/packages/desktop/src/main/url-scheme.ts b/packages/desktop/src/main/url-scheme.ts
index 7a44d2c8c..dd0aad8ca 100644
--- a/packages/desktop/src/main/url-scheme.ts
+++ b/packages/desktop/src/main/url-scheme.ts
@@ -406,7 +406,7 @@ interface ProtocolHandlerDeps {
path: string,
): CheckTargetExistsResult;
routeShareToNavigator?(payload: ShareNavigatorPayload): void;
- openScreen?(win: BrowserWindowHandle, screen: ScreenTarget): void;
+ openScreen?(win: BrowserWindowHandle | null, screen: ScreenTarget): void;
getFocusedWindow?(): BrowserWindowHandle | null;
getAnyReadyWindow(): BrowserWindowHandle | null;
getInitialArgv?: () => readonly string[];
@@ -765,7 +765,7 @@ export function registerProtocolHandler(deps: ProtocolHandlerDeps): ProtocolHand
return;
}
const target = deps.getFocusedWindow?.() ?? deps.getAnyReadyWindow();
- if (!target) {
+ if (!target && screen !== 'settings') {
deps.log?.warn({ url, screen }, '[url-scheme] no target window — screen deep link dropped');
return;
}
diff --git a/packages/desktop/tests/main/url-scheme-handler.test.ts b/packages/desktop/tests/main/url-scheme-handler.test.ts
index 887b8d625..f10a954e5 100644
--- a/packages/desktop/tests/main/url-scheme-handler.test.ts
+++ b/packages/desktop/tests/main/url-scheme-handler.test.ts
@@ -1983,7 +1983,7 @@ describe('registerProtocolHandler — screen-flow routing', () => {
const env = makeEnv();
const focusedWin: FakeWindowHandle = { id: 'focused' };
env.readyWindow = focusedWin;
- const openScreen = vi.fn((_win: FakeWindowHandle, _screen: ScreenTarget) => {});
+ const openScreen = vi.fn((_win: FakeWindowHandle | null, _screen: ScreenTarget) => {});
registerProtocolHandler({
app: env.app,
@@ -2011,7 +2011,7 @@ describe('registerProtocolHandler — screen-flow routing', () => {
const env = makeEnv();
const focusedWin: FakeWindowHandle = { id: 'focused' };
env.readyWindow = focusedWin;
- const openScreen = vi.fn((_win: FakeWindowHandle, _screen: ScreenTarget) => {});
+ const openScreen = vi.fn((_win: FakeWindowHandle | null, _screen: ScreenTarget) => {});
registerProtocolHandler({
app: env.app,
@@ -2038,7 +2038,7 @@ describe('registerProtocolHandler — screen-flow routing', () => {
const env = makeEnv();
const readyWin: FakeWindowHandle = { id: 'fallback' };
env.readyWindow = readyWin;
- const openScreen = vi.fn((_win: FakeWindowHandle, _screen: ScreenTarget) => {});
+ const openScreen = vi.fn((_win: FakeWindowHandle | null, _screen: ScreenTarget) => {});
registerProtocolHandler({
app: env.app,
@@ -2085,31 +2085,39 @@ describe('registerProtocolHandler — screen-flow routing', () => {
expect(env.sendDeepLink).not.toHaveBeenCalled();
});
- test('screen URL with no window available surfaces warn + no dispatch', async () => {
- const env = makeEnv();
- env.readyWindow = { id: 'ready' };
- const openScreen = vi.fn((_win: FakeWindowHandle, _screen: ScreenTarget) => {});
+ test.each(['settings', 'install-claude'] as const)(
+ '%s screen routing handles an app with no windows',
+ async (screen) => {
+ const env = makeEnv();
+ env.readyWindow = { id: 'ready' };
+ const openScreen = vi.fn((_win: FakeWindowHandle | null, _screen: ScreenTarget) => {});
- registerProtocolHandler({
- app: env.app,
- focusWindowForProject: env.focusWindowForProject,
- openProject: env.openProject,
- sendDeepLink: env.sendDeepLink,
- getAnyReadyWindow: vi.fn(() => null),
- openScreen,
- getFocusedWindow: () => null,
- setTimeout: (cb, ms) => env.timers.push({ cb, ms }),
- log: env.log,
- });
- env.app.resolveReady();
- await flushPromises();
+ registerProtocolHandler({
+ app: env.app,
+ focusWindowForProject: env.focusWindowForProject,
+ openProject: env.openProject,
+ sendDeepLink: env.sendDeepLink,
+ getAnyReadyWindow: vi.fn(() => null),
+ openScreen,
+ getFocusedWindow: () => null,
+ setTimeout: (cb, ms) => env.timers.push({ cb, ms }),
+ log: env.log,
+ });
+ env.app.resolveReady();
+ await flushPromises();
- env.app.fireOpenUrl('openknowledge://screen?name=settings');
- await flushPromises();
+ env.app.fireOpenUrl(`openknowledge://screen?name=${screen}`);
+ await flushPromises();
- expect(openScreen).not.toHaveBeenCalled();
- expect(env.warnLog.some((e) => e.msg.includes('no target window'))).toBe(true);
- });
+ if (screen === 'settings') {
+ expect(openScreen).toHaveBeenCalledExactlyOnceWith(null, 'settings');
+ expect(env.warnLog.some((e) => e.msg.includes('no target window'))).toBe(false);
+ } else {
+ expect(openScreen).not.toHaveBeenCalled();
+ expect(env.warnLog.some((e) => e.msg.includes('no target window'))).toBe(true);
+ }
+ },
+ );
});
describe('registerProtocolHandler — continue-activity Handoff path', () => {
diff --git a/packages/desktop/tests/smoke/terminal-dock.e2e.ts b/packages/desktop/tests/smoke/terminal-dock.e2e.ts
index 260dae813..2ddee79c1 100644
--- a/packages/desktop/tests/smoke/terminal-dock.e2e.ts
+++ b/packages/desktop/tests/smoke/terminal-dock.e2e.ts
@@ -1069,7 +1069,8 @@ test.describe('Docked terminal — live Electron', () => {
.click();
const setup = page.getByRole('dialog', { name: 'Claude', exact: true });
await expect(setup).toContainText('Choose what OpenKnowledge sets up for Claude.');
- await setup.getByRole('checkbox', { name: 'Project MCP server', exact: true }).uncheck();
+ await setup.getByRole('checkbox', { name: 'Project MCP server', exact: true }).check();
+ await setup.getByRole('checkbox', { name: 'Project skill', exact: true }).check();
await setup.getByRole('checkbox', { name: 'Global MCP server', exact: true }).uncheck();
await setup
.getByRole('checkbox', { name: 'OpenKnowledge discovery skill', exact: true })