@yushaw/sanqian-chat 0.2.3 → 0.2.6

package/dist/main/index.d.mts

@@ -1,6 +1,6 @@
 import * as _yushaw_sanqian_sdk from '@yushaw/sanqian-sdk';
 import { SanqianSDK } from '@yushaw/sanqian-sdk';
-import { BrowserWindow } from 'electron';
+import { BrowserWindow, WebContents } from 'electron';
 
 /**
  * @yushaw/sanqian-chat Main - Facade Types
@@ -8,6 +8,51 @@ import { BrowserWindow } from 'electron';
  * Application-facing types that hide SDK implementation details.
  * These provide a stable API even as the underlying SDK evolves.
  */
+/**
+ * Context data returned by a provider
+ */
+interface AppContextData {
+    /** Resource ID (for getById scenarios) */
+    id?: string;
+    /** Content to inject into conversation */
+    content: string;
+    /** Display title */
+    title?: string;
+    /** Summary for preview */
+    summary?: string;
+    /** Version for change detection (optional, Sanqian uses content hash if not provided) */
+    version?: string;
+}
+/**
+ * List item for context provider's getList method
+ */
+interface AppContextListItem {
+    /** Resource ID */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Optional summary */
+    summary?: string;
+    /** Optional icon */
+    icon?: string;
+}
+/**
+ * Context provider definition
+ */
+interface AppContextProvider {
+    /** Provider ID (unique within app) */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description: string;
+    /** Get current state (for dynamic context) */
+    getCurrent?: () => Promise<AppContextData | null>;
+    /** Get list of available contexts */
+    getList?: () => Promise<AppContextListItem[]>;
+    /** Get full content by ID */
+    getById?: (id: string) => Promise<AppContextData | null>;
+}
 /**
  * Application configuration for connecting to Sanqian
  */
@@ -22,6 +67,8 @@ interface AppConfig {
     launchCommand?: string;
     /** Tools provided by this application */
     tools?: AppToolDefinition[];
+    /** Context providers for injecting app state */
+    contexts?: AppContextProvider[];
     /** Enable debug logging */
     debug?: boolean;
 }
@@ -79,6 +126,12 @@ interface AppAgentConfig {
      * @example ["pdf", "web-research", "xlsx"]
      */
     skills?: string[];
+    /**
+     * Context providers to attach by default.
+     * Uses provider ID without app prefix (auto-prefixed with appName).
+     * @example ["editor-state"] -> "sanqian-notes:editor-state"
+     */
+    attachedContexts?: string[];
 }
 /**
  * Embedding configuration from Sanqian
@@ -315,6 +368,12 @@ interface ChatUiStrings {
     hitlInputRequest: string;
     hitlApprovalRequired: string;
     hitlInputRequired: string;
+    attachWindow: string;
+    detachWindow: string;
+    floatWindow: string;
+    embedWindow: string;
+    collapseSidebar: string;
+    history: string;
 }
 type ChatThemeMode = 'light' | 'dark' | 'auto';
 type ChatFontSize = 'small' | 'normal' | 'large' | 'extra-large';
@@ -353,6 +412,153 @@ interface FloatingWindowConfig {
     /** Optional full path for window state file */
     windowStatePath?: string;
 }
+type ChatPanelMode = 'embedded' | 'floating';
+type ChatPanelPosition = 'right' | 'left';
+type AttachState = 'attached' | 'detached' | 'unavailable';
+type AttachPosition = 'right' | 'left' | 'top' | 'bottom';
+/**
+ * Window attachment configuration for floating mode
+ */
+interface AttachConfig {
+    /**
+     * Target window to attach to (BrowserWindow instance)
+     */
+    window: unknown;
+    /**
+     * Attach position relative to target window
+     * @default 'right'
+     */
+    position?: AttachPosition;
+    /**
+     * Gap between windows (px)
+     * @default 0
+     */
+    gap?: number;
+    /**
+     * Sync height/width with target window
+     * @default true
+     */
+    syncSize?: boolean;
+    /**
+     * Behavior when target window is minimized
+     * @default 'hide'
+     */
+    onMinimize?: 'hide' | 'detach' | 'minimize';
+    /**
+     * Behavior when target window is closed
+     * @default 'hide'
+     */
+    onClose?: 'hide' | 'destroy';
+    /**
+     * Allow user to drag and detach
+     * @default true
+     */
+    allowDetach?: boolean;
+    /**
+     * Allow re-attach when dragged near target edge
+     * @default true
+     */
+    allowReattach?: boolean;
+    /**
+     * Distance threshold for re-attach (px)
+     * @default 20
+     */
+    reattachThreshold?: number;
+}
+/**
+ * ChatPanel configuration
+ */
+interface ChatPanelConfig {
+    /**
+     * Host window (BaseWindow supports embedded, BrowserWindow floating only)
+     */
+    hostWindow: unknown;
+    /**
+     * Host window's main content view (required for embedded mode)
+     */
+    hostMainView?: unknown;
+    /**
+     * Initial mode
+     * @default 'embedded'
+     */
+    initialMode?: ChatPanelMode;
+    /**
+     * Embed position
+     * @default 'right'
+     */
+    position?: ChatPanelPosition;
+    /**
+     * Panel width
+     * @default 360
+     */
+    width?: number;
+    /**
+     * Minimum width
+     * @default 240
+     */
+    minWidth?: number;
+    /**
+     * Minimum host content width when showing panel.
+     * If window is too narrow, expand it to ensure main content has this width.
+     * Set to 0 to disable auto-expand.
+     * @default 0
+     */
+    minHostContentWidth?: number;
+    /**
+     * Allow resize
+     * @default true
+     */
+    resizable?: boolean;
+    /**
+     * Preload script path
+     */
+    preloadPath: string;
+    /**
+     * Renderer HTML path or URL
+     */
+    rendererPath: string;
+    /**
+     * Dev mode - load URL instead of file
+     */
+    devMode?: boolean;
+    /**
+     * SDK client getter
+     */
+    getClient: () => unknown;
+    /**
+     * Agent ID getter
+     */
+    getAgentId: () => string | null;
+    /**
+     * Layout change callback (for host app to adjust main content)
+     */
+    onLayoutChange?: (layout: {
+        mainWidth: number;
+        chatWidth: number;
+        chatVisible: boolean;
+    }) => void;
+    /**
+     * Shortcut configuration
+     */
+    shortcuts?: {
+        /** Toggle show/hide, false to disable */
+        toggle?: string | false;
+        /** Toggle mode, false to disable */
+        toggleMode?: string | false;
+    };
+    /**
+     * Floating window attach configuration
+     */
+    attach?: AttachConfig;
+    /**
+     * State persistence key
+     */
+    stateKey?: string;
+    /**
+     * UI config for renderer
+     */
+    uiConfig?: ChatUiConfigSerializable;
+}
 
 /**
  * FloatingWindow - Main process module for floating chat window
@@ -415,4 +621,222 @@ declare class FloatingWindow {
     getWindow(): BrowserWindow | null;
 }
 
-export { type AppAgentConfig, type AppClientEvent, type AppClientEventHandlers, type AppConfig, type AppEmbeddingConfig, type AppJsonSchemaProperty, type AppToolDefinition, type ChatUiConfigSerializable, FloatingWindow, type FloatingWindowConfig, type FloatingWindowOptions, SanqianAppClient, type WindowPosition };
+/**
+ * ChatPanel - Core class for embedded + floating chat panel
+ *
+ * Manages two modes:
+ * - Embedded: WebContentsView inside host BaseWindow
+ * - Floating: Independent BrowserWindow with WebContentsView
+ *
+ * Both modes share the same webContents, allowing runtime switching
+ * without losing state.
+ *
+ * REQUIRES: Electron >= 30.0.0 (for BaseWindow and WebContentsView APIs)
+ */
+
+declare class ChatPanel {
+    private webContents;
+    private config;
+    private mode;
+    private visible;
+    private currentWidth;
+    private embeddedWidth;
+    private floatingWidth;
+    private floatingHeight;
+    private floatingX?;
+    private floatingY?;
+    private embeddedModeAvailable;
+    private embeddedView;
+    private floatingWindow;
+    private floatingView;
+    private registeredShortcuts;
+    private stateSaveTimer;
+    private activeStreams;
+    constructor(config: ChatPanelConfig);
+    private hostResizeHandler;
+    private setupHostWindowListeners;
+    private cleanupHostWindowListeners;
+    /**
+     * Handle window resize - update layout
+     */
+    private handleResponsiveResize;
+    /**
+     * Show panel
+     */
+    show(): void;
+    /**
+     * Hide panel
+     */
+    hide(): void;
+    /**
+     * Toggle visibility
+     */
+    toggle(): void;
+    /**
+     * Get current mode
+     */
+    getMode(): ChatPanelMode;
+    /**
+     * Set mode
+     */
+    setMode(mode: ChatPanelMode): void;
+    /**
+     * Toggle mode
+     */
+    toggleMode(): ChatPanelMode;
+    /**
+     * Check if visible
+     */
+    isVisible(): boolean;
+    /**
+     * Set width with optional animation
+     */
+    setWidth(width: number, animate?: boolean): void;
+    /**
+     * Called when resize drag ends - update window min width constraint
+     */
+    onResizeEnd(): void;
+    /**
+     * Animate width change smoothly
+     */
+    private animateWidth;
+    /**
+     * Get width
+     */
+    getWidth(): number;
+    /**
+     * Get attach state (for floating mode)
+     * Note: Attachment feature not implemented yet - see FloatingWindow.ts for reference
+     */
+    getAttachState(): AttachState;
+    /**
+     * Toggle attach state
+     * Note: Attachment feature not implemented yet - see FloatingWindow.ts for reference
+     */
+    toggleAttach(): AttachState;
+    /**
+     * Get webContents (for IPC)
+     */
+    getWebContents(): WebContents;
+    /**
+     * Destroy panel
+     */
+    destroy(): void;
+    private normalizeConfig;
+    private checkEmbeddedModeAvailable;
+    private determineInitialMode;
+    private initWebContents;
+    private showEmbedded;
+    /**
+     * Update host window minimum width constraint based on chat panel visibility.
+     * When chat is visible: minWidth = minHostContentWidth + chatWidth
+     * When chat is hidden: minWidth = minHostContentWidth
+     */
+    private updateHostWindowMinWidth;
+    /**
+     * Expand host window to the right if main content area would be too narrow.
+     * If expansion would exceed screen bounds, shift window left as needed.
+     */
+    private expandHostWindowIfNeeded;
+    private hideEmbedded;
+    private updateEmbeddedLayout;
+    private updateHostLayoutForHidden;
+    private createFloatingWindow;
+    private showFloating;
+    private hideFloating;
+    private updateFloatingViewBounds;
+    private positionFloatingWindow;
+    private getHostWindowBounds;
+    private sharedView;
+    private getOrCreateSharedView;
+    private switchToEmbedded;
+    private switchToFloating;
+    private notifyVisibilityChange;
+    private notifyModeChange;
+    private setupShortcuts;
+    private getStatePath;
+    private loadState;
+    private scheduleSaveState;
+    private saveState;
+    private getSdk;
+    private setupIpcHandlers;
+    private cleanupIpcHandlers;
+}
+
+/**
+ * WindowAttachment - Manages floating window attachment to a target window
+ *
+ * Handles:
+ * - Position sync when target window moves/resizes
+ * - Minimize/maximize/fullscreen handling
+ * - Drag detach and reattach detection
+ * - Windows Aero Snap workaround (polling)
+ */
+
+declare class WindowAttachment {
+    private chatWindow;
+    private config;
+    private state;
+    private pollTimer;
+    private reattachHandler;
+    private onStateChangeCallback?;
+    private updatePending;
+    constructor(chatWindow: BrowserWindow, config: AttachConfig);
+    /**
+     * Start attachment listeners
+     */
+    attach(): void;
+    /**
+     * Stop attachment listeners
+     */
+    detach(): void;
+    /**
+     * Update chat window position to match target
+     */
+    updatePosition(): void;
+    /**
+     * Set state change callback
+     */
+    onStateChange(callback: (state: AttachState) => void): void;
+    /**
+     * Toggle attach state
+     */
+    toggle(): AttachState;
+    /**
+     * Manual detach
+     */
+    manualDetach(): void;
+    /**
+     * Manual attach
+     */
+    manualAttach(): void;
+    /**
+     * Get current attach state
+     */
+    get isAttached(): boolean;
+    /**
+     * Get current position
+     */
+    get position(): AttachPosition;
+    private normalizeConfig;
+    private throttledUpdatePosition;
+    private calculateAttachedBounds;
+    private constrainToScreen;
+    private notifyStateChange;
+    private handleTargetMinimize;
+    private handleTargetRestore;
+    private handleTargetMaximize;
+    private handleTargetUnmaximize;
+    private handleTargetEnterFullScreen;
+    private handleTargetLeaveFullScreen;
+    private handleTargetClose;
+    private handleTargetClosed;
+    private handleChatMove;
+    private onDetached;
+    private startReattachListener;
+    private stopReattachListener;
+    private startPolling;
+    private stopPolling;
+}
+
+export { type AppAgentConfig, type AppClientEvent, type AppClientEventHandlers, type AppConfig, type AppContextData, type AppContextListItem, type AppContextProvider, type AppEmbeddingConfig, type AppJsonSchemaProperty, type AppToolDefinition, type AttachConfig, type AttachPosition, type AttachState, ChatPanel, type ChatPanelConfig, type ChatPanelMode, type ChatPanelPosition, type ChatUiConfigSerializable, FloatingWindow, type FloatingWindowConfig, type FloatingWindowOptions, SanqianAppClient, WindowAttachment, type WindowPosition };