@yushaw/sanqian-chat 0.2.6 → 0.2.9

package/README.md

@@ -99,6 +99,19 @@ src/renderer/styles/
 
 ## Changelog
 
+### 0.2.7 (2026-01-06)
+- **Added**: External resource reference support
+  - `useResourcePicker` hook - manage resource picker state, search, pagination
+  - `ResourcePicker` component - two-level picker (providers → resources)
+  - `ResourceChip` / `ResourceChipList` - display attached resources
+  - `AddResourceButton` - + button with dropdown menu
+- **Added**: `ChatAdapter` extensions: `listResourceProviders`, `getResourceList`, `onLocaleChanged`
+- **Added**: `FloatingWindow.notifyLocaleChanged(locale)` and `ChatPanel.notifyLocaleChanged(locale)` - notify renderer when locale changes
+- **Added**: `sendMessage` now accepts `options.attachedResources`
+- **Added**: Message rendering displays attached resources in user messages
+- **Added**: New types: `AttachedResource`, `ResourcePickerItem`, `ContextProviderInfo`
+- **Changed**: `AppContextProvider.getList` now accepts `options` parameter for search/pagination
+
 ### 2025-01-03
 - **Added**: Focus persistence - input keeps focus when clicking empty areas (unless selecting text)
 - **Added**: `Cmd+N` (macOS) / `Ctrl+N` (Windows) keyboard shortcut for new chat

package/dist/chunk-S6HCEDWX.mjs

@@ -0,0 +1,86 @@
+// src/preload/factories.ts
+import { ipcRenderer } from "electron";
+function createSanqianChatApi() {
+  return {
+    connect: () => ipcRenderer.invoke("sanqian-chat:connect"),
+    isConnected: () => ipcRenderer.invoke("sanqian-chat:isConnected"),
+    stream: (params) => ipcRenderer.invoke("sanqian-chat:stream", params),
+    cancelStream: (params) => ipcRenderer.invoke("sanqian-chat:cancelStream", params),
+    onStreamEvent: (callback) => {
+      const handler = (_, data) => {
+        callback(data.streamId, data.event);
+      };
+      ipcRenderer.on("sanqian-chat:streamEvent", handler);
+      return () => ipcRenderer.removeListener("sanqian-chat:streamEvent", handler);
+    },
+    sendHitlResponse: (params) => ipcRenderer.invoke("sanqian-chat:hitlResponse", params),
+    listConversations: (params) => ipcRenderer.invoke("sanqian-chat:listConversations", params),
+    getConversation: (params) => ipcRenderer.invoke("sanqian-chat:getConversation", params),
+    deleteConversation: (params) => ipcRenderer.invoke("sanqian-chat:deleteConversation", params),
+    hide: () => ipcRenderer.invoke("sanqian-chat:hide"),
+    setAlwaysOnTop: (params) => ipcRenderer.invoke("sanqian-chat:setAlwaysOnTop", params),
+    getAlwaysOnTop: () => ipcRenderer.invoke("sanqian-chat:getAlwaysOnTop"),
+    getUiConfig: () => ipcRenderer.invoke("sanqian-chat:getUiConfig"),
+    setBackgroundColor: (params) => ipcRenderer.invoke("sanqian-chat:setBackgroundColor", params),
+    getPlatform: () => process.platform,
+    // Resource Picker
+    listResourceProviders: () => ipcRenderer.invoke("sanqian-chat:listResourceProviders"),
+    getResourceList: (params) => ipcRenderer.invoke("sanqian-chat:getResourceList", params),
+    // Locale
+    onLocaleChanged: (callback) => {
+      const handler = (_, data) => {
+        callback(data.locale);
+      };
+      ipcRenderer.on("sanqian-chat:localeChanged", handler);
+      return () => ipcRenderer.removeListener("sanqian-chat:localeChanged", handler);
+    }
+  };
+}
+function createChatPanelApi() {
+  return {
+    // Mode
+    getMode: () => ipcRenderer.invoke("chatPanel:getMode"),
+    setMode: (mode) => ipcRenderer.invoke("chatPanel:setMode", mode),
+    toggleMode: () => ipcRenderer.invoke("chatPanel:toggleMode"),
+    onModeChanged: (callback) => {
+      const handler = (_, data) => {
+        callback(data.mode);
+      };
+      ipcRenderer.on("chatPanel:modeChanged", handler);
+      return () => ipcRenderer.removeListener("chatPanel:modeChanged", handler);
+    },
+    // Visibility
+    isVisible: () => ipcRenderer.invoke("chatPanel:isVisible"),
+    show: () => ipcRenderer.invoke("chatPanel:show"),
+    hide: () => ipcRenderer.invoke("chatPanel:hide"),
+    toggle: () => ipcRenderer.invoke("chatPanel:toggle"),
+    onVisibilityChanged: (callback) => {
+      const handler = (_, data) => {
+        callback(data.visible);
+      };
+      ipcRenderer.on("chatPanel:visibilityChanged", handler);
+      return () => ipcRenderer.removeListener("chatPanel:visibilityChanged", handler);
+    },
+    // Attach state
+    getAttachState: () => ipcRenderer.invoke("chatPanel:getAttachState"),
+    toggleAttach: () => ipcRenderer.invoke("chatPanel:toggleAttach"),
+    onAttachStateChanged: (callback) => {
+      const handler = (_, data) => {
+        callback(data.state);
+      };
+      ipcRenderer.on("chatPanel:attachStateChanged", handler);
+      return () => ipcRenderer.removeListener("chatPanel:attachStateChanged", handler);
+    },
+    // Width
+    getWidth: () => ipcRenderer.invoke("chatPanel:getWidth"),
+    setWidth: (width, animate) => ipcRenderer.invoke("chatPanel:setWidth", { width, animate }),
+    onResizeEnd: () => ipcRenderer.invoke("chatPanel:onResizeEnd"),
+    // UI Config
+    getUiConfig: () => ipcRenderer.invoke("chatPanel:getUiConfig")
+  };
+}
+
+export {
+  createSanqianChatApi,
+  createChatPanelApi
+};

package/dist/core/index.d.mts

@@ -1,5 +1,5 @@
-import { HitlInterruptPayload, HitlResponse, SanqianSDK } from '@yushaw/sanqian-sdk';
-export { ChatStreamEvent, HitlInterruptPayload, HitlInterruptType, HitlResponse, HitlRiskLevel, ChatMessage as SdkChatMessage, ConversationDetail as SdkConversationDetail, ConversationInfo as SdkConversationInfo, ToolCall as SdkToolCall } from '@yushaw/sanqian-sdk';
+import { ResourceType, HitlInterruptPayload, ContextListItem, HitlResponse, ResourceListOptions, SanqianSDK } from '@yushaw/sanqian-sdk';
+export { ChatStreamEvent, ContextListItem, HitlInterruptPayload, HitlInterruptType, HitlResponse, HitlRiskLevel, ResourceListOptions, ResourceListResult, ResourceType, ChatMessage as SdkChatMessage, ConversationDetail as SdkConversationDetail, ConversationInfo as SdkConversationInfo, ToolCall as SdkToolCall } from '@yushaw/sanqian-sdk';
 
 /**
  * @yushaw/sanqian-chat Core Types
@@ -120,6 +120,8 @@ interface ChatMessage {
     finalContent?: string;
     isComplete?: boolean;
     filePaths?: string[];
+    /** Attached external resources (for user messages) */
+    attachedResources?: AttachedResource[];
 }
 /** Conversation info for UI */
 interface ConversationInfo {
@@ -307,6 +309,86 @@ interface ChatPanelConfig {
      */
     uiConfig?: ChatUiConfigSerializable;
 }
+/**
+ * Context provider info for UI display (in + menu)
+ */
+interface ContextProviderInfo {
+    /** Full provider ID (format: "appName:providerId") */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description: string;
+    /** App name (extracted from id) */
+    appName: string;
+    /** Whether app is currently connected */
+    isConnected?: boolean;
+    /** Whether provider supports getList (resource picker) */
+    hasGetList?: boolean;
+    /** Whether provider supports getCurrent (auto-inject) */
+    hasGetCurrent?: boolean;
+}
+/**
+ * Resource item for picker display (extends ContextListItem with provider info)
+ */
+interface ResourcePickerItem extends ContextListItem {
+    /** Full provider ID that owns this resource */
+    providerId: string;
+    /** Provider display name */
+    providerName?: string;
+}
+/**
+ * Attached resource reference (selected by user)
+ */
+interface AttachedResource {
+    /** Full provider ID (format: "appName:providerId") */
+    providerId: string;
+    /** Resource ID (from ContextListItem.id) */
+    resourceId: string;
+    /** Display title */
+    title: string;
+    /** Optional summary for tooltip */
+    summary?: string;
+    /** Resource type for icon/styling */
+    type?: ResourceType;
+    /** Icon emoji or URL */
+    icon?: string;
+}
+/**
+ * Resource picker state
+ */
+interface ResourcePickerState {
+    /** Currently loading */
+    isLoading: boolean;
+    /** Search query */
+    query: string;
+    /** Available items grouped by provider */
+    itemsByProvider: Record<string, ResourcePickerItem[]>;
+    /** Whether more items are available (for pagination) */
+    hasMoreByProvider: Record<string, boolean>;
+    /** Error message if any */
+    error?: string;
+}
+/**
+ * Attachment menu item type
+ */
+type AttachmentMenuItemType = 'upload' | 'provider';
+/**
+ * Attachment menu item for + button dropdown
+ */
+interface AttachmentMenuItem {
+    type: AttachmentMenuItemType;
+    /** For 'upload': 'file' or 'image'. For 'provider': provider ID */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Icon emoji or URL */
+    icon?: string;
+    /** Description or subtitle */
+    description?: string;
+    /** Whether currently available (e.g., app connected) */
+    available?: boolean;
+}
 
 /**
  * Chat Adapter Interface
@@ -390,10 +472,23 @@ interface ChatAdapter {
     deleteConversation(id: string): Promise<void>;
     chatStream(messages: SendMessage[], conversationId: string | undefined, onEvent: (event: StreamEvent) => void, options?: {
         agentId?: string | null;
+        /** Attached context provider IDs (e.g., ["sanqian-notes:notes"]) - for getCurrent */
+        attachedContexts?: string[];
+        /** Attached resource references (e.g., ["sanqian-notes:notes:abc123"]) - for getById */
+        attachedResources?: string[];
     }): Promise<{
         cancel: () => void;
     }>;
     sendHitlResponse?(response: HitlResponse, runId?: string): void;
+    /** List available context providers */
+    listResourceProviders?(): Promise<ContextProviderInfo[]>;
+    /** Get resource list from a provider with search/pagination */
+    getResourceList?(providerId: string, options?: ResourceListOptions): Promise<{
+        items: ResourcePickerItem[];
+        hasMore?: boolean;
+    }>;
+    /** Subscribe to locale change events */
+    onLocaleChanged?(callback: (locale: string) => void): () => void;
     cleanup?(): void;
 }
 /** SDK adapter config */
@@ -480,4 +575,4 @@ declare function parseToolCalls(toolCalls: unknown): ToolCall[] | undefined;
  */
 declare function mergeConsecutiveAssistantMessages(rawMessages: ApiMessage[]): ChatMessage[];
 
-export { type ApiMessage, type AttachConfig, type AttachPosition, type AttachState, type ChatAdapter, type ChatAdapterConfig, type ChatFontSize, type ChatMessage, type ChatPanelConfig, type ChatPanelMode, type ChatPanelPosition, type ChatThemeMode, type ChatUiConfigSerializable, type ChatUiStrings, type ConnectionErrorCode, type ConnectionStatus, type ConversationDetail, type ConversationInfo, type FloatingWindowConfig, type HitlInterruptData, type Locale, type MessageBlock, type MessageRole, type SdkAdapterConfig, type SendMessage, type StreamEvent, type ToolCall, type ToolCallStatus, type WindowPosition, createChatAdapter, createSdkAdapter, mergeConsecutiveAssistantMessages, parseToolCalls };
+export { type ApiMessage, type AttachConfig, type AttachPosition, type AttachState, type AttachedResource, type AttachmentMenuItem, type AttachmentMenuItemType, type ChatAdapter, type ChatAdapterConfig, type ChatFontSize, type ChatMessage, type ChatPanelConfig, type ChatPanelMode, type ChatPanelPosition, type ChatThemeMode, type ChatUiConfigSerializable, type ChatUiStrings, type ConnectionErrorCode, type ConnectionStatus, type ContextProviderInfo, type ConversationDetail, type ConversationInfo, type FloatingWindowConfig, type HitlInterruptData, type Locale, type MessageBlock, type MessageRole, type ResourcePickerItem, type ResourcePickerState, type SdkAdapterConfig, type SendMessage, type StreamEvent, type ToolCall, type ToolCallStatus, type WindowPosition, createChatAdapter, createSdkAdapter, mergeConsecutiveAssistantMessages, parseToolCalls };

package/dist/core/index.d.ts

@@ -1,5 +1,5 @@
-import { HitlInterruptPayload, HitlResponse, SanqianSDK } from '@yushaw/sanqian-sdk';
-export { ChatStreamEvent, HitlInterruptPayload, HitlInterruptType, HitlResponse, HitlRiskLevel, ChatMessage as SdkChatMessage, ConversationDetail as SdkConversationDetail, ConversationInfo as SdkConversationInfo, ToolCall as SdkToolCall } from '@yushaw/sanqian-sdk';
+import { ResourceType, HitlInterruptPayload, ContextListItem, HitlResponse, ResourceListOptions, SanqianSDK } from '@yushaw/sanqian-sdk';
+export { ChatStreamEvent, ContextListItem, HitlInterruptPayload, HitlInterruptType, HitlResponse, HitlRiskLevel, ResourceListOptions, ResourceListResult, ResourceType, ChatMessage as SdkChatMessage, ConversationDetail as SdkConversationDetail, ConversationInfo as SdkConversationInfo, ToolCall as SdkToolCall } from '@yushaw/sanqian-sdk';
 
 /**
  * @yushaw/sanqian-chat Core Types
@@ -120,6 +120,8 @@ interface ChatMessage {
     finalContent?: string;
     isComplete?: boolean;
     filePaths?: string[];
+    /** Attached external resources (for user messages) */
+    attachedResources?: AttachedResource[];
 }
 /** Conversation info for UI */
 interface ConversationInfo {
@@ -307,6 +309,86 @@ interface ChatPanelConfig {
      */
     uiConfig?: ChatUiConfigSerializable;
 }
+/**
+ * Context provider info for UI display (in + menu)
+ */
+interface ContextProviderInfo {
+    /** Full provider ID (format: "appName:providerId") */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description: string;
+    /** App name (extracted from id) */
+    appName: string;
+    /** Whether app is currently connected */
+    isConnected?: boolean;
+    /** Whether provider supports getList (resource picker) */
+    hasGetList?: boolean;
+    /** Whether provider supports getCurrent (auto-inject) */
+    hasGetCurrent?: boolean;
+}
+/**
+ * Resource item for picker display (extends ContextListItem with provider info)
+ */
+interface ResourcePickerItem extends ContextListItem {
+    /** Full provider ID that owns this resource */
+    providerId: string;
+    /** Provider display name */
+    providerName?: string;
+}
+/**
+ * Attached resource reference (selected by user)
+ */
+interface AttachedResource {
+    /** Full provider ID (format: "appName:providerId") */
+    providerId: string;
+    /** Resource ID (from ContextListItem.id) */
+    resourceId: string;
+    /** Display title */
+    title: string;
+    /** Optional summary for tooltip */
+    summary?: string;
+    /** Resource type for icon/styling */
+    type?: ResourceType;
+    /** Icon emoji or URL */
+    icon?: string;
+}
+/**
+ * Resource picker state
+ */
+interface ResourcePickerState {
+    /** Currently loading */
+    isLoading: boolean;
+    /** Search query */
+    query: string;
+    /** Available items grouped by provider */
+    itemsByProvider: Record<string, ResourcePickerItem[]>;
+    /** Whether more items are available (for pagination) */
+    hasMoreByProvider: Record<string, boolean>;
+    /** Error message if any */
+    error?: string;
+}
+/**
+ * Attachment menu item type
+ */
+type AttachmentMenuItemType = 'upload' | 'provider';
+/**
+ * Attachment menu item for + button dropdown
+ */
+interface AttachmentMenuItem {
+    type: AttachmentMenuItemType;
+    /** For 'upload': 'file' or 'image'. For 'provider': provider ID */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Icon emoji or URL */
+    icon?: string;
+    /** Description or subtitle */
+    description?: string;
+    /** Whether currently available (e.g., app connected) */
+    available?: boolean;
+}
 
 /**
  * Chat Adapter Interface
@@ -390,10 +472,23 @@ interface ChatAdapter {
     deleteConversation(id: string): Promise<void>;
     chatStream(messages: SendMessage[], conversationId: string | undefined, onEvent: (event: StreamEvent) => void, options?: {
         agentId?: string | null;
+        /** Attached context provider IDs (e.g., ["sanqian-notes:notes"]) - for getCurrent */
+        attachedContexts?: string[];
+        /** Attached resource references (e.g., ["sanqian-notes:notes:abc123"]) - for getById */
+        attachedResources?: string[];
     }): Promise<{
         cancel: () => void;
     }>;
     sendHitlResponse?(response: HitlResponse, runId?: string): void;
+    /** List available context providers */
+    listResourceProviders?(): Promise<ContextProviderInfo[]>;
+    /** Get resource list from a provider with search/pagination */
+    getResourceList?(providerId: string, options?: ResourceListOptions): Promise<{
+        items: ResourcePickerItem[];
+        hasMore?: boolean;
+    }>;
+    /** Subscribe to locale change events */
+    onLocaleChanged?(callback: (locale: string) => void): () => void;
     cleanup?(): void;
 }
 /** SDK adapter config */
@@ -480,4 +575,4 @@ declare function parseToolCalls(toolCalls: unknown): ToolCall[] | undefined;
  */
 declare function mergeConsecutiveAssistantMessages(rawMessages: ApiMessage[]): ChatMessage[];
 
-export { type ApiMessage, type AttachConfig, type AttachPosition, type AttachState, type ChatAdapter, type ChatAdapterConfig, type ChatFontSize, type ChatMessage, type ChatPanelConfig, type ChatPanelMode, type ChatPanelPosition, type ChatThemeMode, type ChatUiConfigSerializable, type ChatUiStrings, type ConnectionErrorCode, type ConnectionStatus, type ConversationDetail, type ConversationInfo, type FloatingWindowConfig, type HitlInterruptData, type Locale, type MessageBlock, type MessageRole, type SdkAdapterConfig, type SendMessage, type StreamEvent, type ToolCall, type ToolCallStatus, type WindowPosition, createChatAdapter, createSdkAdapter, mergeConsecutiveAssistantMessages, parseToolCalls };
+export { type ApiMessage, type AttachConfig, type AttachPosition, type AttachState, type AttachedResource, type AttachmentMenuItem, type AttachmentMenuItemType, type ChatAdapter, type ChatAdapterConfig, type ChatFontSize, type ChatMessage, type ChatPanelConfig, type ChatPanelMode, type ChatPanelPosition, type ChatThemeMode, type ChatUiConfigSerializable, type ChatUiStrings, type ConnectionErrorCode, type ConnectionStatus, type ContextProviderInfo, type ConversationDetail, type ConversationInfo, type FloatingWindowConfig, type HitlInterruptData, type Locale, type MessageBlock, type MessageRole, type ResourcePickerItem, type ResourcePickerState, type SdkAdapterConfig, type SendMessage, type StreamEvent, type ToolCall, type ToolCallStatus, type WindowPosition, createChatAdapter, createSdkAdapter, mergeConsecutiveAssistantMessages, parseToolCalls };

package/dist/core/index.js

@@ -412,7 +412,8 @@ function createChatAdapter(config) {
         sdkMessages,
         {
           conversationId,
-          persistHistory: config.persistHistory ?? false
+          persistHistory: config.persistHistory ?? false,
+          attachedResources: options?.attachedResources
         }
       );
       return processStreamEvents(stream, onEvent, sdk, (id) => {
@@ -635,7 +636,10 @@ function createSdkAdapter(config) {
       const stream = sdk.chatStream(
         agentId,
         sdkMessages,
-        { conversationId }
+        {
+          conversationId,
+          attachedResources: options?.attachedResources
+        }
       );
       return processStreamEvents(stream, onEvent, sdk, (id) => {
         currentRunId = id;

package/dist/core/index.mjs

@@ -373,7 +373,8 @@ function createChatAdapter(config) {
         sdkMessages,
         {
           conversationId,
-          persistHistory: config.persistHistory ?? false
+          persistHistory: config.persistHistory ?? false,
+          attachedResources: options?.attachedResources
         }
       );
       return processStreamEvents(stream, onEvent, sdk, (id) => {
@@ -596,7 +597,10 @@ function createSdkAdapter(config) {
       const stream = sdk.chatStream(
         agentId,
         sdkMessages,
-        { conversationId }
+        {
+          conversationId,
+          attachedResources: options?.attachedResources
+        }
       );
       return processStreamEvents(stream, onEvent, sdk, (id) => {
         currentRunId = id;

package/dist/main/index.d.mts

@@ -8,6 +8,8 @@ import { BrowserWindow, WebContents } from 'electron';
  * Application-facing types that hide SDK implementation details.
  * These provide a stable API even as the underlying SDK evolves.
  */
+/** Resource type for display styling (can be any string for custom types) */
+type AppResourceType = string;
 /**
  * Context data returned by a provider
  */
@@ -22,6 +24,16 @@ interface AppContextData {
     summary?: string;
     /** Version for change detection (optional, Sanqian uses content hash if not provided) */
     version?: string;
+    /** Resource type for display styling */
+    type?: AppResourceType;
+    /** Additional metadata (accessible in templates via {{metadata.xxx}}) */
+    metadata?: Record<string, unknown>;
+    /**
+     * Custom injection template using Mustache-style variables.
+     * Available variables: {{title}}, {{content}}, {{summary}}, {{type}}, {{metadata.xxx}}
+     * @example "# {{title}}\n\n{{content}}"
+     */
+    template?: string;
 }
 /**
  * List item for context provider's getList method
@@ -35,6 +47,34 @@ interface AppContextListItem {
     summary?: string;
     /** Optional icon */
     icon?: string;
+    /** Resource type for display styling */
+    type?: AppResourceType;
+    /** Last updated timestamp (ISO 8601) */
+    updatedAt?: string;
+    /** Group name for categorization in picker UI */
+    group?: string;
+    /** Tags for filtering */
+    tags?: string[];
+}
+/**
+ * Options for getList() pagination and search
+ */
+interface AppResourceListOptions {
+    /** Search query string */
+    query?: string;
+    /** Pagination offset (default: 0) */
+    offset?: number;
+    /** Max items to return (default: 20) */
+    limit?: number;
+}
+/**
+ * Result from getList() with pagination info
+ */
+interface AppResourceListResult {
+    /** List items */
+    items: AppContextListItem[];
+    /** Whether more items are available */
+    hasMore?: boolean;
 }
 /**
  * Context provider definition
@@ -48,8 +88,8 @@ interface AppContextProvider {
     description: string;
     /** Get current state (for dynamic context) */
     getCurrent?: () => Promise<AppContextData | null>;
-    /** Get list of available contexts */
-    getList?: () => Promise<AppContextListItem[]>;
+    /** Get list of available resources with pagination and search */
+    getList?: (options?: AppResourceListOptions) => Promise<AppResourceListResult>;
     /** Get full content by ID */
     getById?: (id: string) => Promise<AppContextData | null>;
 }
@@ -207,6 +247,11 @@ declare class SanqianAppClient {
      * Ensure SDK is ready (connects if needed, waits for registration)
      */
     ensureReady(): Promise<void>;
+    /**
+     * Get the port number for the Sanqian backend
+     * @throws Error if not connected
+     */
+    getPort(): number;
     /**
      * Request persistent connection (enables auto-reconnect)
      * Call when a component needs the connection to stay alive
@@ -224,6 +269,11 @@ declare class SanqianAppClient {
     createAgent(config: AppAgentConfig): Promise<{
         agentId: string;
     }>;
+    /**
+     * Update context providers dynamically
+     * Use this to update provider names/descriptions when locale changes
+     */
+    updateContexts(contexts: AppContextProvider[]): Promise<void>;
     /**
      * Get embedding configuration from Sanqian
      * @returns Embedding config or null if not available
@@ -619,6 +669,18 @@ declare class FloatingWindow {
     isVisible(): boolean;
     destroy(): void;
     getWindow(): BrowserWindow | null;
+    /**
+     * Notify renderer that locale has changed.
+     * Call this after updating contexts with new locale via client.updateContexts().
+     *
+     * @example
+     * ```typescript
+     * // When locale changes
+     * await client.updateContexts(getLocalizedContexts(newLocale));
+     * floatingWindow.notifyLocaleChanged(newLocale);
+     * ```
+     */
+    notifyLocaleChanged(locale: string): void;
 }
 
 /**
@@ -718,6 +780,18 @@ declare class ChatPanel {
      * Get webContents (for IPC)
      */
     getWebContents(): WebContents;
+    /**
+     * Notify renderer that locale has changed.
+     * Call this after updating contexts with new locale via client.updateContexts().
+     *
+     * @example
+     * ```typescript
+     * // When locale changes
+     * await client.updateContexts(getLocalizedContexts(newLocale));
+     * chatPanel.notifyLocaleChanged(newLocale);
+     * ```
+     */
+    notifyLocaleChanged(locale: string): void;
     /**
      * Destroy panel
      */
@@ -839,4 +913,32 @@ declare class WindowAttachment {
     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 };
+/**
+ * @yushaw/sanqian-chat Main
+ *
+ * Electron main process module
+ *
+ * Provides:
+ * - SanqianAppClient: Facade for SDK, stable application-facing API
+ * - FloatingWindow: Floating chat window manager
+ * - ChatPanel: Embedded + Floating chat panel (new)
+ * - WindowAttachment: Floating window attachment (new)
+ * - getPreloadPath: Get the path to the built preload script
+ */
+/**
+ * Get the path to the chat SDK's built preload script.
+ * Use this when creating ChatPanel or FloatingWindow.
+ *
+ * @example
+ * ```typescript
+ * import { ChatPanel, getPreloadPath } from '@yushaw/sanqian-chat/main'
+ *
+ * const chatPanel = new ChatPanel({
+ *   preloadPath: getPreloadPath(),
+ *   // ...
+ * })
+ * ```
+ */
+declare function getPreloadPath(): string;
+
+export { type AppAgentConfig, type AppClientEvent, type AppClientEventHandlers, type AppConfig, type AppContextData, type AppContextListItem, type AppContextProvider, type AppEmbeddingConfig, type AppJsonSchemaProperty, type AppResourceListOptions, type AppResourceListResult, type AppResourceType, 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, getPreloadPath };