@hachej/boring-workspace 0.1.59 → 0.1.60

package/dist/workspace.d.ts

@@ -7,12 +7,14 @@ import { DockviewApi } from 'dockview-react';
 import { DockviewPanelApi } from 'dockview-react';
 import { ErrorInfo } from 'react';
 import { Extension } from '@codemirror/state';
+import { FunctionComponentElement } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { JSXElementConstructor } from 'react';
 import { LucideIcon } from 'lucide-react';
 import { MouseEvent as MouseEvent_2 } from 'react';
 import { PersistOptions } from 'zustand/middleware';
 import { PiChatPanelProps } from '@hachej/boring-agent/front';
+import { ProviderProps } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { ReactPortal } from 'react';
@@ -82,10 +84,12 @@ export declare interface BootstrapOptions {
     excludeDefaults?: string[];
     registries: {
         panels: PanelRegistryLike;
+        workspaceSources?: WorkspaceSourceRegistryLike;
         commands: CommandRegistryLike;
         catalogs: CatalogRegistryLike;
         surfaceResolvers?: SurfaceResolverRegistryLike;
     };
+    panelCommandRunner?: (command: BoringFrontPanelCommandRegistration) => (() => void) | undefined;
 }
 
 export declare interface BootstrapResult {
@@ -98,8 +102,8 @@ declare interface BoringFrontAPI {
     registerBinding(registration: BoringFrontBindingRegistration): void;
     registerCatalog(registration: CatalogConfig): void;
     registerPanel<T = unknown>(registration: BoringFrontPanelRegistration<T>): void;
+    registerWorkspaceSource<T = unknown>(registration: BoringFrontWorkspaceSourceRegistration<T>): void;
     registerPanelCommand(registration: BoringFrontPanelCommandRegistration): void;
-    registerLeftTab<T = LeftTabParams>(registration: BoringFrontLeftTabRegistration<T>): void;
     registerSurfaceResolver(registration: BoringFrontSurfaceResolverRegistration): void;
     registerToolRenderer(registration: BoringFrontToolRendererRegistration): void;
 }
@@ -121,20 +125,6 @@ declare type BoringFrontFactoryWithId = BoringFrontFactory & {
     pluginLabel?: string;
 };
 
-declare interface BoringFrontLeftTabRegistration<T = LeftTabParams> {
-    id: string;
-    title: string;
-    panelId: string;
-    icon?: ComponentType<{
-        className?: string;
-    }>;
-    component?: PanelConfig<T>["component"];
-    lazy?: boolean;
-    chromeless?: boolean;
-    requiresCapabilities?: string[];
-    source?: string;
-}
-
 declare interface BoringFrontPanelCommandRegistration {
     id: string;
     title: string;
@@ -154,7 +144,7 @@ declare interface BoringFrontPanelRegistration<T = unknown> {
     icon?: ComponentType<{
         className?: string;
     }>;
-    placement?: string;
+    placement?: PanelConfig["placement"];
     requiresCapabilities?: string[];
     essential?: boolean;
     lazy?: boolean;
@@ -171,6 +161,11 @@ declare interface BoringFrontProviderRegistration {
 declare interface BoringFrontSurfaceResolverRegistration {
     id?: string;
     kind: string;
+    title?: string;
+    description?: string;
+    targetHint?: string;
+    examples?: SurfaceResolverExample[];
+    metaSchema?: Record<string, unknown>;
     source?: string;
     resolve: (request: SurfaceOpenRequest) => SurfacePanelResolution | null | undefined;
 }
@@ -182,6 +177,22 @@ declare interface BoringFrontToolRendererRegistration {
     render: BoringFrontToolRenderer;
 }
 
+declare interface BoringFrontWorkspaceSourceRegistration<T = unknown> {
+    id: string;
+    component: ComponentType<WorkspaceSourceProps<T>> | (() => Promise<{
+        default: ComponentType<WorkspaceSourceProps<T>>;
+    }>);
+    label?: string;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    requiresCapabilities?: string[];
+    lazy?: boolean;
+    chromeless?: boolean;
+    defaultPanelId?: string;
+    source?: string;
+}
+
 export declare interface BridgeClient {
     connect(): void;
     disconnect(): void;
@@ -257,8 +268,8 @@ declare interface CapturedBoringFrontRegistrations {
     bindings: BoringFrontBindingRegistration[];
     catalogs: CatalogConfig[];
     panels: BoringFrontPanelRegistration<any>[];
+    workspaceSources: BoringFrontWorkspaceSourceRegistration<any>[];
     panelCommands: BoringFrontPanelCommandRegistration[];
-    leftTabs: BoringFrontLeftTabRegistration<any>[];
     surfaceResolvers: BoringFrontSurfaceResolverRegistration[];
     toolRenderers: BoringFrontToolRendererRegistration[];
 }
@@ -386,6 +397,10 @@ export declare interface ChatLayoutProps {
     flashChatPaneId?: string | null;
     surface?: string | null;
     surfaceParams?: Record<string, unknown>;
+    /** Opaque overlay rendered over the full chat stage only (not over the workbench). */
+    chatOverlay?: ReactNode;
+    /** Called when shell chrome needs to dismiss the chat overlay before collapsing chat. */
+    onCloseChatOverlay?: () => void;
     surfaceOverlay?: ReactNode;
     sidebar?: string | null;
     sidebarParams?: Record<string, unknown>;
@@ -420,6 +435,7 @@ export declare function CodeEditorPane({ params, api, className }: CodeEditorPan
 
 export declare type CodeEditorPaneProps = PaneProps<{
     path?: string;
+    mode?: "view" | "edit" | "diff";
 }>;
 
 export declare interface CodeEditorProps {
@@ -442,9 +458,29 @@ export declare interface CommandConfig {
     pluginId?: string;
 }
 
-export declare function CommandPalette(_props?: CommandPaletteProps): JSX.Element;
+export declare function CommandPalette({ sessionSearch, apiBaseUrl, authHeaders }?: CommandPaletteProps): JSX.Element;
+
+export declare interface CommandPaletteProps {
+    sessionSearch?: CommandPaletteSessionSearchConfig;
+    apiBaseUrl?: string;
+    authHeaders?: Record<string, string>;
+}
+
+declare interface CommandPaletteSessionItem {
+    id: string;
+    title?: string | null;
+    updatedAt?: string | number;
+    turnCount?: number;
+}
 
-export declare type CommandPaletteProps = Record<string, never>;
+declare interface CommandPaletteSessionSearchConfig {
+    sessions: CommandPaletteSessionItem[];
+    activeId?: string | null;
+    openIds?: readonly string[];
+    search?: (sessions: readonly CommandPaletteSessionItem[], query: string) => CommandPaletteSessionItem[];
+    onSwitch: (id: string) => void;
+    onOpenAsTab: (id: string) => void;
+}
 
 export declare class CommandRegistry {
     private commands;
@@ -490,6 +526,8 @@ export declare function createShadcnTheme(options?: {
     dark?: boolean;
 }): Extension[];
 
+export declare function createWorkspacePluginClient(apiBaseUrl: string, workspaceId?: string, authHeaders?: Record<string, string>): WorkspacePluginClient;
+
 export declare function createWorkspaceStore(options?: CreateWorkspaceStoreOptions): {
     (): WorkspaceStore;
     <U>(selector: (state: WorkspaceStore) => U): U;
@@ -651,7 +689,7 @@ export declare interface EmptyPaneProps {
  * Tiny typed event bus. ~30 lines, no runtime deps.
  *
  * Design constraints (locked by reviewer feedback in
- * `docs/plans/UNIFIED_EVENT_BUS.md`):
+ * `packages/workspace/docs/plans/archive/UNIFIED_EVENT_BUS.md`):
  *
  * - Synchronous emit only. Slow subscribers fire-and-forget their own async work.
  * - Snapshot listeners before iterating so subscribe / unsubscribe
@@ -1017,7 +1055,7 @@ export declare interface LayoutConfig {
     groups: GroupConfig[];
 }
 
-export declare type LeftTabComponent = ComponentType<PaneProps<LeftTabParams>>;
+export declare type LeftTabComponent = ComponentType<WorkspaceSourceProps<LeftTabParams>>;
 
 export declare interface LeftTabParams {
     rootDir?: string;
@@ -1039,6 +1077,7 @@ export declare function MarkdownEditorPane({ params, api, className }: MarkdownE
 
 export declare type MarkdownEditorPaneProps = PaneProps<{
     path?: string;
+    mode?: "view" | "edit" | "diff";
 }>;
 
 export declare interface MarkdownEditorProps {
@@ -1173,14 +1212,12 @@ export declare interface PanelConfig<T = any> {
     icon?: ComponentType<{
         className?: string;
     }>;
-    /** Placement hint: "left" | "center" | "right" | "bottom" | "left-tab" | "right-tab" */
-    placement?: string;
+    /** Placement hint. Public plugin placements: "workspace-page" | "shared-dockview". */
+    placement?: PanelPlacement | string;
     requiresCapabilities?: string[];
     essential?: boolean;
     chromeless?: boolean;
     supportsFullPage?: boolean;
-    /** Center-panel id opened when this config is used as a left-tab category. */
-    defaultPanelId?: string;
     /** Source: "builtin" | "app" */
     source?: string;
     pluginId?: string;
@@ -1224,6 +1261,8 @@ export declare interface PanelLifecycleApi {
     isActive: boolean;
 }
 
+declare type PanelPlacement = "left" | "center" | "right" | "bottom" | "shared-dockview" | "workspace-page" | "right-tab";
+
 export declare type PanelRegistration<T = any> = Omit<PanelConfig<T>, 'id'>;
 
 export declare class PanelRegistry {
@@ -1311,7 +1350,7 @@ export declare type PluginBinding = ComponentType<unknown>;
 export declare interface PluginContributionError {
     kind: "contribution";
     pluginId: string;
-    contributionKind: "panel" | "catalog-row" | "chat-suggestion";
+    contributionKind: "panel" | "workspace-source" | "catalog-row" | "chat-suggestion";
     contributionId?: string;
     error: Error;
     componentStack?: string | null;
@@ -1360,7 +1399,7 @@ export declare function postUiCommand(command: UiCommand): void;
 
 declare interface Props {
     pluginId: string;
-    contributionKind: "panel" | "catalog-row" | "chat-suggestion";
+    contributionKind: "panel" | "workspace-source" | "catalog-row" | "chat-suggestion";
     contributionId?: string;
     children?: ReactNode;
     onError?: (error: Error, info: ErrorInfo) => void;
@@ -1385,10 +1424,11 @@ declare interface RegisteredPluginMeta {
     label?: string;
 }
 
-export declare function RegistryProvider({ panelRegistry, commandRegistry, catalogRegistry, surfaceResolverRegistry, children, }: RegistryProviderProps): JSX.Element;
+export declare function RegistryProvider({ panelRegistry, workspaceSourceRegistry, commandRegistry, catalogRegistry, surfaceResolverRegistry, children, }: RegistryProviderProps): JSX.Element;
 
 declare interface RegistryProviderProps {
     panelRegistry: PanelRegistry;
+    workspaceSourceRegistry?: WorkspaceSourceRegistry;
     commandRegistry: CommandRegistry;
     catalogRegistry?: CatalogRegistry;
     surfaceResolverRegistry?: SurfaceResolverRegistry;
@@ -1489,13 +1529,28 @@ export declare interface SurfacePanelResolution {
     score?: number;
 }
 
-export declare interface SurfaceResolverConfig {
+export declare interface SurfaceResolverConfig extends SurfaceResolverMetadata {
     id: string;
     resolve: (request: SurfaceOpenRequest) => SurfacePanelResolution | undefined;
     source?: string;
     pluginId?: string;
 }
 
+declare interface SurfaceResolverExample {
+    target: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+}
+
+declare interface SurfaceResolverMetadata {
+    kind?: string;
+    title?: string;
+    description?: string;
+    targetHint?: string;
+    examples?: SurfaceResolverExample[];
+    metaSchema?: Record<string, unknown>;
+}
+
 export declare type SurfaceResolverRegistration = Omit<SurfaceResolverConfig, "id">;
 
 export declare class SurfaceResolverRegistry {
@@ -1526,11 +1581,13 @@ export declare interface SurfaceResolverRegistryLike {
     register(id: string, config: SurfaceResolverRegistration): void;
 }
 
-export declare function SurfaceShell({ rootDir, sidebarDefaultWidth, sidebarMinWidth, sidebarMaxWidth, storageKey, onReady, onChange, onClose, extraPanels, defaultLeftTab, onReloadAgentPlugins, initialPanels, className, }: SurfaceShellProps): JSX.Element;
+export declare function SurfaceShell({ rootDir, sidebarDefaultWidth, sidebarMinWidth, sidebarMaxWidth, storageKey, onReady, onChange, onClose, showCloseAction, extraPanels, defaultLeftTab, onReloadAgentPlugins, initialPanels, className, }: SurfaceShellProps): JSX.Element;
 
 export declare interface SurfaceShellApi {
     /** Open a file in the workbench. Idempotent — re-activates an existing pane for the same path. */
-    openFile: (path: string) => void;
+    openFile: (path: string, opts?: {
+        mode?: "view" | "edit" | "diff";
+    }) => void;
     /** Open a plugin-defined surface target through the registered surface resolvers. */
     openSurface: (request: SurfaceOpenRequest) => void;
     /**
@@ -1560,6 +1617,8 @@ export declare interface SurfaceShellProps {
     onChange?: (snapshot: SurfaceShellSnapshot) => void;
     /** Optional close action for hosts that model the workbench as collapsible. */
     onClose?: () => void;
+    /** Render the built-in top-right close affordance. Hosts can set false when they provide their own chrome. */
+    showCloseAction?: boolean;
     /**
      * Extra panel ids (registered via WorkspaceProvider's `panels` prop) that
      * this workbench is allowed to render. Defaults to the built-in
@@ -1590,6 +1649,8 @@ export declare interface SurfaceShellSnapshot {
 
 export declare interface SurfaceShellTab {
     id: string;
+    /** Registered panel component id for this tab. May differ from the tab instance id. */
+    component?: string;
     title: string;
     params?: Record<string, unknown>;
 }
@@ -1887,9 +1948,13 @@ export declare function useWorkspaceContext(): WorkspaceContextValue;
 
 export declare function useWorkspaceContextOptional(): WorkspaceContextValue | null;
 
+export declare function useWorkspacePluginClient(): WorkspacePluginClient;
+
 export declare function useWorkspaceRequestId(): string | null;
 
-export declare function WorkbenchLeftPane({ rootDir, bridge, defaultTab, revealFileTreeRequest, onOpenPanel, onReloadAgentPlugins, onCollapse, className, }: WorkbenchLeftPaneProps): JSX.Element;
+export declare function useWorkspaceSourceRegistry(): WorkspaceSourceRegistry;
+
+export declare function WorkbenchLeftPane({ rootDir, bridge, defaultTab, activeTab: controlledActiveTab, activePanelId, onActiveTabChange, revealFileTreeRequest, onOpenPanel, onReloadAgentPlugins, onCollapse, onExpand, onCloseSourcePane, railOnly, className, }: WorkbenchLeftPaneProps): JSX.Element;
 
 declare interface WorkbenchLeftPaneOpenPanelConfig {
     id: string;
@@ -1902,6 +1967,14 @@ export declare interface WorkbenchLeftPaneProps {
     rootDir?: string;
     bridge?: FileTreeBridge;
     defaultTab?: WorkbenchLeftTabId;
+    activeTab?: WorkbenchLeftTabId;
+    /**
+     * Id of the currently-focused surface tab (dockview's active panel). Drives the
+     * accent for "workspace-page" rail icons so a page only glows while it's the open
+     * tab — `activeTab` is the rail's own click state and goes stale on tab switches.
+     */
+    activePanelId?: string | null;
+    onActiveTabChange?: (tab: WorkbenchLeftTabId) => void;
     revealFileTreeRequest?: {
         path: string;
         seq: number;
@@ -1909,6 +1982,9 @@ export declare interface WorkbenchLeftPaneProps {
     onOpenPanel?: (config: WorkbenchLeftPaneOpenPanelConfig) => void;
     onReloadAgentPlugins?: () => void | Promise<unknown>;
     onCollapse?: () => void;
+    onExpand?: (tab?: WorkbenchLeftTabId) => void;
+    onCloseSourcePane?: () => void;
+    railOnly?: boolean;
     className?: string;
 }
 
@@ -2169,6 +2245,34 @@ declare type WorkspacePanelMatch = {
     value: string;
 };
 
+export declare interface WorkspacePluginClient {
+    apiBaseUrl: string;
+    workspaceId?: string;
+    workspaceHeaders(): Record<string, string>;
+    getJson<T = unknown>(path: string, options?: {
+        missingMessage?: string;
+    }): Promise<T>;
+    readJsonFile<T>(path: string, options?: {
+        missingMessage?: string;
+    }): Promise<T>;
+    postJson<T = unknown>(path: string, body?: unknown, options?: {
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    sendAgentPrompt(message: string, options?: {
+        title?: string;
+        noncePrefix?: string;
+    }): Promise<void>;
+}
+
+export declare function WorkspacePluginClientProvider({ apiBaseUrl, workspaceId, authHeaders, children, }: WorkspacePluginClientProviderProps): FunctionComponentElement<ProviderProps<WorkspacePluginClient | null>>;
+
+declare interface WorkspacePluginClientProviderProps {
+    apiBaseUrl: string;
+    workspaceId?: string;
+    authHeaders?: Record<string, string>;
+    children: ReactNode;
+}
+
 /**
  * Built-in plugin events baked into the public workspace event map.
  *
@@ -2196,7 +2300,7 @@ export declare interface WorkspacePluginEventMap {
     };
 }
 
-export declare function WorkspaceProvider({ children, chatPanel, plugins, excludeDefaults, panels, commands, catalogs, capabilities, apiBaseUrl, authHeaders, apiTimeout, activeSessionId, openSessionIds, defaultTheme, onThemeChange, workspaceId, workspaceLabel, appTitle, storageKey, persistenceEnabled, manageDocumentTitle, bridgeEndpoint, onAuthError, onOpenFile, debug, frontPluginHotReload, fullPageBasePath, }: WorkspaceProviderProps): JSX.Element;
+export declare function WorkspaceProvider({ children, chatPanel, plugins, excludeDefaults, panels, commands, catalogs, capabilities, apiBaseUrl, authHeaders, apiTimeout, activeSessionId, openSessionIds, defaultTheme, onThemeChange, workspaceId, workspaceLabel, appTitle, storageKey, persistenceEnabled, manageDocumentTitle, bridgeEndpoint, onAuthError, onOpenFile, debug, frontPluginHotReload, fullPageBasePath, commandPaletteSessionSearch, }: WorkspaceProviderProps): JSX.Element;
 
 export declare interface WorkspaceProviderProps {
     children: ReactNode;
@@ -2239,6 +2343,76 @@ export declare interface WorkspaceProviderProps {
      */
     frontPluginHotReload?: FrontPluginHotReloadMode;
     fullPageBasePath?: string;
+    commandPaletteSessionSearch?: CommandPaletteSessionSearchConfig;
+}
+
+export declare interface WorkspaceSourceConfig<T = any> {
+    id: string;
+    title: string;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    component: ComponentType<WorkspaceSourceProps<T>> | (() => Promise<{
+        default: ComponentType<WorkspaceSourceProps<T>>;
+    }>);
+    requiresCapabilities?: string[];
+    chromeless?: boolean;
+    /** Panel id opened in the main workspace when this source is selected. */
+    defaultPanelId?: string;
+    /** Source: "builtin" | "app" */
+    source?: string;
+    pluginId?: string;
+    /** Revision emitted by the runtime plugin asset manager for hot-loaded sources. */
+    pluginRevision?: number;
+    lazy?: boolean;
+}
+
+export declare interface WorkspaceSourceOpenPanelConfig {
+    id: string;
+    component: string;
+    title?: string;
+    params?: Record<string, unknown>;
+}
+
+/**
+ * Props for workspace source panes hosted in the left workspace rail.
+ * These are not Dockview panels: they receive only source-pane params and
+ * the explicit actions that the source host supports.
+ */
+export declare interface WorkspaceSourceProps<T = unknown> {
+    params: T;
+    className?: string;
+    openPanel?: (config: WorkspaceSourceOpenPanelConfig) => void;
+}
+
+export declare type WorkspaceSourceRegistration<T = any> = Omit<WorkspaceSourceConfig<T>, 'id'>;
+
+export declare class WorkspaceSourceRegistry {
+    private sources;
+    private registrationOrder;
+    private capabilities;
+    private listeners;
+    private snapshotCache;
+    private lazyComponentCache;
+    constructor(capabilities?: Record<string, boolean>);
+    register(id: string, config: WorkspaceSourceRegistration): void;
+    unregister(id: string): void;
+    replaceByPluginId(pluginId: string, sources: WorkspaceSourceConfig[]): void;
+    get(id: string): WorkspaceSourceConfig | undefined;
+    has(id: string): boolean;
+    getComponent(sourceId: string): ComponentType<any> | undefined;
+    list(): WorkspaceSourceConfig[];
+    listAll(): WorkspaceSourceConfig[];
+    subscribe: (cb: () => void) => (() => void);
+    getSnapshot: () => readonly WorkspaceSourceConfig[];
+    private getLazyComponent;
+    private emit;
+    private filteredSources;
+    private satisfiesCapabilities;
+}
+
+export declare interface WorkspaceSourceRegistryLike {
+    register(id: string, config: WorkspaceSourceRegistration): void;
 }
 
 export declare interface WorkspaceState {