').text(value).html();
+globalThis.i18n = key => key;
+
+const { default: launch_app } = await import('./launchApp.js');
+const { default: UIAlert } = await import('../UI/UIAlert.js');
+const { openAppInNewTab } = await import('./dashboardAppLaunch.js');
+
+describe('openAppInNewTab', () => {
+ let opened;
+
+ beforeEach(() => {
+ opened = { closed: false };
+ vi.spyOn(window, 'open').mockImplementation(() => opened);
+ launch_app.mockResolvedValue({ launchResult: { launched: true } });
+ jQuery.fn.focusWindow = vi.fn();
+ jQuery.fn.showWindow = vi.fn();
+ document.body.innerHTML = '';
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ vi.clearAllMocks();
+ });
+
+ it('opens the app in a new tab, kept connected so the app can ask it for its token', async () => {
+ await openAppInNewTab('notes');
+ expect(window.open).toHaveBeenCalledWith('', '_blank');
+ expect(launch_app).toHaveBeenCalledWith({ name: 'notes', newTab: opened });
+ });
+
+ it('ignores a second click while the first launch is loading', async () => {
+ let finish;
+ launch_app.mockReturnValueOnce(new Promise((resolve) => {
+ finish = resolve;
+ }));
+ const first = openAppInNewTab('notes');
+ openAppInNewTab('notes');
+ expect(window.open).toHaveBeenCalledTimes(1);
+
+ finish();
+ await first;
+ await openAppInNewTab('notes');
+ expect(window.open).toHaveBeenCalledTimes(2);
+ });
+
+ it('brings back an open window when the browser refuses the tab', async () => {
+ window.open.mockReturnValue(null);
+ document.body.innerHTML = '
';
+ await openAppInNewTab('notes');
+ expect(jQuery.fn.focusWindow).toHaveBeenCalled();
+ expect(launch_app).not.toHaveBeenCalled();
+ });
+
+ it('opens the app in this page when the browser refuses the tab', async () => {
+ window.open.mockReturnValue(null);
+ await openAppInNewTab('notes');
+ expect(launch_app).toHaveBeenCalledWith({ name: 'notes', maximized: true });
+ });
+
+ it('tells the user when the launch fails', async () => {
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+ launch_app.mockRejectedValueOnce(new Error('offline'));
+ await openAppInNewTab('notes');
+ expect(UIAlert).toHaveBeenCalledWith('something_went_wrong');
+ });
+});
diff --git a/src/gui/src/helpers/focusAppWindow.js b/src/gui/src/helpers/focusAppWindow.js
new file mode 100644
index 000000000..6cf25ba3f
--- /dev/null
+++ b/src/gui/src/helpers/focusAppWindow.js
@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see
.
+ */
+
+import { is_window_on_screen, user_facing_windows } from './windowVisibility.js';
+
+/**
+ * Brings back the user's open window of an app, if there is one: focused when
+ * on screen, otherwise shown, since focusing a minimized or hidden window
+ * would leave it invisible. Windows another app launched in the background
+ * are its helpers, not the user's, so they don't count.
+ *
+ * @param {string} appName
+ * @returns {boolean} whether a window was brought back
+ */
+export function focusExistingAppWindow (appName) {
+ const $existing = $(user_facing_windows($(`.window[data-app="${html_encode(appName)}"]`)));
+ if ( ! $existing.length ) return false;
+ const $on_screen = $existing.filter((_, el) => is_window_on_screen(el)).last();
+ if ( $on_screen.length ) {
+ $on_screen.focusWindow();
+ return true;
+ }
+ $existing.last().showWindow();
+ return true;
+}