@pstdio/workbench 0.4.0 → 0.6.0

package/dist/extensions.d.ts

@@ -1,4 +1,5 @@
 import { CommandExecuteRequest } from '@pstdio/sdk/api';
+import { CommandExecuteResponse } from '@pstdio/sdk/api';
 import { ComponentType } from 'react';
 import { ExtensionCommandPaletteContribution } from '@pstdio/sdk/api';
 import { ExtensionMenuContribution } from '@pstdio/sdk/api';
@@ -113,9 +114,7 @@ export declare const buildWorkbenchExtensionMenuRegistrations: (input: {
 export declare const buildWorkbenchExtensionRouteEntries: (input: {
     metadata: WorkbenchExtensionMetadata | undefined;
     createResource: (resourceInput: WorkbenchExtensionRouteResourceInput) => ResourceRef;
-}) => {
-    resource: ResourceRef;
-}[];
+}) => any;
 
 /**
  * A data-driven list of items, each opening a contributor-supplied editor. The
@@ -205,6 +204,7 @@ declare interface CommandParamDescriptor {
 declare interface CommandParamOption {
     label: string;
     value: string;
+    icon?: string;
 }
 
 declare type CommandParamSchema = Record<string, CommandParamDescriptor>;
@@ -225,6 +225,72 @@ declare interface CommandRegistryStoreState {
     commands: Record<string, RegisteredCommand>;
 }
 
+declare interface CompositionDiagnostic {
+    code: "extension_resource_kind_missing" | "extension_resource_slot_missing" | "extension_resource_slot_closed" | "extension_panel_missing" | "extension_panel_placement_unresolvable" | "extension_mode_resource_unsupported" | "extension_placement_required_invalid" | "extension_resource_primary_invalid";
+    message: string;
+    panelId?: string;
+    slot?: string;
+}
+
+declare interface CompositionModeDefinition {
+    id: string;
+    extensionId?: string;
+    resources?: Record<string, CompositionModeRecipe>;
+    modePanels?: Record<string, CompositionPlacementPolicy>;
+}
+
+declare interface CompositionModeRecipe {
+    slots?: Record<string, CompositionPlacementPolicy>;
+    panels?: Record<string, CompositionPlacementPolicy>;
+}
+
+declare interface CompositionPanelDefinition {
+    id: string;
+    extensionId: string;
+    title: string;
+    icon?: string;
+    show?: CompositionPanelPlacement | readonly CompositionPanelPlacement[];
+}
+
+declare interface CompositionPanelPlacement extends CompositionPlacementPolicy {
+    resourceKind?: string;
+}
+
+declare interface CompositionPlacementPolicy {
+    region: DockedCompositionRegion;
+    allowedRegions?: readonly DockedCompositionRegion[];
+    required?: boolean;
+    defaultOpen?: boolean;
+    pinned?: boolean;
+}
+
+declare interface CompositionReconcileContext {
+    layout: LayoutModel;
+    notifications: NotificationRegistry;
+}
+
+export declare const compositionRequiredNotificationId: (modeId: string) => string;
+
+declare interface CompositionResourceKindDefinition {
+    id: string;
+    extensionId: string;
+    surface: "primary" | "secondary" | "attached";
+    slots: Record<string, CompositionSlotDefinition>;
+}
+
+declare interface CompositionResourcePanelEdge {
+    id: string;
+    extensionId: string;
+    resourceKind: string;
+    panel: string;
+    slot: string;
+}
+
+declare interface CompositionSlotDefinition {
+    cardinality: "one" | "many";
+    external: boolean;
+}
+
 declare interface ContextKeyScope extends Disposable_2 {
     ownerId: string;
     set(key: string, value: ContextKeyValue): void;
@@ -367,6 +433,8 @@ declare interface CreateTerminalSessionCapabilityInput {
     hostEvents: HostEventPublisher;
 }
 
+export declare const createWorkbenchCompositionRegistry: () => WorkbenchCompositionRegistry;
+
 export declare const createWorkbenchWebviewHostCapabilities: (input: CreateWorkbenchWebviewHostCapabilitiesInput) => {
     "terminal.session"?: HostCapability | undefined;
     "commands.execute": (params: unknown) => Promise<unknown>;
@@ -446,7 +514,7 @@ declare interface DataTableRendererContribution {
     emptyDescription?: string;
     executeQuery(context: DataTableRendererQueryContext): Promise<DataTableRendererQueryResult> | DataTableRendererQueryResult;
     subscribe?: (listener: () => void) => Disposable_2 | (() => void);
-    onRowClick?: (row: DataTableRendererRow) => void;
+    onRowActivate?: (row: DataTableRendererRow) => Promise<void> | void;
 }
 
 declare type DataTableRendererImplementation = (input: WorkbenchPanelRenderInput & {
@@ -514,28 +582,28 @@ declare interface DataTableRendererThemeColor {
 
 declare type DataTableViewRecord = WorkbenchExtensionMetadata["panels"][number];
 
+declare interface DeclaredPanelPlacement {
+    for?: string;
+    region: DockedCompositionRegion;
+    allowedRegions?: readonly DockedCompositionRegion[];
+    required?: boolean;
+    defaultOpen?: boolean;
+    pinned?: boolean;
+}
+
 declare interface Disposable_2 {
     dispose(): void;
 }
 
-export declare const emptyWorkbenchExtensionMetadata: {
-    commands: never[];
-    commandPaletteContributions: never[];
-    diagnostics: never[];
-    extensions: never[];
-    menuContributions: never[];
-    modes: never[];
-    navigation: never[];
-    routes: never[];
-    kanbanRenderers: never[];
-    dataTableRenderers: never[];
-    treeRenderers: never[];
-    fileRenderers: never[];
-    settingsPanels: never[];
-    settingsDefinitions: never[];
-    treeItems: never[];
-    panels: never[];
-};
+declare type DockedCompositionRegion = (typeof dockedCompositionRegions)[number];
+
+declare type DockedCompositionRegion_2 = (typeof dockedCompositionRegions_2)[number];
+
+declare const dockedCompositionRegions: readonly ["sidenav", "main", "secondary", "side"];
+
+declare const dockedCompositionRegions_2: readonly ["sidenav", "main", "secondary", "side"];
+
+export declare const emptyWorkbenchExtensionMetadata: WorkbenchExtensionMetadata;
 
 declare interface EnumOption {
     value: string;
@@ -556,8 +624,19 @@ declare interface EnumOptionsSource {
     getSnapshot: () => EnumOption[];
 }
 
+declare type ExtensionPanelRecord = WorkbenchExtensionMetadata["panels"][number];
+
+declare type ExtensionResourcePanels = WorkbenchExtensionMetadata["resourcePanels"];
+
 declare type ExtensionTreeRendererRecord = NonNullable<WorkbenchExtensionMetadata["treeRenderers"]>[number];
 
+declare interface ExtensionTreeResource {
+    type: string;
+    id: string;
+    label?: string;
+    metadata?: Record<string, unknown>;
+}
+
 declare type ExtensionTreeViewRecord = WorkbenchExtensionMetadata["panels"][number] | NonNullable<WorkbenchExtensionMetadata["panels"][number]["panelMenus"]>[number];
 
 export declare interface ExtensionWebviewFileCapabilities {
@@ -606,6 +685,8 @@ declare interface FileRendererContent {
     content?: string;
     dataUrl?: string;
     placeholder?: string;
+    /** Ordered backing-store revision when one is available. */
+    revision?: string;
 }
 
 declare interface FileRendererContribution {
@@ -615,35 +696,55 @@ declare interface FileRendererContribution {
     /** Resolve the file's content (and identity) for the bound resource. */
     load(resource: ResourceRef | undefined): Promise<FileRendererContent> | FileRendererContent;
     /** Persist edited text. Absent ⇒ read-only. Never called for images. */
-    save?(resource: ResourceRef | undefined, content: string): Promise<void> | void;
+    save?(resource: ResourceRef | undefined, content: string, origin?: FileRendererRefreshOrigin): Promise<FileRendererSaveResult | undefined> | FileRendererSaveResult | void;
 }
 
 declare type FileRendererImplementation = (input: WorkbenchPanelRenderInput & {
     fileRendererId: string;
 }) => unknown;
 
-declare interface FileRendererRefreshEvent {
+declare interface FileRendererRefreshEnvelope {
+    resourceUri?: string;
+    origin?: FileRendererRefreshOrigin;
+    revision?: string;
+}
+
+export declare const fileRendererRefreshEnvelopeFromCommand: (body: CommandExecuteRequest, response: CommandExecuteResponse) => FileRendererRefreshEnvelope | undefined;
+
+declare interface FileRendererRefreshEvent extends FileRendererRefreshEnvelope {
     fileRendererId: string;
 }
 
 declare type FileRendererRefreshListener = (event: FileRendererRefreshEvent) => void;
 
+declare interface FileRendererRefreshOrigin {
+    rendererId: string;
+    instanceId: string;
+    operationId: string;
+}
+
 declare interface FileRendererRegistry {
     fileRendererStore: WorkbenchStore<FileRendererStoreState>;
     registerFileRenderer(contribution: FileRendererContribution, metadata?: ContributionMetadata): Disposable_2;
     setFileRendererImplementation(impl: FileRendererImplementation): void;
     getFileRenderer(id: string): RegisteredFileRendererContribution | undefined;
     listFileRenderers(): RegisteredFileRendererContribution[];
-    refreshFileRenderer(id: string): void;
+    refreshFileRenderer(id: string, event?: FileRendererRefreshEnvelope): void;
     onDidRefreshFileRenderer(listener: FileRendererRefreshListener): Disposable_2;
 }
 
+declare interface FileRendererSaveResult {
+    revision?: string;
+}
+
 declare interface FileRendererStoreState {
     renderers: Record<string, RegisteredFileRendererContribution>;
 }
 
 declare interface HistoryController {
     store: WorkbenchStore<HistoryStoreState>;
+    /** Snapshot the history for a compound navigation; the returned function restores it. */
+    createCheckpoint(): () => void;
     goBack(): HistoryEntry | undefined;
     goForward(): HistoryEntry | undefined;
     goPrevious(): HistoryEntry | undefined;
@@ -677,6 +778,8 @@ declare interface KanbanRendererContribution<TRow extends KanbanRendererRow = Ka
     id: string;
     title: string;
     resourceKind?: string;
+    /** Host-owned scope for persisted display settings. */
+    storageScope?: string;
     /**
      * Declarative attribute schema. The renderer dispatches filter / group /
      * sort / display / inline-edit behavior on each descriptor's `type.kind`.
@@ -704,8 +807,8 @@ declare interface KanbanRendererContribution<TRow extends KanbanRendererRow = Ka
      */
     executeQuery(state: KanbanRendererQueryState): Promise<TRow[]> | TRow[];
     subscribe?: (listener: () => void) => Disposable_2 | (() => void);
-    /** Row interactions surfaced by the renderer (mirrored from <KanbanRenderer>). */
-    onRowClick?: (row: TRow) => void;
+    /** Row activation surfaced by the renderer (mirrored from <KanbanRenderer>). */
+    onRowActivate?: (row: TRow) => Promise<void> | void;
     /** Per-row right-click context menu actions (mirrored from <KanbanRenderer>). */
     getRowContextMenuActions?: (row: TRow) => ResourceContextAction[];
     /**
@@ -799,7 +902,7 @@ declare interface KanbanRendererRow {
     title: string;
     /**
      * Optional navigation handle. When set, the renderer's default click handler
-     * routes through the contribution's onRowClick (which typically opens the
+     * routes through the contribution's onRowActivate (which typically opens the
      * resource via the workbench).
      */
     resource?: unknown;
@@ -906,6 +1009,16 @@ declare interface LayoutModel {
         carryRegionState?: readonly WorkbenchRegion[];
     }): void;
     getPersistenceScope(): LayoutScope | undefined;
+    /** True when the current persistence scope already stores a layout. A new scope returns false. */
+    /** Whether anything is stored for the active scope right now. */
+    hasPersistedLayout(): boolean;
+    /**
+     * Whether the active scope was entered with a layout the user already had. Unlike
+     * `hasPersistedLayout`, writes made while entering a mode do not change the answer.
+     */
+    enteredWithPersistedLayout(): boolean;
+    /** Moves owned panel menus beside their owner's current region and removes orphan menus. */
+    reconcilePanelMenus(): void;
     onWillChangePersistenceScope(listener: (scope: LayoutScope | undefined) => void): {
         dispose(): void;
     };
@@ -916,6 +1029,13 @@ declare interface LayoutModel {
 
 declare type LayoutScope = string;
 
+export declare const listCompositionAddablePanels: (input: {
+    registry: WorkbenchCompositionRegistry;
+    modeId: string;
+    layout: ReturnType<LayoutModel["getLayout"]>;
+    resourceKind?: string;
+}) => readonly ResolvedCompositionAddablePanel[];
+
 declare type Localizer = (value: unknown, fallback?: string) => string;
 
 declare const MANUAL_ORDERING = "manual";
@@ -1020,6 +1140,7 @@ declare interface OpenWidgetInput {
     resource?: ResourceRef;
     title?: string;
     region?: WorkbenchRegion;
+    role?: WorkbenchWidgetRole;
     ownerId?: string;
     source?: ContributionSource;
     pinned?: boolean;
@@ -1037,13 +1158,19 @@ declare interface OpenWorkbenchPanelInput {
     resource?: ResourceRef;
     title?: string;
     region?: WorkbenchRegion;
+    role?: WorkbenchWidgetRole;
     pinned?: boolean;
+    closable?: boolean;
     mountStrategy?: WorkbenchPanelMountStrategy;
     hiddenByDefault?: boolean;
     tab?: WorkbenchPanelTab;
     strategy?: WorkbenchPanelOpenStrategy;
 }
 
+export declare const panelMenuDeclarationOffsets: <T extends {
+    panelMenus?: readonly unknown[];
+}>(panels: readonly T[]) => number[];
+
 declare interface PlaceholderContribution {
     id: string;
     title: string;
@@ -1088,9 +1215,16 @@ declare interface PreferenceScopeRef {
 
 declare type PreferenceValue = boolean | number | string | string[] | number[] | boolean[] | Record<string, unknown>;
 
+export declare const reconcileCompositionLayout: (ctx: CompositionReconcileContext, input: {
+    registry: WorkbenchCompositionRegistry;
+    modeId: string;
+    resourceKind?: string;
+    seeding?: boolean;
+}) => ResolvedComposition | undefined;
+
 export declare const refreshOpenWorkbenchExtensionWebviews: (workbench: WorkbenchModuleContext, metadata: WorkbenchExtensionMetadata) => void;
 
-export declare const refreshWorkbenchExtensionContributions: (workbench: WorkbenchModuleContext, metadata: WorkbenchExtensionMetadata, commandId: string) => void;
+export declare const refreshWorkbenchExtensionRenderer: (workbench: WorkbenchModuleContext, target: RendererRefreshTarget, envelope?: FileRendererRefreshEnvelope) => void;
 
 declare interface RegisteredCommand extends RegisteredContributionMetadata {
     command: Command;
@@ -1153,7 +1287,6 @@ declare type RegisteredWidgetContribution = Omit<WidgetContribution, "priority"
     ownedPanelMenuIds?: readonly string[];
     singleton: boolean;
     reuse: WidgetReusePolicy;
-    role: WorkbenchWidgetRole;
 } & RegisteredContributionMetadata;
 
 declare interface RegisteredWorkbenchNotification extends RegisteredContributionMetadata {
@@ -1194,9 +1327,9 @@ export declare interface RegisterWorkbenchExtensionContributionsInput {
     workbench: WorkbenchModuleContext;
 }
 
-export declare const registerWorkbenchExtensionControlsRenderers: (context: WorkbenchExtensionCommandContext, records: WorkbenchExtensionControlsRendererRecord[], panels: ControlsViewRecord[], adapter?: WorkbenchExtensionControlsAdapter) => Disposable_2;
+export declare const registerWorkbenchExtensionControlsRenderers: (context: WorkbenchExtensionCommandContext, records: WorkbenchExtensionControlsRendererRecord[], panels: ControlsViewRecord[], adapter?: WorkbenchExtensionControlsAdapter, resourcePanels?: WorkbenchExtensionMetadata["resourcePanels"]) => Disposable_2;
 
-export declare const registerWorkbenchExtensionDataTableRenderers: (context: WorkbenchExtensionCommandContext, records: WorkbenchExtensionDataTableRendererRecord[], panels: DataTableViewRecord[]) => Disposable_2;
+export declare const registerWorkbenchExtensionDataTableRenderers: (context: WorkbenchExtensionCommandContext, records: WorkbenchExtensionDataTableRendererRecord[], panels: DataTableViewRecord[], resourcePanels?: WorkbenchExtensionMetadata["resourcePanels"]) => Disposable_2;
 
 export declare const registerWorkbenchExtensionFileRenderers: (input: RegisterWorkbenchExtensionFileRenderersInput) => {
     dispose(): void;
@@ -1209,7 +1342,7 @@ export declare interface RegisterWorkbenchExtensionFileRenderersInput {
     workbench: WorkbenchModuleContext;
 }
 
-export declare const registerWorkbenchExtensionKanbanRenderers: (context: WorkbenchExtensionCommandContext, records: readonly WorkbenchExtensionKanbanRendererRecord[], adapter?: WorkbenchExtensionKanbanRendererAdapter) => {
+export declare const registerWorkbenchExtensionKanbanRenderers: (context: WorkbenchExtensionCommandContext, records: readonly WorkbenchExtensionKanbanRendererRecord[], adapter?: WorkbenchExtensionKanbanRendererAdapter, panels?: WorkbenchExtensionMetadata["panels"], resourcePanels?: WorkbenchExtensionMetadata["resourcePanels"]) => {
     dispose(): void;
 };
 
@@ -1220,6 +1353,14 @@ export declare interface RegisterWorkbenchExtensionPanelInput {
     workbench: WorkbenchModuleContext;
 }
 
+export declare const registerWorkbenchExtensionRendererRefreshEvents: (input: RegisterWorkbenchExtensionRendererRefreshEventsInput) => Disposable_2;
+
+export declare interface RegisterWorkbenchExtensionRendererRefreshEventsInput {
+    metadata: WorkbenchExtensionMetadata;
+    subscribe: (listener: (event: WorkbenchExtensionRefreshEvent) => void) => Disposable_2;
+    workbench: WorkbenchModuleContext;
+}
+
 export declare const registerWorkbenchExtensionTreeRenderers: (input: RegisterWorkbenchExtensionTreeRenderersInput) => {
     dispose(): void;
 };
@@ -1230,6 +1371,13 @@ export declare interface RegisterWorkbenchExtensionTreeRenderersInput {
     getHostTreeHeaderNodes?: HostTreeDefaultNodesResolver;
     metadata: WorkbenchExtensionMetadata;
     projectId: string;
+    /**
+     * Host canonicalization for node resources. A host that gives extension
+     * resources its own URIs (layout scopes, history, and hierarchy key on the
+     * URI) must convert tree node resources the same way, or the same resource
+     * gets a second identity when opened from a tree.
+     */
+    resolveNodeResource?: (resource: ExtensionTreeResource) => ResourceRef;
     workbench: WorkbenchModuleContext;
 }
 
@@ -1243,6 +1391,47 @@ export declare const renderBridgeWebviewFrame: (input: {
     webview: BridgeWebviewConfig;
 }) => JSX.Element;
 
+declare interface RendererRefreshTarget {
+    id: string;
+    kind: WorkbenchExtensionRendererKind;
+}
+
+declare interface ResolvedComposition {
+    placements: readonly ResolvedCompositionPlacement[];
+    regionOrder: Partial<Record<DockedCompositionRegion, readonly string[]>>;
+    activePanelIds: Partial<Record<DockedCompositionRegion, string>>;
+    addablePanels: readonly ResolvedCompositionAddablePanel_2[];
+    diagnostics: readonly CompositionDiagnostic[];
+    requiredFallback?: {
+        panelId: string;
+    };
+}
+
+declare interface ResolvedCompositionAddablePanel {
+    panelId: string;
+    region: DockedCompositionRegion_2;
+    allowedRegions: readonly DockedCompositionRegion_2[];
+    pinned?: boolean;
+}
+
+declare interface ResolvedCompositionAddablePanel_2 {
+    panelId: string;
+    region: DockedCompositionRegion;
+    allowedRegions: readonly DockedCompositionRegion[];
+    pinned?: boolean;
+}
+
+declare interface ResolvedCompositionPlacement {
+    panelId: string;
+    region: DockedCompositionRegion;
+    slot?: string;
+    required: boolean;
+    defaultOpen: boolean;
+    pinned?: boolean;
+    allowedRegions: readonly DockedCompositionRegion[];
+    origin: "persisted" | "required" | "default";
+}
+
 declare type ResolvedResourceHierarchyProvider = Required<ResourceHierarchyProvider>;
 
 declare type ResolvedResourcePresenter = Required<ResourcePresenter>;
@@ -1267,6 +1456,14 @@ declare interface ResourceContextAction {
     separatorBefore?: boolean;
 }
 
+declare interface ResourceHierarchyCycle {
+    code: typeof resourceHierarchyCycleCode;
+    path: ResourceRef[];
+    repeatedUri: string;
+}
+
+declare const resourceHierarchyCycleCode = "resource_hierarchy_cycle";
+
 declare interface ResourceHierarchyProvider {
     id: string;
     priority?: number;
@@ -1339,6 +1536,7 @@ declare interface ResourceRegistry {
     registerHierarchyProvider(provider: ResourceHierarchyProvider): Disposable_2;
     listHierarchyProviders(): ResolvedResourceHierarchyProvider[];
     walkHierarchy(resource: ResourceRef | undefined): ResourceRef[];
+    onDidDetectHierarchyCycle(listener: (cycle: ResourceHierarchyCycle) => void): Disposable_2;
     isOpeningResource(): boolean;
     openResource(resource: ResourceRef, input?: OpenResourceInput): Promise<WorkbenchPanelInstance>;
     onDidOpenResource(listener: (resource: ResourceRef) => void): Disposable_2;
@@ -1430,10 +1628,6 @@ declare interface SettingsSectionContribution {
     actions?: SettingsAction[];
 }
 
-export declare const shouldRefreshWorkbenchExtensionDataTableRenderers: (metadata: WorkbenchExtensionMetadata, commandId: string) => boolean;
-
-export declare const shouldRefreshWorkbenchExtensionTrees: (metadata: WorkbenchExtensionMetadata, commandId: string) => boolean;
-
 declare type SortDirection = "asc" | "desc";
 
 /**
@@ -1461,6 +1655,17 @@ declare interface ThemeRegistry {
     listThemes(): readonly ThemePreferenceOption[];
 }
 
+export declare const toPanelPlacements: (show: DeclaredPanelPlacement | readonly DeclaredPanelPlacement[] | undefined) => any[];
+
+export declare const toWorkbenchCompositionPanelContribution: (input: {
+    panel: ExtensionPanelRecord;
+    rendererId: string;
+    declarationIndex: number;
+    menuDeclarationOffset: number;
+    resourcePanels?: ExtensionResourcePanels;
+    config?: WorkbenchPanelContribution["config"];
+}) => WorkbenchPanelContribution;
+
 declare interface TreeAction {
     id: string;
     label?: string;
@@ -1607,6 +1812,7 @@ declare interface WidgetContribution {
     mountStrategy?: WidgetMountStrategy;
     closable?: boolean;
     hiddenByDefault?: boolean;
+    subPanelsOnly?: boolean;
     regionSize?: WorkbenchRegionSize;
     regionCollapsible?: boolean;
     headerBorderBottom?: boolean;
@@ -1615,7 +1821,6 @@ declare interface WidgetContribution {
     priority?: number;
     rendererId: string;
     openCommandId?: string;
-    role?: WorkbenchWidgetRole;
     eligibleLocations?: WorkbenchLocationEligibility;
     panelMenuOwner?: WorkbenchPanelMenuOwner;
     tab?: WorkbenchWidgetTab;
@@ -1715,6 +1920,35 @@ declare interface WorkbenchCommandParamsRequest {
     context?: WorkbenchCommandExecutionContext;
 }
 
+declare interface WorkbenchComposition {
+    resourceKinds: readonly CompositionResourceKindDefinition[];
+    panels: readonly CompositionPanelDefinition[];
+    resourcePanels: readonly CompositionResourcePanelEdge[];
+}
+
+declare interface WorkbenchCompositionAddablePanel extends WorkbenchModeAddablePanel {
+    contribution: RegisteredWidgetContribution;
+}
+
+declare interface WorkbenchCompositionController {
+    panelsFor(region: WorkbenchPanelRegion): WorkbenchCompositionRegionPanels;
+}
+
+declare interface WorkbenchCompositionRegionPanels {
+    open: readonly WorkbenchWidgetPlacement[];
+    addable: readonly WorkbenchCompositionAddablePanel[];
+    closable: readonly string[];
+}
+
+export declare interface WorkbenchCompositionRegistry {
+    registerResourceKind(definition: CompositionResourceKindDefinition): Disposable_2;
+    registerPanelCapability(definition: CompositionPanelDefinition): Disposable_2;
+    registerResourcePanel(edge: CompositionResourcePanelEdge): Disposable_2;
+    registerModeComposition(definition: CompositionModeDefinition): Disposable_2;
+    getComposition(): WorkbenchComposition;
+    getModeComposition(modeId: string): CompositionModeDefinition | undefined;
+}
+
 declare interface WorkbenchCore extends WorkbenchCoreContributionContext {
     host: WorkbenchHost;
     registerModule(module: WorkbenchModuleContribution): Disposable_2;
@@ -1726,6 +1960,7 @@ declare interface WorkbenchCoreContributionContext {
     commandPalette: WorkbenchCommandPaletteController;
     commandPaletteResources: CommandPaletteResourceRegistry;
     commands: CommandRegistry;
+    composition: WorkbenchCompositionController;
     context: ContextKeyService;
     focus: WorkbenchFocusController;
     history: HistoryController;
@@ -1734,6 +1969,7 @@ declare interface WorkbenchCoreContributionContext {
     layout: WorkbenchLayoutModel;
     modes: WorkbenchModeRegistry;
     navigation: NavigationRegistry;
+    navigator: WorkbenchNavigator;
     notifications: NotificationRegistry;
     panels: WorkbenchPanelsController;
     preferences: PreferenceRegistry;
@@ -1808,6 +2044,8 @@ export declare interface WorkbenchExtensionKanbanRendererAdapter {
         row: KanbanRendererRow_2;
         resource: ResourceRef | undefined;
     }) => void;
+    /** Translate extension navigation resource targets into host resources. */
+    resolveNavigationResource?: (record: WorkbenchExtensionKanbanRendererRecord, resource: NonNullable<CommandExecuteRequest["resource"]>) => ResourceRef;
     /** Called after a successful renderer-owned create form submission. */
     onAfterCreate?: (input: {
         record: WorkbenchExtensionKanbanRendererRecord;
@@ -1841,6 +2079,12 @@ export declare type WorkbenchExtensionMenuWhenBuilder = (contribution: Extension
 
 export { WorkbenchExtensionMetadata }
 
+declare interface WorkbenchExtensionRefreshEvent extends FileRendererRefreshEnvelope {
+    id: string;
+}
+
+export declare type WorkbenchExtensionRendererKind = "tree" | "file" | "controls" | "dataTable" | "kanban";
+
 export declare type WorkbenchExtensionRoute = WorkbenchExtensionMetadata["routes"][number];
 
 export declare interface WorkbenchExtensionRouteResourceInput {
@@ -1904,7 +2148,7 @@ declare interface WorkbenchLayoutStoreState {
     placeholders: Partial<Record<WorkbenchRegion, RegisteredPlaceholderContribution>>;
 }
 
-declare type WorkbenchLocationContribution = Omit<WidgetContribution, "role"> & WorkbenchPanelMenusContribution;
+declare type WorkbenchLocationContribution = WidgetContribution & WorkbenchPanelMenusContribution;
 
 declare interface WorkbenchLocationEligibility {
     modeIds?: string[];
@@ -1926,15 +2170,31 @@ declare type WorkbenchModeActivationContext = WorkbenchCoreContributionContext;
 
 declare type WorkbenchModeActivationResult = Disposable_2 | readonly Disposable_2[] | undefined;
 
+declare interface WorkbenchModeAddablePanel {
+    panelId: string;
+    region: WorkbenchPanelRegion;
+    allowedRegions?: readonly WorkbenchRegion[];
+    pinned?: boolean;
+}
+
+declare interface WorkbenchModeAddablePanelContext {
+    layout: WorkbenchLayout;
+    resource?: ResourceRef;
+}
+
 declare type WorkbenchModeChangeListener = () => void;
 
 declare interface WorkbenchModeContribution {
     id: string;
     label?: string;
     panels?: readonly WorkbenchPanelRegion[];
+    resourceKinds?: readonly string[];
+    defaultResource?: ResourceRef | (() => Promise<ResourceRef | undefined> | ResourceRef | undefined);
+    listAddablePanels?(context: WorkbenchModeAddablePanelContext): readonly WorkbenchModeAddablePanel[];
     activate(ctx: WorkbenchModeActivationContext): WorkbenchModeActivationResult;
     seed?(ctx: WorkbenchModeActivationContext): void;
     enter?(ctx: WorkbenchModeActivationContext): WorkbenchModeActivationResult;
+    reconcile?(ctx: WorkbenchModeActivationContext): void;
 }
 
 declare interface WorkbenchModeRegistry {
@@ -1970,6 +2230,14 @@ declare interface WorkbenchModuleContribution {
 
 declare type WorkbenchModuleContributionContext = WorkbenchModuleContext;
 
+declare interface WorkbenchNavigationCommit {
+    modeId: string | undefined;
+    resource: ResourceRef | undefined;
+    replaceActive: boolean;
+}
+
+declare type WorkbenchNavigationDiagnosticCode = "navigation_mode_missing" | "navigation_resource_missing" | "navigation_resource_incompatible" | "navigation_default_missing" | "navigation_target_stale";
+
 declare interface WorkbenchNavigationEntry {
     entryId: string;
     recordedAt: number;
@@ -1984,6 +2252,53 @@ declare interface WorkbenchNavigationEntry {
     closedSubPanel?: WorkbenchClosedSubPanel;
 }
 
+declare type WorkbenchNavigationResult = {
+    ok: true;
+    modeId: string | undefined;
+    resource: ResourceRef | undefined;
+} | {
+    ok: false;
+    code: WorkbenchNavigationDiagnosticCode;
+    message: string;
+};
+
+declare interface WorkbenchNavigationTarget {
+    modeId?: string;
+    resource?: ResourceRef;
+    replaceActive?: boolean;
+}
+
+declare interface WorkbenchNavigator {
+    configure(hooks: WorkbenchNavigatorHostHooks): void;
+    getSelectedResource(): ResourceRef | undefined;
+    open(target: WorkbenchNavigationTarget): Promise<WorkbenchNavigationResult>;
+    commitContext(input: WorkbenchNavigatorCommitInput): WorkbenchNavigationResult;
+    getLastResource(projectId: string | undefined, modeId: string): ResourceRef | undefined;
+    forgetResource(uri: string): void;
+    onDidCommit(listener: (commit: WorkbenchNavigationCommit) => void): {
+        dispose(): void;
+    };
+}
+
+declare interface WorkbenchNavigatorCommitInput {
+    modeId?: string | null;
+    resource?: ResourceRef | null;
+    replaceActive?: boolean;
+    present?: boolean;
+}
+
+declare interface WorkbenchNavigatorHostHooks {
+    getProjectId?(): string | undefined;
+    getSelectedResource?(): ResourceRef | undefined;
+    interpretSelection?(resource: ResourceRef): ResourceRef | undefined;
+    applySelection?(resource: ResourceRef | undefined): void;
+    applyScope?(commit: WorkbenchNavigationCommit): void;
+    applyBreadcrumb?(resource: ResourceRef | undefined): void;
+    presentResource?(resource: ResourceRef, input: {
+        replaceActive: boolean;
+    }): Promise<unknown> | unknown;
+}
+
 declare interface WorkbenchNotification {
     id?: string;
     level: WorkbenchNotificationLevel;
@@ -2025,11 +2340,11 @@ declare interface WorkbenchPanelContribution {
     region: WorkbenchRegion;
     fallbackRegion?: WorkbenchRegion;
     rendererId: string;
-    closable: boolean;
     singleton?: boolean;
     reuse?: WorkbenchPanelReusePolicy;
     mountStrategy?: WorkbenchPanelMountStrategy;
     hiddenByDefault?: boolean;
+    subPanelsOnly?: boolean;
     regionSize?: WorkbenchRegionSize;
     regionCollapsible?: boolean;
     headerBorderBottom?: boolean;
@@ -2080,7 +2395,7 @@ declare interface WorkbenchPanelInstance_2 {
     tab?: WorkbenchPanelTab_2;
 }
 
-declare type WorkbenchPanelMenuContribution = Omit<WidgetContribution, "region" | "fallbackRegion" | "role"> & {
+declare type WorkbenchPanelMenuContribution = Omit<WidgetContribution, "region" | "fallbackRegion"> & {
     region: WorkbenchPanelMenuRegion;
     fallbackRegion?: WorkbenchPanelMenuRegion;
 };
@@ -2138,13 +2453,14 @@ declare type WorkbenchPanelMountStrategy = WidgetMountStrategy;
 declare type WorkbenchPanelMountStrategy_2 = WidgetMountStrategy_2;
 
 declare type WorkbenchPanelOpenStrategy = {
-    kind: "activate-or-open";
+    kind: "persistent";
     position?: WorkbenchTabPosition;
 } | {
     kind: "replace-active";
 } | {
     kind: "replace-panel";
     instanceId: string;
+    retention?: WorkbenchTabRetention;
 } | {
     kind: "preview";
     position?: WorkbenchTabPosition;
@@ -2285,7 +2601,7 @@ declare type WorkbenchStoreSelector<TState, TValue> = (state: TState) => TValue;
 
 declare type WorkbenchStoreSelectorListener<TValue> = (value: TValue, previousValue: TValue) => void;
 
-declare type WorkbenchSubPanelContribution = Omit<WidgetContribution, "region" | "fallbackRegion" | "role"> & {
+declare type WorkbenchSubPanelContribution = Omit<WidgetContribution, "region" | "fallbackRegion"> & {
     region: WorkbenchPanelRegion;
     fallbackRegion?: WorkbenchPanelRegion;
 } & WorkbenchPanelMenusContribution;