@followbin/dsh-selection 0.0.0-stage → 0.2.0

package/src/host/service.mjs

@@ -0,0 +1,334 @@
+// The Host half: owns settings, the worker process and model calls, and answers the settings page.
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { CUSTOM_SKILL_ICONS, ICONS } from '../shared/icons.mjs'
+import { openWithSystem } from '../shared/open-with-system.mjs'
+import { dataDirectory } from '../shared/paths.mjs'
+import { ModelError, createModelClient } from './llm.mjs'
+import {
+  BUILTIN_SKILLS, LANGUAGES, LIMITS, SEARCH_ENGINES,
+  createSettingsStore, defaultSettings, enabledSkills, findSkill, searchTemplate,
+} from './settings.mjs'
+import { buildRequest } from './skills.mjs'
+import { startWorker } from './supervisor.mjs'
+import { createUsageStore } from './usage.mjs'
+
+const WORKER_PATH = fileURLToPath(new URL('../worker/main.mjs', import.meta.url))
+const SUPPORTED_PLATFORMS = new Set(['darwin', 'win32'])
+const RECENT_APPS = 12
+const ACCESSIBILITY_SETTINGS_URL = 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'
+
+export class BadRequest extends Error {}
+
+/**
+ * @param {{
+ *   getLlm: () => any,
+ *   log: (level: string, message: string, fields?: object) => void,
+ *   dataDir?: string,
+ *   desktop: boolean,
+ *   promptForPermission?: boolean,
+ *   platform?: string,
+ *   startWorker?: typeof startWorker,
+ *   openExternal?: (url: string) => void,
+ * }} options `desktop` is false when the Host is not on the user's machine (e.g. a remote web Host).
+ *   Tests replace `platform`, `startWorker` and `openExternal`.
+ */
+export function createSelectionService({
+  getLlm, log, dataDir = dataDirectory(), desktop, promptForPermission = true,
+  platform = process.platform, startWorker: launchWorker = startWorker, openExternal = (url) => openWithSystem(url, log),
+}) {
+  const settings = createSettingsStore({ file: join(dataDir, 'settings.json'), log })
+  const model = createModelClient({ getLlm, log })
+  const usage = createUsageStore({ file: join(dataDir, 'usage.json'), log })
+  const subscribers = new Set()
+  const runs = new Map()
+  const recentApps = []
+  const status = {
+    platform,
+    supported: desktop && SUPPORTED_PLATFORMS.has(platform),
+    worker: 'stopped',
+    permission: platform === 'darwin' ? 'unknown' : 'granted',
+    hook: false,
+  }
+
+  const worker = status.supported
+    ? launchWorker({
+      workerPath: WORKER_PATH,
+      args: promptForPermission ? [] : ['--no-prompt'],
+      log,
+      onMessage: handleWorkerMessage,
+      onState: ({ state }) => {
+        // Answers in flight belong to the panel of the process that just went away.
+        if (state !== 'starting' && state !== 'running') abortRuns()
+        setStatus({ worker: state })
+      },
+    })
+    : null
+  if (!status.supported) log('info', 'selection toolbar not started', { platform, desktop })
+
+  let modelChoice = JSON.stringify(settings.get().model)
+  const unsubscribe = settings.onChange((next) => {
+    worker?.send({ type: 'config', config: workerConfig(next) })
+    if (JSON.stringify(next.model) !== modelChoice) {
+      modelChoice = JSON.stringify(next.model)
+      model.invalidate()
+    }
+    emit('settings', next)
+  })
+
+  function abortRuns() {
+    for (const controller of runs.values()) controller.abort()
+    runs.clear()
+  }
+
+  function recordUsage(skill, route, counts) {
+    usage.record({ skill, route, usage: counts })
+    emit('usage', usage.summary())
+  }
+
+  function emit(event, data) {
+    for (const subscriber of subscribers) subscriber(event, data)
+  }
+
+  function setStatus(patch) {
+    Object.assign(status, patch)
+    emit('status', status)
+  }
+
+  /** What the worker needs: no prompts or model details, only what to draw and how to behave. */
+  function workerConfig(current) {
+    return {
+      enabled: current.enabled,
+      trigger: current.trigger,
+      toolbarSize: current.toolbarSize,
+      toolbarStyle: current.toolbarStyle,
+      skills: enabledSkills(current),
+      disabledApps: current.disabledApps,
+      clipboardFallback: current.clipboardFallback,
+      maxTextLength: current.maxTextLength,
+      searchTemplate: searchTemplate(current),
+      translateTarget: current.translateTarget,
+      languages: LANGUAGES.map(({ code, name }) => ({ code, name })),
+    }
+  }
+
+  function handleWorkerMessage(message) {
+    switch (message?.type) {
+      case 'hello':
+        worker?.send({ type: 'config', config: workerConfig(settings.get()) })
+        break
+      case 'ready':
+        setStatus({ hook: Boolean(message.hookStarted) })
+        break
+      case 'permission':
+        setStatus({ permission: message.trusted ? 'granted' : 'denied' })
+        break
+      case 'selection':
+        rememberApp(message.app)
+        break
+      case 'run':
+        void runSkill(message)
+        break
+      case 'cancel':
+        runs.get(message.requestId)?.abort()
+        break
+      case 'toolbar-style':
+        if (message.style === 'full' || message.style === 'mini') {
+          try {
+            settings.update((current) => ({ ...current, toolbarStyle: message.style }))
+          } catch (error) {
+            log('error', 'saving settings failed', { error: String(error?.message ?? error) })
+          }
+        }
+        break
+      case 'disable-app':
+        if (typeof message.app === 'string' && message.app) {
+          try {
+            const saved = settings.update((current) => ({ ...current, disabledApps: [...current.disabledApps, message.app] }))
+            if (saved.disabledApps.includes(message.app)) log('info', 'app disabled from toolbar', { app: message.app })
+            else log('warn', 'app not disabled: the list is full', { app: message.app, limit: LIMITS.disabledApps })
+          } catch (error) {
+            log('error', 'saving settings failed', { error: String(error?.message ?? error) })
+          }
+        }
+        break
+      case 'open-settings':
+        openSettingsPage()
+        break
+      case 'log':
+        log(message.level ?? 'info', `worker: ${message.message}`, message.fields ?? {})
+        break
+    }
+  }
+
+  function rememberApp(app) {
+    if (typeof app !== 'string' || !app) return
+    const index = recentApps.indexOf(app)
+    if (index !== -1) recentApps.splice(index, 1)
+    recentApps.unshift(app)
+    recentApps.length = Math.min(recentApps.length, RECENT_APPS)
+  }
+
+  async function runSkill({ requestId, skillId, text, language, question, history }) {
+    const current = settings.get()
+    const controller = new AbortController()
+    runs.set(requestId, controller)
+    const started = Date.now()
+    let outputChars = 0
+    let route = null
+    try {
+      const skill = findSkill(current, skillId)
+      if (!skill || (skill.kind !== 'prompt' && skill.kind !== 'ask')) throw new ModelError('MODEL_FAILED', `unknown skill: ${skillId}`)
+      const input = {
+        text: String(text ?? '').slice(0, current.maxTextLength),
+        language: typeof language === 'string' ? language : undefined,
+        question: typeof question === 'string' ? question.slice(0, 2000) : undefined,
+        history: sanitizeHistory(history),
+      }
+      const prompt = (resolved) => {
+        route = resolved
+        return buildRequest(skill, current, { ...input, model: resolved.modelName })
+      }
+      const onUsage = (counts) => recordUsage(skillId, route, counts)
+      for await (const chunk of model.stream({ settings: current, prompt, signal: controller.signal, onUsage })) {
+        outputChars += chunk.length
+        worker?.send({ type: 'result', requestId, chunk })
+      }
+      worker?.send({ type: 'result', requestId, done: true })
+      log('info', 'skill finished', { skill: skillId, ...routeFields(route), ms: Date.now() - started, inputChars: String(text ?? '').length, outputChars })
+    } catch (error) {
+      if (controller.signal.aborted && !(error instanceof ModelError)) {
+        log('info', 'skill cancelled', { skill: skillId, ms: Date.now() - started })
+        return
+      }
+      const failure = toFailure(error)
+      worker?.send({ type: 'result', requestId, error: failure, done: true })
+      log('warn', 'skill failed', { skill: skillId, ...routeFields(route), ...failure, ms: Date.now() - started })
+    } finally {
+      if (runs.get(requestId) === controller) runs.delete(requestId)
+    }
+  }
+
+  /** Runs one request to the end for the settings page's test buttons; the stream's own silence limits apply. */
+  async function collect(skill, build, current) {
+    const controller = new AbortController()
+    const started = Date.now()
+    let route = null
+    const prompt = (resolved) => {
+      route = resolved
+      return build(resolved)
+    }
+    try {
+      let output = ''
+      const onUsage = (counts) => recordUsage(skill, route, counts)
+      for await (const chunk of model.stream({ settings: current, prompt, signal: controller.signal, onUsage })) output += chunk
+      return { ok: true, output, ms: Date.now() - started, route }
+    } catch (error) {
+      return { ok: false, error: toFailure(error), ms: Date.now() - started }
+    }
+  }
+
+  function openSettingsPage() {
+    emit('navigate', { panel: 'dsh-selection' })
+    // The page is open inside DSH; bring the window forward so the user sees it.
+    openExternal('dsh://open')
+  }
+
+  return {
+    getState() {
+      return {
+        settings: settings.get(),
+        defaults: defaultSettings(),
+        status,
+        recentApps: [...recentApps],
+        catalog: {
+          builtins: BUILTIN_SKILLS,
+          languages: LANGUAGES,
+          searchEngines: SEARCH_ENGINES,
+          icons: ICONS,
+          customIcons: CUSTOM_SKILL_ICONS,
+          limits: LIMITS,
+        },
+      }
+    },
+    /** Applies the changed fields only, so edits made meanwhile from the toolbar are not overwritten. */
+    saveSettings(patch) {
+      if (typeof patch !== 'object' || patch === null || Array.isArray(patch)) throw new BadRequest('settings must be an object')
+      return settings.update((current) => ({ ...current, ...patch }))
+    },
+    resetSettings: () => settings.reset(),
+    getUsage: () => usage.summary(),
+    resetUsage() {
+      usage.reset()
+      const summary = usage.summary()
+      emit('usage', summary)
+      return summary
+    },
+    /** DSH's model providers changed (sign-in, sign-out, a new API key). */
+    invalidateModels: () => model.invalidate(),
+    async listModels() {
+      try {
+        const routes = await model.listRoutes({ fresh: true })
+        const selected = routes.length ? await model.resolveRoute(settings.get()) : null
+        return { routes, selected }
+      } catch (error) {
+        return { routes: [], selected: null, error: toFailure(error) }
+      }
+    },
+    /** Sends one short translation through the selected route; the settings page shows the outcome. */
+    testModel() {
+      const current = settings.get()
+      return collect('model-test', () => buildRequest(findSkill(current, 'translate'), { ...current, translateTarget: 'en' }, { text: '你好，世界' }), current)
+    },
+    /** Runs a draft custom skill against sample text without saving it. */
+    testSkill(input) {
+      const prompt = typeof input?.prompt === 'string' ? input.prompt.trim().slice(0, LIMITS.customPrompt) : ''
+      const text = typeof input?.text === 'string' ? input.text.trim().slice(0, 2000) : ''
+      if (!prompt || !text) throw new BadRequest('prompt and text are required')
+      const current = settings.get()
+      const skill = { id: 'custom-test', kind: 'prompt', custom: true, prompt }
+      return collect('skill-test', (route) => buildRequest(skill, current, { text, model: route.modelName }), current)
+    },
+    restartWorker() {
+      if (!worker) throw new BadRequest('the selection toolbar is not supported on this Host')
+      worker.restart()
+    },
+    openPermissionSettings() {
+      if (platform !== 'darwin') throw new BadRequest('only macOS needs an accessibility grant')
+      openExternal(ACCESSIBILITY_SETTINGS_URL)
+    },
+    subscribe(listener) {
+      subscribers.add(listener)
+      return () => subscribers.delete(listener)
+    },
+    async dispose() {
+      unsubscribe()
+      abortRuns()
+      usage.flush()
+      emit('closing', {})
+      subscribers.clear()
+      await worker?.stop()
+    },
+  }
+}
+
+function sanitizeHistory(history) {
+  if (!Array.isArray(history)) return []
+  return history.slice(-6)
+    .filter((turn) => typeof turn?.answer === 'string' && (typeof turn.question === 'string' || typeof turn.skillId === 'string'))
+    .map((turn) => ({
+      ...(typeof turn.question === 'string' ? { question: turn.question.slice(0, 2000) } : { skillId: turn.skillId.slice(0, 64) }),
+      ...(typeof turn.language === 'string' ? { language: turn.language.slice(0, 16) } : {}),
+      answer: turn.answer.slice(0, 6000),
+    }))
+}
+
+/** Which route answered, for the log: ids only. */
+function routeFields(route) {
+  return route ? { provider: route.provider, model: route.model } : {}
+}
+
+function toFailure(error) {
+  if (error instanceof ModelError) return { code: error.code, detail: error.detail.slice(0, 300) }
+  return { code: 'MODEL_FAILED', detail: String(error?.message ?? error).slice(0, 300) }
+}

package/src/host/settings.mjs

@@ -0,0 +1,282 @@
+// User settings: the defaults, a normalizer that turns any input into a valid value,
+// and a file-backed store. Everything the settings page sends goes through normalizeSettings.
+import { readFileSync, renameSync } from 'node:fs'
+import { writeFileAtomic } from './files.mjs'
+import { CUSTOM_SKILL_ICONS, ICONS } from '../shared/icons.mjs'
+
+/** Built-in skills in their default order. `kind` decides who handles a click. */
+export const BUILTIN_SKILLS = Object.freeze([
+  { id: 'translate', kind: 'prompt', icon: 'translate', name: { zh: '翻译', en: 'Translate' } },
+  { id: 'summarize', kind: 'prompt', icon: 'summarize', name: { zh: '总结', en: 'Summarize' } },
+  { id: 'explain', kind: 'prompt', icon: 'explain', name: { zh: '解释', en: 'Explain' } },
+  { id: 'ask', kind: 'ask', icon: 'ask', name: { zh: '问问 DSH', en: 'Ask DSH' } },
+  { id: 'speak', kind: 'speak', icon: 'speak', name: { zh: '朗读', en: 'Read aloud' } },
+  { id: 'copy', kind: 'copy', icon: 'copy', name: { zh: '复制', en: 'Copy' } },
+  { id: 'polish', kind: 'prompt', icon: 'polish', name: { zh: '润色', en: 'Polish' } },
+  { id: 'search', kind: 'search', icon: 'search', name: { zh: '搜索', en: 'Search' } },
+])
+
+export const LANGUAGES = Object.freeze([
+  { code: 'zh-CN', name: '简体中文', english: 'Simplified Chinese' },
+  { code: 'zh-TW', name: '繁體中文', english: 'Traditional Chinese' },
+  { code: 'en', name: 'English', english: 'English' },
+  { code: 'ja', name: '日本語', english: 'Japanese' },
+  { code: 'ko', name: '한국어', english: 'Korean' },
+  { code: 'fr', name: 'Français', english: 'French' },
+  { code: 'de', name: 'Deutsch', english: 'German' },
+  { code: 'es', name: 'Español', english: 'Spanish' },
+  { code: 'ru', name: 'Русский', english: 'Russian' },
+  { code: 'pt', name: 'Português', english: 'Portuguese' },
+])
+
+export const SEARCH_ENGINES = Object.freeze({
+  google: 'https://www.google.com/search?q=%s',
+  bing: 'https://www.bing.com/search?q=%s',
+  baidu: 'https://www.baidu.com/s?wd=%s',
+  duckduckgo: 'https://duckduckgo.com/?q=%s',
+})
+
+export const LIMITS = Object.freeze({
+  toolbarSize: { min: 1, max: 8 },
+  maxTextLength: { min: 200, max: 20000 },
+  customSkills: 30,
+  customName: 16,
+  customPrompt: 4000,
+  disabledApps: 200,
+  appName: 200,
+})
+
+const LANGUAGE_CODES = new Set(LANGUAGES.map((language) => language.code))
+const BUILTIN_IDS = new Set(BUILTIN_SKILLS.map((skill) => skill.id))
+const CUSTOM_ID = /^custom-[a-z0-9]{4,24}$/
+
+/** @returns {Settings} */
+export function defaultSettings() {
+  return {
+    version: 1,
+    enabled: true,
+    trigger: 'auto',
+    toolbarSize: 5,
+    toolbarStyle: 'full',
+    skills: BUILTIN_SKILLS.map((skill) => ({ id: skill.id, enabled: true })),
+    disabledApps: [],
+    nativeLanguage: 'zh-CN',
+    translateTarget: 'auto',
+    answerLanguage: 'native',
+    model: { provider: '', model: '' },
+    maxTextLength: 4000,
+    clipboardFallback: true,
+    searchEngine: 'google',
+    customSearchUrl: '',
+  }
+}
+
+/**
+ * Coerces any value into valid settings. Unknown fields are dropped, bad values fall back to defaults.
+ * @param {unknown} input
+ * @returns {Settings}
+ */
+export function normalizeSettings(input) {
+  const defaults = defaultSettings()
+  const value = isObject(input) ? input : {}
+  const settings = {
+    version: 1,
+    enabled: typeof value.enabled === 'boolean' ? value.enabled : defaults.enabled,
+    trigger: value.trigger === 'modifier' ? 'modifier' : 'auto',
+    toolbarSize: clampInt(value.toolbarSize, LIMITS.toolbarSize, defaults.toolbarSize),
+    toolbarStyle: value.toolbarStyle === 'mini' ? 'mini' : 'full',
+    skills: normalizeSkills(value.skills),
+    disabledApps: normalizeApps(value.disabledApps),
+    nativeLanguage: LANGUAGE_CODES.has(value.nativeLanguage) ? value.nativeLanguage : defaults.nativeLanguage,
+    translateTarget: value.translateTarget === 'auto' || LANGUAGE_CODES.has(value.translateTarget) ? value.translateTarget : 'auto',
+    answerLanguage: ['native', 'source'].includes(value.answerLanguage) || LANGUAGE_CODES.has(value.answerLanguage) ? value.answerLanguage : 'native',
+    model: {
+      provider: shortString(value.model?.provider, 100),
+      model: shortString(value.model?.model, 200),
+    },
+    maxTextLength: clampInt(value.maxTextLength, LIMITS.maxTextLength, defaults.maxTextLength),
+    clipboardFallback: typeof value.clipboardFallback === 'boolean' ? value.clipboardFallback : defaults.clipboardFallback,
+    searchEngine: value.searchEngine === 'custom' || Object.hasOwn(SEARCH_ENGINES, value.searchEngine) ? value.searchEngine : 'google',
+    customSearchUrl: isSearchTemplate(value.customSearchUrl) ? value.customSearchUrl.trim() : '',
+  }
+  if (settings.searchEngine === 'custom' && !settings.customSearchUrl) settings.searchEngine = 'google'
+  return settings
+}
+
+/** URL template for the search skill; `%s` is replaced by the encoded selection. */
+export function searchTemplate(settings) {
+  return settings.searchEngine === 'custom' ? settings.customSearchUrl : SEARCH_ENGINES[settings.searchEngine]
+}
+
+/** Enabled skills in toolbar order, with what the toolbar needs to draw them. */
+export function enabledSkills(settings) {
+  const builtins = new Map(BUILTIN_SKILLS.map((skill) => [skill.id, skill]))
+  return settings.skills.filter((entry) => entry.enabled).map((entry) => {
+    if (entry.custom) return { id: entry.id, kind: 'prompt', icon: entry.icon, name: entry.name, custom: true }
+    const builtin = builtins.get(entry.id)
+    return { id: builtin.id, kind: builtin.kind, icon: builtin.icon, name: builtin.name, custom: false }
+  })
+}
+
+/** Looks a skill up by id, including disabled ones (a click may race a settings change). */
+export function findSkill(settings, id) {
+  const entry = settings.skills.find((skill) => skill.id === id)
+  if (!entry) return null
+  if (entry.custom) return { ...entry, kind: 'prompt' }
+  return { ...BUILTIN_SKILLS.find((skill) => skill.id === id), enabled: entry.enabled }
+}
+
+const UNREAD_RETRY_MS = 2000
+
+/**
+ * File-backed settings. Writes are atomic (temp file + rename). A file that is not valid JSON is moved
+ * aside and replaced by defaults instead of blocking startup.
+ * @param {{ file: string, log?: (level: string, message: string, fields?: object) => void }} options
+ */
+export function createSettingsStore({ file, log }) {
+  const listeners = new Set()
+  // The file exists but could not be read (locked, no permission, out of descriptors). Until a read
+  // succeeds the defaults stand in, nothing is written over the file, and it is read again now and
+  // then; when that works, every listener (the worker among them) gets the real settings.
+  let unread = false
+  let retry = null
+  let current = load()
+
+  function load() {
+    let text
+    try {
+      text = readFileSync(file, 'utf8')
+    } catch (error) {
+      if (error?.code === 'ENOENT') return defaultSettings()
+      if (!unread) log?.('warn', 'settings file could not be read, using defaults for now', { error: String(error?.message ?? error) })
+      unread = true
+      retry ??= setTimeout(() => {
+        retry = null
+        latest()
+      }, UNREAD_RETRY_MS)
+      retry.unref?.()
+      return defaultSettings()
+    }
+    unread = false
+    try {
+      return normalizeSettings(JSON.parse(text))
+    } catch (error) {
+      log?.('warn', 'settings file is not valid JSON, moved aside', { error: String(error?.message ?? error) })
+      try { renameSync(file, `${file}.broken-${Date.now()}`) } catch { /* nothing left to preserve */ }
+      return defaultSettings()
+    }
+  }
+
+  function latest() {
+    if (!unread) return current
+    const next = load()
+    if (unread) return current
+    current = next
+    for (const listener of listeners) listener(current)
+    return current
+  }
+
+  function save(next) {
+    latest()
+    if (unread) throw new Error('the settings file cannot be read right now, so it was left unchanged')
+    const normalized = normalizeSettings(next)
+    // A change that normalization undid, or no change at all: nothing to write or announce.
+    if (JSON.stringify(normalized) === JSON.stringify(current)) return current
+    writeFileAtomic(file, `${JSON.stringify(normalized, null, 2)}\n`)
+    current = normalized
+    for (const listener of listeners) listener(current)
+    return current
+  }
+
+  return {
+    get: latest,
+    save,
+    update: (change) => save(change(structuredClone(latest()))),
+    reset: () => save(defaultSettings()),
+    onChange(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+}
+
+function normalizeSkills(input) {
+  const skills = []
+  const seen = new Set()
+  let customCount = 0
+  for (const entry of Array.isArray(input) ? input : []) {
+    if (!isObject(entry) || typeof entry.id !== 'string' || seen.has(entry.id)) continue
+    const enabled = typeof entry.enabled === 'boolean' ? entry.enabled : true
+    if (BUILTIN_IDS.has(entry.id)) {
+      skills.push({ id: entry.id, enabled })
+      seen.add(entry.id)
+      continue
+    }
+    if (!CUSTOM_ID.test(entry.id) || customCount >= LIMITS.customSkills) continue
+    const name = shortString(entry.name, LIMITS.customName)
+    const prompt = shortString(entry.prompt, LIMITS.customPrompt)
+    if (!name || !prompt) continue
+    const icon = CUSTOM_SKILL_ICONS.includes(entry.icon) && Object.hasOwn(ICONS, entry.icon) ? entry.icon : 'sparkles'
+    skills.push({ id: entry.id, custom: true, enabled, name, icon, prompt })
+    seen.add(entry.id)
+    customCount += 1
+  }
+  // Skills added in a newer release show up enabled at the end of an existing list.
+  for (const builtin of BUILTIN_SKILLS) {
+    if (!seen.has(builtin.id)) skills.push({ id: builtin.id, enabled: true })
+  }
+  return skills
+}
+
+function normalizeApps(input) {
+  const apps = new Set()
+  for (const entry of Array.isArray(input) ? input : []) {
+    const app = shortString(entry, LIMITS.appName)
+    if (app) apps.add(app)
+    if (apps.size >= LIMITS.disabledApps) break
+  }
+  return [...apps]
+}
+
+function isSearchTemplate(value) {
+  if (typeof value !== 'string' || value.length > 500 || !value.includes('%s')) return false
+  try {
+    const url = new URL(value.trim().replace('%s', 'x'))
+    return url.protocol === 'https:' || url.protocol === 'http:'
+  } catch {
+    return false
+  }
+}
+
+function clampInt(value, { min, max }, fallback) {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.min(max, Math.max(min, Math.round(number)))
+}
+
+function shortString(value, max) {
+  return typeof value === 'string' ? value.trim().slice(0, max) : ''
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * @typedef {object} Settings
+ * @property {1} version
+ * @property {boolean} enabled Show the toolbar when text is selected.
+ * @property {'auto' | 'modifier'} trigger `modifier` shows it only while ⌥ / Alt is held.
+ * @property {number} toolbarSize How many enabled skills sit on the toolbar; the rest go to the ⋯ menu.
+ * @property {'full' | 'mini'} toolbarStyle Full: skill buttons on the toolbar. Mini: one icon whose menu holds every skill.
+ * @property {Array<{ id: string, enabled: boolean, custom?: true, name?: string, icon?: string, prompt?: string }>} skills
+ * @property {string[]} disabledApps Program names (as reported by the OS) where the toolbar never shows.
+ * @property {string} nativeLanguage Language the user reads best; auto translation flips around it.
+ * @property {string} translateTarget `auto` or a language code.
+ * @property {string} answerLanguage `native`, `source` or a language code, for summaries, explanations and answers.
+ * @property {{ provider: string, model: string }} model Empty strings pick a route automatically.
+ * @property {number} maxTextLength Longer selections are cut before being sent anywhere.
+ * @property {boolean} clipboardFallback Simulate a copy when accessibility APIs cannot read the selection.
+ * @property {string} searchEngine A key of SEARCH_ENGINES or `custom`.
+ * @property {string} customSearchUrl http(s) URL containing `%s`.
+ */