@talex-touch/utils 1.0.38 → 1.0.40

package/plugin/sdk/feature-sdk.ts

@@ -14,6 +14,24 @@ import { ensureRendererChannel } from './channel'
  */
 export type InputChangeHandler = (input: string) => void
 
+/**
+ * Keyboard event data forwarded from CoreBox
+ */
+export interface ForwardedKeyEvent {
+  key: string
+  code: string
+  metaKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  shiftKey: boolean
+  repeat: boolean
+}
+
+/**
+ * Key event handler
+ */
+export type KeyEventHandler = (event: ForwardedKeyEvent) => void
+
 /**
  * Feature SDK interface for plugins
  * 
@@ -125,6 +143,36 @@ export interface FeatureSDK {
    * ```
    */
   onInputChange(handler: InputChangeHandler): () => void
+
+  /**
+   * Registers a listener for keyboard events forwarded from CoreBox
+   * 
+   * When a plugin's UI view is attached to CoreBox, certain key events
+   * (Enter, Arrow keys, Meta+key combinations) are forwarded to the plugin.
+   * 
+   * @param handler - Callback function invoked when a key event is forwarded
+   * @returns Unsubscribe function
+   * 
+   * @example
+   * ```typescript
+   * const unsubscribe = plugin.feature.onKeyEvent((event) => {
+   *   if (event.key === 'Enter') {
+   *     // Handle enter key
+   *     submitSelection()
+   *   } else if (event.key === 'ArrowDown') {
+   *     // Navigate down in list
+   *     selectNext()
+   *   } else if (event.metaKey && event.key === 'k') {
+   *     // Handle Cmd+K
+   *     openSearch()
+   *   }
+   * })
+   * 
+   * // Later, unsubscribe
+   * unsubscribe()
+   * ```
+   */
+  onKeyEvent(handler: KeyEventHandler): () => void
 }
 
 /**
@@ -138,25 +186,48 @@ export interface FeatureSDK {
  */
 export function createFeatureSDK(boxItemsAPI: any, channel: any): FeatureSDK {
   const inputChangeHandlers: Set<InputChangeHandler> = new Set()
+  const keyEventHandlers: Set<KeyEventHandler> = new Set()
 
   // Register listener for input change events from main process
-  const registerListener = () => {
+  const registerInputListener = () => {
     if (channel.onMain) {
       // Main process plugin context
-      channel.onMain('core-box:input-changed', (event: any) => {
-        const input = event.data?.input || event.input || ''
+      channel.onMain('core-box:input-change', (event: any) => {
+        const input = event.data?.input || event.data?.query?.text || event.input || ''
         inputChangeHandlers.forEach(handler => handler(input))
       })
     } else if (channel.on) {
       // Renderer process context
-      channel.on('core-box:input-changed', (data: any) => {
-        const input = data?.input || data || ''
+      channel.on('core-box:input-change', (data: any) => {
+        const input = data?.input || data?.query?.text || data || ''
         inputChangeHandlers.forEach(handler => handler(input))
       })
     }
   }
 
-  registerListener()
+  // Register listener for key events from main process
+  const registerKeyListener = () => {
+    if (channel.onMain) {
+      // Main process plugin context
+      channel.onMain('core-box:key-event', (event: any) => {
+        const keyEvent = event.data as ForwardedKeyEvent
+        if (keyEvent) {
+          keyEventHandlers.forEach(handler => handler(keyEvent))
+        }
+      })
+    } else if (channel.on) {
+      // Renderer process context
+      channel.on('core-box:key-event', (data: any) => {
+        const keyEvent = data as ForwardedKeyEvent
+        if (keyEvent) {
+          keyEventHandlers.forEach(handler => handler(keyEvent))
+        }
+      })
+    }
+  }
+
+  registerInputListener()
+  registerKeyListener()
 
   return {
     pushItems(items: TuffItem[]): void {
@@ -200,6 +271,14 @@ export function createFeatureSDK(boxItemsAPI: any, channel: any): FeatureSDK {
       return () => {
         inputChangeHandlers.delete(handler)
       }
+    },
+
+    onKeyEvent(handler: KeyEventHandler): () => void {
+      keyEventHandlers.add(handler)
+      
+      return () => {
+        keyEventHandlers.delete(handler)
+      }
     }
   }
 }

package/plugin/sdk/flow.ts

@@ -0,0 +1,246 @@
+/**
+ * Flow SDK
+ *
+ * Plugin-side API for Flow Transfer operations.
+ * Allows plugins to dispatch flows and receive flow data.
+ */
+
+import type {
+  FlowPayload,
+  FlowDispatchOptions,
+  FlowDispatchResult,
+  FlowTargetInfo,
+  FlowSessionUpdate,
+  FlowPayloadType
+} from '../../types/flow'
+import { FlowIPCChannel } from '../../types/flow'
+
+/**
+ * Flow SDK interface
+ */
+export interface IFlowSDK {
+  /**
+   * Dispatches a flow payload to another plugin
+   *
+   * @param payload - Data to transfer
+   * @param options - Dispatch options
+   * @returns Dispatch result
+   *
+   * @example
+   * ```typescript
+   * const result = await flow.dispatch(
+   *   {
+   *     type: 'text',
+   *     data: 'Hello from plugin A',
+   *     context: { sourcePluginId: 'plugin-a' }
+   *   },
+   *   {
+   *     title: 'Share Text',
+   *     preferredTarget: 'plugin-b.quick-note'
+   *   }
+   * )
+   * ```
+   */
+  dispatch(payload: FlowPayload, options?: FlowDispatchOptions): Promise<FlowDispatchResult>
+
+  /**
+   * Gets available flow targets
+   *
+   * @param payloadType - Filter by payload type (optional)
+   * @returns List of available targets
+   */
+  getAvailableTargets(payloadType?: FlowPayloadType): Promise<FlowTargetInfo[]>
+
+  /**
+   * Listens for session updates
+   *
+   * @param sessionId - Session to listen to
+   * @param handler - Update handler
+   * @returns Unsubscribe function
+   */
+  onSessionUpdate(
+    sessionId: string,
+    handler: (update: FlowSessionUpdate) => void
+  ): () => void
+
+  /**
+   * Cancels a flow session
+   *
+   * @param sessionId - Session to cancel
+   */
+  cancel(sessionId: string): Promise<void>
+
+  /**
+   * Acknowledges a received flow (for target plugins)
+   *
+   * @param sessionId - Session to acknowledge
+   * @param ackPayload - Optional acknowledgment data
+   */
+  acknowledge(sessionId: string, ackPayload?: any): Promise<void>
+
+  /**
+   * Reports an error for a received flow (for target plugins)
+   *
+   * @param sessionId - Session to report error for
+   * @param message - Error message
+   */
+  reportError(sessionId: string, message: string): Promise<void>
+}
+
+/**
+ * Creates a Flow SDK instance
+ *
+ * @param channel - Channel for IPC communication
+ * @param pluginId - Current plugin ID
+ * @returns Flow SDK instance
+ */
+export function createFlowSDK(
+  channel: { send: (event: string, data?: any) => Promise<any> },
+  pluginId: string
+): IFlowSDK {
+  const sessionListeners = new Map<string, Set<(update: FlowSessionUpdate) => void>>()
+
+  // Listen for session updates
+  if (typeof window !== 'undefined') {
+    window.addEventListener('message', (event) => {
+      if (event.data?.type === FlowIPCChannel.SESSION_UPDATE) {
+        const update = event.data.payload as FlowSessionUpdate
+        const listeners = sessionListeners.get(update.sessionId)
+        if (listeners) {
+          for (const listener of listeners) {
+            try {
+              listener(update)
+            } catch (error) {
+              console.error('[FlowSDK] Error in session listener:', error)
+            }
+          }
+        }
+      }
+    })
+  }
+
+  return {
+    async dispatch(payload: FlowPayload, options?: FlowDispatchOptions): Promise<FlowDispatchResult> {
+      // Ensure context has sourcePluginId
+      const enrichedPayload: FlowPayload = {
+        ...payload,
+        context: {
+          ...payload.context,
+          sourcePluginId: payload.context?.sourcePluginId || pluginId
+        }
+      }
+
+      const response = await channel.send(FlowIPCChannel.DISPATCH, {
+        senderId: pluginId,
+        payload: enrichedPayload,
+        options
+      })
+
+      if (!response?.success) {
+        throw new Error(response?.error?.message || 'Flow dispatch failed')
+      }
+
+      return response.data
+    },
+
+    async getAvailableTargets(payloadType?: FlowPayloadType): Promise<FlowTargetInfo[]> {
+      const response = await channel.send(FlowIPCChannel.GET_TARGETS, {
+        payloadType
+      })
+
+      if (!response?.success) {
+        throw new Error(response?.error?.message || 'Failed to get targets')
+      }
+
+      return response.data || []
+    },
+
+    onSessionUpdate(
+      sessionId: string,
+      handler: (update: FlowSessionUpdate) => void
+    ): () => void {
+      if (!sessionListeners.has(sessionId)) {
+        sessionListeners.set(sessionId, new Set())
+      }
+      sessionListeners.get(sessionId)!.add(handler)
+
+      return () => {
+        const listeners = sessionListeners.get(sessionId)
+        if (listeners) {
+          listeners.delete(handler)
+          if (listeners.size === 0) {
+            sessionListeners.delete(sessionId)
+          }
+        }
+      }
+    },
+
+    async cancel(sessionId: string): Promise<void> {
+      const response = await channel.send(FlowIPCChannel.CANCEL, {
+        sessionId
+      })
+
+      if (!response?.success) {
+        throw new Error(response?.error?.message || 'Failed to cancel session')
+      }
+    },
+
+    async acknowledge(sessionId: string, ackPayload?: any): Promise<void> {
+      const response = await channel.send(FlowIPCChannel.ACKNOWLEDGE, {
+        sessionId,
+        ackPayload
+      })
+
+      if (!response?.success) {
+        throw new Error(response?.error?.message || 'Failed to acknowledge session')
+      }
+    },
+
+    async reportError(sessionId: string, message: string): Promise<void> {
+      const response = await channel.send(FlowIPCChannel.REPORT_ERROR, {
+        sessionId,
+        message
+      })
+
+      if (!response?.success) {
+        throw new Error(response?.error?.message || 'Failed to report error')
+      }
+    }
+  }
+}
+
+/**
+ * Helper to extract flow data from TuffQuery
+ *
+ * When a feature is triggered via Flow, the query will contain flow information.
+ *
+ * @param query - TuffQuery from feature trigger
+ * @returns Flow data if present, null otherwise
+ */
+export function extractFlowData(query: any): {
+  sessionId: string
+  payload: FlowPayload
+  senderId: string
+  senderName?: string
+} | null {
+  if (!query?.flow) {
+    return null
+  }
+
+  return {
+    sessionId: query.flow.sessionId,
+    payload: query.flow.payload,
+    senderId: query.flow.senderId,
+    senderName: query.flow.senderName
+  }
+}
+
+/**
+ * Helper to check if a feature was triggered via Flow
+ *
+ * @param query - TuffQuery from feature trigger
+ * @returns True if triggered via Flow
+ */
+export function isFlowTriggered(query: any): boolean {
+  return !!query?.flow
+}

package/plugin/sdk/hooks/bridge.ts

@@ -12,6 +12,7 @@ export type BridgeHook<T = any> = (data: T) => void
 const __hooks: Record<BridgeEvent, Array<BridgeHook>> = {
   [BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE]: [],
   [BridgeEventForCoreBox.CORE_BOX_CLIPBOARD_CHANGE]: [],
+  [BridgeEventForCoreBox.CORE_BOX_KEY_EVENT]: [],
 }
 
 /**
@@ -65,6 +66,22 @@ export const createBridgeHook = <T>(type: BridgeEvent) => (hook: BridgeHook<T>)
  * The hook receives the new input value as a string.
  * @param data The input change data (string).
  */
-export const onCoreBoxInputChange = createBridgeHook<{ query: string }>(BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE)
+export const onCoreBoxInputChange = createBridgeHook<{ query: { inputs: Array<any>, text: string } }>(BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE)
 
 export const onCoreBoxClipboardChange = createBridgeHook<{ item: any }>(BridgeEventForCoreBox.CORE_BOX_CLIPBOARD_CHANGE)
+
+/**
+ * Hook for when a keyboard event is forwarded from CoreBox.
+ * This is triggered when the plugin's UI view is attached and the user
+ * presses certain keys (Enter, Arrow keys, Meta+key combinations).
+ * @param data The forwarded keyboard event data.
+ */
+export const onCoreBoxKeyEvent = createBridgeHook<{
+  key: string
+  code: string
+  metaKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  shiftKey: boolean
+  repeat: boolean
+}>(BridgeEventForCoreBox.CORE_BOX_KEY_EVENT)

package/plugin/sdk/index.ts

@@ -13,9 +13,11 @@ export * from './clipboard'
 export * from './core-box'
 export * from './division-box'
 export * from './feature-sdk'
+export * from './flow'
 export { createFeaturesManager, useFeatures } from './features'
 
 export * from './hooks/index'
+export * from './performance'
 export * from './service/index'
 export * from './storage'
 export * from './system'

package/plugin/sdk/performance.ts

@@ -0,0 +1,201 @@
+/**
+ * Plugin Performance SDK
+ *
+ * Provides APIs for plugins to access their own performance metrics
+ * and storage statistics.
+ */
+import type { ITouchClientChannel } from '@talex-touch/utils/channel'
+import { ensureRendererChannel } from './channel'
+
+/**
+ * Storage statistics interface
+ */
+export interface StorageStats {
+  /** Total size in bytes */
+  totalSize: number
+  /** Number of files */
+  fileCount: number
+  /** Number of directories */
+  dirCount: number
+  /** Maximum allowed size in bytes */
+  maxSize: number
+  /** Usage percentage (0-100) */
+  usagePercent: number
+}
+
+/**
+ * Performance metrics interface
+ */
+export interface PerformanceMetrics {
+  /** Plugin load time in milliseconds */
+  loadTime: number
+  /** Estimated memory usage in bytes */
+  memoryUsage: number
+  /** CPU usage percentage (0-100) */
+  cpuUsage: number
+  /** Last active timestamp */
+  lastActiveTime: number
+}
+
+/**
+ * Plugin paths interface
+ */
+export interface PluginPaths {
+  /** Plugin installation directory */
+  pluginPath: string
+  /** Plugin data directory */
+  dataPath: string
+  /** Plugin config directory */
+  configPath: string
+  /** Plugin logs directory */
+  logsPath: string
+  /** Plugin temp directory */
+  tempPath: string
+}
+
+/**
+ * Performance SDK interface
+ */
+export interface PerformanceSDK {
+  /**
+   * Get storage statistics for the current plugin
+   *
+   * @example
+   * ```typescript
+   * const stats = await plugin.performance.getStorageStats()
+   * console.log(`Using ${stats.usagePercent}% of storage`)
+   * ```
+   */
+  getStorageStats: () => Promise<StorageStats>
+
+  /**
+   * Get performance metrics for the current plugin
+   *
+   * @example
+   * ```typescript
+   * const metrics = await plugin.performance.getMetrics()
+   * console.log(`Load time: ${metrics.loadTime}ms`)
+   * ```
+   */
+  getMetrics: () => Promise<PerformanceMetrics>
+
+  /**
+   * Get all paths for the current plugin
+   *
+   * @example
+   * ```typescript
+   * const paths = await plugin.performance.getPaths()
+   * console.log(`Plugin installed at: ${paths.pluginPath}`)
+   * ```
+   */
+  getPaths: () => Promise<PluginPaths>
+
+  /**
+   * Get combined performance data (storage + metrics + paths)
+   *
+   * @example
+   * ```typescript
+   * const data = await plugin.performance.getAll()
+   * console.log(data.storage, data.metrics, data.paths)
+   * ```
+   */
+  getAll: () => Promise<{
+    storage: StorageStats
+    metrics: PerformanceMetrics
+    paths: PluginPaths
+  }>
+}
+
+/**
+ * Creates a Performance SDK instance for plugin use
+ *
+ * @param channel - The plugin channel bridge for IPC communication
+ * @returns Configured Performance SDK instance
+ *
+ * @internal
+ */
+export function createPerformanceSDK(channel: ITouchClientChannel): PerformanceSDK {
+  return {
+    async getStorageStats(): Promise<StorageStats> {
+      try {
+        const result = await channel.send('plugin:storage:get-stats')
+        return result?.data || {
+          totalSize: 0,
+          fileCount: 0,
+          dirCount: 0,
+          maxSize: 10 * 1024 * 1024,
+          usagePercent: 0,
+        }
+      }
+      catch (error) {
+        console.error('[Performance SDK] Failed to get storage stats:', error)
+        throw error
+      }
+    },
+
+    async getMetrics(): Promise<PerformanceMetrics> {
+      try {
+        const result = await channel.send('plugin:performance:get-metrics')
+        return result?.data || {
+          loadTime: 0,
+          memoryUsage: 0,
+          cpuUsage: 0,
+          lastActiveTime: 0,
+        }
+      }
+      catch (error) {
+        console.error('[Performance SDK] Failed to get performance metrics:', error)
+        throw error
+      }
+    },
+
+    async getPaths(): Promise<PluginPaths> {
+      try {
+        const result = await channel.send('plugin:performance:get-paths')
+        return result?.data || {
+          pluginPath: '',
+          dataPath: '',
+          configPath: '',
+          logsPath: '',
+          tempPath: '',
+        }
+      }
+      catch (error) {
+        console.error('[Performance SDK] Failed to get plugin paths:', error)
+        throw error
+      }
+    },
+
+    async getAll(): Promise<{
+      storage: StorageStats
+      metrics: PerformanceMetrics
+      paths: PluginPaths
+    }> {
+      const [storage, metrics, paths] = await Promise.all([
+        this.getStorageStats(),
+        this.getMetrics(),
+        this.getPaths(),
+      ])
+
+      return { storage, metrics, paths }
+    },
+  }
+}
+
+/**
+ * Hook for using Performance SDK in plugin context
+ *
+ * @returns Performance SDK instance
+ *
+ * @example
+ * ```typescript
+ * const performance = usePerformance()
+ *
+ * const stats = await performance.getStorageStats()
+ * const metrics = await performance.getMetrics()
+ * ```
+ */
+export function usePerformance(): PerformanceSDK {
+  const channel = ensureRendererChannel('[Performance SDK] Channel not available. Make sure this is called in a plugin context.')
+  return createPerformanceSDK(channel)
+}

package/plugin/widget.ts

@@ -18,6 +18,11 @@ export interface WidgetRegistrationPayload {
   code: string
   styles: string
   hash: string
+  /**
+   * List of allowed module dependencies for widget sandbox
+   * Widget 沙箱允许的模块依赖列表
+   */
+  dependencies?: string[]
 }
 
 export function makeWidgetId(pluginName: string, featureId: string): string {