@theia/terminal 1.73.0-next.9 → 1.73.0

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@theia/terminal",
-  "version": "1.73.0-next.9+310484268",
+  "version": "1.73.0",
   "description": "Theia - Terminal Extension",
   "dependencies": {
-    "@theia/core": "1.73.0-next.9+310484268",
-    "@theia/editor": "1.73.0-next.9+310484268",
-    "@theia/file-search": "1.73.0-next.9+310484268",
-    "@theia/filesystem": "1.73.0-next.9+310484268",
-    "@theia/process": "1.73.0-next.9+310484268",
-    "@theia/variable-resolver": "1.73.0-next.9+310484268",
-    "@theia/workspace": "1.73.0-next.9+310484268",
+    "@theia/core": "1.73.0",
+    "@theia/editor": "1.73.0",
+    "@theia/file-search": "1.73.0",
+    "@theia/filesystem": "1.73.0",
+    "@theia/process": "1.73.0",
+    "@theia/variable-resolver": "1.73.0",
+    "@theia/workspace": "1.73.0",
     "tslib": "^2.8.1",
     "xterm": "^5.3.0",
     "xterm-addon-fit": "^0.8.0",
@@ -51,10 +51,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.72.0"
+    "@theia/ext-scripts": "1.73.0"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "31048426875ed92ecdb45c7446e92dddb8048f81"
+  "gitHead": "25e1b7fdf4c39ecea7066e1c8be3af1cc02e4d2e"
 }

package/src/browser/base/terminal-service.ts

@@ -29,7 +29,7 @@ export interface TerminalService {
      */
     newTerminal(options: TerminalWidgetOptions): Promise<TerminalWidget>;
 
-    open(terminal: TerminalWidget, options?: WidgetOpenerOptions): void;
+    open(terminal: TerminalWidget, options?: WidgetOpenerOptions): Promise<void>;
 
     readonly all: TerminalWidget[];
 

package/src/browser/base/terminal-widget.ts

@@ -181,6 +181,13 @@ export abstract class TerminalWidget extends BaseWidget {
      */
     abstract hasSelection(): boolean;
 
+    /**
+     * Paste the given text into the terminal as if it were typed by the user.
+     * Honors bracketed paste mode when enabled by the running program.
+     * @param text the text to paste
+     */
+    abstract paste(text: string): void;
+
     abstract writeLine(line: string): void;
 
     abstract write(data: string): void;

package/src/browser/index.ts

@@ -15,3 +15,4 @@
 // *****************************************************************************
 
 export * from './terminal-frontend-module';
+export * from './terminal-creation-handler';

package/src/browser/search/terminal-search-widget.tsx

@@ -51,13 +51,13 @@ export class TerminalSearchWidget extends ReactWidget {
 
     protected render(): React.ReactNode {
         return <div className='theia-search-terminal-widget'>
-            <div className='theia-search-elem-box' ref={searchBox => this.searchBox = searchBox} >
+            <div className='theia-search-elem-box' ref={searchBox => { this.searchBox = searchBox; }} >
                 <input
                     title={nls.localizeByDefault('Find')}
                     type='text'
                     spellCheck='false'
                     placeholder={nls.localizeByDefault('Find')}
-                    ref={ip => this.searchInput = ip}
+                    ref={ip => { this.searchInput = ip; }}
                     onKeyUp={this.onInputChanged}
                     onFocus={this.onSearchInputFocus}
                     onBlur={this.onSearchInputBlur}

package/src/browser/terminal-creation-handler.ts

@@ -0,0 +1,53 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource 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 { MaybePromise } from '@theia/core';
+import { WidgetOpenerOptions } from '@theia/core/lib/browser';
+import { TerminalWidget } from './base/terminal-widget';
+
+/**
+ * Contribution point that allows extensions to intercept terminal placement
+ * and take ownership of how/where terminals are displayed.
+ *
+ * When a terminal is opened via {@link TerminalService.open}, registered
+ * handlers are consulted in priority order. A handler can:
+ * - Return `true` to claim the terminal (the default shell placement is skipped)
+ * - Return `false` / `undefined` to decline (the next handler or default behavior applies)
+ *
+ * This is the canonical way for alternative terminal UIs (e.g. the terminal
+ * manager's tree view) to take ownership of terminal placement without relying
+ * on post-hoc event interception or timing-sensitive side-channel flags.
+ */
+export const TerminalCreationHandler = Symbol('TerminalCreationHandler');
+export interface TerminalCreationHandler {
+
+    /**
+     * Called when a terminal is about to be placed in the shell.
+     * The handler may take ownership of the terminal (e.g. add it to a custom container)
+     * by returning `true`. In that case, the default shell placement will be skipped.
+     *
+     * @param terminal The terminal widget to be placed.
+     * @param options The opener options, if any.
+     * @returns `true` if this handler claimed the terminal, `false` or `undefined` otherwise.
+     */
+    onWillOpenTerminal(terminal: TerminalWidget, options?: WidgetOpenerOptions): MaybePromise<boolean | undefined>;
+
+    /**
+     * The priority of this handler. Higher values are consulted first.
+     * Defaults to `0` if not specified.
+     */
+    readonly priority?: number;
+}

package/src/browser/terminal-file-link-provider.ts

@@ -14,10 +14,10 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
 
-import { OS, Path, QuickInputService } from '@theia/core';
+import { OS, Path, QuickInputService, ILogger } from '@theia/core';
 import { OpenerService } from '@theia/core/lib/browser';
 import URI from '@theia/core/lib/common/uri';
-import { inject, injectable } from '@theia/core/shared/inversify';
+import { inject, injectable, named } from '@theia/core/shared/inversify';
 import { Position } from '@theia/editor/lib/browser';
 import { FileService } from '@theia/filesystem/lib/browser/file-service';
 import { TerminalWidget } from './base/terminal-widget';
@@ -33,6 +33,8 @@ export class FileLinkProvider implements TerminalLinkProvider {
     @inject(FileService) protected fileService: FileService;
     @inject(FileSearchService) protected searchService: FileSearchService;
     @inject(WorkspaceService) protected readonly workspaceService: WorkspaceService;
+    @inject(ILogger) @named('terminal:FileLinkProvider')
+    protected readonly logger: ILogger;
 
     async provideLinks(line: string, terminal: TerminalWidget): Promise<TerminalLink[]> {
         const links: TerminalLink[] = [];
@@ -64,7 +66,7 @@ export class FileLinkProvider implements TerminalLinkProvider {
                 return this.isValidFileURI(toOpen);
             }
         } catch (err) {
-            console.trace('Error validating ' + match, err);
+            this.logger.error('Error validating ' + match, err);
         }
         return false;
     }
@@ -120,7 +122,7 @@ export class FileLinkProvider implements TerminalLinkProvider {
             const opener = await this.openerService.getOpener(toOpen, options);
             opener.open(toOpen, options);
         } catch (err) {
-            console.error('Cannot open link ' + toOpen, err);
+            this.logger.error('Cannot open link ' + toOpen, err);
         }
     }
 

package/src/browser/terminal-frontend-contribution.ts

@@ -14,7 +14,7 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
 
-import { inject, injectable, optional, postConstruct } from '@theia/core/shared/inversify';
+import { inject, injectable, named, optional, postConstruct } from '@theia/core/shared/inversify';
 import {
     CommandContribution,
     Command,
@@ -26,7 +26,7 @@ import {
     SelectionService,
     Emitter,
     Event,
-    ViewColumn,
+
     OS,
     MAIN_MENU_BAR,
     PreferenceService,
@@ -37,10 +37,11 @@ import {
     KeybindingRegistry, LabelProvider, WidgetOpenerOptions, StorageService, QuickInputService,
     codicon, CommonCommands, FrontendApplicationContribution, OnWillStopAction, Dialog, ConfirmDialog, FrontendApplication, Widget, SHELL_TABBAR_CONTEXT_MENU
 } from '@theia/core/lib/browser';
+import { ClipboardService } from '@theia/core/lib/browser/clipboard-service';
 import { TabBarToolbarContribution, TabBarToolbarRegistry } from '@theia/core/lib/browser/shell/tab-bar-toolbar';
-import { TERMINAL_WIDGET_FACTORY_ID, TerminalWidgetFactoryOptions, TerminalWidgetImpl } from './terminal-widget-impl';
+import { TERMINAL_WIDGET_FACTORY_ID, TerminalWidgetFactoryOptions, TerminalWidgetImpl, nextTerminalCreationToken } from './terminal-widget-impl';
 import { TerminalService } from './base/terminal-service';
-import { TerminalWidgetOptions, TerminalWidget, TerminalLocation } from './base/terminal-widget';
+import { TerminalWidgetOptions, TerminalWidget } from './base/terminal-widget';
 import { ContributedTerminalProfileStore, NULL_PROFILE, TerminalProfile, TerminalProfileService, TerminalProfileStore, UserTerminalProfileStore } from './terminal-profile-service';
 import { UriAwareCommandHandler } from '@theia/core/lib/common/uri-command-handler';
 import { ShellTerminalServerProxy } from '../common/shell-terminal-protocol';
@@ -58,6 +59,8 @@ import { Profiles, terminalAnsiColorMap, TerminalPreferences } from '../common/t
 import { ShellTerminalProfile } from './shell-terminal-profile';
 import { VariableResolverService } from '@theia/variable-resolver/lib/browser';
 import { Color } from '@theia/core/lib/common/color';
+import { ContributionProvider } from '@theia/core';
+import { TerminalCreationHandler } from './terminal-creation-handler';
 
 export namespace TerminalMenus {
     export const TERMINAL = [...MAIN_MENU_BAR, '7_terminal'];
@@ -164,6 +167,16 @@ export namespace TerminalCommands {
         label: 'Select All',
         category: TERMINAL_CATEGORY,
     });
+    export const PASTE_TERMINAL = Command.toDefaultLocalizedCommand({
+        id: 'workbench.action.terminal.paste',
+        category: TERMINAL_CATEGORY,
+        label: 'Paste into Active Terminal'
+    });
+    export const COPY_TERMINAL_SELECTION = Command.toDefaultLocalizedCommand({
+        id: 'workbench.action.terminal.copySelection',
+        category: TERMINAL_CATEGORY,
+        label: 'Copy Selection'
+    });
 
     /**
      * Command that displays all terminals that are currently opened
@@ -230,9 +243,15 @@ export class TerminalFrontendContribution implements FrontendApplicationContribu
     @inject(TerminalCopyOnSelectionHandler)
     protected readonly copyHandler: TerminalCopyOnSelectionHandler;
 
+    @inject(ClipboardService)
+    protected readonly clipboardService: ClipboardService;
+
     @inject(ContextKeyService)
     protected readonly contextKeyService: ContextKeyService;
 
+    @inject(ContributionProvider) @named(TerminalCreationHandler)
+    protected readonly terminalCreationHandlers: ContributionProvider<TerminalCreationHandler>;
+
     @postConstruct()
     protected init(): void {
         this.shell.onDidChangeCurrentWidget(() => this.updateCurrentTerminal());
@@ -670,20 +689,47 @@ export class TerminalFrontendContribution implements FrontendApplicationContribu
             isEnabled: () => !!this.currentTerminal,
             execute: () => this.currentTerminal?.selectAll()
         });
-        commands.registerHandler(CommonCommands.COPY.id, {
+        commands.registerCommand(TerminalCommands.PASTE_TERMINAL, {
+            isEnabled: () => !!this.getPasteTargetTerminal(),
+            execute: async () => {
+                const terminal = this.getPasteTargetTerminal();
+                if (!terminal) {
+                    return;
+                }
+                const text = await this.clipboardService.readText();
+                if (text) {
+                    terminal.paste(text);
+                }
+            }
+        });
+        commands.registerCommand(TerminalCommands.COPY_TERMINAL_SELECTION, {
+            isEnabled: () => !!this.getCopySourceTerminal(),
             execute: () => {
-                const terminal = this.shell.activeWidget;
-                if (terminal instanceof TerminalWidget && terminal.hasSelection()) {
-                    this.copyHandler.syncCopy(terminal.getSelection());
+                const terminal = this.getCopySourceTerminal();
+                if (!terminal) {
+                    return;
                 }
-            },
-            isEnabled: () => {
-                const terminal = this.shell.activeWidget;
-                return terminal instanceof TerminalWidget && terminal.hasSelection();
+                this.copyHandler.syncCopy(terminal.getSelection());
             }
         });
     }
 
+    protected getPasteTargetTerminal(): TerminalWidget | undefined {
+        const terminal = this.shell.activeWidget;
+        if (terminal instanceof TerminalWidget && this.terminalPreferences['terminal.enablePaste']) {
+            return terminal;
+        }
+        return undefined;
+    }
+
+    protected getCopySourceTerminal(): TerminalWidget | undefined {
+        const terminal = this.shell.activeWidget;
+        if (terminal instanceof TerminalWidget && terminal.hasSelection() && this.terminalPreferences['terminal.enableCopy']) {
+            return terminal;
+        }
+        return undefined;
+    }
+
     protected toggleTerminal(): void {
         const terminals = this.shell.getWidgets('bottom').filter(w => w instanceof TerminalWidget);
 
@@ -765,10 +811,12 @@ export class TerminalFrontendContribution implements FrontendApplicationContribu
             commandId: TerminalCommands.SPLIT.id
         });
         menus.registerMenuAction([...TerminalMenus.TERMINAL_CONTEXT_MENU, '_2'], {
-            commandId: CommonCommands.COPY.id
+            commandId: TerminalCommands.COPY_TERMINAL_SELECTION.id,
+            label: nls.localizeByDefault('Copy')
         });
         menus.registerMenuAction([...TerminalMenus.TERMINAL_CONTEXT_MENU, '_2'], {
-            commandId: CommonCommands.PASTE.id
+            commandId: TerminalCommands.PASTE_TERMINAL.id,
+            label: nls.localizeByDefault('Paste')
         });
         menus.registerMenuAction([...TerminalMenus.TERMINAL_CONTEXT_MENU, '_2'], {
             commandId: TerminalCommands.SELECT_ALL.id
@@ -898,6 +946,16 @@ export class TerminalFrontendContribution implements FrontendApplicationContribu
             keybinding: 'ctrlcmd+k',
             when: 'terminalFocus'
         });
+        keybindings.registerKeybinding({
+            command: TerminalCommands.PASTE_TERMINAL.id,
+            keybinding: 'ctrlcmd+v',
+            when: 'terminalFocus'
+        });
+        keybindings.registerKeybinding({
+            command: TerminalCommands.COPY_TERMINAL_SELECTION.id,
+            keybinding: 'ctrlcmd+c',
+            when: 'terminalFocus'
+        });
         keybindings.registerKeybinding({
             command: TerminalCommands.TERMINAL_FIND_TEXT.id,
             keybinding: 'ctrlcmd+f',
@@ -946,56 +1004,20 @@ export class TerminalFrontendContribution implements FrontendApplicationContribu
 
     async newTerminal(options: TerminalWidgetOptions): Promise<TerminalWidget> {
         const widget = <TerminalWidget>await this.widgetManager.getOrCreateWidget(TERMINAL_WIDGET_FACTORY_ID, <TerminalWidgetFactoryOptions>{
-            created: new Date().toISOString(),
+            created: nextTerminalCreationToken(),
             ...options
         });
         return widget;
     }
 
-    // TODO: reuse WidgetOpenHandler.open
-    open(widget: TerminalWidget, options?: WidgetOpenerOptions): void {
-        const area = widget.location === TerminalLocation.Editor ? 'main' : 'bottom';
-        const widgetOptions: ApplicationShell.WidgetOptions = { area: area, ...options?.widgetOptions };
-        let preserveFocus = false;
-
-        if (typeof widget.location === 'object') {
-            if ('parentTerminal' in widget.location) {
-                widgetOptions.ref = this.getById(widget.location.parentTerminal);
-                widgetOptions.mode = 'split-right';
-            } else if ('viewColumn' in widget.location) {
-                preserveFocus = widget.location.preserveFocus ?? false;
-                switch (widget.location.viewColumn) {
-                    case ViewColumn.Active:
-                        widgetOptions.ref = this.shell.currentWidget;
-                        widgetOptions.mode = 'tab-after';
-                        break;
-                    case ViewColumn.Beside:
-                        widgetOptions.ref = this.shell.currentWidget;
-                        widgetOptions.mode = 'split-right';
-                        break;
-                    default:
-                        widgetOptions.area = 'main';
-                        const mainAreaTerminals = this.shell.getWidgets('main').filter(w => w instanceof TerminalWidget && w.isVisible);
-                        const column = Math.min(widget.location.viewColumn, mainAreaTerminals.length);
-                        widgetOptions.mode = widget.location.viewColumn <= mainAreaTerminals.length ? 'split-left' : 'split-right';
-                        widgetOptions.ref = mainAreaTerminals[column - 1];
-                }
+    async open(widget: TerminalWidget, options?: WidgetOpenerOptions): Promise<void> {
+        const handlers = this.terminalCreationHandlers.getContributions(true)
+            .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+        for (const handler of handlers) {
+            if (await handler.onWillOpenTerminal(widget, options)) {
+                return;
             }
         }
-
-        const op: WidgetOpenerOptions = {
-            mode: 'activate',
-            ...options,
-            widgetOptions: widgetOptions
-        };
-        if (!widget.isAttached) {
-            this.shell.addWidget(widget, op.widgetOptions);
-        }
-        if (op.mode === 'activate' && !preserveFocus) {
-            this.shell.activateWidget(widget.id);
-        } else if (op.mode === 'reveal' || preserveFocus) {
-            this.shell.revealWidget(widget.id);
-        }
     }
 
     protected async selectTerminalCwd(): Promise<string | undefined> {

package/src/browser/terminal-frontend-module.ts

@@ -31,6 +31,8 @@ import { IShellTerminalServer, shellTerminalPath, ShellTerminalServerProxy } fro
 import { TerminalService } from './base/terminal-service';
 import { bindTerminalPreferences } from '../common/terminal-preferences';
 import { TerminalContribution } from './terminal-contribution';
+import { TerminalCreationHandler } from './terminal-creation-handler';
+import { TerminalShellHandler } from './terminal-shell-handler';
 import { TerminalSearchWidgetFactory } from './search/terminal-search-widget';
 import { TerminalQuickOpenService, TerminalQuickOpenContribution } from './terminal-quick-open-service';
 import { createTerminalSearchFactory } from './search/terminal-search-container';
@@ -105,6 +107,9 @@ export default new ContainerModule(bind => {
     bind(IShellTerminalServer).toService(ShellTerminalServerProxy);
 
     bindRootContributionProvider(bind, TerminalContribution);
+    bindRootContributionProvider(bind, TerminalCreationHandler);
+    bind(TerminalShellHandler).toSelf().inSingletonScope();
+    bind(TerminalCreationHandler).toService(TerminalShellHandler);
 
     // terminal link provider contribution point
     bindRootContributionProvider(bind, TerminalLinkProvider);

package/src/browser/terminal-shell-handler.ts

@@ -0,0 +1,89 @@
+// *****************************************************************************
+// Copyright (C) 2017-2026 TypeFox 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 { inject, injectable } from '@theia/core/shared/inversify';
+import { ViewColumn } from '@theia/core/lib/common';
+import { ApplicationShell, WidgetOpenerOptions } from '@theia/core/lib/browser';
+import { TerminalCreationHandler } from './terminal-creation-handler';
+import { TerminalWidget, TerminalLocation } from './base/terminal-widget';
+import { TerminalService } from './base/terminal-service';
+
+/**
+ * Default {@link TerminalCreationHandler} that places terminals into the
+ * application shell. This handles the standard panel/editor/split placement
+ * logic and always claims the terminal (returning `true`).
+ *
+ * Because it always claims, it should run at the lowest priority so that
+ * other handlers (e.g. the terminal manager) get a chance to intercept first.
+ */
+@injectable()
+export class TerminalShellHandler implements TerminalCreationHandler {
+
+    readonly priority = -100;
+
+    @inject(ApplicationShell)
+    protected readonly shell: ApplicationShell;
+
+    @inject(TerminalService)
+    protected readonly terminalService: TerminalService;
+
+    async onWillOpenTerminal(terminal: TerminalWidget, options?: WidgetOpenerOptions): Promise<boolean> {
+        const area = terminal.location === TerminalLocation.Editor ? 'main' : 'bottom';
+        const widgetOptions: ApplicationShell.WidgetOptions = { area, ...options?.widgetOptions };
+        let preserveFocus = false;
+
+        if (typeof terminal.location === 'object') {
+            if ('parentTerminal' in terminal.location) {
+                widgetOptions.ref = this.terminalService.getById(terminal.location.parentTerminal);
+                widgetOptions.mode = 'split-right';
+            } else if ('viewColumn' in terminal.location) {
+                preserveFocus = terminal.location.preserveFocus ?? false;
+                switch (terminal.location.viewColumn) {
+                    case ViewColumn.Active:
+                        widgetOptions.ref = this.shell.currentWidget;
+                        widgetOptions.mode = 'tab-after';
+                        break;
+                    case ViewColumn.Beside:
+                        widgetOptions.ref = this.shell.currentWidget;
+                        widgetOptions.mode = 'split-right';
+                        break;
+                    default:
+                        widgetOptions.area = 'main';
+                        const mainAreaTerminals = this.shell.getWidgets('main').filter(w => w instanceof TerminalWidget && w.isVisible);
+                        const column = Math.min(terminal.location.viewColumn, mainAreaTerminals.length);
+                        widgetOptions.mode = terminal.location.viewColumn <= mainAreaTerminals.length ? 'split-left' : 'split-right';
+                        widgetOptions.ref = mainAreaTerminals[column - 1];
+                }
+            }
+        }
+
+        const op: WidgetOpenerOptions = {
+            mode: 'activate',
+            ...options,
+            widgetOptions
+        };
+        if (!terminal.isAttached) {
+            this.shell.addWidget(terminal, op.widgetOptions);
+        }
+        if (op.mode === 'activate' && !preserveFocus) {
+            this.shell.activateWidget(terminal.id);
+        } else if (op.mode === 'reveal' || preserveFocus) {
+            this.shell.revealWidget(terminal.id);
+        }
+
+        return true;
+    }
+}

package/src/browser/terminal-widget-impl.ts

@@ -53,16 +53,34 @@ import { EnhancedPreviewWidget } from '@theia/core/lib/browser/widgets/enhanced-
 import { MarkdownRenderer, MarkdownRendererFactory } from '@theia/core/lib/browser/markdown-rendering/markdown-renderer';
 import { RemoteConnectionProvider, ServiceConnectionProvider } from '@theia/core/lib/browser/messaging/service-connection-provider';
 import { ColorRegistry } from '@theia/core/lib/browser/color-registry';
+import { ContextKeyService } from '@theia/core/lib/browser/context-key-service';
 import { cleanTerminalTitle, guessShellTypeFromExecutable } from '../common/shell-type';
 import { TerminalCommandHistoryStateFactory } from './terminal-command-history';
 
 export const TERMINAL_WIDGET_FACTORY_ID = 'terminal';
 
 export interface TerminalWidgetFactoryOptions extends Partial<TerminalWidgetOptions> {
-    /* a unique string per terminal */
+    /**
+     * An opaque, unique string per terminal. Historically a date string, but
+     * it should not be interpreted as a date. Callers should use
+     * {@link nextTerminalCreationToken} to obtain a value that is guaranteed
+     * unique within the current process.
+     */
     created: string
 }
 
+let terminalCreationCounter = 0;
+/**
+ * Produce a token suitable for {@link TerminalWidgetFactoryOptions.created}
+ * that is guaranteed unique within the current process. Combines the current
+ * wall-clock time with a monotonically increasing counter so callers cannot
+ * accidentally collide even when constructing terminals within the same
+ * millisecond.
+ */
+export function nextTerminalCreationToken(): string {
+    return `${Date.now()}-${terminalCreationCounter++}`;
+}
+
 export const TerminalContribution = Symbol('TerminalContribution');
 export interface TerminalContribution {
     onCreate(term: TerminalWidgetImpl): void;
@@ -147,6 +165,7 @@ export class TerminalWidgetImpl extends TerminalWidget implements StatefulWidget
     @inject(ContextMenuRenderer) protected readonly contextMenuRenderer: ContextMenuRenderer;
     @inject(MarkdownRendererFactory) protected readonly markdownRendererFactory: MarkdownRendererFactory;
     @inject(TerminalCommandHistoryStateFactory) protected readonly commandHistoryStateFactory: TerminalCommandHistoryStateFactory;
+    @inject(ContextKeyService) protected readonly contextKeyService: ContextKeyService;
 
     protected _markdownRenderer: MarkdownRenderer | undefined;
     protected get markdownRenderer(): MarkdownRenderer {
@@ -211,6 +230,14 @@ export class TerminalWidgetImpl extends TerminalWidget implements StatefulWidget
         this.title.caption = initialTitle;
         this.setIconClass();
 
+        // Declare 'terminalFocus' as a local context key on this widget's DOM scope so that
+        // terminal-scoped keybindings (e.g. ctrlcmd+v) take precedence over global bindings
+        // for the same keystroke when focus is inside the terminal.
+        // See KeybindingRegistry.selectBindingByLocalContext.
+        const localContext = this.contextKeyService.createScoped(this.node);
+        localContext.createKey('terminalFocus', true);
+        this.toDispose.push(localContext);
+
         if (this.options.kind) {
             this.terminalKind = this.options.kind;
         }
@@ -306,13 +333,8 @@ export class TerminalWidgetImpl extends TerminalWidget implements StatefulWidget
                 } else {
                     this.exitStatus = { code, reason: TerminalExitReason.Process };
                 }
-                // Ensure any in-progress command block is closed even if the process exits
-                // before its OSC prompt_started bytes are flushed from the ring buffer.
-                if (this._commandHistoryState?.currentCommand) {
-                    this.finishCurrentCommand();
-                }
                 if (!attached) {
-                    this.dispose();
+                    this.deferredFinalizeCommandHistory();
                 }
             }
         }));
@@ -525,6 +547,28 @@ export class TerminalWidgetImpl extends TerminalWidget implements StatefulWidget
         this.promptStartMarker = undefined;
     }
 
+    protected connectionClosed = false;
+    protected waitingForConnectionCloseToDispose = false;
+
+    protected finalizeAndDispose(): void {
+        // enqueue a callback after all pending xterm writes drain
+        this.term.write('', () => {
+            if (this.isDisposed) { return; }
+            if (this._commandHistoryState?.currentCommand) {
+                this.finishCurrentCommand();
+            }
+            this.dispose();
+        });
+    }
+
+    protected deferredFinalizeCommandHistory(): void {
+        if (this.connectionClosed) {
+            this.finalizeAndDispose();
+        } else {
+            this.waitingForConnectionCloseToDispose = true;
+        }
+    }
+
     private addCommandSeparator(): void {
         const marker = this.term.registerMarker(0);
         if (!marker) {
@@ -740,6 +784,10 @@ export class TerminalWidgetImpl extends TerminalWidget implements StatefulWidget
         return this.term.hasSelection();
     }
 
+    paste(text: string): void {
+        this.term.paste(text);
+    }
+
     async hasChildProcesses(): Promise<boolean> {
         return this.shellTerminalServer.hasChildProcesses(await this.processId);
     }
@@ -902,6 +950,8 @@ export class TerminalWidgetImpl extends TerminalWidget implements StatefulWidget
         }
         this.toDisposeOnConnect.dispose();
         this.toDispose.push(this.toDisposeOnConnect);
+        this.connectionClosed = false;
+        this.waitingForConnectionCloseToDispose = false;
         const waitForConnection = this.waitForConnection = new Deferred<Channel>();
         this.connectionProvider.listen(
             `${terminalsPath}/${this.terminalId}`,
@@ -921,7 +971,13 @@ export class TerminalWidgetImpl extends TerminalWidget implements StatefulWidget
                 disposable.push(this.term.onData(sendData));
                 disposable.push(this.term.onBinary(sendData));
 
-                connection.onClose(() => disposable.dispose());
+                connection.onClose(() => {
+                    disposable.dispose();
+                    this.connectionClosed = true;
+                    if (this.waitingForConnectionCloseToDispose) {
+                        this.finalizeAndDispose();
+                    }
+                });
 
                 if (waitForConnection) {
                     waitForConnection.resolve(connection);