@talex-touch/utils 1.0.42 → 1.0.44

package/common/storage/entity/preset-export-types.ts

@@ -0,0 +1,256 @@
+import type {
+  CoreBoxCanvasConfig,
+  CoreBoxThemeConfig,
+  LayoutAtomConfig,
+  LayoutCanvasConfig,
+  ThemePresetConfig,
+} from './layout-atom-types'
+
+/**
+ * Version of the preset export format
+ * Increment when breaking changes occur
+ */
+export const PRESET_EXPORT_VERSION = 2
+
+/**
+ * Preset export data structure
+ * Supports both local file export and future cloud publishing
+ */
+export interface PresetExportData {
+  /** Export format version */
+  version: number
+  /** Export timestamp (ISO 8601) */
+  exportedAt: string
+  /** Optional preset metadata */
+  meta: PresetMeta
+  /** Layout atom configuration */
+  layout?: LayoutAtomConfig
+  /** CoreBox theme configuration */
+  coreBox?: CoreBoxThemeConfig
+  /** Theme-level configuration */
+  theme?: ThemePresetConfig
+  /** Main layout canvas configuration */
+  mainCanvas?: LayoutCanvasConfig
+  /** CoreBox canvas configuration */
+  coreBoxCanvas?: CoreBoxCanvasConfig
+}
+
+export interface PresetCompat {
+  minAppVersion?: string
+  maxAppVersion?: string
+}
+
+/**
+ * Preset metadata for identification and discovery
+ */
+export interface PresetMeta {
+  /** Unique preset ID (uuid for local, assigned for cloud) */
+  id?: string
+  /** Human-readable name */
+  name: string
+  /** Optional description */
+  description?: string
+  /** Author information */
+  author?: PresetAuthor
+  /** Tags for categorization */
+  tags?: string[]
+  /** Preview image URL or data URI */
+  preview?: string
+  /** Creation timestamp */
+  createdAt?: string
+  /** Last update timestamp */
+  updatedAt?: string
+  /** Release channel */
+  channel?: 'stable' | 'beta'
+  /** Compatibility window */
+  compat?: PresetCompat
+  /** Preset source */
+  source?: 'local' | 'nexus'
+}
+
+/**
+ * Author information for cloud-published presets
+ */
+export interface PresetAuthor {
+  /** Author display name */
+  name: string
+  /** Author ID (for cloud) */
+  id?: string
+  /** Author avatar URL */
+  avatar?: string
+}
+
+/**
+ * Cloud preset listing item (for marketplace)
+ */
+export interface CloudPresetItem {
+  /** Unique cloud ID */
+  id: string
+  /** Preset metadata */
+  meta: PresetMeta
+  /** Download count */
+  downloads: number
+  /** Like count */
+  likes: number
+  /** Whether current user liked */
+  liked?: boolean
+  /** Publish status */
+  status: 'published' | 'pending' | 'rejected'
+  /** Publish timestamp */
+  publishedAt: string
+}
+
+/**
+ * Cloud preset API response
+ */
+export interface CloudPresetListResponse {
+  items: CloudPresetItem[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+/**
+ * Cloud preset publish request
+ */
+export interface CloudPresetPublishRequest {
+  preset: PresetExportData
+  visibility: 'public' | 'unlisted' | 'private'
+}
+
+/**
+ * Validation result for preset import
+ */
+export interface PresetValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+}
+
+/**
+ * Validates a preset export data structure
+ */
+export function validatePresetData(data: unknown): PresetValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  if (!data || typeof data !== 'object') {
+    return { valid: false, errors: ['Invalid data format'], warnings: [] }
+  }
+
+  const preset = data as Record<string, unknown>
+
+  // Check version
+  if (typeof preset.version !== 'number') {
+    errors.push('Missing or invalid version field')
+  } else if (preset.version > PRESET_EXPORT_VERSION) {
+    warnings.push(`Preset version (${preset.version}) is newer than supported (${PRESET_EXPORT_VERSION})`)
+  }
+
+  // Check meta
+  if (!preset.meta || typeof preset.meta !== 'object') {
+    errors.push('Missing or invalid meta field')
+  } else {
+    const meta = preset.meta as Record<string, unknown>
+    if (typeof meta.name !== 'string' || !meta.name.trim()) {
+      errors.push('Missing or invalid preset name')
+    }
+  }
+
+  // Check that at least one config is present
+  if (!preset.layout && !preset.coreBox && !preset.theme && !preset.mainCanvas && !preset.coreBoxCanvas) {
+    warnings.push('Preset contains no configurable fields')
+  }
+
+  // Validate layout structure if present
+  if (preset.layout) {
+    const layout = preset.layout as Record<string, unknown>
+    if (!layout.preset || !layout.header || !layout.aside || !layout.view || !layout.nav) {
+      errors.push('Invalid layout configuration structure')
+    }
+  }
+
+  // Validate coreBox structure if present
+  if (preset.coreBox) {
+    const coreBox = preset.coreBox as Record<string, unknown>
+    if (!coreBox.preset || !coreBox.logo || !coreBox.input || !coreBox.results) {
+      errors.push('Invalid CoreBox configuration structure')
+    }
+  }
+
+  if (preset.theme) {
+    const theme = preset.theme as Record<string, unknown>
+    if (!theme.style && !theme.addon && !theme.transition && !theme.palette && !theme.window) {
+      warnings.push('Theme preset is empty')
+    }
+  }
+
+  if (preset.mainCanvas) {
+    const mainCanvas = preset.mainCanvas as Record<string, unknown>
+    if (
+      typeof mainCanvas.columns !== 'number'
+      || typeof mainCanvas.rowHeight !== 'number'
+      || !Array.isArray(mainCanvas.items)
+    ) {
+      errors.push('Invalid mainCanvas configuration structure')
+    }
+  }
+
+  if (preset.coreBoxCanvas) {
+    const coreBoxCanvas = preset.coreBoxCanvas as Record<string, unknown>
+    if (
+      typeof coreBoxCanvas.columns !== 'number'
+      || typeof coreBoxCanvas.rowHeight !== 'number'
+      || !Array.isArray(coreBoxCanvas.items)
+    ) {
+      errors.push('Invalid coreBoxCanvas configuration structure')
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  }
+}
+
+/**
+ * Creates a new preset export data structure
+ */
+export function createPresetExport(options: {
+  name: string
+  description?: string
+  layout?: LayoutAtomConfig
+  coreBox?: CoreBoxThemeConfig
+  theme?: ThemePresetConfig
+  mainCanvas?: LayoutCanvasConfig
+  coreBoxCanvas?: CoreBoxCanvasConfig
+  author?: PresetAuthor
+  tags?: string[]
+  channel?: 'stable' | 'beta'
+  source?: 'local' | 'nexus'
+  compat?: PresetCompat
+}): PresetExportData {
+  const now = new Date().toISOString()
+  return {
+    version: PRESET_EXPORT_VERSION,
+    exportedAt: now,
+    meta: {
+      id: crypto.randomUUID(),
+      name: options.name,
+      description: options.description,
+      author: options.author,
+      tags: options.tags,
+      createdAt: now,
+      updatedAt: now,
+      channel: options.channel ?? 'beta',
+      source: options.source ?? 'local',
+      compat: options.compat,
+    },
+    layout: options.layout,
+    coreBox: options.coreBox,
+    theme: options.theme,
+    mainCanvas: options.mainCanvas,
+    coreBoxCanvas: options.coreBoxCanvas,
+  }
+}

package/common/storage/entity/shortcut-settings.ts

@@ -8,6 +8,7 @@ export interface ShortcutMeta {
   modificationTime: number
   author: string
   description?: string
+  enabled?: boolean
 }
 
 export interface Shortcut {

package/common/storage/shortcut-storage.ts

@@ -55,6 +55,17 @@ class ShortcutStorage {
     this._save()
     return true
   }
+
+  updateShortcutEnabled(id: string, enabled: boolean): boolean {
+    const shortcut = this.getShortcutById(id)
+    if (!shortcut) {
+      return false
+    }
+    shortcut.meta.enabled = enabled
+    shortcut.meta.modificationTime = Date.now()
+    this._save()
+    return true
+  }
 }
 
 export default ShortcutStorage

package/common/utils/clone-diagnostics.ts

@@ -0,0 +1,105 @@
+export interface CloneIssue {
+  path: string
+  reason: string
+  type: string
+}
+
+const DEFAULT_MAX_DEPTH = 4
+const MAX_INSPECT_ITEMS = 50
+
+function getValueType(value: unknown): string {
+  return Object.prototype.toString.call(value)
+}
+
+export function isCloneError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  return message.includes('could not be cloned')
+    || message.includes('DataCloneError')
+    || message.includes('Cannot clone')
+}
+
+export function summarizeClonePayload(payload: unknown): Record<string, unknown> {
+  const summary: Record<string, unknown> = { valueType: typeof payload }
+  if (payload === null) {
+    summary.value = null
+    return summary
+  }
+  if (typeof payload !== 'object') {
+    summary.value = payload
+    return summary
+  }
+  summary.objectType = getValueType(payload)
+  if (Array.isArray(payload)) {
+    summary.length = payload.length
+    return summary
+  }
+  try {
+    const keys = Object.keys(payload as Record<string, unknown>)
+    summary.keys = keys.slice(0, 20)
+    summary.keysCount = keys.length
+  } catch (error) {
+    summary.keysError = error instanceof Error ? error.message : String(error)
+  }
+  return summary
+}
+
+export function findCloneIssue(
+  payload: unknown,
+  options?: { maxDepth?: number }
+): CloneIssue | null {
+  if (typeof structuredClone !== 'function') return null
+
+  const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH
+  const seen = new WeakSet<object>()
+
+  const inspect = (value: unknown, path: string, depth: number): CloneIssue | null => {
+    try {
+      structuredClone(value)
+      return null
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      if (depth >= maxDepth) {
+        return { path, reason: 'max_depth', type: getValueType(value) }
+      }
+      if (value && typeof value === 'object') {
+        if (seen.has(value)) {
+          return { path, reason: 'circular_ref', type: getValueType(value) }
+        }
+        seen.add(value)
+        if (Array.isArray(value)) {
+          const limit = Math.min(value.length, MAX_INSPECT_ITEMS)
+          for (let i = 0; i < limit; i += 1) {
+            const result = inspect(value[i], `${path}[${i}]`, depth + 1)
+            if (result) return result
+          }
+          if (value.length > limit) {
+            return { path, reason: 'array_truncated', type: getValueType(value) }
+          }
+        } else {
+          let entries: [string, unknown][]
+          try {
+            entries = Object.entries(value as Record<string, unknown>)
+          } catch (entryError) {
+            const entryReason = entryError instanceof Error ? entryError.message : String(entryError)
+            return { path, reason: entryReason, type: getValueType(value) }
+          }
+          const limit = Math.min(entries.length, MAX_INSPECT_ITEMS)
+          for (let i = 0; i < limit; i += 1) {
+            const entry = entries[i]
+            if (!entry)
+              continue
+            const [key, entryValue] = entry
+            const result = inspect(entryValue, `${path}.${key}`, depth + 1)
+            if (result) return result
+          }
+          if (entries.length > limit) {
+            return { path, reason: 'keys_truncated', type: getValueType(value) }
+          }
+        }
+      }
+      return { path, reason, type: getValueType(value) }
+    }
+  }
+
+  return inspect(payload, 'payload', 0)
+}

package/common/utils/file.ts

@@ -1,14 +1,22 @@
-// eslint-disable-next-line @typescript-eslint/no-var-requires
+import pathBrowserify from 'path-browserify'
+import { hasWindow } from '../../env'
+
 const path = (() => {
-  if (typeof window === 'undefined') {
-    return require('node:path')
-  }
-  try {
-    return require('path-browserify')
+  if (hasWindow()) {
+    return pathBrowserify
   }
-  catch {
-    return require('node:path')
+
+  const nodeRequire = typeof require === 'function' ? require : null
+  if (nodeRequire) {
+    try {
+      return nodeRequire('node:path')
+    }
+    catch {
+      return pathBrowserify
+    }
   }
+
+  return pathBrowserify
 })()
 
 /**

package/common/utils/index.ts

@@ -1,3 +1,5 @@
+import { hasDocument } from '../../env'
+
 /**
  * Delays execution for a given amount of milliseconds.
  *
@@ -51,7 +53,7 @@ export function anyStr2Num(str: string): bigint {
  * ```
  */
 export function num2anyStr(num: bigint): string {
-  const [baseStr, encoded] = num.toString().split('000')
+  const [baseStr, encoded = ''] = num.toString().split('000')
   const base = Number(baseStr)
 
   let result = ''
@@ -100,7 +102,7 @@ export function structuredStrictStringify(value: unknown): string {
       return 'null'
     if (Array.isArray(val))
       return 'Array'
-    if (typeof Document !== 'undefined') {
+    if (hasDocument()) {
       if (val instanceof Node)
         return 'DOMNode'
     }
@@ -177,6 +179,8 @@ export function structuredStrictStringify(value: unknown): string {
 }
 
 export * from './file'
+export * from './safe-path'
+export * from './safe-shell'
 
 export { type AdaptiveTaskQueueOptions, runAdaptiveTaskQueue } from './task-queue'
 

package/common/utils/payload-preview.ts

@@ -0,0 +1,173 @@
+export interface PayloadPreviewOptions {
+  maxOutputChars?: number
+  maxStringChars?: number
+  maxDepth?: number
+  maxKeys?: number
+  maxArrayLength?: number
+}
+
+const DEFAULT_OPTIONS: Required<PayloadPreviewOptions> = {
+  maxOutputChars: 800,
+  maxStringChars: 200,
+  maxDepth: 4,
+  maxKeys: 30,
+  maxArrayLength: 20,
+}
+
+function truncate(value: string, maxChars: number): string {
+  if (maxChars <= 0)
+    return ''
+  return value.length > maxChars ? `${value.slice(0, maxChars)}…` : value
+}
+
+function redactDataUrl(value: string, maxPrefixChars: number): string {
+  if (!value.startsWith('data:'))
+    return value
+  const base64Index = value.indexOf(';base64,')
+  if (base64Index === -1)
+    return value
+
+  const prefixEnd = base64Index + ';base64,'.length
+  const prefix = value.slice(0, prefixEnd)
+  const omittedChars = Math.max(0, value.length - prefixEnd)
+  const safePrefix = truncate(prefix, Math.max(10, maxPrefixChars))
+  return `${safePrefix}[base64 omitted ${omittedChars} chars]`
+}
+
+function isTypedArray(value: unknown): value is ArrayBufferView {
+  return (
+    typeof ArrayBuffer !== 'undefined'
+    && typeof ArrayBuffer.isView === 'function'
+    && ArrayBuffer.isView(value)
+  )
+}
+
+function bufferLength(value: unknown): number | null {
+  try {
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) {
+      return value.length
+    }
+  }
+  catch {
+    // ignore
+  }
+  return null
+}
+
+export function formatPayloadPreview(payload: unknown, options?: PayloadPreviewOptions): string {
+  const opts = { ...DEFAULT_OPTIONS, ...(options ?? {}) }
+
+  if (payload === null || payload === undefined)
+    return String(payload)
+  if (typeof payload === 'string') {
+    const redacted = redactDataUrl(payload, opts.maxStringChars)
+    return truncate(redacted, opts.maxOutputChars)
+  }
+
+  const seen = typeof WeakSet !== 'undefined' ? new WeakSet<object>() : null
+
+  const simplify = (value: unknown, depth: number): unknown => {
+    if (value === null || value === undefined)
+      return value
+    if (depth >= opts.maxDepth)
+      return '[max-depth]'
+
+    const valueType = typeof value
+    if (valueType === 'string') {
+      const redacted = redactDataUrl(value as string, opts.maxStringChars)
+      return truncate(redacted, opts.maxStringChars)
+    }
+    if (valueType === 'number' || valueType === 'boolean')
+      return value
+    if (valueType === 'bigint')
+      return `${value.toString()}n`
+    if (valueType === 'symbol')
+      return String(value)
+    if (valueType === 'function')
+      return '[function]'
+
+    if (value instanceof Error) {
+      return {
+        name: value.name,
+        message: truncate(value.message ?? '', opts.maxStringChars),
+        stack: typeof value.stack === 'string' ? truncate(value.stack, opts.maxOutputChars) : undefined,
+      }
+    }
+
+    const bufLen = bufferLength(value)
+    if (typeof bufLen === 'number')
+      return `[buffer ${bufLen} bytes]`
+    if (isTypedArray(value))
+      return `[typed-array ${value.byteLength} bytes]`
+    if (typeof ArrayBuffer !== 'undefined' && value instanceof ArrayBuffer) {
+      return `[array-buffer ${value.byteLength} bytes]`
+    }
+
+    if (Array.isArray(value)) {
+      const items = value.slice(0, opts.maxArrayLength).map(item => simplify(item, depth + 1))
+      if (value.length > opts.maxArrayLength) {
+        items.push(`[+${value.length - opts.maxArrayLength} more]`)
+      }
+      return items
+    }
+
+    if (valueType === 'object') {
+      const obj = value as Record<string, unknown>
+      if (seen) {
+        if (seen.has(obj))
+          return '[circular]'
+        seen.add(obj)
+      }
+
+      if (obj instanceof Map) {
+        return {
+          _type: 'Map',
+          size: obj.size,
+          entries: Array.from(obj.entries())
+            .slice(0, opts.maxArrayLength)
+            .map(([k, v]) => [simplify(k, depth + 1), simplify(v, depth + 1)]),
+        }
+      }
+
+      if (obj instanceof Set) {
+        return {
+          _type: 'Set',
+          size: obj.size,
+          values: Array.from(obj.values())
+            .slice(0, opts.maxArrayLength)
+            .map(v => simplify(v, depth + 1)),
+        }
+      }
+
+      const keys = Object.keys(obj)
+      const out: Record<string, unknown> = {}
+      for (const key of keys.slice(0, opts.maxKeys)) {
+        try {
+          out[key] = simplify(obj[key], depth + 1)
+        }
+        catch {
+          out[key] = '[throws]'
+        }
+      }
+      if (keys.length > opts.maxKeys) {
+        out._moreKeys = keys.length - opts.maxKeys
+      }
+      return out
+    }
+
+    try {
+      return truncate(String(value), opts.maxStringChars)
+    }
+    catch {
+      return '[unserializable]'
+    }
+  }
+
+  try {
+    const text = JSON.stringify(simplify(payload, 0))
+    return truncate(text, opts.maxOutputChars)
+  }
+  catch {
+    return '[unserializable]'
+  }
+}