Implements welcome overlay over Homve View for new users in Cursor

and other IDEs without walkthrough support.

Adds a welcome overlay to the home webview for new users to improve the first-time user experience. The overlay is displayed only on the first install and when the walkthrough is not supported. It can be dismissed, and its state is persisted.

(#4769, #4773, PLG-138)

Author: sergeibbb

src/extension.ts

@@ -366,11 +366,11 @@ async function showWhatsNew(
 	if (previousVersion == null) {
 		Logger.log(`GitLens first-time install; window.focused=${window.state.focused}`);
 
-		// Show welcome webview on first install for IDEs that don't support walkthroughs (e.g., Cursor)
-		// For IDEs that support walkthroughs, the walkthrough will be shown instead
-		if (window.state.focused && !container.walkthrough.isWalkthroughSupported) {
-			void executeCommand('gitlens.showWelcomePage');
-		}
+		// // Show welcome webview on first install for IDEs that don't support walkthroughs (e.g., Cursor)
+		// // For IDEs that support walkthroughs, the walkthrough will be shown instead
+		// if (window.state.focused && !container.walkthrough.isWalkthroughSupported) {
+		// 	void executeCommand('gitlens.showWelcomePage');
+		// }
 
 		return;
 	}

src/webviews/apps/home/components/welcome-overlay.ts

@@ -0,0 +1,74 @@
+import { consume } from '@lit/context';
+import { css, html, LitElement, nothing } from 'lit';
+import { customElement, state } from 'lit/decorators.js';
+import type { State } from '../../../home/protocol';
+import { CollapseSectionCommand } from '../../../home/protocol';
+import { ipcContext } from '../../shared/contexts/ipc';
+import type { HostIpc } from '../../shared/ipc';
+import { stateContext } from '../context';
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'gl-welcome-overlay': GlWelcomeOverlay;
+	}
+}
+
+@customElement('gl-welcome-overlay')
+export class GlWelcomeOverlay extends LitElement {
+	static override shadowRootOptions: ShadowRootInit = {
+		...LitElement.shadowRootOptions,
+		delegatesFocus: true,
+	};
+
+	static override styles = [
+		css`
+			.overlay {
+				position: fixed;
+				top: 0;
+				left: 0;
+				right: 0;
+				bottom: 0;
+				z-index: 1000;
+				display: flex;
+				align-items: center;
+				justify-content: center;
+				background-color: #007acc;
+				color: white;
+			}
+		`,
+	];
+
+	@consume<State>({ context: stateContext, subscribe: true })
+	@state()
+	private _state!: State;
+
+	@consume<HostIpc>({ context: ipcContext, subscribe: true })
+	@state()
+	private _ipc!: HostIpc;
+
+	@state()
+	private closed = false;
+
+	override render(): unknown {
+		const { welcomeOverlayCollapsed, walkthroughSupported, newInstall } = this._state;
+		if (this.closed || welcomeOverlayCollapsed || walkthroughSupported || !newInstall) {
+			return nothing;
+		}
+
+		return html`
+			<div class="overlay">
+				<h1 class="title">Welcome!!!</h1>
+				<button class="close-button" @click=${() => this.onClose()}>Dismiss</button>
+			</div>
+		`;
+	}
+
+	private onClose() {
+		this.closed = true;
+
+		this._ipc.sendCommand(CollapseSectionCommand, {
+			section: 'welcomeOverlay',
+			collapsed: true,
+		});
+	}
+}

src/webviews/apps/home/home.ts

@@ -29,6 +29,7 @@ import './components/ai-all-access-banner';
 import './components/ama-banner';
 import './components/integration-banner';
 import './components/preview-banner';
+import './components/welcome-overlay';
 import '../shared/components/mcp-banner';
 import './components/repo-alerts';
 import '../shared/components/banner/banner';
@@ -111,6 +112,7 @@ export class GlHomeApp extends GlAppHost<State> {
 						`,
 					)}
 				</main>
+				<gl-welcome-overlay></gl-welcome-overlay>
 			</div>
 		`;
 	}

src/webviews/home/homeWebview.ts

@@ -803,6 +803,10 @@ export class HomeWebviewProvider implements WebviewProvider<State, State, HomeWe
 		return this.container.storage.get('home:walkthrough:dismissed') ?? false;
 	}
 
+	private getWelcomeOverlayCollapsed() {
+		return this.container.storage.get('home:sections:collapsed')?.includes('welcomeOverlay') ?? false;
+	}
+
 	private getPreviewCollapsed() {
 		return this.container.storage.get('home:sections:collapsed')?.includes('newHomePreview') ?? false;
 	}
@@ -922,6 +926,7 @@ export class HomeWebviewProvider implements WebviewProvider<State, State, HomeWe
 			amaBannerCollapsed: this.getAmaBannerCollapsed(),
 			mcpBannerCollapsed: this.getMcpBannerCollapsed(),
 			mcpCanAutoRegister: this.getMcpCanAutoRegister(),
+			welcomeOverlayCollapsed: this.getWelcomeOverlayCollapsed(),
 		};
 	}
 

src/webviews/home/protocol.ts

@@ -52,6 +52,7 @@ export interface State extends WebviewState<'gitlens.views.home'> {
 	previewEnabled: boolean;
 	newInstall: boolean;
 	amaBannerCollapsed: boolean;
+	welcomeOverlayCollapsed: boolean;
 }
 
 export interface IntegrationState extends IntegrationDescriptor {