@talex-touch/utils 1.0.29 → 1.0.31

package/core-box/tuff/tuff-dsl.ts

@@ -16,7 +16,7 @@
  * @module core-box/tuff-dsl
  */
 
-import { TalexTouch } from "packages/utils/types";
+// import { TalexTouch } from "packages/utils/types";
 
 /**
  * 定义高亮范围
@@ -375,55 +375,15 @@ export interface TuffCustomRender {
   scripts?: string[];
 }
 
+import type { ITuffIcon } from '../../types/icon'
+
 /**
- * 图标定义
+ * Icon definition
  *
  * @description
- * 支持多种图标类型，从简单的emoji到复杂的组件。
- * 可以是简单字符串或包含详细配置的对象。
+ * Unified icon type supporting only ITuffIcon object format
  */
-export type TuffIcon =
-  | string  // 简单字符串：emoji、URL、组件名
-  | {
-      /**
-       * 图标类型
-       * @description 指定图标的数据格式和来源
-       * @required
-       */
-      type: 'emoji' | 'url' | 'base64' | 'fluent' | 'component';
-
-      /**
-       * 图标值
-       * @description 根据type不同，可能是emoji字符、URL地址、Base64编码或组件名
-       * @required
-       */
-      value: string;
-
-      /**
-       * 备用图标
-       * @description 当主图标无法加载时显示的替代图标
-       */
-      fallback?: string;
-
-      /**
-       * 动态加载函数
-       * @description 用于异步加载图标资源的函数
-       */
-      loader?: () => Promise<string>;
-
-      /**
-       * 样式配置
-       * @description 控制图标的视觉效果
-       */
-      style?: {
-        /** 图标尺寸 */
-        size?: number;
-        /** 图标颜色 */
-        color?: string;
-        /** 动画效果 */
-        animation?: 'spin' | 'pulse' | 'bounce';
-      };
-    };
+export type TuffIcon = ITuffIcon
 
 /**
  * 标签定义
@@ -1081,18 +1041,88 @@ export interface TuffDisplayAction extends Omit<TuffAction, 'payload'> {
 
 // ==================== 工具类型 ====================
 
+/**
+ * 查询输入类型枚举
+ *
+ * @description
+ * 定义系统支持的所有输入类型。
+ * 用于插件、providers 和 features 声明其支持的输入类型。
+ */
+export enum TuffInputType {
+  /** 纯文本输入 */
+  Text = 'text',
+  /** 图像输入（data URL 格式） */
+  Image = 'image',
+  /** 文件输入（文件路径数组） */
+  Files = 'files',
+  /** 富文本输入（HTML 格式） */
+  Html = 'html'
+}
+
+/**
+ * 查询输入项
+ *
+ * @description
+ * 定义查询中除文本外的多种类型输入（如剪贴板数据）。
+ * 用于支持图像、文件、富文本等多媒体输入。
+ */
+export interface TuffQueryInput {
+  /**
+   * 输入类型
+   * @description 定义输入数据的类型
+   * @required
+   */
+  type: TuffInputType;
+
+  /**
+   * 输入内容
+   * @description 根据类型不同包含不同格式的数据：
+   * - text: 纯文本字符串
+   * - image: data URL 格式的图像数据
+   * - files: JSON 序列化的文件路径数组
+   * - html: HTML 格式的富文本
+   * @required
+   */
+  content: string;
+
+  /**
+   * 原始内容
+   * @description 可选的原始格式内容，如富文本的 HTML 源码
+   */
+  rawContent?: string;
+
+  /**
+   * 缩略图
+   * @description 图像的缩略图 data URL（用于预览）
+   */
+  thumbnail?: string;
+
+  /**
+   * 元数据
+   * @description 附加的元数据信息
+   */
+  metadata?: Record<string, any>;
+}
+
 /**
  * 搜索查询结构
  *
  * @description
  * 定义搜索请求的参数和过滤条件。
  * 系统根据这些参数执行搜索并返回匹配结果。
+ * 
+ * **重要区分**：
+ * - `text`: 用户在输入框中主动输入的查询文本
+ * - `inputs`: 来自剪贴板或其他来源的附加输入数据（图像、文件、富文本等）
  */
 export interface TuffQuery {
   /**
-   * 查询文本
-   * @description 用户输入的搜索文本
+   * 用户输入的查询文本
+   * @description 这是用户在搜索框中主动输入的文本，不包括剪贴板内容
    * @required
+   * 
+   * @example
+   * 用户输入 "translate" → text = "translate"
    */
   text: string;
 
@@ -1102,6 +1132,31 @@ export interface TuffQuery {
    */
   type?: 'text' | 'voice' | 'image';
 
+  /**
+   * 多类型输入（附加数据）
+   * @description 除了用户输入的文本外的其他输入数据（如剪贴板中的图像、文件、富文本等）
+   * 
+   * **与 text 的区别**：
+   * - `text`: 用户主动输入，总是存在
+   * - `inputs`: 系统自动检测的附加数据，可能为空
+   * 
+   * 当用户触发 feature 时，系统会自动检测剪贴板并填充此字段。
+   * 
+   * @example
+   * 场景 1: 用户输入 "translate" + 剪贴板有图片
+   *   text: "translate"
+   *   inputs: [{ type: 'image', content: 'data:image/png;base64,...' }]
+   * 
+   * 场景 2: 用户输入 "compress" + 剪贴板有文件
+   *   text: "compress" 
+   *   inputs: [{ type: 'files', content: '["/path/to/file"]' }]
+   * 
+   * 场景 3: 用户输入 "format" + 剪贴板有富文本
+   *   text: "format"
+   *   inputs: [{ type: 'html', content: 'plain text', rawContent: '<p>html</p>' }]
+   */
+  inputs?: TuffQueryInput[];
+
   /**
    * 过滤条件
    * @description 限制搜索范围的过滤器
@@ -1277,6 +1332,15 @@ export interface ISearchProvider<C> {
    */
   readonly icon?: any
 
+  /**
+   * Supported input types
+   * @description Declares which types of inputs this provider can handle.
+   * If not specified, defaults to [TuffInputType.Text] only.
+   * When query contains non-text inputs, only providers supporting those types will be searched.
+   * @example [TuffInputType.Text, TuffInputType.Image, TuffInputType.Files]
+   */
+  readonly supportedInputTypes?: TuffInputType[]
+
   /**
    * Core search method (PULL mode).
    * The engine calls this method to get results from the provider.

package/index.ts

@@ -1,8 +1,12 @@
+// export * from './auth' // Renderer-only, use @talex-touch/utils/renderer instead
 export * from './base'
 export * from './common'
 export * from './plugin'
 export * from './core-box'
 export * from './channel'
 export * from './types'
+export * from './types/icon'
 export * from './eventbus'
 export * from './preload'
+export * from './types/download'
+export * from './types/update'

package/package.json

@@ -5,7 +5,7 @@
   "module": "./index.ts",
   "license": "MPL-2.0",
   "private": false,
-  "version": "1.0.29",
+  "version": "1.0.31",
   "scripts": {
     "publish": "npm publish --access public"
   },

package/plugin/index.ts

@@ -14,6 +14,9 @@ export enum PluginStatus {
   LOADING,
   LOADED,
   LOAD_FAILED,
+
+  DEV_DISCONNECTED,  // Dev Server 断连
+  DEV_RECONNECTING,  // 正在重连
 }
 
 export interface PluginIssue {
@@ -26,14 +29,16 @@ export interface PluginIssue {
   timestamp?: number
 }
 
-export interface IPluginIcon {
-  type: string | 'remixicon' | 'class'
-  value: any
-  _value?: string
-
-  init(): Promise<void>
+export interface DevServerHealthCheckResult {
+  healthy: boolean
+  version?: string
+  timestamp: number
+  error?: string
 }
 
+import type { ITuffIcon } from '../types/icon'
+
+
 export interface IPlatformInfo {
   enable: boolean
   arch: Arch[]
@@ -51,7 +56,7 @@ export interface IPluginBaseInfo {
   readme: string
   version: string
   desc: string
-  icon: IPluginIcon
+  icon: ITuffIcon
   platforms: IPlatform
   _uniqueChannelKey: string
 }
@@ -134,7 +139,7 @@ export interface IPluginFeature {
   id: string
   name: string
   desc: string
-  icon: IPluginIcon
+  icon: ITuffIcon
   push: boolean
   platform: IPlatform
   commands: IFeatureCommand[]
@@ -145,6 +150,15 @@ export interface IPluginFeature {
    * Default is 0
    */
   priority?: number
+  /**
+   * Accepted input types for this feature
+   * @description Declares which types of inputs this feature can accept and process.
+   * If not specified, defaults to ['text'] only (backward compatible).
+   * When query contains inputs, only features accepting those input types will be shown.
+   * @example ['text', 'image'] - Feature accepts both text and images
+   * @example ['image', 'files'] - Feature only accepts images and files (no text-only queries)
+   */
+  acceptedInputTypes?: Array<'text' | 'image' | 'files' | 'html'>
 }
 
 export type IFeatureInteraction = {
@@ -182,11 +196,14 @@ export interface IFeatureLifeCycle {
   /**
    * Called when a feature is triggered via a matching command.
    * @param id - Feature ID
-   * @param data - The triggering payload
+   * @param data - The triggering payload. Can be:
+   *   - string: Plain text query (backward compatible)
+   *   - TuffQuery object: Complete query with text and optional inputs array containing clipboard data (images, files, HTML)
    * @param feature - The full feature definition
    * @param signal - An AbortSignal to cancel the operation
+   * @returns If returns false, the feature will not enter activation state (e.g., just opens browser and exits)
    */
-  onFeatureTriggered(id: string, data: any, feature: IPluginFeature, signal?: AbortSignal): void
+  onFeatureTriggered(id: string, data: any, feature: IPluginFeature, signal?: AbortSignal): boolean | void
 
   /**
    * Called when user input changes within this feature’s input box.
@@ -248,10 +265,13 @@ export interface ITargetFeatureLifeCycle {
 
   /**
    * Called when the feature is triggered via a matching command.
-   * @param data - The triggering payload
+   * @param data - The triggering payload. Can be:
+   *   - string: Plain text query (backward compatible)
+   *   - TuffQuery object: Complete query with text and optional inputs array containing clipboard data (images, files, HTML)
    * @param feature - The full feature definition
+   * @returns If returns false, the feature will not enter activation state (e.g., just opens browser and exits)
    */
-  onFeatureTriggered(data: any, feature: IPluginFeature): void
+  onFeatureTriggered(data: any, feature: IPluginFeature): boolean | void
 
   /**
    * Called when user input changes within this feature’s input box.
@@ -323,11 +343,14 @@ export interface IPluginManager {
   pluginPath: string
   watcher: FSWatcher | null
   devWatcher: any // Temporarily any, as DevPluginWatcher is internal to core-app
+  healthMonitor: any | null // DevServerHealthMonitor instance, set by PluginModule
 
   getPluginList(): Array<object>
   setActivePlugin(pluginName: string): boolean
   hasPlugin(name: string): boolean
   getPluginByName(name: string): ITouchPlugin | undefined
+  enablePlugin(pluginName: string): Promise<boolean>
+  disablePlugin(pluginName: string): Promise<boolean>
   reloadPlugin(pluginName: string): Promise<void>
   persistEnabledPlugins(): Promise<void>
   listPlugins(): Promise<Array<string>>

package/plugin/preload.ts

@@ -1,9 +1,11 @@
 import type { ITouchClientChannel } from '../channel'
+import type { ITouchSDK } from './sdk/index'
+// Import SDK for side effects (initializes hooks)
 import './sdk/index'
 
-// window type
+// window type - includes both plugin preload types and SDK types
 declare global {
-  export interface Window {
+  interface Window {
     $plugin: {
       name: string
       path: Object
@@ -13,6 +15,7 @@ declare global {
     $config: {
       themeStyle: any
     }
+    $touchSDK: ITouchSDK
   }
 }
 

package/plugin/sdk/features.ts

@@ -121,7 +121,7 @@ export interface IFeaturesManager {
  * ```
  */
 export function createFeaturesManager(
-  pluginName: string,
+  _pluginName: string,
   utils: any
 ): IFeaturesManager {
   return {

package/plugin/sdk/index.ts

@@ -5,12 +5,7 @@ export interface ITouchSDK {
   __hooks: {}
 }
 
-// window type
-declare global {
-  export interface Window {
-    $touchSDK: ITouchSDK
-  }
-}
+// Note: Window.$touchSDK is declared in ../preload.ts to avoid duplicate declarations
 
 export * from './types'
 export * from './window/index'
@@ -22,4 +17,4 @@ export * from './clipboard'
 export * from './core-box'
 export * from './storage'
 export * from './system'
-export * from './features'
+export { createFeaturesManager, useFeatures } from './features'

package/plugin/sdk/storage.ts

@@ -1,3 +1,5 @@
+import type { StorageStats, StorageTreeNode, FileDetails } from '../../types/storage'
+
 /**
  * Get the storage for the current plugin.
  * It provides simple file-based storage that is persisted across application launches.
@@ -50,6 +52,68 @@ export function usePluginStorage() {
      */
     listFiles: async (): Promise<string[]> => {
       return channel.send('plugin:storage:list-files', { pluginName })
+    },
+
+    /**
+     * Gets storage statistics for the current plugin.
+     * @returns A promise that resolves with storage statistics.
+     */
+    getStats: async (): Promise<StorageStats> => {
+      return channel.send('plugin:storage:get-stats', { pluginName })
+    },
+
+    /**
+     * Gets the directory tree structure of plugin storage.
+     * @returns A promise that resolves with the tree structure.
+     */
+    getTree: async (): Promise<StorageTreeNode[]> => {
+      return channel.send('plugin:storage:get-tree', { pluginName })
+    },
+
+    /**
+     * Gets detailed information about a specific file.
+     * @param fileName The name of the file to get details for.
+     * @returns A promise that resolves with file details.
+     */
+    getFileDetails: async (fileName: string): Promise<FileDetails | null> => {
+      return channel.send('plugin:storage:get-file-details', { pluginName, fileName })
+    },
+
+    /**
+     * Clears all storage for the current plugin.
+     * @returns A promise that resolves with the operation result.
+     */
+    clearAll: async (): Promise<{ success: boolean, error?: string }> => {
+      return channel.send('plugin:storage:clear', { pluginName })
+    },
+
+    /**
+     * Opens the plugin storage folder in the system file manager.
+     * @returns A promise that resolves when the folder is opened.
+     */
+    openFolder: async (): Promise<void> => {
+      await channel.send('plugin:storage:open-folder', { pluginName })
+    },
+
+    /**
+     * Listens for changes to the storage.
+     * @param fileName The file name to listen for changes
+     * @param callback The function to call when the storage changes for the current plugin.
+     * @returns A function to unsubscribe from the listener.
+     */
+    onDidChange: (fileName: string, callback: (newConfig: any) => void) => {
+      const listener = (data: { name: string, fileName?: string }) => {
+        if (data.name === pluginName &&
+            (data.fileName === fileName || data.fileName === undefined)) {
+          callback(data)
+        }
+      }
+
+      channel.regChannel('plugin:storage:update', listener)
+
+      return () => {
+        channel.unRegChannel('plugin:storage:update', listener)
+      }
     }
   }
 }

package/plugin/sdk/types.ts

@@ -518,9 +518,29 @@ export interface IPluginLifecycle {
   /**
    * Called when a plugin feature is triggered
    * @param featureId - The ID of the triggered feature
-   * @param query - The search query or input data
+   * @param query - The search query or input data. Can be:
+   *   - string: Plain text query (backward compatible)
+   *   - TuffQuery object: Complete query with text and optional inputs array
+   *     - query.text: The text query string
+   *     - query.inputs: Array of TuffQueryInput objects (images, files, HTML)
    * @param feature - The feature configuration object
    * @returns Promise or void
+   * @example
+   * ```typescript
+   * onFeatureTriggered(featureId, query, feature) {
+   *   if (typeof query === 'string') {
+   *     // Backward compatible: plain text query
+   *     console.log('Text query:', query)
+   *   } else {
+   *     // New: complete query object
+   *     console.log('Text:', query.text)
+   *     const imageInput = query.inputs?.find(i => i.type === 'image')
+   *     if (imageInput) {
+   *       console.log('Image data:', imageInput.content)
+   *     }
+   *   }
+   * }
+   * ```
    */
   onFeatureTriggered(featureId: string, query: any, feature: any): Promise<void> | void;
 
@@ -842,3 +862,78 @@ export interface IPluginInfoManager {
    */
   getPlatforms(): any
 }
+
+/**
+ * Plugin state change event types
+ *
+ * @description
+ * Represents different types of plugin state changes for incremental updates
+ */
+export type PluginStateEvent =
+  | { type: 'added'; plugin: any }
+  | { type: 'removed'; name: string }
+  | { type: 'updated'; name: string; changes: Partial<any> }
+  | { type: 'status-changed'; name: string; status: number }
+  | { type: 'readme-updated'; name: string; readme: string }
+
+/**
+ * Plugin filter options for list queries
+ */
+export interface PluginFilters {
+  /** Filter by plugin status */
+  status?: number
+  /** Filter by enabled state */
+  enabled?: boolean
+  /** Filter by development mode */
+  dev?: boolean
+}
+
+/**
+ * Trigger feature request payload
+ */
+export interface TriggerFeatureRequest {
+  /** Plugin name */
+  plugin: string
+  /** Feature ID */
+  feature: string
+  /** Search query or trigger input */
+  query?: string
+}
+
+/**
+ * Input changed event payload
+ */
+export interface InputChangedRequest {
+  /** Plugin name */
+  plugin: string
+  /** Feature ID */
+  feature: string
+  /** Current input value */
+  query: string
+}
+
+/**
+ * Plugin install request payload
+ */
+export interface InstallRequest {
+  /** Install source (URL, file path, etc) */
+  source: string
+  /** Hint type for installer */
+  hintType?: string
+  /** Additional metadata */
+  metadata?: Record<string, any>
+  /** Client metadata */
+  clientMetadata?: Record<string, any>
+}
+
+/**
+ * Plugin install response
+ */
+export interface InstallResponse {
+  /** Whether installation was successful */
+  success: boolean
+  /** Error message if failed */
+  error?: string
+  /** Installed plugin name */
+  pluginName?: string
+}

package/preload/renderer.ts

@@ -2,7 +2,7 @@ import type { LoadingEvent, LoadingMode, LoadingState, PreloadAPI } from './load
 
 function getPreloadApi(): PreloadAPI | null {
   if (typeof window === 'undefined') return null
-  return window.api ?? null
+  return (window as any).api ?? null
 }
 
 export function sendPreloadEvent(event: LoadingEvent): void {

package/renderer/hooks/index.ts

@@ -1,2 +1,3 @@
 export * from './arg-mapper'
 export * from './initialize'
+export * from './performance'

package/renderer/hooks/initialize.ts

@@ -196,3 +196,8 @@ export function refreshPerformanceInfo(): IInitializationInfo {
   }
   return window.$initInfo
 }
+
+/**
+ * Development mode flag
+ */
+export const isDev = import.meta.env.MODE === 'development'

package/renderer/hooks/performance.ts

@@ -0,0 +1,87 @@
+/**
+ * Renderer Process Performance Monitoring
+ *
+ * Collects detailed performance metrics in the renderer process
+ */
+
+/**
+ * Renderer performance metrics
+ */
+export interface RendererPerformanceMetrics {
+  /** Performance timing origin */
+  timeOrigin: number
+  /** Navigation start time */
+  navigationStart: number
+  /** DOM content loaded event end */
+  domContentLoadedEventEnd?: number
+  /** Load event end */
+  loadEventEnd?: number
+  /** DOM interactive time */
+  domInteractive?: number
+  /** First paint time */
+  firstPaint?: number
+  /** First contentful paint time */
+  firstContentfulPaint?: number
+}
+
+/**
+ * Get current renderer performance metrics
+ */
+export function getRendererPerformanceMetrics(): RendererPerformanceMetrics {
+  const navEntry = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming
+  const paintEntries = performance.getEntriesByType('paint')
+
+  const firstPaint = paintEntries.find(e => e.name === 'first-paint')
+  const firstContentfulPaint = paintEntries.find(e => e.name === 'first-contentful-paint')
+
+  return {
+    timeOrigin: performance.timeOrigin,
+    navigationStart: performance.timeOrigin,
+    domContentLoadedEventEnd: navEntry?.domContentLoadedEventEnd,
+    loadEventEnd: navEntry?.loadEventEnd,
+    domInteractive: navEntry?.domInteractive,
+    firstPaint: firstPaint?.startTime,
+    firstContentfulPaint: firstContentfulPaint?.startTime
+  }
+}
+
+/**
+ * Wait for page load and collect metrics
+ */
+export function collectPerformanceMetricsOnLoad(): Promise<RendererPerformanceMetrics> {
+  return new Promise((resolve) => {
+    if (document.readyState === 'complete') {
+      // Page already loaded
+      setTimeout(() => {
+        resolve(getRendererPerformanceMetrics())
+      }, 0)
+    } else {
+      // Wait for load event
+      window.addEventListener('load', () => {
+        setTimeout(() => {
+          resolve(getRendererPerformanceMetrics())
+        }, 0)
+      }, { once: true })
+    }
+  })
+}
+
+/**
+ * Get performance summary for display
+ */
+export function getPerformanceSummary(): {
+  domReady: number
+  pageLoad: number
+  firstPaint: number | undefined
+  firstContentfulPaint: number | undefined
+} {
+  const metrics = getRendererPerformanceMetrics()
+
+  return {
+    domReady: metrics.domContentLoadedEventEnd || 0,
+    pageLoad: metrics.loadEventEnd || 0,
+    firstPaint: metrics.firstPaint,
+    firstContentfulPaint: metrics.firstContentfulPaint
+  }
+}
+