@theia/core 1.74.0-next.9 → 1.74.1

package/src/browser/widgets/select-component.tsx

@@ -61,6 +61,10 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
     protected optimalWidth = 0;
     protected optimalHeight = 0;
     protected resizeObserver: ResizeObserver | undefined;
+    /** Window the scroll/wheel/resize listeners are attached to; may differ from the main window in secondary windows. */
+    protected listenersWindow: Window | undefined;
+    /** Perfect-scrollbar ancestors the `ps-scroll-y` listener was attached to. The field may have moved to another window since, so the elements are remembered. */
+    protected psScrollListenerTargets: HTMLElement[] = [];
 
     constructor(props: SelectComponentProps) {
         super(props);
@@ -71,14 +75,28 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
             hover: selected
         };
 
-        let list = document.getElementById(SELECT_COMPONENT_CONTAINER);
+        this.dropdownElement = this.resolveDropdownContainer(document);
+    }
+
+    /**
+     * The document that currently hosts this component. Falls back to the main document before
+     * the first render. Widgets can be moved to secondary windows, so this must be re-queried
+     * instead of captured once.
+     */
+    protected getHostDocument(): Document {
+        return this.fieldRef.current?.ownerDocument ?? document;
+    }
+
+    /** Finds or creates the dropdown portal container in the given document. */
+    protected resolveDropdownContainer(hostDocument: Document): HTMLElement {
+        let list = hostDocument.getElementById(SELECT_COMPONENT_CONTAINER);
         if (!list) {
-            list = document.createElement('div');
+            list = hostDocument.createElement('div');
             list.id = SELECT_COMPONENT_CONTAINER;
             list.className = 'theia-select-component-container';
-            document.body.appendChild(list);
+            hostDocument.body.appendChild(list);
         }
-        this.dropdownElement = list;
+        return list;
     }
 
     protected getInitialSelectedIndex(props: SelectComponentProps): number {
@@ -91,7 +109,20 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
         return selected;
     }
 
-    override componentDidUpdate(prevProps: SelectComponentProps): void {
+    override componentDidUpdate(prevProps: SelectComponentProps, prevState: SelectComponentState): void {
+        if (prevState.selected !== this.state.selected && this.state.dimensions) {
+            const dropdownContainer = this.dropdownRef?.current;
+            const selectedOption = dropdownContainer?.querySelector(`[data-option-index="${this.state.selected}"]`) as HTMLElement | undefined;
+            if (dropdownContainer && selectedOption) {
+                const optionBottom = selectedOption.offsetTop + selectedOption.offsetHeight;
+                const visibleBottom = dropdownContainer.scrollTop + dropdownContainer.clientHeight;
+                if (optionBottom > visibleBottom) {
+                    dropdownContainer.scrollTop = optionBottom - dropdownContainer.clientHeight;
+                } else if (selectedOption.offsetTop < dropdownContainer.scrollTop) {
+                    dropdownContainer.scrollTop = selectedOption.offsetTop;
+                }
+            }
+        }
         if (prevProps.defaultValue !== this.props.defaultValue || prevProps.options !== this.props.options) {
             const selected = this.getInitialSelectedIndex(this.props);
             this.setState({
@@ -166,12 +197,14 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
             // neither triggers the `scroll`, `wheel` nor `blur` event
             if (parent.classList.contains('ps')) {
                 parent.addEventListener('ps-scroll-y', hide);
+                this.psScrollListenerTargets.push(parent);
             }
             parent = parent.parentElement;
         }
 
+        this.listenersWindow = this.getHostDocument().defaultView ?? window;
         for (const [key, listener] of this.mountedListeners.entries()) {
-            window.addEventListener(key, listener);
+            this.listenersWindow.addEventListener(key, listener);
         }
 
         // Catch Lumino sash drags globally - observe the closest lm-Widget panel
@@ -209,18 +242,24 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
     }
 
     override componentWillUnmount(): void {
+        this.detachListeners();
+    }
+
+    protected detachListeners(): void {
         this.resizeObserver?.disconnect();
+        this.resizeObserver = undefined;
         if (this.mountedListeners.size > 0) {
             const eventListener = this.mountedListeners.get('scroll')!;
-            let parent = this.fieldRef.current?.parentElement;
-            while (parent) {
-                parent.removeEventListener('ps-scroll-y', eventListener);
-                parent = parent.parentElement;
+            for (const target of this.psScrollListenerTargets) {
+                target.removeEventListener('ps-scroll-y', eventListener);
             }
             for (const [key, listener] of this.mountedListeners.entries()) {
-                window.removeEventListener(key, listener);
+                (this.listenersWindow ?? window).removeEventListener(key, listener);
             }
+            this.mountedListeners.clear();
         }
+        this.psScrollListenerTargets = [];
+        this.listenersWindow = undefined;
     }
 
     override render(): React.ReactNode {
@@ -230,13 +269,18 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
             selected = this.nextNotSeparator('forwards');
         }
         const selectedItemLabel = options[selected]?.label ?? options[selected]?.value;
+        // Expose when the currently shown option is disabled so consumers can style the field to match
+        // it (e.g. the option previewed while navigating), instead of a fixed committed-value class.
+        const selectionDisabled = !!options[selected]?.disabled;
+        const fieldClassName = `theia-select-component${this.props.className ? ` ${this.props.className}` : ''}`
+            + `${selectionDisabled ? ' theia-select-component-selection-disabled' : ''}`;
         return <>
             <div
                 id={this.props.id}
                 key="select-component"
                 ref={this.fieldRef}
                 tabIndex={0}
-                className={`theia-select-component${this.props.className ? ` ${this.props.className}` : ''}`}
+                className={fieldClassName}
                 onClick={e => this.handleClickEvent(e)}
                 onBlur={
                     () => {
@@ -254,11 +298,11 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
         </>;
     }
 
-    protected nextNotSeparator(direction: 'forwards' | 'backwards'): number {
+    protected nextNotSeparator(direction: 'forwards' | 'backwards', startFrom?: number): number {
         const { options } = this.props;
         const step = direction === 'forwards' ? 1 : -1;
         const length = this.props.options.length;
-        let selected = this.state.selected;
+        let selected = startFrom ?? this.state.selected;
         let count = 0;
         do {
             selected = (selected + step) % length;
@@ -267,7 +311,8 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
             }
             count++;
         }
-        while (options[selected]?.separator && count < length);
+        // Skip separators and disabled options so keyboard navigation never lands on a non-selectable entry.
+        while ((options[selected]?.separator || options[selected]?.disabled) && count < length);
         return selected;
     }
 
@@ -276,23 +321,26 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
             return;
         }
         if (ev.key === 'ArrowUp') {
-            const selected = this.nextNotSeparator('backwards');
+            const selected = this.nextNotSeparator('backwards', this.state.hover);
             this.setState({
                 selected,
                 hover: selected
             });
         } else if (ev.key === 'ArrowDown') {
             if (this.state.dimensions) {
-                const selected = this.nextNotSeparator('forwards');
+                const selected = this.nextNotSeparator('forwards', this.state.hover);
                 this.setState({
                     selected,
                     hover: selected
                 });
             } else {
                 this.toggleVisibility();
+                // Start on the first selectable option (startFrom -1 evaluates index 0 first), so a
+                // leading separator or disabled option is skipped instead of becoming the active row.
+                const selected = this.nextNotSeparator('forwards', -1);
                 this.setState({
-                    selected: 0,
-                    hover: 0,
+                    selected,
+                    hover: selected,
                 });
             }
         } else if (ev.key === 'Enter') {
@@ -300,7 +348,10 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
                 this.toggleVisibility();
             } else {
                 const selected = this.state.selected;
-                this.selectOption(selected, this.props.options[selected]);
+                const option = this.props.options[selected];
+                if (!option?.disabled) {
+                    this.selectOption(selected, option);
+                }
             }
         } else if (ev.key === 'Escape' || ev.key === 'Tab') {
             this.hide(undefined, true);
@@ -320,6 +371,14 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
             return;
         }
         if (!this.state.dimensions) {
+            // Re-resolve the portal container and listener window against the document that
+            // currently hosts the field: the widget may have been moved to a secondary window
+            // (or back to the main window) since the last time the dropdown was opened.
+            const hostDocument = this.getHostDocument();
+            this.dropdownElement = this.resolveDropdownContainer(hostDocument);
+            if (this.listenersWindow && this.listenersWindow !== hostDocument.defaultView) {
+                this.detachListeners();
+            }
             const rect = this.fieldRef.current.getBoundingClientRect();
             this.setState({ dimensions: rect });
         } else {
@@ -336,7 +395,8 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
             hover: selectedIndex
         });
         // Force releasing focus of the select element to allow closing via escape later on
-        if (releaseFocus && document.activeElement && document.activeElement === this.fieldRef.current) {
+        const hostDocument = this.getHostDocument();
+        if (releaseFocus && hostDocument.activeElement && hostDocument.activeElement === this.fieldRef.current) {
             this.fieldRef.current.blur();
         }
     }
@@ -346,7 +406,9 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
             return;
         }
 
-        const shellArea = document.getElementById('theia-app-shell')!.getBoundingClientRect();
+        // Secondary windows have no 'theia-app-shell' element; use the document element as the boundary there.
+        const hostDocument = this.getHostDocument();
+        const shellArea = (hostDocument.getElementById('theia-app-shell') ?? hostDocument.documentElement).getBoundingClientRect();
         const maxWidth = this.alignLeft ? shellArea.width - this.state.dimensions.left : this.state.dimensions.right;
         if (this.mountedListeners.size === 0) {
             // Only attach our listeners once we render our dropdown menu
@@ -401,17 +463,21 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
             return <div key={index} className="theia-select-component-separator" />;
         }
         const selected = this.state.hover;
+        const disabled = !!option.disabled;
         return (
             <div
                 key={index}
-                className={`theia-select-component-option${index === selected ? ' selected' : ''}`}
+                data-option-index={index}
+                className={`theia-select-component-option${index === selected ? ' selected' : ''}${disabled ? ' disabled' : ''}`}
                 onMouseOver={() => {
                     this.setState({
                         hover: index
                     });
                 }}
                 onMouseDown={() => {
-                    this.selectOption(index, option);
+                    if (!disabled) {
+                        this.selectOption(index, option);
+                    }
                 }}
             >
                 <div key="value" className="theia-select-component-option-value">{option.label ?? option.value}</div>

package/src/browser/widgets/tab-bar-tracker.spec.ts

@@ -0,0 +1,121 @@
+// *****************************************************************************
+// Copyright (C) 2026 JuliaHub, Inc. and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { enableJSDOM } from '../test/jsdom';
+let disableJSDOM = enableJSDOM();
+
+import { expect } from 'chai';
+import { MessageLoop } from '@lumino/messaging';
+import { DockPanel, TabBar, Widget } from '@lumino/widgets';
+import { TabBarTracker } from './tab-bar-tracker';
+
+disableJSDOM();
+
+describe('TabBarTracker', () => {
+
+    before(() => {
+        disableJSDOM = enableJSDOM();
+    });
+
+    after(() => {
+        disableJSDOM();
+    });
+
+    let panel: DockPanel | undefined;
+
+    afterEach(() => {
+        if (panel) {
+            Widget.detach(panel);
+            panel.dispose();
+            panel = undefined;
+        }
+    });
+
+    function attachInDockPanel(): Widget {
+        panel = new DockPanel();
+        Widget.attach(panel, document.body);
+        const widget = new Widget();
+        panel.addWidget(widget);
+        MessageLoop.flush();
+        return widget;
+    }
+
+    it('reports the enclosing tab-bar on the first check', () => {
+        const widget = attachInDockPanel();
+        const events: Array<[TabBar<Widget> | undefined, TabBar<Widget> | undefined]> = [];
+        const tracker = new TabBarTracker(widget, (oldTabBar, newTabBar) => events.push([oldTabBar, newTabBar]));
+        tracker.check();
+        expect(events).lengthOf(1);
+        expect(events[0][0]).undefined;
+        expect(events[0][1]).not.undefined;
+    });
+
+    it('does not report again when the tab-bar has not changed', () => {
+        const widget = attachInDockPanel();
+        let count = 0;
+        const tracker = new TabBarTracker(widget, () => count++);
+        tracker.check();
+        tracker.check();
+        expect(count).equal(1);
+    });
+
+    it('does nothing when the widget is not inside a DockPanel', () => {
+        let count = 0;
+        const tracker = new TabBarTracker(new Widget(), () => count++);
+        tracker.check();
+        expect(count).equal(0);
+    });
+
+    it('stops reporting once disposed', () => {
+        const widget = attachInDockPanel();
+        let count = 0;
+        const tracker = new TabBarTracker(widget, () => count++);
+        tracker.dispose();
+        tracker.check();
+        expect(count).equal(0);
+    });
+
+    it('reports a move between two tab-bars', () => {
+        panel = new DockPanel();
+        Widget.attach(panel, document.body);
+        const other = new Widget();
+        const widget = new Widget();
+        panel.addWidget(other);
+        panel.addWidget(widget, { mode: 'split-right', ref: other });
+        MessageLoop.flush();
+        const events: Array<[TabBar<Widget> | undefined, TabBar<Widget> | undefined]> = [];
+        const tracker = new TabBarTracker(widget, (oldTabBar, newTabBar) => events.push([oldTabBar, newTabBar]));
+        tracker.check();
+        panel.addWidget(widget, { mode: 'tab-after', ref: other });
+        MessageLoop.flush();
+        tracker.check();
+        expect(events).lengthOf(2);
+        expect(events[1][0]).not.undefined;
+        expect(events[1][0]).not.equal(events[1][1]);
+    });
+
+    it('re-reports the current tab-bar after reset', () => {
+        const widget = attachInDockPanel();
+        const events: Array<[TabBar<Widget> | undefined, TabBar<Widget> | undefined]> = [];
+        const tracker = new TabBarTracker(widget, (oldTabBar, newTabBar) => events.push([oldTabBar, newTabBar]));
+        tracker.check();
+        tracker.reset();
+        tracker.check();
+        expect(events).lengthOf(2);
+        expect(events[1][0]).undefined;
+        expect(events[1][1]).not.undefined;
+    });
+});

package/src/browser/widgets/tab-bar-tracker.ts

@@ -0,0 +1,68 @@
+// *****************************************************************************
+// Copyright (C) 2026 JuliaHub, Inc. and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { find } from '@lumino/algorithm';
+import { DockPanel, TabBar, Widget } from '@lumino/widgets';
+import { Disposable, DisposableCollection } from '../../common';
+
+/**
+ * Detects when a widget is moved between the tab-bars of its enclosing {@link DockPanel} and
+ * notifies a callback with the previous and current tab-bar. Call {@link check} from the host
+ * widget's `onAfterAttach`.
+ */
+export class TabBarTracker implements Disposable {
+
+    protected currentTabBar: TabBar<Widget> | undefined;
+    protected isDisposed = false;
+    protected readonly toDisposeOnTabBarChange = new DisposableCollection();
+
+    constructor(
+        protected readonly widget: Widget,
+        protected readonly onTabBarChange: (oldTabBar?: TabBar<Widget>, newTabBar?: TabBar<Widget>) => void
+    ) { }
+
+    check(): void {
+        if (this.isDisposed) {
+            return;
+        }
+        const parent = this.widget.parent;
+        if (parent instanceof DockPanel) {
+            const newTabBar = find(parent.tabBars(), tabBar => !!tabBar.titles.find(title => title === this.widget.title));
+            if (this.currentTabBar !== newTabBar) {
+                this.toDisposeOnTabBarChange.dispose();
+                const listener = () => this.check();
+                parent.layoutModified.connect(listener);
+                this.toDisposeOnTabBarChange.push(Disposable.create(() => parent.layoutModified.disconnect(listener)));
+                const last = this.currentTabBar;
+                this.currentTabBar = newTabBar;
+                this.onTabBarChange(last, newTabBar);
+            }
+        }
+    }
+
+    /**
+     * Forgets the current tab-bar so that the next {@link check} reports it again as
+     * `(undefined, currentTabBar)`. Listeners on the enclosing panel stay connected.
+     */
+    reset(): void {
+        this.currentTabBar = undefined;
+    }
+
+    dispose(): void {
+        this.isDisposed = true;
+        this.toDisposeOnTabBarChange.dispose();
+    }
+}

package/src/browser/window/default-secondary-window-service.ts

@@ -28,6 +28,8 @@ import { WindowFocusService } from './window-focus-service';
 export class DefaultSecondaryWindowService implements SecondaryWindowService {
     protected readonly onWindowOpenedEmitter = new Emitter<Window>;
     readonly onWindowOpened: Event<Window> = this.onWindowOpenedEmitter.event;
+    protected readonly onWindowLoadedEmitter = new Emitter<Window>;
+    readonly onWindowLoaded: Event<Window> = this.onWindowLoadedEmitter.event;
     protected readonly onWindowClosedEmitter = new Emitter<Window>;
     readonly onWindowClosed: Event<Window> = this.onWindowClosedEmitter.event;
     protected readonly beforeWidgetRestoreEmitter = new Emitter<[Widget, Window]>;
@@ -110,6 +112,10 @@ export class DefaultSecondaryWindowService implements SecondaryWindowService {
             this.secondaryWindows.push(newWindow);
             this.onWindowOpenedEmitter.fire(newWindow);
             newWindow.addEventListener('DOMContentLoaded', () => {
+                // This fires for the final secondary-window.html document, not for the initial
+                // about:blank document the window starts out with, so onWindowLoaded listeners
+                // can safely modify the document.
+                this.onWindowLoadedEmitter.fire(newWindow);
                 const focusRegistration = this.windowFocusService.registerWindow(newWindow);
                 newWindow.addEventListener('beforeunload', evt => {
                     const widgets = getAllWidgetsFromSecondaryWindow(newWindow) ?? [widget];
@@ -124,7 +130,7 @@ export class DefaultSecondaryWindowService implements SecondaryWindowService {
                     }
                 }, { capture: true });
 
-                newWindow.addEventListener('unload', () => {
+                newWindow.addEventListener('pagehide', () => {
                     focusRegistration.dispose();
                     const extIndex = this.secondaryWindows.indexOf(newWindow);
                     if (extIndex > -1) {
@@ -140,7 +146,7 @@ export class DefaultSecondaryWindowService implements SecondaryWindowService {
     }
 
     protected windowCreated(newWindow: Window, widget: ExtractableWidget, shell: ApplicationShell): void {
-        newWindow.addEventListener('unload', () => {
+        newWindow.addEventListener('pagehide', () => {
             this.restoreWidgets(newWindow, widget, shell);
         });
     }

package/src/browser/window/default-window-service.spec.ts

@@ -77,4 +77,26 @@ describe('DefaultWindowService', () => {
         assert(windowService['collectContributionUnloadVetoes']().length > 0, 'there should be vetoes');
         assert(frontendContributions.every(contribution => contribution.onWillStopCalled), 'contributions should have been called');
     });
+    it('should reload unconditionally when restored from the back/forward cache', () => {
+        const frontendContributions: TestFrontendApplicationContribution[] = [
+            new TestFrontendApplicationContribution(true),
+        ];
+        const windowService = setupWindowService('always', frontendContributions);
+        let reloaded = 0;
+        windowService.reload = () => { reloaded++; };
+        windowService['handlePageShow']({ persisted: false } as PageTransitionEvent);
+        const reloadsBeforeRestore = reloaded;
+        windowService['handlePageShow']({ persisted: true } as PageTransitionEvent);
+        assert(reloadsBeforeRestore === 0, 'a regular page show should not reload');
+        assert(reloaded === 1, 'a restored page should reload');
+        assert(windowService['collectContributionUnloadVetoes']().length === 0, 'the recovery reload should not be vetoed');
+    });
+    it('onUnload should fire at most once, even if `pagehide` fires repeatedly', () => {
+        const windowService = setupWindowService('never', []);
+        let fired = 0;
+        windowService.onUnload(() => fired++);
+        windowService['handlePageHide']();
+        windowService['handlePageHide']();
+        assert(fired === 1, `onUnload should have fired once, but fired ${fired} time(s)`);
+    });
 });

package/src/browser/window/default-window-service.ts

@@ -30,6 +30,7 @@ export class DefaultWindowService implements WindowService, FrontendApplicationC
 
     protected frontendApplication: FrontendApplication;
     protected allowVetoes = true;
+    protected unloaded = false;
 
     protected onUnloadEmitter = new Emitter<void>();
     get onUnload(): Event<void> {
@@ -103,12 +104,43 @@ export class DefaultWindowService implements WindowService, FrontendApplicationC
      * Implement the mechanism to detect unloading of the page.
      */
     protected registerUnloadListeners(): void {
+        // If `beforeunload` is cancelled and the user stays, the page is not unloaded, so `pagehide` is not fired.
         window.addEventListener('beforeunload', event => this.handleBeforeUnloadEvent(event));
-        // In a browser, `unload` is correctly fired when the page unloads, unlike Electron.
-        // If `beforeunload` is cancelled, the user will be prompted to leave or stay.
-        // If the user stays, the page won't be unloaded, so `unload` is not fired.
-        // If the user leaves, the page will be unloaded, so `unload` is fired.
-        window.addEventListener('unload', () => this.onUnloadEmitter.fire());
+        this.registerPageHideListener();
+        window.addEventListener('pageshow', event => this.handlePageShow(event));
+    }
+
+    /**
+     * `pagehide` is used instead of the deprecated `unload` event, which Chrome may block
+     * via permissions policy (https://developer.chrome.com/docs/web-platform/deprecating-unload),
+     * silently skipping the handler and thus e.g. losing the layout.
+     */
+    protected registerPageHideListener(): void {
+        window.addEventListener('pagehide', () => this.handlePageHide());
+    }
+
+    /**
+     * `pagehide` also fires when the page enters the back/forward cache, in which case the frontend
+     * has already shut down (state saved, connections closed). Reload to get a working application
+     * again if the page is restored from the cache. That shutdown already happened, so the reload
+     * must not be vetoed by the contributions.
+     */
+    protected handlePageShow(event: PageTransitionEvent): void {
+        if (event.persisted) {
+            this.setSafeToShutDown();
+            this.reload();
+        }
+    }
+
+    /**
+     * Fires {@link onUnload} at most once per document: `pagehide` fires again for the reload that
+     * recovers a page restored from the back/forward cache, but the application is already stopped.
+     */
+    protected handlePageHide(): void {
+        if (!this.unloaded) {
+            this.unloaded = true;
+            this.onUnloadEmitter.fire();
+        }
     }
 
     async isSafeToShutDown(stopReason: StopReason): Promise<boolean> {

package/src/browser/window/secondary-window-service.ts

@@ -55,6 +55,13 @@ export interface SecondaryWindowService {
      */
     createSecondaryWindow(widget: ExtractableWidget, shell: ApplicationShell): SecondaryWindow | Window | undefined;
     readonly onWindowOpened: Event<Window>;
+    /**
+     * Emitted once a secondary window's final document has finished loading. Listeners can safely
+     * modify the window's document, unlike with {@link onWindowOpened}: at that point the window
+     * still shows the initial `about:blank` document, and anything added to it is discarded when
+     * the final document replaces it.
+     */
+    readonly onWindowLoaded: Event<Window>;
     readonly onWindowClosed: Event<Window>;
     readonly beforeWidgetRestore: Event<[Widget, Window]>;
 

package/src/browser/window/window-service.ts

@@ -56,7 +56,7 @@ export interface WindowService {
     focus(): void;
 
     /**
-     * Fires when the `window` unloads. The unload event is inevitable. On this event, the frontend application can save its state and release resource.
+     * Fires when the application is shutting down. On this event, the frontend application can save its state and release resource.
      * Saving the state and releasing any resources must be a synchronous call. Any asynchronous calls invoked after emitting this event might be ignored.
      */
     readonly onUnload: Event<void>;

package/src/browser-only/messaging/frontend-only-service-connection-provider.ts

@@ -24,6 +24,33 @@ export class FrontendOnlyConnectionSource implements ConnectionSource {
     onConnectionDidOpen = new Emitter<Channel>().event;
 }
 
+/**
+ * Proxy factory for services without a frontend-only implementation. There is no backend,
+ * so no channel will ever open and requests would otherwise be queued forever, blocking
+ * any caller that awaits the result, e.g. during application startup.
+ * Instead, requests fail immediately and notifications (fire-and-forget) resolve silently.
+ */
+export class FrontendOnlyRpcProxyFactory<T extends object> extends RpcProxyFactory<T> {
+
+    constructor(protected readonly path: string, target?: object) {
+        super(target);
+    }
+
+    override get(target: T, p: PropertyKey, receiver: unknown): unknown {
+        if (typeof p !== 'string') {
+            return undefined;
+        }
+        // members handled by the base proxy without a connection
+        if (['setClient', 'getClient', 'onDidOpenConnection', 'onDidCloseConnection', 'then', 'toJSON'].includes(p)) {
+            return super.get(target, p, receiver);
+        }
+        if (this.isNotification(p)) {
+            return () => Promise.resolve();
+        }
+        return () => Promise.reject(new Error(`Request '${p}' on service '${this.path}' is unavailable: no backend in frontend-only mode.`));
+    }
+}
+
 @injectable()
 export class FrontendOnlyServiceConnectionProvider extends ServiceConnectionProvider {
 
@@ -33,10 +60,12 @@ export class FrontendOnlyServiceConnectionProvider extends ServiceConnectionProv
     onSocketDidOpen = Event.None;
     onSocketDidClose = Event.None;
     onIncomingMessageActivity = Event.None;
-    override createProxy<T extends object>(path: unknown, target?: unknown): RpcProxy<T> {
+    override createProxy<T extends object>(path: string, target?: object): RpcProxy<T> {
         this.logger.debug(`[Frontend-Only Fallback] Created proxy connection for ${path}`);
-        const factory = target instanceof RpcProxyFactory ? target : new RpcProxyFactory<T>(target);
-        return factory.createProxy();
+        if (target instanceof RpcProxyFactory) {
+            return target.createProxy();
+        }
+        return new FrontendOnlyRpcProxyFactory<T>(path, target).createProxy();
     }
     override listen(path: string, handler: ServiceConnectionProvider.ConnectionHandler, reconnect: boolean): void {
         this.logger.debug('[Frontend-Only Fallback] Listen to websocket connection requested');