@codingame/monaco-vscode-welcome-service-override 36.2.7 → 37.1.0

package/vscode/src/vs/workbench/contrib/onboarding/browser/spotlight/spotlightOverlay.js

@@ -33,6 +33,7 @@ class SpotlightOverlay extends Disposable {
         this._onDidSkip = this._register(( new Emitter()));
         this.onDidSkip = this._onDidSkip.event;
         this._options = {};
+        this._hasShown = false;
         this._root = append(this._container, $(".spotlight-overlay"));
         this._root.style.display = "none";
         this._blockers = [
@@ -63,8 +64,8 @@ class SpotlightOverlay extends Disposable {
             ...defaultButtonStyles,
             secondary: true
         })));
-        this._skipButton.label = ( localize(12888, "End Tour"));
-        this._skipButton.setTitle(( localize(12889, "End Tour (Esc)")));
+        this._skipButton.label = ( localize(14872, "End Tour"));
+        this._skipButton.setTitle(( localize(14873, "End Tour (Esc)")));
         this._register(
             this._skipButton.onDidClick(() => this._onDidSkip.fire(OnboardingDismissReason.SkipButton))
         );
@@ -72,12 +73,12 @@ class SpotlightOverlay extends Disposable {
             ...defaultButtonStyles,
             secondary: true
         })));
-        this._backButton.label = ( localize(12890, "Back"));
+        this._backButton.label = ( localize(14874, "Back"));
         this._register(this._backButton.onDidClick(() => this._onDidClickPrevious.fire()));
         this._nextButton = this._register(( new Button(actions, {
             ...defaultButtonStyles
         })));
-        this._nextButton.label = ( localize(12891, "Next"));
+        this._nextButton.label = ( localize(14875, "Next"));
         this._register(this._nextButton.onDidClick(() => this._onDidClickNext.fire("button")));
         for (const button of [this._skipButton, this._backButton, this._nextButton]) {
             this._register(
@@ -92,13 +93,16 @@ class SpotlightOverlay extends Disposable {
         });
     }
     show(target, content, options = {}) {
-        const isFirstShow = this._root.style.display === "none";
-        if (isFirstShow) {
+        if (!this._hasShown) {
+            this._hasShown = true;
             this._previousFocus = isHTMLElement(getActiveElement()) ? getActiveElement() : undefined;
         }
         this._target = target;
         this._options = options;
         this._renderContent(content);
+        const externalUiParticipates = !!options.targetOverlayVisible || !!options.allowTargetInteraction || !!options.advanceOnTargetClick || !!options.hideNext;
+        this._root.classList.toggle("target-overlay-visible", externalUiParticipates);
+        this._callout.setAttribute("aria-modal", externalUiParticipates ? "false" : "true");
         this._root.style.display = "";
         this._stepListeners.clear();
         const targetWindow = getWindow(this._container);
@@ -119,15 +123,45 @@ class SpotlightOverlay extends Disposable {
             this._scheduledLayout = undefined;
         }));
         const advanceOnTargetClick = !!options.advanceOnTargetClick;
-        this._nextButton.element.style.display = advanceOnTargetClick ? "none" : "";
+        const advanceOnly = options.advanceOnTargetClick === "advanceOnly";
+        const hideNext = options.hideNext ?? advanceOnTargetClick;
+        this._nextButton.element.style.display = hideNext ? "none" : "";
         if (advanceOnTargetClick) {
-            this._stepListeners.add(
-                addDisposableListener(target, EventType.CLICK, () => this._onDidClickNext.fire("target"))
-            );
+            this._stepListeners.add(addDisposableListener(target, EventType.CLICK, event => {
+                if (advanceOnly) {
+                    event.preventDefault();
+                    event.stopImmediatePropagation();
+                }
+                this._onDidClickNext.fire("target");
+            }, advanceOnly));
+        }
+        if (advanceOnly) {
+            const onTargetKey = event => {
+                const key = ( new StandardKeyboardEvent(event));
+                if (key.equals(KeyCode.Enter) || key.equals(KeyCode.Space)) {
+                    event.preventDefault();
+                    event.stopImmediatePropagation();
+                    if (event.type === EventType.KEY_UP) {
+                        this._onDidClickNext.fire("target");
+                    }
+                } else if (event.type === EventType.KEY_DOWN) {
+                    this._onKeyDown(event);
+                }
+            };
+            this._stepListeners.add(addDisposableListener(target, EventType.KEY_DOWN, onTargetKey, true));
+            this._stepListeners.add(addDisposableListener(target, EventType.KEY_UP, onTargetKey, true));
+        } else if (options.allowTargetInteraction || advanceOnTargetClick || options.hideNext) {
             this._stepListeners.add(addDisposableListener(target, EventType.KEY_DOWN, e => this._onKeyDown(e)));
         }
         this.layout();
-        (advanceOnTargetClick ? target : this._nextButton.element).focus();
+        (hideNext ? target : this._nextButton.element).focus();
+    }
+    hide() {
+        this._stepListeners.clear();
+        this._root.style.display = "none";
+        this._root.classList.remove("target-overlay-visible");
+        this._target = undefined;
+        this._options = {};
     }
     layout() {
         const target = this._target;
@@ -311,9 +345,10 @@ class SpotlightOverlay extends Disposable {
         } else {
             this._description.textContent = content.description;
         }
-        this._counter.textContent = ( localize(12892, "{0} of {1}", content.stepIndex + 1, content.stepCount));
+        this._counter.textContent = content.stepCount > 1 ? ( localize(14876, "{0} of {1}", content.stepIndex + 1, content.stepCount)) : "";
+        this._skipButton.element.style.display = content.isLastStep ? "none" : "";
         this._backButton.element.style.display = content.canGoBack ? "" : "none";
-        this._nextButton.label = content.isLastStep ? ( localize(12893, "Done")) : ( localize(12891, "Next"));
+        this._nextButton.label = content.nextButtonLabel ?? (content.isLastStep ? ( localize(14877, "Done")) : ( localize(14875, "Next")));
     }
     _onKeyDown(e) {
         const event = ( new StandardKeyboardEvent(e));
@@ -346,14 +381,24 @@ class SpotlightOverlay extends Disposable {
         focusable[nextIndex].focus();
     }
     _collectFocusable() {
-        const target = (this._options.advanceOnTargetClick && this._target) ? [this._target] : [];
+        const targetFocusables =
+        (this._options.allowTargetInteraction || this._options.advanceOnTargetClick || this._options.hideNext) && this._target ? [this._target, ...this._target.querySelectorAll(
+            "a[href], button, input, select, textarea, [tabindex]:not([tabindex=\"-1\"])"
+        )] : [];
         const descriptionFocusables = Array.from(
             this._description.querySelectorAll(
                 "a[href], button, input, select, textarea, [tabindex]:not([tabindex=\"-1\"])"
             )
         );
         const buttons = ( [this._skipButton, this._backButton, this._nextButton].filter(button => button.element.style.display !== "none").map(button => button.element));
-        return [...target, ...descriptionFocusables, ...buttons];
+        return [...targetFocusables, ...descriptionFocusables, ...buttons].filter(element => this._isTabbable(element));
+    }
+    _isTabbable(element) {
+        if (!element.isConnected || element.getAttribute("aria-hidden") === "true" || element.tabIndex === -1 || element.hasAttribute("disabled")) {
+            return false;
+        }
+        const style = getWindow(this._container).getComputedStyle(element);
+        return style.display !== "none" && style.visibility !== "hidden";
     }
     scheduleLayout() {
         if (this._scheduledLayout) {

package/vscode/src/vs/workbench/contrib/onboarding/browser/spotlight/spotlightPresentation.d.ts

@@ -4,19 +4,23 @@ import { IWorkbenchLayoutService } from "@codingame/monaco-vscode-api/vscode/vs/
 import { IHostService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/host/browser/host.service";
 import { IOnboardingPresentation, IOnboardingRunContext } from "../../common/onboardingPresentation.js";
 import { IOnboardingRunResult, IOnboardingScenario } from "../../common/onboardingScenario.js";
+import { IOnboardingSequenceStep, IOnboardingSequenceStepContext, IOnboardingSequenceStepPresentation, IOnboardingSequenceStepResult } from "../../common/onboardingSequence.js";
 /**
  * Renders {@link ISpotlightPayload} scenarios: it dims the window (including the
  * native window controls), walks the steps, and shows an anchored callout for
  * each. Implements the engine's {@link IOnboardingPresentation} contract so the
  * scenario engine can drive it without knowing anything about spotlights.
  */
-export declare class SpotlightPresentation extends Disposable implements IOnboardingPresentation {
+export declare class SpotlightPresentation extends Disposable implements IOnboardingPresentation, IOnboardingSequenceStepPresentation {
     private readonly layoutService;
     private readonly hostService;
     private readonly contextKeyService;
     readonly kind = "spotlight";
+    readonly countsAsVisualStep = true;
     constructor(layoutService: IWorkbenchLayoutService, hostService: IHostService, contextKeyService: IContextKeyService);
     run(scenario: IOnboardingScenario, context: IOnboardingRunContext): Promise<IOnboardingRunResult>;
+    runStep(sequenceStep: IOnboardingSequenceStep, context: IOnboardingSequenceStepContext): Promise<IOnboardingSequenceStepResult>;
+    private _runPayload;
     private _resolveTarget;
     private _waitForTargetReady;
     private _getActiveFiniteAnimations;

package/vscode/src/vs/workbench/contrib/onboarding/browser/spotlight/spotlightPresentation.js

@@ -1,13 +1,14 @@
 
 import { __decorate, __param } from '@codingame/monaco-vscode-api/external/tslib/tslib.es6';
 import { timeout } from '@codingame/monaco-vscode-api/vscode/vs/base/common/async';
+import { CancellationTokenSource } from '@codingame/monaco-vscode-api/vscode/vs/base/common/cancellation';
 import { onUnexpectedError } from '@codingame/monaco-vscode-api/vscode/vs/base/common/errors';
 import { Disposable, DisposableStore, toDisposable } from '@codingame/monaco-vscode-api/vscode/vs/base/common/lifecycle';
 import { IContextKeyService } from '@codingame/monaco-vscode-api/vscode/vs/platform/contextkey/common/contextkey.service';
 import { IWorkbenchLayoutService } from '@codingame/monaco-vscode-api/vscode/vs/workbench/services/layout/browser/layoutService.service';
 import { IHostService } from '@codingame/monaco-vscode-api/vscode/vs/workbench/services/host/browser/host.service';
 import { OnboardingDismissReason, OnboardingOutcome } from '../../common/onboardingScenario.js';
-import { findOnboardingTarget } from './onboardingTarget.js';
+import { findOnboardingTarget, openOnboardingTarget } from './onboardingTarget.js';
 import { SpotlightOverlay } from './spotlightOverlay.js';
 import { SPOTLIGHT_PRESENTATION_KIND } from './spotlightTypes.js';
 
@@ -21,9 +22,102 @@ let SpotlightPresentation = class SpotlightPresentation extends Disposable {
         this.hostService = hostService;
         this.contextKeyService = contextKeyService;
         this.kind = SPOTLIGHT_PRESENTATION_KIND;
+        this.countsAsVisualStep = true;
     }
     async run(scenario, context) {
         const payload = scenario.presentation.payload;
+        return this._runPayload(payload, context);
+    }
+    async runStep(sequenceStep, context) {
+        const step = sequenceStep.payload;
+        if (step.when && !this.contextKeyService.contextMatchesRules(step.when)) {
+            return {
+                action: "skipStep",
+                shown: false
+            };
+        }
+        try {
+            await step.onBeforeShow?.();
+        } catch (error) {
+            onUnexpectedError(error);
+        }
+        if (context.cancellationToken.isCancellationRequested) {
+            return {
+                action: "abort",
+                shown: false
+            };
+        }
+        const target = await this._resolveTarget(
+            context.targetWindow,
+            step.targetId,
+            context.cancellationToken,
+            step.missingTarget
+        );
+        if (!target) {
+            return context.cancellationToken.isCancellationRequested || step.missingTarget?.kind === "abort" ? {
+                action: "abort",
+                shown: false
+            } : {
+                action: "skipStep",
+                shown: false
+            };
+        }
+        await this._waitForTargetReady(context.targetWindow, target);
+        if (context.cancellationToken.isCancellationRequested) {
+            return {
+                action: "abort",
+                shown: false
+            };
+        }
+        const store = ( new DisposableStore());
+        try {
+            const container = this.layoutService.getContainer(context.targetWindow);
+            const overlay = store.add(( new SpotlightOverlay(container)));
+            this.hostService.setWindowDimmed(context.targetWindow, true);
+            store.add(
+                toDisposable(() => this.hostService.setWindowDimmed(context.targetWindow, false))
+            );
+            store.add(this.layoutService.onDidLayoutContainer(() => overlay.scheduleLayout()));
+            const end = await this._runStep(
+                overlay,
+                context,
+                step,
+                target,
+                context.visualStepIndex,
+                context.visualStepCount,
+                context.canGoBack,
+                context.isLastVisualStep
+            );
+            overlay.hide();
+            switch (end.action) {
+            case "next":
+                return {
+                    action: "next",
+                    shown: true,
+                    dismissReason: end.via === "target" ? OnboardingDismissReason.TargetClick : OnboardingDismissReason.Completed
+                };
+            case "back":
+                return {
+                    action: "back",
+                    shown: true
+                };
+            case "skip":
+                return {
+                    action: "skipSequence",
+                    shown: true,
+                    dismissReason: end.reason
+                };
+            case "abort":
+                return {
+                    action: "abort",
+                    shown: true
+                };
+            }
+        } finally {
+            store.dispose();
+        }
+    }
+    async _runPayload(payload, context) {
         const steps = payload?.steps ?? [];
         const stepCount = steps.length;
         if (stepCount === 0) {
@@ -37,6 +131,7 @@ let SpotlightPresentation = class SpotlightPresentation extends Disposable {
         }
         let lastStepIndex = 0;
         let shown = false;
+        const skippedStepIndexes = ( new Set());
         const store = ( new DisposableStore());
         try {
             const container = this.layoutService.getContainer(context.targetWindow);
@@ -46,8 +141,10 @@ let SpotlightPresentation = class SpotlightPresentation extends Disposable {
                 toDisposable(() => this.hostService.setWindowDimmed(context.targetWindow, false))
             );
             let aborted = false;
+            const targetResolutionCancellation = store.add(( new CancellationTokenSource()));
             store.add(context.onAbort(() => {
                 aborted = true;
+                targetResolutionCancellation.cancel();
             }));
             store.add(this.layoutService.onDidLayoutContainer(() => overlay.scheduleLayout()));
             let index = 0;
@@ -55,6 +152,7 @@ let SpotlightPresentation = class SpotlightPresentation extends Disposable {
             while (index >= 0 && index < stepCount && !aborted) {
                 const step = steps[index];
                 if (step.when && !this.contextKeyService.contextMatchesRules(step.when)) {
+                    skippedStepIndexes.add(index);
                     index += direction;
                     continue;
                 }
@@ -66,21 +164,36 @@ let SpotlightPresentation = class SpotlightPresentation extends Disposable {
                 if (aborted) {
                     break;
                 }
-                const target = await this._resolveTarget(context.targetWindow, step.targetId);
+                const target = await this._resolveTarget(
+                    context.targetWindow,
+                    step.targetId,
+                    targetResolutionCancellation.token,
+                    step.missingTarget
+                );
                 if (aborted) {
                     break;
                 }
                 if (!target) {
+                    if (step.missingTarget?.kind === "abort") {
+                        aborted = true;
+                        break;
+                    }
+                    skippedStepIndexes.add(index);
                     index += direction;
                     continue;
                 }
+                skippedStepIndexes.delete(index);
                 await this._waitForTargetReady(context.targetWindow, target);
                 if (aborted) {
                     break;
                 }
                 lastStepIndex = Math.max(lastStepIndex, index);
                 shown = true;
-                const end = await this._runStep(overlay, context, step, target, index, stepCount);
+                const skippedBefore = Array.from(skippedStepIndexes).filter(skippedIndex => skippedIndex < index).length;
+                const displayStepIndex = index - skippedBefore;
+                const displayStepCount = stepCount - skippedStepIndexes.size;
+                const end = await this._runStep(overlay, context, step, target, displayStepIndex, displayStepCount);
+                overlay.hide();
                 switch (end.action) {
                 case "next":
                     if (index === stepCount - 1) {
@@ -118,13 +231,16 @@ let SpotlightPresentation = class SpotlightPresentation extends Disposable {
                     };
                 }
             }
-            return aborted ? {
-                outcome: OnboardingOutcome.Aborted,
-                shown,
-                dismissReason: OnboardingDismissReason.Aborted,
-                lastStepIndex,
-                stepCount
-            } : {
+            if (aborted) {
+                return {
+                    outcome: OnboardingOutcome.Aborted,
+                    shown,
+                    dismissReason: OnboardingDismissReason.Aborted,
+                    lastStepIndex,
+                    stepCount
+                };
+            }
+            return {
                 outcome: OnboardingOutcome.Completed,
                 shown,
                 dismissReason: OnboardingDismissReason.Completed,
@@ -135,11 +251,25 @@ let SpotlightPresentation = class SpotlightPresentation extends Disposable {
             store.dispose();
         }
     }
-    async _resolveTarget(targetWindow, targetId) {
-        const deadline = Date.now() + TARGET_RESOLVE_TIMEOUT;
+    async _resolveTarget(targetWindow, targetId, cancellationToken, behavior) {
+        if (cancellationToken.isCancellationRequested) {
+            return undefined;
+        }
         let element = findOnboardingTarget(targetWindow, targetId);
-        while (!element && Date.now() < deadline) {
-            await timeout(TARGET_POLL_INTERVAL);
+        if (element || behavior?.kind === "skip" || behavior?.kind === "abort") {
+            return element;
+        }
+        const timeoutMs = behavior?.kind === "wait" ? Math.max(0, behavior.timeoutMs) : TARGET_RESOLVE_TIMEOUT;
+        const deadline = Date.now() + timeoutMs;
+        while (!element && Date.now() < deadline && !cancellationToken.isCancellationRequested) {
+            try {
+                await timeout(TARGET_POLL_INTERVAL, cancellationToken);
+            } catch (error) {
+                if (cancellationToken.isCancellationRequested) {
+                    return undefined;
+                }
+                throw error;
+            }
             element = findOnboardingTarget(targetWindow, targetId);
         }
         return element;
@@ -162,42 +292,85 @@ let SpotlightPresentation = class SpotlightPresentation extends Disposable {
         }
         return animations;
     }
-    _runStep(overlay, context, step, target, index, stepCount) {
-        return ( new Promise(resolve => {
-            const stepStore = ( new DisposableStore());
-            const done = end => {
-                stepStore.dispose();
-                resolve(end);
-            };
-            stepStore.add(overlay.onDidClickNext(via => done({
-                action: "next",
-                via
-            })));
-            stepStore.add(overlay.onDidClickPrevious(() => done({
-                action: "back"
-            })));
-            stepStore.add(overlay.onDidSkip(reason => done({
-                action: "skip",
-                reason
-            })));
-            stepStore.add(context.onAbort(() => done({
-                action: "abort"
-            })));
-            const content = {
-                title: step.title,
-                description: step.description,
-                stepIndex: index,
-                stepCount,
-                canGoBack: index > 0,
-                isLastStep: index === stepCount - 1
+    async _runStep(
+        overlay,
+        context,
+        step,
+        target,
+        index,
+        stepCount,
+        canGoBack = index > 0,
+        isLastStep = index === stepCount - 1
+    ) {
+        const stepStore = ( new DisposableStore());
+        let ended = false;
+        let resolveStep;
+        const result = ( new Promise(resolve => resolveStep = resolve));
+        const done = end => {
+            if (ended) {
+                return;
+            }
+            ended = true;
+            stepStore.dispose();
+            resolveStep(end);
+        };
+        stepStore.add(overlay.onDidClickNext(via => done({
+            action: "next",
+            via
+        })));
+        stepStore.add(overlay.onDidClickPrevious(() => done({
+            action: "back"
+        })));
+        stepStore.add(overlay.onDidSkip(reason => done({
+            action: "skip",
+            reason
+        })));
+        stepStore.add(context.onAbort(() => done({
+            action: "abort"
+        })));
+        const content = {
+            title: step.title,
+            description: step.description,
+            nextButtonLabel: step.nextButtonLabel,
+            stepIndex: index,
+            stepCount,
+            canGoBack,
+            isLastStep
+        };
+        overlay.show(target, content, {
+            placement: step.placement,
+            allowTargetInteraction: step.allowTargetInteraction,
+            advanceOnTargetClick: step.advanceOnTargetClick,
+            hideNext: step.advanceWhen ? true : step.hideNext,
+            targetOverlayVisible: step.openTarget,
+            padding: step.padding
+        });
+        context.onDidShow?.();
+        if (step.advanceWhen) {
+            const keys = ( new Set(( step.advanceWhen.keys())));
+            const advanceIfSatisfied = () => {
+                if (this.contextKeyService.contextMatchesRules(step.advanceWhen)) {
+                    done({
+                        action: "next",
+                        via: "condition"
+                    });
+                }
             };
-            overlay.show(target, content, {
-                placement: step.placement,
-                allowTargetInteraction: step.allowTargetInteraction,
-                advanceOnTargetClick: step.advanceOnTargetClick,
-                padding: step.padding
-            });
-        }));
+            stepStore.add(this.contextKeyService.onDidChangeContext(event => {
+                if (event.affectsSome(keys)) {
+                    advanceIfSatisfied();
+                }
+            }));
+            advanceIfSatisfied();
+        }
+        if (step.openTarget && !ended) {
+            try {
+                await openOnboardingTarget(target);
+            } catch (error) {
+                onUnexpectedError(error);
+            }
+        }
+        return result;
     }
 };
 SpotlightPresentation = ( __decorate([( __param(0, IWorkbenchLayoutService)), ( __param(1, IHostService)), ( __param(2, IContextKeyService))], SpotlightPresentation));

package/vscode/src/vs/workbench/contrib/onboarding/browser/spotlight/spotlightTypes.d.ts

@@ -4,6 +4,17 @@ import { ContextKeyExpression } from "@codingame/monaco-vscode-api/vscode/vs/pla
 export declare const SPOTLIGHT_PRESENTATION_KIND = "spotlight";
 /** Preferred placement of the callout relative to the spotlighted target. */
 export type SpotlightPlacement = "above" | "below" | "left" | "right" | "auto";
+/** `advanceOnly` consumes target activation instead of running the target's action. */
+export type SpotlightTargetClickBehavior = boolean | "advanceOnly";
+/** Behavior when a spotlight target is not rendered when its step is reached. */
+export type SpotlightMissingTargetBehavior = {
+    readonly kind: "skip";
+} | {
+    readonly kind: "abort";
+} | {
+    readonly kind: "wait";
+    readonly timeoutMs: number;
+};
 /**
  * A single step in a spotlight tour. Steps are pure data; the spotlight
  * presentation turns them into the dim overlay, the cut-out highlight and the
@@ -22,17 +33,24 @@ export interface ISpotlightStep {
     readonly title: string;
     /** Callout body (localized string or markdown). */
     readonly description: string | IMarkdownString;
+    /** Localized primary button label, replacing the default Next or Done. */
+    readonly nextButtonLabel?: string;
     /** Preferred placement of the callout. Defaults to `'auto'`. */
     readonly placement?: SpotlightPlacement;
     /** When present and unsatisfied, the step is skipped. */
     readonly when?: ContextKeyExpression;
+    /** Defaults to waiting two seconds before skipping; `abort` ends the run immediately if the target is missing. */
+    readonly missingTarget?: SpotlightMissingTargetBehavior;
+    /** Opens or expands the target through its owner before the step begins. */
+    readonly openTarget?: boolean;
     /** Allow the spotlighted element to remain interactive. Defaults to `false`. */
     readonly allowTargetInteraction?: boolean;
-    /**
-     * When set, the step advances when the user clicks the spotlighted target
-     * itself (rather than a "Next" button). The target is kept interactive.
-     */
-    readonly advanceOnTargetClick?: boolean;
+    /** Advances on target activation; `advanceOnly` consumes the activation without running its action. */
+    readonly advanceOnTargetClick?: SpotlightTargetClickBehavior;
+    /** Overrides hiding Next when advancing on target clicks. `advanceWhen` always hides Next. */
+    readonly hideNext?: boolean;
+    /** Hides Next and advances once this context expression becomes satisfied. */
+    readonly advanceWhen?: ContextKeyExpression;
     /** Extra padding (px) around the target when cutting the highlight hole. */
     readonly padding?: number;
     /**

package/vscode/src/vs/workbench/contrib/onboarding/common/onboardingPresentation.d.ts

@@ -8,6 +8,10 @@ import { IOnboardingRunResult, IOnboardingScenario } from "./onboardingScenario.
 export interface IOnboardingRunContext {
     /** The window hosting the UI the scenario targets (usually the main window). */
     readonly targetWindow: Window;
+    /**
+     * Reports that the presentation rendered its first visible element. Called at most once per run.
+     */
+    readonly onDidShow?: () => void;
     /**
      * Fires when the engine wants the presentation to abort the current run
      * (e.g. the application is shutting down). The presentation should resolve

package/vscode/src/vs/workbench/contrib/onboarding/common/onboardingScenario.d.ts

@@ -39,17 +39,17 @@ export interface IOnboardingPresentationRef<TPayload = unknown> {
  * onboarding would be shown — otherwise the scorecard counts activity from before the
  * experiment could have had any effect.
  *
- * The treatment flags that tell the client *which* identifier belongs to a given tour resolve
+ * The treatment flags that tell the client *which* variant belongs to a given tour resolve
  * asynchronously, after the assignment context has already been committed to telemetry, so
  * they are too late to block the very first events. This prefix solves that race: because it
  * is a *static, well-known* string, the client can pre-emptively exclude **any**
  * assignment-context entry that starts with it from the very first event, and then
- * selectively unblock the one specific identifier once the user reaches the onboarding moment.
+ * selectively unblock the one specific variant once the user reaches the onboarding moment.
  *
  * ### Contract for experiment authors
- * - Every onboarding experiment configured in ExP MUST set its assignment-context identifier
- *   to a value beginning with this prefix.
- * - That same value MUST be returned by the experiment's
+ * - Every onboarding experiment configured in ExP MUST use variant names beginning with this
+ *   prefix.
+ * - Each arm's variant name MUST be returned by the experiment's
  *   {@link IOnboardingExperiment.assignmentContextIdFlag} treatment flag.
  *
  * The engine enforces this defensively: an id that lacks the prefix is rejected (the experiment
@@ -77,9 +77,8 @@ export interface IOnboardingExperiment {
      */
     readonly behaviorFlag: string;
     /**
-     * Name of the string treatment flag whose value is this experiment's assignment-context
-     * identifier — the exact entry that appears inside the telemetry `abexp.assignmentcontext`
-     * property and that the scorecard keys on. The value MUST start with
+     * Name of the string treatment flag whose value is the current arm's ExP variant name. The
+     * telemetry entry appends `:<allocationId>`; the value itself MUST start with
      * {@link ONBOARDING_ASSIGNMENT_CONTEXT_PREFIX}; an id without the prefix is rejected (the
      * experiment is treated as inactive) so it can never leak into telemetry ungated.
      */
@@ -115,6 +114,8 @@ export interface IOnboardingScenario<TPayload = unknown> {
      * {@link IOnboardingExperiment}.
      */
     readonly experiment?: IOnboardingExperiment;
+    /** Variations exposed through the onboarding developer-mode variation override. */
+    readonly developerModeVariations?: readonly string[];
     /** When `true`, the scenario runs on every eligible session instead of once per user. */
     readonly repeatable?: boolean;
 }

package/vscode/src/vs/workbench/contrib/onboarding/common/onboardingScenarioService.d.ts

@@ -26,6 +26,8 @@ export declare const ONBOARDING_ENABLED_CONFIG = "onboarding.enabled";
  * available ids are discoverable (and toggleable) in the settings editor.
  */
 export declare const ONBOARDING_DEVELOPER_MODE_CONFIG = "onboarding.developerMode";
+/** Developer override for a scenario's experiment-selected variation. */
+export declare const ONBOARDING_DEVELOPER_MODE_VARIATIONS_CONFIG = "onboarding.developerModeVariations";
 /**
  * The shape of the {@link ONBOARDING_DEVELOPER_MODE_CONFIG} setting: a map of
  * scenario/tour id to whether developer mode is enabled for that scenario.
@@ -33,9 +35,14 @@ export declare const ONBOARDING_DEVELOPER_MODE_CONFIG = "onboarding.developerMod
 export type OnboardingDeveloperMode = {
     readonly [scenarioId: string]: boolean;
 };
+/** The shape of the {@link ONBOARDING_DEVELOPER_MODE_VARIATIONS_CONFIG} setting. */
+export type OnboardingDeveloperModeVariations = {
+    readonly [scenarioId: string]: string;
+};
 /**
  * Whether onboarding developer mode is enabled for the given scenario/tour id.
  * Reads {@link ONBOARDING_DEVELOPER_MODE_CONFIG} and returns `true` only when the
  * setting is an object whose entry for `scenarioId` is explicitly `true`.
  */
 export declare function isOnboardingDeveloperModeEnabled(configurationService: IConfigurationService, scenarioId: string): boolean;
+export declare function getOnboardingDeveloperModeVariation(configurationService: IConfigurationService, scenarioId: string): string | undefined;