@hachej/boring-workspace 0.1.22 → 0.1.24

package/dist/workspace.d.ts

@@ -39,6 +39,7 @@ export declare interface AgentTool {
     name: string;
     description: string;
     promptSnippet?: string;
+    readinessRequirements?: ToolReadinessRequirement[];
     parameters: JSONSchema;
     execute(params: Record<string, unknown>, ctx: ToolExecContext): Promise<ToolResult>;
 }
@@ -155,6 +156,7 @@ declare interface BoringFrontPanelRegistration<T = unknown> {
     essential?: boolean;
     lazy?: boolean;
     chromeless?: boolean;
+    supportsFullPage?: boolean;
     source?: string;
 }
 
@@ -230,6 +232,14 @@ export declare interface BridgeEventMap {
 
 export declare function buildChatLayout(props?: ChatLayoutProps): LayoutConfig;
 
+export declare function buildFullPagePanelHref({ componentId, params, basePath }: BuildFullPagePanelHrefInput): string;
+
+export declare interface BuildFullPagePanelHrefInput {
+    componentId: string;
+    params?: Record<string, unknown>;
+    basePath: string;
+}
+
 export declare function buildIdeLayout(props?: IdeLayoutProps): LayoutConfig;
 
 declare interface CapturedBoringFrontRegistrations {
@@ -358,11 +368,13 @@ export declare interface ChatLayoutProps {
     centerParams?: Record<string, unknown>;
     surface?: string | null;
     surfaceParams?: Record<string, unknown>;
+    surfaceOverlay?: ReactNode;
     sidebar?: string | null;
     sidebarParams?: Record<string, unknown>;
     storageKey?: string;
     onOpenNav?: () => void;
     onOpenSurface?: () => void;
+    surfaceButtonBottomOffset?: number;
     onOpenSidebar?: () => void;
     className?: string;
 }
@@ -487,6 +499,15 @@ export declare interface CreateWorkspaceStoreOptions {
     onLayoutVersionMismatch?: () => void;
 }
 
+declare interface DataProviderProps {
+    apiBaseUrl: string;
+    authHeaders?: Record<string, string>;
+    onAuthError?: (statusCode: number) => void;
+    timeout?: number;
+    client?: FetchClient;
+    children: ReactNode;
+}
+
 /**
  * Identity helper for type-safe panel registration. Pure runtime
  * passthrough — the value of this is forcing TypeScript to verify that
@@ -518,6 +539,8 @@ export declare interface DispatchContext {
     isWorkbenchOpen: () => boolean;
     /** Toggle the workbench pane open. Must be a no-op when already open. */
     openWorkbench: () => void;
+    /** Open the workbench sources/file-tree pane. Must be a no-op when already open. */
+    openWorkbenchSources?: () => void;
     /** Close the workbench pane when a command opened it only for an ephemeral task. */
     closeWorkbench?: () => void;
 }
@@ -622,6 +645,93 @@ export declare const expandToFileSchema: z.ZodObject<{
     path: string;
 }>;
 
+declare class FetchClient {
+    private baseUrl;
+    private headers;
+    private onAuthError?;
+    private onTimeout?;
+    private timeout;
+    private maxRetries;
+    private retryBaseMs;
+    constructor(opts: FetchClientOptions);
+    private request;
+    getTree(path: string, signal?: AbortSignal): Promise<FileEntry[]>;
+    getFile(path: string, signal?: AbortSignal): Promise<FileContent>;
+    /**
+     * Write file content. When `expectedMtimeMs` is supplied, the server
+     * runs an optimistic-concurrency check and returns 409 if the file
+     * has been modified since that mtime — surfaced here as a typed
+     * `FileConflictError` so the editor can ask the user to reload or
+     * force-overwrite. The returned `mtimeMs` is the server's stat
+     * after the write; callers use it as the OCC baseline for the
+     * next save.
+     */
+    writeFile(path: string, content: string, opts?: {
+        expectedMtimeMs?: number;
+    }): Promise<{
+        mtimeMs?: number;
+    }>;
+    deleteFile(path: string): Promise<void>;
+    stat(path: string, signal?: AbortSignal): Promise<FileStat>;
+    search(query: string, limit?: number, signal?: AbortSignal): Promise<string[]>;
+    createDir(path: string): Promise<void>;
+    moveFile(from: string, to: string): Promise<void>;
+}
+
+declare interface FetchClientOptions {
+    apiBaseUrl: string;
+    authHeaders?: Record<string, string>;
+    onAuthError?: (statusCode: number) => void;
+    onTimeout?: (route: string) => void;
+    timeout?: number;
+    maxRetries?: number;
+    retryBaseMs?: number;
+}
+
+declare class FetchError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(status: number, message: string, body?: unknown | undefined);
+}
+
+/**
+ * Thrown by `writeFile` when the server returns 409 because the file
+ * has been modified since the client's last read. Carries the
+ * server's current mtime so the editor can show the user a
+ * Reload-vs-Overwrite choice with the actual conflict context.
+ */
+declare class FileConflictError extends Error {
+    readonly path: string;
+    readonly currentMtimeMs: number | null;
+    readonly expectedMtimeMs: number | null;
+    constructor(path: string, currentMtimeMs: number | null, expectedMtimeMs: number | null);
+    static from(err: FetchError, path: string): FileConflictError;
+}
+
+declare interface FileContent {
+    content: string;
+    /**
+     * Server-stat'd modification time. Used as the OCC baseline for the
+     * next write — the client sends it back as `expectedMtimeMs` so the
+     * server can return 409 if the file changed underneath. Optional
+     * because not every workspace impl can stat cheaply (sandbox
+     * impl is best-effort).
+     */
+    mtimeMs?: number;
+}
+
+declare interface FileEntry {
+    name: string;
+    kind: "file" | "dir";
+    path: string;
+}
+
+declare interface FileStat {
+    size: number;
+    mtimeMs: number;
+    kind: "file" | "dir";
+}
+
 declare const FILESYSTEM_FILE_CHANGED_EVENT = "filesystem:file.changed";
 
 declare const FILESYSTEM_FILE_CREATED_EVENT = "filesystem:file.created";
@@ -668,7 +778,7 @@ export declare const filesystemEvents: {
 
 export declare const filesystemPlugin: BoringFrontFactoryWithId;
 
-export declare function FileTree({ files, selectedPath, searchQuery, height, editing, revealPath, pendingPaths, onSelect, onExpand, onCollapse, onContextMenu, onSubmitEdit, onCancelEdit, onDragDrop, className, }: FileTreeProps): JSX.Element;
+export declare function FileTree({ files, selectedPath, searchQuery, height, editing, revealPath, pendingPaths, onSelect, onExpand, onCollapse, onContextMenu, onSubmitEdit, onCancelEdit, onRevealHandled, onDragDrop, className, }: FileTreeProps): JSX.Element;
 
 declare interface FileTreeEditState {
     /** Path of the row currently being edited (rename target or draft path). */
@@ -705,6 +815,10 @@ declare interface FileTreePaneParams extends LeftTabParams {
     query?: string;
     bridge?: unknown;
     chromeless?: boolean;
+    revealFileTreeRequest?: {
+        path: string;
+        seq: number;
+    } | null;
 }
 
 export declare interface FileTreePaneProps extends Partial<PaneProps<FileTreePaneParams>> {
@@ -732,6 +846,8 @@ export declare interface FileTreeProps {
     onCollapse?: (path: string) => void;
     onContextMenu?: (event: React.MouseEvent, node: FileTreeNode) => void;
     onDragDrop?: (sourcePath: string, targetDirPath: string) => void;
+    /** Called after a reveal request has opened parents and scheduled scrolling. */
+    onRevealHandled?: (path: string) => void;
     /** Called when the user presses Enter on an inline-edit input. */
     onSubmitEdit?: (path: string, value: string) => void;
     /** Called when the user presses Esc or blurs without submitting. */
@@ -750,13 +866,17 @@ export declare interface FileTreeProps {
  * want a "Files" panel; `WorkbenchLeftPane` uses this primitive directly to
  * share its search input with the Data tab.
  */
-export declare function FileTreeView({ rootDir, searchQuery, bridge, ignoreNames, className, }: FileTreeViewProps): JSX.Element;
+export declare function FileTreeView({ rootDir, searchQuery, bridge, revealFileTreeRequest, ignoreNames, className, }: FileTreeViewProps): JSX.Element;
 
 export declare interface FileTreeViewProps {
     rootDir?: string;
     /** Already-debounced query. Empty/undefined means no filter. */
     searchQuery?: string;
-    bridge?: Pick<WorkspaceBridge, "openFile" | "getActiveFile" | "select">;
+    bridge?: Pick<WorkspaceBridge, "openFile" | "getActiveFile" | "select"> & Partial<Pick<WorkspaceBridge, "subscribe">>;
+    revealFileTreeRequest?: {
+        path: string;
+        seq: number;
+    } | null;
     /**
      * Names (or regex patterns) to hide from the tree. Defaults to
      * `DEFAULT_TREE_IGNORE` (node_modules, .git, dist, …). Pass `[]` to
@@ -818,6 +938,10 @@ export declare interface LeftTabParams {
     searchQuery?: string;
     bridge?: unknown;
     chromeless?: boolean;
+    revealFileTreeRequest?: {
+        path: string;
+        seq: number;
+    } | null;
 }
 
 export declare function MarkdownEditor({ content, onChange, readOnly, placeholder, className, documentPath, }: MarkdownEditorProps): JSX.Element;
@@ -965,6 +1089,7 @@ export declare interface PanelConfig<T = any> {
     requiresCapabilities?: string[];
     essential?: boolean;
     chromeless?: boolean;
+    supportsFullPage?: boolean;
     /** Source: "builtin" | "app" */
     source?: string;
     pluginId?: string;
@@ -1050,6 +1175,8 @@ export declare interface PanelRegistryLike {
     register(id: string, config: PanelRegistration): void;
 }
 
+export declare type PanelRenderMode = "dock" | "full-page";
+
 export declare interface PanelState {
     id: string;
     component: string;
@@ -1280,7 +1407,7 @@ export declare interface SurfaceResolverRegistryLike {
     register(id: string, config: SurfaceResolverRegistration): void;
 }
 
-export declare function SurfaceShell({ rootDir, sidebarDefaultWidth, sidebarMinWidth, sidebarMaxWidth, storageKey, onReady, onChange, onClose, extraPanels, defaultLeftTab, className, }: SurfaceShellProps): JSX.Element;
+export declare function SurfaceShell({ rootDir, sidebarDefaultWidth, sidebarMinWidth, sidebarMaxWidth, storageKey, onReady, onChange, onClose, extraPanels, defaultLeftTab, 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. */
@@ -1296,6 +1423,8 @@ export declare interface SurfaceShellApi {
     openPanel: (config: OpenPanelConfig) => void;
     /** Hide the workbench's left sources/files pane while leaving the workbench open. */
     closeWorkbenchLeftPane: () => void;
+    /** Reveal/select a file-tree path without opening an editor pane. */
+    expandToFile: (path: string) => void;
     /** Current snapshot of open tabs + active tab. */
     getSnapshot: () => SurfaceShellSnapshot;
 }
@@ -1325,6 +1454,12 @@ export declare interface SurfaceShellProps {
      */
     extraPanels?: string[];
     defaultLeftTab?: string;
+    initialPanels?: Array<{
+        id: string;
+        component: string;
+        title?: string;
+        params?: Record<string, unknown>;
+    }>;
     className?: string;
 }
 
@@ -1369,6 +1504,8 @@ export declare interface ToolExecContext {
     sessionId?: string;
 }
 
+declare type ToolReadinessRequirement = 'workspace-fs' | 'sandbox-exec' | 'ui-bridge';
+
 export declare interface ToolResult {
     content: Array<{
         type: "text";
@@ -1423,6 +1560,8 @@ export declare function useActivePanel(): string | null;
 
 export declare function useActivePanels(): readonly PanelConfig[];
 
+export declare function useApiBaseUrl(): string;
+
 export declare function useArtifactPanels(surfaceApi: DockviewShellApi | null): UseArtifactPanelsReturn;
 
 export declare interface UseArtifactPanelsReturn {
@@ -1483,6 +1622,7 @@ export declare interface UseEditorLifecycleReturn {
     isSaving: boolean;
     lastSavedAt: number | null;
     markDirty: () => void;
+    markClean: () => void;
     flushSave: () => Promise<void>;
     shouldSync: boolean;
     ackSync: () => void;
@@ -1500,8 +1640,74 @@ export declare interface UseEditorLifecycleReturn {
  */
 export declare function useEvent<K extends keyof WorkspaceEventMap>(name: K, handler: (payload: WorkspaceEventMap[K]) => void): void;
 
+/**
+ * Shared hook for file-based panes (code editor, markdown editor, etc.).
+ *
+ * Handles:
+ * - File loading via React Query
+ * - Local content state with dirty tracking
+ * - Optimistic concurrency control (OCC) via mtime
+ * - External file change detection
+ * - Conflict resolution (reload vs overwrite)
+ * - Panel title updates with dirty indicator
+ *
+ * @example
+ * ```typescript
+ * function MyEditorPane({ params, api }) {
+ *   const { content, setContent, isLoading, error, conflict, ... } = useFilePane({
+ *     path: params.path,
+ *     panelId: api.id,
+ *   })
+ *
+ *   if (!params.path) return <NoFileSelected />
+ *   if (error) return <ErrorBanner error={error} />
+ *
+ *   return (
+ *     <>
+ *       {conflict && <ConflictBanner onReload={onReloadFromServer} onOverwrite={onOverwrite} />}
+ *       <MyEditor content={content} onChange={setContent} />
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export declare function useFilePane(options: UseFilePaneOptions): UseFilePaneReturn;
+
+export declare interface UseFilePaneOptions {
+    /** The file path to load/edit. If empty/undefined, pane shows "no file selected". */
+    path: string;
+    /** Unique panel ID for lifecycle tracking. Omit to use a stable per-pane fallback ID. */
+    panelId?: string;
+    /** Initial content (optional, for draft/unsaved files). */
+    initialContent?: string;
+}
+
+export declare interface UseFilePaneReturn {
+    isLoading: boolean;
+    error: Error | null;
+    content: string | null;
+    isDirty: boolean;
+    conflict: FileConflictError | null;
+    onReloadFromServer: () => Promise<void>;
+    onOverwrite: () => Promise<void>;
+    setContent: (content: string) => void;
+    save: () => Promise<void>;
+    flushSave: () => Promise<void>;
+    fileName: string;
+    tabTitle: string;
+}
+
+export declare function useFullPagePanelHref(input: {
+    componentId: string;
+    params?: Record<string, unknown>;
+}): string | null;
+
+export declare function useHasWorkspaceFilesProvider(): boolean;
+
 export declare function useHydrationComplete(): boolean;
 
+export declare function useIsFullPagePanel(): boolean;
+
 export declare function useKeyboardShortcuts({ shortcuts, enabled }: UseKeyboardShortcutsOptions): void;
 
 export declare interface UseKeyboardShortcutsOptions {
@@ -1511,6 +1717,8 @@ export declare interface UseKeyboardShortcutsOptions {
 
 export declare function useOpenPanels(): PanelState[];
 
+export declare function usePanelRenderMode(): PanelRenderMode;
+
 export declare function usePluginErrors(): PluginErrorContextValue;
 
 export declare function useRegistry(): PanelRegistry;
@@ -1557,12 +1765,18 @@ export declare function useWorkspaceContext(): WorkspaceContextValue;
 
 export declare function useWorkspaceContextOptional(): WorkspaceContextValue | null;
 
-export declare function WorkbenchLeftPane({ rootDir, bridge, defaultTab, onCollapse, className, }: WorkbenchLeftPaneProps): JSX.Element;
+export declare function useWorkspaceRequestId(): string | null;
+
+export declare function WorkbenchLeftPane({ rootDir, bridge, defaultTab, revealFileTreeRequest, onCollapse, className, }: WorkbenchLeftPaneProps): JSX.Element;
 
 export declare interface WorkbenchLeftPaneProps {
     rootDir?: string;
     bridge?: WorkspaceBridge;
     defaultTab?: WorkbenchLeftTabId;
+    revealFileTreeRequest?: {
+        path: string;
+        seq: number;
+    } | null;
     onCollapse?: () => void;
     className?: string;
 }
@@ -1662,6 +1876,8 @@ export declare interface WorkspaceChatPanelProps {
     isWorkbenchOpen?: () => boolean;
     /** Opens the visible workbench surface before dispatching a command. */
     openWorkbench?: () => void;
+    /** Opens the visible workbench sources/file-tree pane before dispatching a reveal. */
+    openWorkbenchSources?: () => void;
     /** Closes the visible workbench surface after an ephemeral command finishes. */
     closeWorkbench?: () => void;
     /** Generic workspace blockers that should prevent submitting new chat turns. */
@@ -1685,6 +1901,8 @@ export declare interface WorkspaceEventMap extends WorkspaceHostEventMap, Worksp
 /** Names that share a prefix can be filtered with `startsWith`. */
 export declare type WorkspaceEventName = keyof WorkspaceEventMap;
 
+export declare function WorkspaceFilesProvider({ apiBaseUrl, authHeaders, onAuthError, timeout, client: providedClient, children, }: DataProviderProps): JSX.Element;
+
 declare interface WorkspaceHostEventMap {
     /** Shared UI manipulation contract used by the agent stream and plugin bindings. */
     [WORKSPACE_UI_COMMAND_EVENT]: EventMeta & {
@@ -1732,6 +1950,9 @@ declare type WorkspacePanelMatch = {
 } | {
     param: string;
     value: unknown;
+} | {
+    paramPrefix: string;
+    value: string;
 };
 
 /**
@@ -1761,7 +1982,7 @@ export declare interface WorkspacePluginEventMap {
     };
 }
 
-export declare function WorkspaceProvider({ children, chatPanel, plugins, excludeDefaults, panels, commands, catalogs, capabilities, apiBaseUrl, authHeaders, apiTimeout, defaultTheme, onThemeChange, workspaceId, storageKey, persistenceEnabled, bridgeEndpoint, onAuthError, onOpenFile, debug, frontPluginHotReload, }: WorkspaceProviderProps): JSX.Element;
+export declare function WorkspaceProvider({ children, chatPanel, plugins, excludeDefaults, panels, commands, catalogs, capabilities, apiBaseUrl, authHeaders, apiTimeout, defaultTheme, onThemeChange, workspaceId, storageKey, persistenceEnabled, bridgeEndpoint, onAuthError, onOpenFile, debug, frontPluginHotReload, fullPageBasePath, }: WorkspaceProviderProps): JSX.Element;
 
 export declare interface WorkspaceProviderProps {
     children: ReactNode;
@@ -1796,6 +2017,7 @@ export declare interface WorkspaceProviderProps {
      * own module asset endpoint.
      */
     frontPluginHotReload?: FrontPluginHotReloadMode;
+    fullPageBasePath?: string;
 }
 
 export declare interface WorkspaceState {