@talex-touch/utils 1.0.40 → 1.0.44

package/plugin/sdk/storage.ts

@@ -1,5 +1,6 @@
 import type { FileDetails, StorageStats, StorageTreeNode } from '../../types/storage'
 import { ensureRendererChannel } from './channel'
+import { usePluginName } from './plugin-info'
 
 /**
  * Get the storage for the current plugin.
@@ -9,12 +10,7 @@ import { ensureRendererChannel } from './channel'
  * @returns An object with methods to interact with the storage.
  */
 export function usePluginStorage() {
-  // @ts-ignore
-  const pluginName = window.$plugin.name as string
-
-  if (!pluginName) {
-    throw new Error('[Plugin SDK] Cannot determine plugin name. Make sure this is called in a plugin context.')
-  }
+  const pluginName = usePluginName('[Plugin SDK] Cannot determine plugin name. Make sure this is called in a plugin context.')
 
   const channel = ensureRendererChannel('[Plugin Storage] Channel not available. Make sure this is called in a plugin context.')
 

package/plugin/sdk/system.ts

@@ -1,14 +1,7 @@
 import type { ActiveAppSnapshot } from './types'
-
-function ensurePluginChannel() {
-  const channel = (window as any)?.$channel
-  if (!channel) {
-    throw new Error('[Plugin SDK] System channel requires plugin renderer context with $channel available.')
-  }
-  return channel
-}
+import { useChannel } from './channel'
 
 export async function getActiveAppSnapshot(options: { forceRefresh?: boolean } = {}): Promise<ActiveAppSnapshot | null> {
-  const channel = ensurePluginChannel()
+  const channel = useChannel('[Plugin SDK] System channel requires plugin renderer context with $channel available.')
   return channel.send('system:get-active-app', options)
 }

package/plugin/sdk/temp-files.ts

@@ -0,0 +1,41 @@
+import { useChannel } from './channel'
+
+export interface TempPluginFileCreateOptions {
+  ext?: string
+  text?: string
+  base64?: string
+  prefix?: string
+  /**
+   * Optional retention in milliseconds.
+   * If omitted, the host will apply a default plugin temp retention policy.
+   */
+  retentionMs?: number
+}
+
+export interface TempPluginFileResult {
+  url: string
+  sizeBytes: number
+  createdAt: number
+}
+
+export function useTempPluginFiles() {
+  const channel = useChannel('[Plugin SDK] Temp files require plugin renderer context with $channel available.')
+
+  return {
+    async create(options: TempPluginFileCreateOptions): Promise<TempPluginFileResult> {
+      const res = await channel.send('temp-file:create', options ?? {})
+      if (!res || typeof res !== 'object') {
+        throw new Error('[Plugin SDK] temp-file:create returned invalid response')
+      }
+      return res as TempPluginFileResult
+    },
+
+    async delete(url: string): Promise<boolean> {
+      const res = await channel.send('temp-file:delete', { url })
+      if (res && typeof res === 'object' && 'success' in res) {
+        return Boolean((res as any).success)
+      }
+      return Boolean(res)
+    },
+  }
+}

package/plugin/sdk/touch-sdk.ts

@@ -0,0 +1,18 @@
+import type { ITouchSDK } from './index'
+import { hasWindow } from '../../env'
+
+const DEFAULT_TOUCH_SDK_ERROR
+  = '[TouchSDK] Touch SDK not available. Make sure this is called in a plugin context.'
+
+let cachedTouchSDK: ITouchSDK | null = null
+
+export function useTouchSDK(errorMessage: string = DEFAULT_TOUCH_SDK_ERROR): ITouchSDK {
+  const globalWindow = hasWindow() ? window : undefined
+  const windowSdk = (globalWindow as any)?.$touchSDK as ITouchSDK | undefined
+  const sdk = windowSdk ?? cachedTouchSDK
+  if (!sdk) {
+    throw new Error(errorMessage)
+  }
+  cachedTouchSDK = sdk
+  return sdk
+}

package/plugin/sdk/types.ts

@@ -6,6 +6,7 @@
 
 import type { ITouchChannel, ITouchClientChannel, StandardChannelData } from '@talex-touch/utils/channel'
 import type { IPluginFeature } from '../index'
+import path from 'node:path'
 
 /**
  * Handler signature for plugin channel events.
@@ -90,6 +91,15 @@ export interface IPluginRendererChannel {
 export interface PluginClipboardItem {
   id?: number
   type: 'text' | 'image' | 'files'
+  /**
+   * Clipboard content:
+   * - text: plain string
+   * - files: JSON string array
+   * - image: defaults to a small preview data URL to keep IPC payload light
+   *
+   * For images, the original asset URL (tfile://...) may be available at:
+   * - `meta.image_original_url`
+   */
   content: string
   thumbnail?: string | null
   rawContent?: string | null
@@ -144,7 +154,6 @@ export interface PluginClipboardSearchResponse {
   pageSize: number
 }
 
-
 export interface ActiveAppSnapshot {
   identifier: string | null
   displayName: string | null
@@ -230,6 +239,24 @@ export interface IPluginUtils {
    */
   feature: import('./feature-sdk').FeatureSDK
 
+  /**
+   * MetaOverlay SDK for registering global actions
+   * @see {@link MetaSDK}
+   */
+  meta: import('./meta-sdk').MetaSDK
+
+  /**
+   * Power SDK for low power status
+   * @see {@link PowerSDK}
+   */
+  power: import('./power').PowerSDK
+
+  /**
+   * Recommend SDK for registering custom recommendation providers
+   * @see {@link RecommendSDK}
+   */
+  recommend: import('./recommend').RecommendSDK
+
   /**
    * Opens a URL in the default browser
    * @param url - The URL to open
@@ -496,14 +523,14 @@ export interface IEventManager {
    * @param event - The event name to listen for
    * @param callback - The callback function to execute when event is emitted
    */
-  on: (event: string, callback: Function) => void
+  on: (event: string, callback: PluginEventHandler) => void
 
   /**
    * Removes an event listener
    * @param event - The event name to stop listening for
    * @param callback - The callback function to remove
    */
-  off: (event: string, callback: Function) => void
+  off: (event: string, callback: PluginEventHandler) => void
 
   /**
    * Emits an event with optional arguments
@@ -513,6 +540,8 @@ export interface IEventManager {
   emit: (event: string, ...args: any[]) => void
 }
 
+export type PluginEventHandler = (...args: any[]) => void
+
 /**
  * Plugin configuration interface
  *
@@ -644,7 +673,6 @@ export function createStorageManager(
   pluginPath: string,
   fse: any,
 ): IStorageManager {
-  const path = require('node:path')
   const dataPath = path.join(pluginPath, 'data')
 
   /**
@@ -954,6 +982,18 @@ export interface TriggerFeatureRequest {
   query?: string
 }
 
+/**
+ * Register a widget for preview or rendering
+ */
+export interface RegisterWidgetRequest {
+  /** Plugin name */
+  plugin: string
+  /** Feature ID */
+  feature: string
+  /** Emit update event even if cached */
+  emitAsUpdate?: boolean
+}
+
 /**
  * Input changed event payload
  */

package/plugin/sdk/window/index.ts

@@ -3,28 +3,31 @@ import type {
   BrowserWindowConstructorOptions,
   WebContents,
 } from 'electron'
-import { genChannel } from '../../channel'
+import { useChannel } from '../channel'
 
-export function createWindow(options: BrowserWindowConstructorOptions & { file?: string } & { url?: string }): number {
-  const res = genChannel().sendSync('window:new', options)
+export async function createWindow(
+  options: BrowserWindowConstructorOptions & { file?: string } & { url?: string },
+): Promise<number> {
+  const channel = useChannel('[Plugin SDK] Window creation requires renderer channel.')
+  const res = await channel.send('window:new', options)
   if (res.error)
     throw new Error(res.error)
 
   return res.id
 }
 
-export function toggleWinVisible(id: number, visible?: boolean): boolean {
-  const res = genChannel().sendSync('window:visible', visible !== undefined ? { id, visible } : { id })
+export async function toggleWinVisible(id: number, visible?: boolean): Promise<boolean> {
+  const channel = useChannel('[Plugin SDK] Window visibility requires renderer channel.')
+  const res = await channel.send('window:visible', visible !== undefined ? { id, visible } : { id })
   if (res.error)
     throw new Error(res.error)
 
   return res.visible
 }
 
-export function setWindowProperty(id: number, property: {
-
-}): boolean {
-  const res = genChannel().sendSync('window:property', { id, property })
+export async function setWindowProperty(id: number, property: WindowProperties): Promise<boolean> {
+  const channel = useChannel('[Plugin SDK] Window property requires renderer channel.')
+  const res = await channel.send('window:property', { id, property })
   if (res.error)
     throw new Error(res.error)
 

package/plugin/sdk-version.ts

@@ -0,0 +1,231 @@
+import type { SdkApiVersion } from './index'
+
+/**
+ * Known SDK API versions (format: YYMMDD).
+ *
+ * Ranges (rough):
+ * - < 251212: legacy mode (no permission enforcement, no category requirement)
+ * - 251212 ~ 260113: permission enforcement + new input model baseline
+ * - >= 260114: `manifest.json.category` is required for plugin grouping
+ * - >= 260121: `tfileScope` is required when requesting tfile access
+ * - >= 260215: plugin sqlite sdk is available
+ */
+export enum SdkApi {
+  /**
+   * 2025-12-12: permissions + input model baseline.
+   */
+  V251212 = 251212,
+  /**
+   * 2026-01-14: require `manifest.json.category` for plugins.
+   */
+  V260114 = 260114,
+  /**
+   * 2026-01-21: add tfile permission + scope enforcement.
+   */
+  V260121 = 260121,
+  /**
+   * 2026-02-15: add plugin sqlite sdk support.
+   */
+  V260215 = 260215,
+}
+
+/**
+ * Supported SDK versions in descending order.
+ * Used to gracefully fallback for unknown/invalid sdkapi values.
+ */
+export const SUPPORTED_SDK_VERSIONS: readonly SdkApiVersion[] = [
+  SdkApi.V260215,
+  SdkApi.V260121,
+  SdkApi.V260114,
+  SdkApi.V251212,
+]
+
+/**
+ * Current SDK API version.
+ * Updated when breaking changes are introduced to plugin APIs.
+ */
+export const CURRENT_SDK_VERSION: SdkApiVersion = SdkApi.V260215
+
+/**
+ * Minimum SDK version required for permission enforcement.
+ * Plugins below this version will bypass permission checks with a warning.
+ */
+export const PERMISSION_ENFORCEMENT_MIN_VERSION: SdkApiVersion = SdkApi.V251212
+
+/**
+ * Minimum SDK version required for `manifest.json.category`.
+ */
+export const CATEGORY_REQUIRED_MIN_VERSION: SdkApiVersion = SdkApi.V260114
+
+/**
+ * Minimum SDK version required for `tfileScope` enforcement.
+ */
+export const TFILE_SCOPE_REQUIRED_MIN_VERSION: SdkApiVersion = SdkApi.V260121
+
+/**
+ * SDK version compatibility result
+ */
+export interface SdkCompatibilityResult {
+  /** Whether the plugin SDK version is compatible */
+  compatible: boolean
+  /** Whether permission enforcement should be applied */
+  enforcePermissions: boolean
+  /** Warning message if compatibility issues exist */
+  warning?: string
+  /** Suggestion for fixing compatibility issues */
+  suggestion?: string
+}
+
+/**
+ * Check SDK version compatibility for a plugin.
+ * @param pluginSdkVersion - The sdkapi value from plugin manifest (undefined if not declared)
+ * @param pluginName - Plugin name for error messages
+ * @returns Compatibility check result
+ */
+export function checkSdkCompatibility(
+  pluginSdkVersion: SdkApiVersion | undefined,
+  pluginName: string,
+): SdkCompatibilityResult {
+  // No sdkapi declared - legacy plugin
+  if (pluginSdkVersion === undefined) {
+    return {
+      compatible: true,
+      enforcePermissions: false,
+      warning: `Plugin "${pluginName}" does not declare sdkapi version. Permission enforcement is disabled for compatibility.`,
+      suggestion: `Add "sdkapi": ${CURRENT_SDK_VERSION} to manifest.json to enable permission enforcement.`,
+    }
+  }
+
+  const resolved = resolveSdkApiVersion(pluginSdkVersion)
+  const warningParts: string[] = []
+  const suggestionParts: string[] = []
+
+  // Validate + normalize to a supported SDK version (graceful fallback)
+  if (resolved === undefined) {
+    return {
+      compatible: true,
+      enforcePermissions: false,
+      warning: `Plugin "${pluginName}" has invalid sdkapi value: ${pluginSdkVersion}. Falling back to legacy mode.`,
+      suggestion: `Use format YYMMDD (e.g., "sdkapi": ${CURRENT_SDK_VERSION}).`,
+    }
+  }
+
+  if (resolved !== pluginSdkVersion) {
+    warningParts.push(
+      `Plugin "${pluginName}" declares sdkapi ${pluginSdkVersion}, but it is not a supported SDK marker. Falling back to ${resolved}.`,
+    )
+    suggestionParts.push(`Use a supported sdkapi marker, e.g., ${CURRENT_SDK_VERSION}.`)
+  }
+
+  // Version too old - bypass permissions with warning
+  if (resolved < PERMISSION_ENFORCEMENT_MIN_VERSION) {
+    return {
+      compatible: true,
+      enforcePermissions: false,
+      warning: [
+        ...warningParts,
+        `Plugin "${pluginName}" uses legacy SDK version ${resolved}. Permission enforcement is disabled.`,
+      ].join(' '),
+      suggestion: [
+        ...suggestionParts,
+        `Update to sdkapi: ${CURRENT_SDK_VERSION} for full permission support.`,
+      ].join(' '),
+    }
+  }
+
+  // Version newer than current - might use unsupported features
+  if (pluginSdkVersion > CURRENT_SDK_VERSION) {
+    return {
+      compatible: true,
+      enforcePermissions: true,
+      warning: [
+        ...warningParts,
+        `Plugin "${pluginName}" requires SDK version ${pluginSdkVersion}, but current version is ${CURRENT_SDK_VERSION}. Some features may not work.`,
+      ].join(' '),
+      suggestion: [
+        ...suggestionParts,
+        `Update Tuff to the latest version for full compatibility.`,
+      ].join(' '),
+    }
+  }
+
+  // Perfect match or compatible older version
+  return {
+    compatible: true,
+    enforcePermissions: true,
+    warning: warningParts.length ? warningParts.join(' ') : undefined,
+    suggestion: suggestionParts.length ? suggestionParts.join(' ') : undefined,
+  }
+}
+
+/**
+ * Resolve a plugin-declared sdkapi to the nearest supported SDK marker.
+ *
+ * Rules:
+ * - Invalid values => undefined (legacy)
+ * - Unknown future versions => fallback to the latest supported <= declared
+ * - Known versions => keep as-is
+ */
+export function resolveSdkApiVersion(raw: unknown): SdkApiVersion | undefined {
+  const num
+    = typeof raw === 'number'
+      ? raw
+      : typeof raw === 'string'
+        ? parseSdkVersion(raw)
+        : undefined
+
+  if (num === undefined || !isValidSdkVersion(num)) {
+    return undefined
+  }
+
+  for (const v of SUPPORTED_SDK_VERSIONS) {
+    if (num >= v) {
+      return v
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Validate SDK version format (YYMMDD)
+ */
+export function isValidSdkVersion(version: number): boolean {
+  if (!Number.isInteger(version) || version < 100000 || version > 999999) {
+    return false
+  }
+
+  const str = version.toString()
+  const year = Number.parseInt(str.substring(0, 2), 10)
+  const month = Number.parseInt(str.substring(2, 4), 10)
+  const day = Number.parseInt(str.substring(4, 6), 10)
+
+  // Basic validation: year 20-99, month 01-12, day 01-31
+  return year >= 20 && year <= 99 && month >= 1 && month <= 12 && day >= 1 && day <= 31
+}
+
+/**
+ * Format SDK version for display
+ * @param version - SDK version number (YYMMDD)
+ * @returns Formatted string like "25.12.12"
+ */
+export function formatSdkVersion(version: SdkApiVersion): string {
+  const str = version.toString().padStart(6, '0')
+  return `${str.substring(0, 2)}.${str.substring(2, 4)}.${str.substring(4, 6)}`
+}
+
+/**
+ * Parse SDK version from string
+ * @param str - Version string like "251212" or "25.12.12"
+ * @returns SDK version number or undefined if invalid
+ */
+export function parseSdkVersion(str: string): SdkApiVersion | undefined {
+  // Remove dots if present
+  const cleaned = str.replace(/\./g, '')
+  const num = Number.parseInt(cleaned, 10)
+
+  if (isValidSdkVersion(num)) {
+    return num
+  }
+  return undefined
+}

package/preload/renderer.ts

@@ -1,7 +1,8 @@
 import type { LoadingEvent, LoadingMode, LoadingState, PreloadAPI } from './loading'
+import { hasWindow } from '../env'
 
 function getPreloadApi(): PreloadAPI | null {
-  if (typeof window === 'undefined')
+  if (!hasWindow())
     return null
   return (window as any).api ?? null
 }
@@ -37,7 +38,7 @@ export function preloadDebugStep(message: string, delta = 0.08): void {
 }
 
 export function preloadRemoveOverlay(): void {
-  if (typeof window === 'undefined')
+  if (!hasWindow())
     return
   window.postMessage({ payload: 'removeLoading' }, '*')
 }

package/renderer/hooks/arg-mapper.ts

@@ -5,6 +5,10 @@
 export interface IArgMapperOptions {
   /** The type of touch window - either main window or core-box popup */
   touchType?: 'main' | 'core-box'
+  /** The sub-type for core-box windows (e.g., division-box) */
+  coreType?: 'division-box'
+  /** Whether this is a meta-overlay WebContentsView */
+  metaOverlay?: 'true' | 'false'
   /** User data directory path */
   userDataDir?: string
   /** Application path */
@@ -31,23 +35,21 @@ declare global {
  * @param args - Array of command line arguments (defaults to process.argv)
  * @returns Mapped command line arguments as key-value pairs
  */
-export function useArgMapper(args: string[] = process.argv): IArgMapperOptions {
-  if (window.$argMapper) {
+export function useArgMapper(args: string[] = (globalThis as any)?.process?.argv ?? []): IArgMapperOptions {
+  if (window.$argMapper)
     return window.$argMapper
-  }
 
   const mapper: IArgMapperOptions = {}
-
   for (const arg of args) {
     if (arg.startsWith('--') && arg.includes('=')) {
       const [key, ...valueParts] = arg.slice(2).split('=')
       const value = valueParts.join('=')
-
+      if (!key)
+        continue
       const camelCaseKey = key.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
       mapper[camelCaseKey] = value
     }
   }
-
   return window.$argMapper = mapper
 }
 
@@ -76,3 +78,29 @@ export function isMainWindow() {
 export function isCoreBox() {
   return useTouchType() === 'core-box'
 }
+
+/**
+ * Gets the core-box sub-type from command line arguments
+ * @returns The core type ('division-box') or undefined
+ */
+export function useCoreType() {
+  const argMapper = useArgMapper()
+  return argMapper.coreType
+}
+
+/**
+ * Checks if the current window is a division-box window
+ * @returns True if the current window is a division-box
+ */
+export function isDivisionBox() {
+  return isCoreBox() && useCoreType() === 'division-box'
+}
+
+/**
+ * Checks if the current window is a meta-overlay WebContentsView
+ * @returns True if the current window is a meta-overlay
+ */
+export function isMetaOverlay() {
+  const argMapper = useArgMapper()
+  return argMapper.metaOverlay === 'true'
+}

package/renderer/hooks/index.ts

@@ -1,5 +1,18 @@
 export * from './arg-mapper'
 export * from './initialize'
 export * from './performance'
+export * from './use-agent-market-sdk'
+export * from './use-agents-sdk'
+export * from './use-app-sdk'
 export * from './use-channel'
+export * from './use-download-sdk'
 export * from './use-intelligence'
+export * from './use-intelligence-sdk'
+export * from './use-intelligence-stats'
+export * from './use-market-sdk'
+export * from './use-notification-sdk'
+export * from './use-permission-sdk'
+export * from './use-platform-sdk'
+export * from './use-plugin-sdk'
+export * from './use-settings-sdk'
+export * from './use-update-sdk'

package/renderer/hooks/initialize.ts

@@ -102,12 +102,13 @@ export function useInitialize(): IInitializationInfo {
   }
 
   const now = Date.now()
+  const runtimePlatform = (globalThis as any)?.process?.platform ?? navigator.platform
   const initInfo: IInitializationInfo = {
     initTimestamp: now,
     initTime: new Date(now).toISOString(),
     userAgent: navigator.userAgent,
     currentUrl: window.location.href,
-    platform: process.platform,
+    platform: runtimePlatform,
     screenResolution: {
       width: screen.width,
       height: screen.height,

package/renderer/hooks/use-agent-market-sdk.ts

@@ -0,0 +1,7 @@
+import { useTuffTransport } from '../../transport'
+import { createAgentMarketSdk } from '../../transport/sdk/domains/agents-market'
+
+export function useAgentMarketSdk() {
+  const transport = useTuffTransport()
+  return createAgentMarketSdk(transport)
+}