@ouraihub/aether-ui 0.1.0 → 0.1.2

package/src/chat/chat-panel-history.svelte.ts

@@ -0,0 +1,430 @@
+import { SvelteMap } from 'svelte/reactivity'
+import type { KitNotify } from '../context'
+import type {
+  Conversation,
+  ConversationClient,
+  ConversationSummary,
+  ModelOption,
+  ModelRef,
+} from '../ports'
+import type { ChatTurn, RunSession } from './run-session.svelte'
+
+type Translate = (key: string, values?: Record<string, string | number>) => string
+
+type HistoryDependencies = {
+  history: ConversationClient | undefined
+  getSession: () => RunSession | null
+  getModelOptions: () => ModelOption[] | null
+  getModelError: () => string | null
+  setDraft: (value: string) => void
+  bumpDraftRevision: () => void
+  setFullAccess: (value: boolean) => void
+  getScope: () => string | undefined
+  getLocale: () => string
+  onConversationChange?: ((id: string | null) => void) | undefined
+  bumpScrollRevision: () => void
+  notify: KitNotify
+  t: Translate
+  errorText: (error: unknown) => string
+  consumeBase: () => Parameters<RunSession['translate']>[0]
+  discardRecovery: () => void
+}
+
+export class ChatPanelHistoryState {
+  readonly history: ConversationClient | undefined
+  conversations = $state<ConversationSummary[]>([])
+  shownSummary = $state<ConversationSummary | null>(null)
+  historyOpen = $state(false)
+  historyBusy = $state(false)
+  historyLoading = $state(false)
+  historyError = $state<string | null>(null)
+  retryHistory = $state<() => Promise<void>>(async () => {
+    await this.refresh()
+  })
+  renameTitle = $state('')
+  renaming = $state(false)
+  restored = $state(false)
+  restoreBlocked = $state(false)
+  replyDialog = $state<'edit' | 'translate' | null>(null)
+  replyOpen = $state(false)
+  sourceReply = $state<ChatTurn | null>(null)
+  editDraft = $state('')
+  expectedText = ''
+  targetLanguage = $state('')
+  replyModel = $state<ModelRef | null>(null)
+  replyError = $state<string | null>(null)
+  viewGeneration = $state(0)
+  disposed = $state(false)
+  #listGeneration = 0
+  #reported: string | null
+  readonly #deps: HistoryDependencies
+
+  constructor(deps: HistoryDependencies, initialConversationId: string | null) {
+    this.#deps = deps
+    this.history = deps.history
+    this.#reported = initialConversationId
+    this.retryHistory = this.refresh
+  }
+
+  get title() {
+    const session = this.#deps.getSession()
+    return (
+      (this.shownSummary?.id === session?.conversationId ? this.shownSummary?.title : null) ??
+      this.conversations.find((conversation) => conversation.id === session?.conversationId)
+        ?.title ??
+      this.#deps.t('chat.newConversation')
+    )
+  }
+
+  get groups() {
+    const grouped = new SvelteMap<string, ChatTurn[]>()
+    for (const turn of this.#deps.getSession()?.turns ?? []) {
+      const replies = grouped.get(turn.questionId)
+      if (replies) replies.push(turn)
+      else grouped.set(turn.questionId, [turn])
+    }
+    return [...grouped.entries()]
+  }
+
+  get actionBusy() {
+    return this.historyBusy || this.#deps.getSession()?.running === true || this.restoreBlocked
+  }
+
+  get validReplyModel() {
+    const model = this.replyModel
+    return (
+      this.#deps
+        .getModelOptions()
+        ?.some(
+          (option) => option.endpointId === model?.endpointId && option.modelId === model?.modelId,
+        ) === true
+    )
+  }
+
+  get isRestored() {
+    return this.restored
+  }
+
+  dispose = () => {
+    this.disposed = true
+    this.viewGeneration++
+    this.#listGeneration++
+    this.#deps.setFullAccess(false)
+    this.#deps.getSession()?.dispose()
+  }
+
+  syncConversation = () => {
+    const session = this.#deps.getSession()
+    const id = session?.conversationId ?? null
+    if (!this.restored || this.restoreBlocked || id === this.#reported) return
+    this.#reported = id
+    this.#deps.onConversationChange?.(id)
+  }
+
+  refresh = async () => {
+    if (!this.history) return
+    const generation = ++this.#listGeneration
+    this.historyLoading = true
+    try {
+      const next = await this.history.list(this.#deps.getScope())
+      if (this.disposed || generation !== this.#listGeneration) return
+      this.conversations = next
+      if (this.retryHistory === this.refresh) this.historyError = null
+    } catch (error) {
+      if (!this.disposed && generation === this.#listGeneration && !this.restoreBlocked) {
+        this.historyError = this.#deps.errorText(error)
+        this.retryHistory = this.refresh
+      }
+    } finally {
+      if (!this.disposed && generation === this.#listGeneration) this.historyLoading = false
+    }
+  }
+
+  restore = async (id: string | null) => {
+    if (id !== null && this.history && this.#deps.getSession()) {
+      this.restoreBlocked = true
+      await this.open(id)
+    }
+    this.restored = true
+  }
+
+  open = async (id: string) => {
+    const session = this.#deps.getSession()
+    if (!this.history || !session || session.running || this.historyBusy) return
+    const generation = ++this.viewGeneration
+    this.#deps.setFullAccess(false)
+    this.historyBusy = true
+    try {
+      const conversation = await this.history.get(id)
+      if (this.disposed || generation !== this.viewGeneration) return
+      session.show(id, conversation.turns, conversation.summary.selectedTurnId)
+      this.shownSummary = conversation.summary
+      this.restoreBlocked = false
+      this.restored = true
+      this.historyError = null
+      this.retryHistory = this.refresh
+      this.historyOpen = false
+      this.renaming = false
+      this.#deps.bumpScrollRevision()
+    } catch (error) {
+      if (this.disposed || generation !== this.viewGeneration) return
+      this.historyError = this.#deps.errorText(error)
+      this.retryHistory = () => this.open(id)
+    } finally {
+      if (!this.disposed && generation === this.viewGeneration) this.historyBusy = false
+    }
+  }
+
+  newConversation = () => {
+    const session = this.#deps.getSession()
+    if (!session || session.running || this.historyBusy) return
+    this.viewGeneration++
+    this.#deps.setFullAccess(false)
+    session.show(null)
+    this.shownSummary = null
+    this.restoreBlocked = false
+    this.restored = true
+    this.historyError = null
+    this.historyOpen = false
+    this.renaming = false
+    this.#deps.bumpScrollRevision()
+  }
+
+  rename = async () => {
+    const session = this.#deps.getSession()
+    const id = session?.conversationId
+    const next = this.renameTitle.trim()
+    if (!this.history || !id || !next || session?.running || this.historyBusy) return
+    const generation = this.viewGeneration
+    this.historyBusy = true
+    try {
+      const summary = await this.history.rename(id, next)
+      if (this.disposed || generation !== this.viewGeneration) return
+      this.shownSummary = summary
+      this.conversations = this.conversations.map((item) => (item.id === id ? summary : item))
+      this.renaming = false
+      this.historyError = null
+    } catch (error) {
+      if (this.disposed || generation !== this.viewGeneration) return
+      this.historyError = this.#deps.errorText(error)
+      this.retryHistory = this.rename
+    } finally {
+      if (!this.disposed && generation === this.viewGeneration) this.historyBusy = false
+    }
+  }
+
+  remove = async () => {
+    const session = this.#deps.getSession()
+    const id = session?.conversationId
+    if (!this.history || !session || !id || session.running || this.historyBusy) return
+    const generation = this.viewGeneration
+    this.historyBusy = true
+    try {
+      const ok = await this.#deps.notify.confirm({
+        title: this.#deps.t('chat.deleteTitle'),
+        body: this.#deps.t('chat.deleteBody'),
+        danger: true,
+      })
+      if (!ok || this.disposed || generation !== this.viewGeneration) return
+      await this.history.remove(id)
+      if (this.disposed || generation !== this.viewGeneration) return
+      if (session.conversationId === id) {
+        session.show(null)
+        this.shownSummary = null
+        this.historyOpen = false
+        this.renaming = false
+        this.#deps.bumpScrollRevision()
+      }
+      this.historyError = null
+      void this.refresh()
+    } catch (error) {
+      if (this.disposed || generation !== this.viewGeneration) return
+      this.historyError = this.#deps.errorText(error)
+      this.retryHistory = this.remove
+    } finally {
+      if (!this.disposed && generation === this.viewGeneration) this.historyBusy = false
+    }
+  }
+
+  sourceModel = (turn: ChatTurn): ModelRef | null =>
+    turn.endpointId && turn.modelId ? { endpointId: turn.endpointId, modelId: turn.modelId } : null
+
+  sourceLabel = (turn: ChatTurn) => {
+    const option = this.#deps
+      .getModelOptions()
+      ?.find((item) => item.endpointId === turn.endpointId && item.modelId === turn.modelId)
+    return option
+      ? (option.name ?? option.modelId)
+      : turn.modelId
+        ? `${turn.endpointId ?? this.#deps.t('chat.unknown')} · ${turn.modelId}`
+        : this.#deps.t('chat.noSourceModel')
+  }
+
+  #hasChildren(turn: ChatTurn) {
+    return (
+      this.#deps
+        .getSession()
+        ?.turns.some((child) => child.parentId === turn.id || child.supersedesId === turn.id) ===
+      true
+    )
+  }
+
+  canEdit = (turn: ChatTurn) => turn.status !== 'running' && !this.#hasChildren(turn)
+
+  editReply = (turn: ChatTurn) => {
+    this.sourceReply = turn
+    this.editDraft = turn.text
+    this.expectedText = turn.text
+    this.replyDialog = 'edit'
+    this.replyOpen = true
+  }
+
+  translateDialog = (turn: ChatTurn) => {
+    this.sourceReply = turn
+    this.replyModel = this.sourceModel(turn)
+    this.targetLanguage = this.#deps.getLocale()
+    this.replyError = null
+    this.replyDialog = 'translate'
+    this.replyOpen = true
+  }
+
+  #showConversation(conversation: Conversation) {
+    this.viewGeneration++
+    this.#deps.setFullAccess(false)
+    this.#deps
+      .getSession()
+      ?.show(conversation.summary.id, conversation.turns, conversation.summary.selectedTurnId)
+    this.shownSummary = conversation.summary
+    this.#deps.bumpScrollRevision()
+  }
+
+  mutateReply = async (turn: ChatTurn, action: 'select' | 'remove' | 'branch' | 'copy') => {
+    const session = this.#deps.getSession()
+    const id = session?.conversationId
+    if (!this.history || !session || !id || this.actionBusy) return
+    let generation = this.viewGeneration
+    this.historyBusy = true
+    try {
+      if (action === 'remove') {
+        if (turn.status === 'running') return
+        const reparent = session.turns.some((child) => child.parentId === turn.id)
+        if (
+          !(await this.#deps.notify.confirm({
+            title: this.#deps.t('chat.deleteReplyTitle'),
+            body: reparent ? this.#deps.t('chat.deleteReparentBody') : '',
+            danger: true,
+          }))
+        )
+          return
+      }
+      if (this.disposed || generation !== this.viewGeneration) return
+      const conversation =
+        action === 'select' || action === 'branch'
+          ? await this.history.selectTurn(id, turn.id)
+          : action === 'remove'
+            ? await this.history.removeTurn(id, turn.id)
+            : await this.history.fork(id, turn.id)
+      if (this.disposed || generation !== this.viewGeneration) return
+      this.#showConversation(conversation)
+      generation = this.viewGeneration
+      if (action === 'branch') {
+        this.#deps.setDraft('')
+        this.#deps.bumpDraftRevision()
+        this.#deps.discardRecovery()
+      }
+      this.historyError = null
+      void this.refresh()
+    } catch (error) {
+      if (this.disposed || generation !== this.viewGeneration) return
+      this.#deps.notify.toast('error', this.#deps.errorText(error))
+    } finally {
+      if (!this.disposed && generation === this.viewGeneration) this.historyBusy = false
+    }
+  }
+
+  retryReply = async (turn: ChatTurn) => {
+    const session = this.#deps.getSession()
+    if (!session || this.actionBusy) return
+    const source = this.sourceModel(turn)
+    const options = this.#deps.getModelOptions()
+    if (this.history && turn.persisted) {
+      if (options === null || this.#deps.getModelError()) {
+        this.#deps.notify.toast(
+          'error',
+          this.#deps.getModelError() ?? this.#deps.t('chat.modelsLoading'),
+        )
+        return
+      }
+      if (
+        !source ||
+        !options.some(
+          (option) => option.endpointId === source.endpointId && option.modelId === source.modelId,
+        )
+      ) {
+        this.#deps.notify.toast('error', this.#deps.t('chat.sourceModelUnavailable'))
+        return
+      }
+    }
+    this.#deps.bumpScrollRevision()
+    await session.retry(this.#deps.consumeBase(), turn.id)
+  }
+
+  switchModel = async (turn: ChatTurn, model: ModelRef) => {
+    const session = this.#deps.getSession()
+    if (!session || this.actionBusy) return
+    this.#deps.bumpScrollRevision()
+    if (!(await session.retry(this.#deps.consumeBase(), turn.id, model)))
+      this.#deps.notify.toast('error', this.#deps.t(`errors.${session.actionError ?? 'internal'}`))
+  }
+
+  submitReply = async () => {
+    const session = this.#deps.getSession()
+    const turn = this.sourceReply
+    if (this.disposed || !session || !turn || this.actionBusy) return
+    let generation = this.viewGeneration
+    this.replyError = null
+    if (this.replyDialog === 'edit') {
+      const id = session.conversationId
+      if (
+        !this.history ||
+        !id ||
+        !this.editDraft.trim() ||
+        this.editDraft.length > 24_000 ||
+        !this.canEdit(turn)
+      )
+        return
+      this.historyBusy = true
+      try {
+        const conversation = await this.history.editTurn(
+          id,
+          turn.id,
+          this.editDraft,
+          this.expectedText,
+        )
+        if (this.disposed || generation !== this.viewGeneration) return
+        this.#showConversation(conversation)
+        generation = this.viewGeneration
+        this.replyOpen = false
+      } catch (error) {
+        if (this.disposed || generation !== this.viewGeneration) return
+        this.replyError = this.#deps.errorText(error)
+      } finally {
+        if (!this.disposed && generation === this.viewGeneration) this.historyBusy = false
+      }
+    } else {
+      if (!this.validReplyModel || !this.replyModel) return
+      if (!this.targetLanguage.trim() || this.targetLanguage.trim().length > 80) return
+      const accepted = await session.translate(
+        { ...this.#deps.consumeBase(), model: this.replyModel },
+        turn.id,
+        this.targetLanguage.trim(),
+      )
+      if (this.disposed || generation !== this.viewGeneration) return
+      if (accepted) this.replyOpen = false
+      else
+        this.replyError = session.actionError
+          ? this.#deps.t(`errors.${session.actionError}`)
+          : this.#deps.t('errors.internal')
+    }
+  }
+}

package/src/chat/chat-panel-models.svelte.ts

@@ -0,0 +1,97 @@
+// Chat model catalog behind the composer picker (docs/31 §5.1). Provider metadata only enriches
+// rows; a failed `list()` never blocks model selection.
+import type { KitI18n } from '../i18n'
+import type { ModelOption, ModelRef, Provider, ProvidersPort, ReasoningEffort } from '../ports'
+import { nearestEffort, REASONING_EFFORTS } from '../providers/reasoning'
+import { modelKey, pickerModels, type PickerModel, type PickerValue } from './model-effort'
+
+export class ChatPanelModels {
+  options = $state<ModelOption[] | null>(null)
+  providers = $state<Provider[] | null>(null)
+  error = $state<string | null>(null)
+  refreshing = $state(false)
+  notice = $state('')
+  readonly #port: ProvidersPort | undefined
+  readonly #i18n: KitI18n
+  readonly #errorText: (error: unknown) => string
+  #generation = 0
+
+  constructor(
+    port: ProvidersPort | undefined,
+    i18n: KitI18n,
+    errorText: (error: unknown) => string,
+  ) {
+    this.#port = port
+    this.#i18n = i18n
+    this.#errorText = errorText
+  }
+
+  get picker(): PickerModel[] {
+    return pickerModels(this.options ?? [], this.providers, this.#i18n)
+  }
+
+  /** Rereads in place: nulling options would reset the chosen effort (docs/41 §3.5). */
+  async load(announce = false): Promise<void> {
+    const generation = ++this.#generation
+    this.error = null
+    if (!this.#port) {
+      this.options = []
+      return
+    }
+    this.refreshing = announce
+    const [options, providers] = await Promise.allSettled([
+      this.#port.modelOptions({ modelType: 'chat' }),
+      this.#port.list(),
+    ])
+    if (generation !== this.#generation) return
+    this.refreshing = false
+    if (options.status === 'rejected') {
+      this.error = this.#errorText(options.reason)
+      if (announce) this.notice = this.error
+      return
+    }
+    this.options = options.value
+    this.providers = providers.status === 'fulfilled' ? providers.value : null
+    if (announce)
+      this.notice = this.#i18n.t('chat.picker.reloaded', { count: options.value.length })
+  }
+
+  #find(key: string): ModelOption | undefined {
+    return this.options?.find((item) => modelKey(item.endpointId, item.modelId) === key)
+  }
+
+  /** Hands the host the model behind the key; a failed save is shown in the picker notice. */
+  async saveDefault(
+    value: PickerValue,
+    save: (model: ModelRef, effort: ReasoningEffort) => Promise<void> | void,
+  ): Promise<void> {
+    const option = this.#find(value.key)
+    if (!option) return
+    try {
+      await save({ endpointId: option.endpointId, modelId: option.modelId }, value.effort)
+    } catch (error) {
+      this.notice = this.#errorText(error)
+    }
+  }
+
+  /**
+   * A model switch keeps the saved effort policy (nearest allowed level); only a level the user
+   * picked on the same model, or typed as a search suffix, is written back.
+   */
+  select(
+    value: PickerValue,
+    picked: ModelRef | null,
+    chosen: ReasoningEffort,
+    pick: (ref: ModelRef) => void,
+    choose: (effort: ReasoningEffort) => void,
+  ): void {
+    const option = this.#find(value.key)
+    if (!option) return
+    const same = picked !== null && modelKey(picked.endpointId, picked.modelId) === value.key
+    if (!same) pick({ endpointId: option.endpointId, modelId: option.modelId })
+    const declared = option.reasoning
+    const allowed = REASONING_EFFORTS.filter((effort) => declared?.efforts.includes(effort))
+    const implied = nearestEffort(chosen, allowed)
+    if (value.effort !== implied && (same || value.effort !== 'default')) choose(value.effort)
+  }
+}

package/src/chat/chat-panel-props.ts

@@ -0,0 +1,38 @@
+import type { ImageRef, ModelRef, PermissionMode, ReasoningEffort, SkillRef } from '../ports'
+
+/** Host inputs for the chat container, independent of its private view composition. */
+export interface ChatPanelProps {
+  purpose?: string
+  model?: ModelRef | null
+  scope?: string
+  /** Host context can be removed for the next message without changing conversation ownership. */
+  context?: { kind: string; id: string; label: string } | null
+  skills?: SkillRef[]
+  onSkillsChange?: (refs: SkillRef[]) => void
+  skillsBudget?: number
+  onInsert?: (markdown: string) => void
+  onSaveNote?: (markdown: string, images: ImageRef[]) => Promise<void> | void
+  onExportMarkdown?: (markdown: string) => Promise<void> | void
+  onOpenSettings?: () => void
+  /** A failed restore stays visible until retried or replaced with a new conversation. */
+  conversationId?: string | null
+  onConversationChange?: (id: string | null) => void
+  onClose?: () => void
+  /** A host painting model gates image generation. */
+  paintingModel?: boolean
+  /** Ordered pinned tool ids; omitted means the default toolbar. */
+  toolbar?: string[]
+  onToolbarChange?: (ids: string[]) => void
+  /** Saved preference mapped to the selected model's nearest supported effort. */
+  reasoningEffort?: ReasoningEffort
+  onReasoningEffortChange?: (effort: ReasoningEffort) => void
+  /** Host default for new conversations; enables「设为默认」when `onDefaultModelChange` is set. */
+  defaultModel?: ModelRef | null
+  /** Saved default effort, independent of the current session choice. */
+  defaultReasoningEffort?: ReasoningEffort
+  /** The host persists the default model and effort; the picker never writes storage itself. */
+  onDefaultModelChange?: (model: ModelRef, effort: ReasoningEffort) => Promise<void> | void
+  permissionModes?: PermissionMode[]
+  /** Full access stays private and is consumed once, never saved as a preference. */
+  permissionMode?: PermissionMode
+}

package/src/chat/context-status.ts

@@ -0,0 +1,101 @@
+// Pure rules for the inline context status beside Send (docs/31 §4.3). No I/O.
+import type { ContextUsage, Cost, TokenUsage } from '../ports'
+
+export type Pressure = 'normal' | 'warning' | 'high' | 'critical'
+export type Platform = 'windows' | 'macos' | 'linux' | 'other'
+
+/** Occupancy in percent, clamped to 0–100; `null` when tokens or window are unknown. */
+export function contextPercent(context: ContextUsage | null, window: number | null): number | null {
+  const tokens = context?.tokens
+  if (tokens == null || window == null || window <= 0) return null
+  return Math.min(100, Math.max(0, (tokens / window) * 100))
+}
+
+/** Highest of percentage and absolute pressure; absolute counts need a known window. */
+export function pressure(context: ContextUsage | null, window: number | null): Pressure {
+  const percent = contextPercent(context, window) ?? 0
+  const tokens = window != null && window > 0 ? (context?.tokens ?? 0) : 0
+  if (percent >= 90 || tokens >= 500_000) return 'critical'
+  if (percent >= 70 || tokens >= 270_000) return 'high'
+  if (percent >= 50 || tokens >= 150_000) return 'warning'
+  return 'normal'
+}
+
+/** Truncates rather than rounds, so 999 999 never reads as 1000k. */
+export function compact(value: number): string {
+  const n = Math.max(0, Math.floor(value))
+  const [divisor, suffix] =
+    n >= 1e9 ? [1e9, 'B'] : n >= 1e6 ? [1e6, 'M'] : n >= 1e3 ? [1e3, 'k'] : [1, '']
+  if (divisor === 1) return String(n)
+  const tenth = Math.floor((n * 10) / divisor)
+  const whole = Math.floor(tenth / 10)
+  return tenth % 10 === 0 ? `${whole}${suffix}` : `${whole}.${tenth % 10}${suffix}`
+}
+
+/** `~12.3%/1.1M`; unknown parts render as `?`. */
+export function summary(context: ContextUsage | null, window: number | null): string {
+  const percent = contextPercent(context, window)
+  const size = window != null && window > 0 ? compact(window) : '?'
+  const estimated = context?.source === 'estimated' ? '~' : ''
+  return `${estimated}${percent === null ? '?' : percent.toFixed(1)}%/${size}`
+}
+
+/** Estimated money from configured prices; invalid amounts are unknown. */
+export function money({ amount, currency }: Cost): string | null {
+  if (!Number.isFinite(amount) || amount < 0) return null
+  const text =
+    amount > 0 && amount < 0.0001
+      ? '<0.0001'
+      : amount > 0 && amount < 0.01
+        ? amount.toFixed(4)
+        : amount.toFixed(2)
+  return `≈${currency === 'CNY' ? '¥' : '$'}${text}`
+}
+
+export interface SpendingTurn {
+  usage: TokenUsage | null
+  cost: Cost | null
+}
+
+/**
+ * Money only when every turn with usage has a priced cost in one currency; otherwise tokens.
+ * Input already contains cache, output contains reasoning, so only the two totals are added.
+ */
+export function spending(turns: readonly SpendingTurn[]): string {
+  const used = turns.filter(
+    ({ usage }) => usage != null && (usage.inputTokens != null || usage.outputTokens != null),
+  )
+  if (used.length === 0) return '? tokens'
+  const priced = used.flatMap(({ usage, cost }) =>
+    cost &&
+    Number.isFinite(cost.amount) &&
+    cost.amount >= 0 &&
+    usage?.inputTokens != null &&
+    usage.outputTokens != null
+      ? [cost]
+      : [],
+  )
+  const first = priced[0]
+  const oneCurrency = priced.every((cost) => cost.currency === first?.currency)
+  if (first && priced.length === used.length && oneCurrency) {
+    const amount = priced.reduce((sum, cost) => sum + cost.amount, 0)
+    const text = money({ amount, currency: first.currency })
+    if (text) return text
+  }
+  let tokens = 0
+  for (const { usage } of used) tokens += (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0)
+  return `${compact(tokens)} tokens`
+}
+
+type PlatformNavigator = Navigator & { userAgentData?: { platform?: string } }
+
+/** Browser-reported OS; on the web this is the visitor's system, not the server's. */
+export function detectPlatform(
+  nav: PlatformNavigator | undefined = globalThis.navigator,
+): Platform {
+  const name = (nav?.userAgentData?.platform || nav?.platform || '').toLowerCase()
+  if (name.startsWith('win')) return 'windows'
+  if (name.startsWith('mac') || name.includes('darwin')) return 'macos'
+  if (name.includes('linux') && !name.includes('android')) return 'linux'
+  return 'other'
+}