dsh-working-activity 0.2.6 → 0.3.2

package/src/client/activity.ts

@@ -1,50 +1,50 @@
-/**
- * Client-side activity snapshot type + the ConversationSnapshot merge that
- * carries it.
- *
- * The host half (@deepseek-ai/dsh-working-activity's node side) publishes
- * `activity/status` session events; the web runtime patch (dsh-client-runtime
- * activity field, shipping separately) narrows those frames into the
- * conversation snapshot's `activity` member. Until that runtime release lands
- * on npm, this module re-declares the field via declaration merging so the
- * dock component type-checks against the published rc.6 types.
- *
- * REMOVE the `declare module` block below once
- * `@deepseek-ai/dsh-client-runtime/client` ships `ConversationSnapshot.activity`
- * natively (the runtime's own `ActivityStatusView` is structurally identical
- * to {@link ActivitySnapshot}; the two then agree by construction).
- * @module @deepseek-ai/dsh-working-activity/client/activity
- */
-
-/** The `activity/status` phase vocabulary, mirroring the host's ActivityPhase. */
-export type ActivityPhase = 'idle' | 'waiting' | 'thinking' | 'tool' | 'done'
-
-/** One `activity/status` snapshot as rendered by the dock line. */
-export interface ActivitySnapshot {
-  /** Which activity phase the model is in right now. */
-  readonly phase: ActivityPhase
-  /** Full human-readable status line (plain text, no ANSI). */
-  readonly line: string
-  /** Short label of the current work (tool action or stage), when any. */
-  readonly label?: string
-  /** Detail fragment (path / command / search pattern), when any. */
-  readonly detail?: string
-  /** The playful phrase currently shown, when any. */
-  readonly phrase?: string
-  /** Tools completed in the current turn. */
-  readonly toolCount: number
-  /** Wall-clock milliseconds since the current turn started (0 when idle). */
-  readonly turnElapsedMs: number
-  /** Wall-clock time the current phase started, for animations. */
-  readonly phaseStartedAt: number
-}
-
-declare module '@deepseek-ai/dsh-client-runtime/client' {
-  interface ConversationSnapshot {
-    /**
-     * Latest validated `activity/status` snapshot (the working-activity
-     * plugin's live working line), or null before the first publish.
-     */
-    activity: ActivitySnapshot | null
-  }
-}
+/**
+ * Client-side activity snapshot type + the ConversationSnapshot merge that
+ * carries it.
+ *
+ * The host half (@deepseek-ai/dsh-working-activity's node side) publishes
+ * `activity/status` session events; the web runtime patch (dsh-client-runtime
+ * activity field, shipping separately) narrows those frames into the
+ * conversation snapshot's `activity` member. Until that runtime release lands
+ * on npm, this module re-declares the field via declaration merging so the
+ * dock component type-checks against the published rc.6 types.
+ *
+ * REMOVE the `declare module` block below once
+ * `@deepseek-ai/dsh-client-runtime/client` ships `ConversationSnapshot.activity`
+ * natively (the runtime's own `ActivityStatusView` is structurally identical
+ * to {@link ActivitySnapshot}; the two then agree by construction).
+ * @module @deepseek-ai/dsh-working-activity/client/activity
+ */
+
+/** The `activity/status` phase vocabulary, mirroring the host's ActivityPhase. */
+export type ActivityPhase = 'idle' | 'waiting' | 'thinking' | 'tool' | 'done'
+
+/** One `activity/status` snapshot as rendered by the dock line. */
+export interface ActivitySnapshot {
+  /** Which activity phase the model is in right now. */
+  readonly phase: ActivityPhase
+  /** Full human-readable status line (plain text, no ANSI). */
+  readonly line: string
+  /** Short label of the current work (tool action or stage), when any. */
+  readonly label?: string
+  /** Detail fragment (path / command / search pattern), when any. */
+  readonly detail?: string
+  /** The playful phrase currently shown, when any. */
+  readonly phrase?: string
+  /** Tools completed in the current turn. */
+  readonly toolCount: number
+  /** Wall-clock milliseconds since the current turn started (0 when idle). */
+  readonly turnElapsedMs: number
+  /** Wall-clock time the current phase started, for animations. */
+  readonly phaseStartedAt: number
+}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  interface ConversationSnapshot {
+    /**
+     * Latest validated `activity/status` snapshot (the working-activity
+     * plugin's live working line), or null before the first publish.
+     */
+    activity: ActivitySnapshot | null
+  }
+}

package/src/client/css-modules.d.ts

@@ -1,6 +1,6 @@
-/* CSS Modules ambient declaration for the client half (tsc only; the tsdown
-   bundle inlines compiled class maps). */
-declare module '*.module.css' {
-  const classes: Readonly<Record<string, string>>
-  export default classes
-}
+/* CSS Modules ambient declaration for the client half (tsc only; the tsdown
+   bundle inlines compiled class maps). */
+declare module '*.module.css' {
+  const classes: Readonly<Record<string, string>>
+  export default classes
+}

package/src/client/index.ts

@@ -1,42 +1,42 @@
-/**
- * Working-activity surface plugin, browser half: the working-line entry in
- * the conversation.input.dock strip. This package's node half emits
- * `activity/status` session events; the web runtime patch narrows them into
- * the conversation snapshot's `activity` member, so this dock entry reads
- * the live frame through the standard session kit and owns no store, no
- * refresh chain, and no event listener.
- *
- * Mount contract (see the root README's "Web UI 集成" section): the web
- * client's client-modules host scans loader entries for `dsh.client`
- * declarations and serves this package's `./client` bundle at
- * /plugins/dsh-working-activity/client.js. The entry contributes into the
- * input dock — no official-source patch is involved.
- */
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
-// Type-only: pulls the ui-conversation SlotMap merge (the input.dock entry)
-// through the Client assembly boundary.
-import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { WorkingLine } from './WorkingLine.tsx'
-import type { ActivityPhase, ActivitySnapshot } from './activity.ts'
-
-export { WorkingLine, type WorkingLineProps } from './WorkingLine.tsx'
-export type { ActivityPhase, ActivitySnapshot } from './activity.ts'
-
-/** Required services for the dock registration. */
-export const inject = ['slots']
-
-/**
- * Client plugin body: the working-line dock entry.
- * @param ctx - client root context.
- */
-export function apply(ctx: ClientContext): void {
-  ctx.slots.inject('conversation.input.dock', () => ctx.slots.register({
-    name: 'conversation.input.dock',
-    // The pre-slots patch used the same id in ui-conversation; entries with
-    // equal order render in registration order, and goal (10) / queue (20)
-    // keep their seats — this row sits between them.
-    id: 'activity',
-    order: 15,
-    registrant: 'dsh-working-activity',
-  }, WorkingLine))
-}
+/**
+ * Working-activity surface plugin, browser half: the working-line entry in
+ * the conversation.input.dock strip. This package's node half emits
+ * `activity/status` session events; the web runtime patch narrows them into
+ * the conversation snapshot's `activity` member, so this dock entry reads
+ * the live frame through the standard session kit and owns no store, no
+ * refresh chain, and no event listener.
+ *
+ * Mount contract (see the root README's "Web UI 集成" section): the web
+ * client's client-modules host scans loader entries for `dsh.client`
+ * declarations and serves this package's `./client` bundle at
+ * /plugins/dsh-working-activity/client.js. The entry contributes into the
+ * input dock — no official-source patch is involved.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: pulls the ui-conversation SlotMap merge (the input.dock entry)
+// through the Client assembly boundary.
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { WorkingLine } from './WorkingLine.tsx'
+import type { ActivityPhase, ActivitySnapshot } from './activity.ts'
+
+export { WorkingLine, type WorkingLineProps } from './WorkingLine.tsx'
+export type { ActivityPhase, ActivitySnapshot } from './activity.ts'
+
+/** Required services for the dock registration. */
+export const inject = ['slots']
+
+/**
+ * Client plugin body: the working-line dock entry.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.slots.inject('conversation.input.dock', () => ctx.slots.register({
+    name: 'conversation.input.dock',
+    // The pre-slots patch used the same id in ui-conversation; entries with
+    // equal order render in registration order, and goal (10) / queue (20)
+    // keep their seats — this row sits between them.
+    id: 'activity',
+    order: 15,
+    registrant: 'dsh-working-activity',
+  }, WorkingLine))
+}

package/src/config.ts

@@ -0,0 +1,174 @@
+/**
+ * Working-activity user configuration, mirroring the pi extension's
+ * `~/.pi/agent/working-activity.json` shape: the UI owns the file (dsh-tui
+ * persists `frames` at `~/.dsh-tui/working-activity.json`) and consumers use
+ * the pure parser here to honor `mode` / `features` / `customPhrases` /
+ * `customActions` without duplicating validation. No I/O — filesystem
+ * ownership stays with the host.
+ * @module @deepseek-ai/dsh-working-activity/config
+ */
+
+import { DEFAULT_PRESET, isPresetName } from './frames.js'
+
+/** Feature flags that can be switched independently (pi extension parity). */
+export const FEATURE_FLAGS = [
+  'phrases',          // 俏皮文案池（思考/等待/收尾/工具动词）
+  'rareEggs',         // 稀有彩虹彩蛋
+  'nightPhrases',     // 深夜文案
+  'weekend',          // 周末问候
+  'holidays',         // 节假日彩蛋
+  'combo',            // 连击火力全开
+  'failPhrases',      // 失败文案池
+  'modelQuips',       // 模型切换梗
+  'shimmer',          // 文案星辉扫过/彩虹流光
+  'continuePhrases',  // 打断后接梗
+  'cost',             // 成本与 token 核算（结束时展示）
+] as const
+
+/** Feature-flag name type. */
+export type FeatureFlag = (typeof FEATURE_FLAGS)[number]
+
+/** Chinese labels for the settings panel / docs. */
+export const FEATURE_LABELS: Record<FeatureFlag, string> = {
+  phrases: '俏皮文案',
+  rareEggs: '稀有彩蛋',
+  nightPhrases: '深夜文案',
+  weekend: '周末问候',
+  holidays: '节假日彩蛋',
+  combo: '工具连击',
+  failPhrases: '失败文案',
+  modelQuips: '模型切换梗',
+  shimmer: '星辉效果',
+  continuePhrases: '打断接梗',
+  cost: '成本与 token',
+}
+
+/** The file-based config, same keys as the pi extension. */
+export type WorkingActivityConfig = {
+  /** Frame preset name (`random` picks one per process). */
+  frames?: string
+  /** Extra thinking phrases appended to the base pool. */
+  customPhrases?: readonly string[]
+  /** Exact tool-name → action-copy pools (case-insensitive match). */
+  customActions?: Readonly<Record<string, readonly string[]>>
+  /** Inject the `⏵` self-narration contract into the system prompt. */
+  narrate?: boolean
+  /** Debug logging to `working-activity-debug.log`. */
+  debugLog?: boolean
+  /** Context usage warning threshold in percent. */
+  contextWarnAt?: number
+  /** Context usage danger threshold in percent. */
+  contextDangerAt?: number
+  /** Show estimated output tokens per second. */
+  showTokPerSec?: boolean
+  /** Hourly work-reminder threshold (0–24, 0 = off). */
+  workRemindAt?: number
+  /** lively: full flourish (default) / minimal: functional labels only. */
+  mode?: 'lively' | 'minimal'
+  /** Per-feature switches; explicit values override `mode` defaults. */
+  features?: Readonly<Record<string, boolean>>
+}
+
+/** The defaults when nothing is configured. */
+export const DEFAULT_ACTIVITY_CONFIG: WorkingActivityConfig = {
+  frames: DEFAULT_PRESET,
+  narrate: true,
+}
+
+/** Result of parsing a config file. */
+export type ConfigReadResult = {
+  readonly config: WorkingActivityConfig
+  /** Raw parsed object, preserving unknown keys for lossless write-back. */
+  readonly raw: Record<string, unknown>
+  /** Parse error message, when the text was not a valid config object. */
+  readonly error?: string
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/** Clamp `dangerAt` to be at least `warnAt` (percent thresholds). */
+export function normalizeThresholds(cfg: WorkingActivityConfig): WorkingActivityConfig {
+  const warnAt = cfg.contextWarnAt ?? 80
+  const dangerAt = cfg.contextDangerAt ?? 95
+  return dangerAt < warnAt ? { ...cfg, contextDangerAt: warnAt } : cfg
+}
+
+/**
+ * Parse a `working-activity.json` text into a validated config. Unknown keys
+ * are preserved in `raw` (for lossless write-back); invalid values are
+ * dropped. A non-object root yields the defaults plus an `error`.
+ * @param text - Raw file contents.
+ * @returns Validated config + raw object (+ optional error).
+ */
+export function parseWorkingActivityConfig(text: string): ConfigReadResult {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    return { config: { ...DEFAULT_ACTIVITY_CONFIG }, raw: {}, error: errorText(error) }
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {
+      config: { ...DEFAULT_ACTIVITY_CONFIG },
+      raw: {},
+      error: '配置根节点必须是 JSON 对象',
+    }
+  }
+  const raw = parsed as Record<string, unknown>
+  const config: WorkingActivityConfig = { ...DEFAULT_ACTIVITY_CONFIG }
+  if (typeof raw.frames === 'string' && isPresetName(raw.frames)) config.frames = raw.frames
+  if (Array.isArray(raw.customPhrases)) {
+    const phrases = raw.customPhrases.filter((s): s is string => typeof s === 'string' && s.trim().length > 0)
+    if (phrases.length > 0) config.customPhrases = phrases
+  }
+  if (raw.customActions !== null && typeof raw.customActions === 'object' && !Array.isArray(raw.customActions)) {
+    const customActions: Record<string, string[]> = {}
+    for (const [key, value] of Object.entries(raw.customActions)) {
+      const actions = Array.isArray(value)
+        ? value.filter((entry): entry is string => typeof entry === 'string' && entry.trim().length > 0)
+          .map((entry) => entry.trim())
+        : []
+      if (key.trim().length > 0 && actions.length > 0) customActions[key.trim()] = actions
+    }
+    if (Object.keys(customActions).length > 0) config.customActions = customActions
+  }
+  if (typeof raw.narrate === 'boolean') config.narrate = raw.narrate
+  if (typeof raw.debugLog === 'boolean') config.debugLog = raw.debugLog
+  if (typeof raw.contextWarnAt === 'number' && Number.isFinite(raw.contextWarnAt)
+    && raw.contextWarnAt >= 0 && raw.contextWarnAt <= 100) {
+    config.contextWarnAt = raw.contextWarnAt
+  }
+  if (typeof raw.contextDangerAt === 'number' && Number.isFinite(raw.contextDangerAt)
+    && raw.contextDangerAt >= 0 && raw.contextDangerAt <= 100) {
+    config.contextDangerAt = raw.contextDangerAt
+  }
+  if (typeof raw.showTokPerSec === 'boolean') config.showTokPerSec = raw.showTokPerSec
+  if (typeof raw.workRemindAt === 'number' && Number.isFinite(raw.workRemindAt)
+    && raw.workRemindAt >= 0 && raw.workRemindAt <= 24) {
+    config.workRemindAt = raw.workRemindAt
+  }
+  if (raw.mode === 'lively' || raw.mode === 'minimal') config.mode = raw.mode
+  if (raw.features !== null && typeof raw.features === 'object' && !Array.isArray(raw.features)) {
+    const features: Record<string, boolean> = {}
+    for (const [key, value] of Object.entries(raw.features)) {
+      if (typeof value === 'boolean') features[key] = value
+    }
+    if (Object.keys(features).length > 0) config.features = features
+  }
+  return { config: normalizeThresholds(config), raw }
+}
+
+/**
+ * Whether a feature is on. Explicit `features` entries win; otherwise
+ * `minimal` mode turns everything off (except `cost`, always on).
+ * @param config - Parsed config.
+ * @param name - Feature flag name.
+ */
+export function featureOn(config: WorkingActivityConfig, name: FeatureFlag): boolean {
+  const explicit = config.features?.[name]
+  if (typeof explicit === 'boolean') return explicit
+  if (name === 'cost') return true
+  return config.mode !== 'minimal'
+}

package/src/events.ts

@@ -1,45 +1,45 @@
-/**
- * `activity/status` session event — a log-only, non-surface snapshot of the
- * model's current working activity, published by this plugin for any UI
- * consumer (Web client, telemetry, …). It never enters derived model history
- * (no `surfaceOp`), so it cannot leak into prompts; UIs render it like
- * `todo/write` or `plan/mode`.
- * @module @deepseek-ai/dsh-working-activity/events
- */
-
-import type { ActivityPhase } from './status.js'
-
-/** Durable payload of one `activity/status` snapshot. */
-export interface ActivityStatusEvent {
-  /** Which activity phase the model is in. */
-  readonly phase: ActivityPhase
-  /** Human-readable status line (plain text, no ANSI). */
-  readonly line: string
-  /** Short label of the current work, when any. */
-  readonly label?: string
-  /** Detail fragment (path / command / pattern), when any. */
-  readonly detail?: string
-  /** The playful phrase currently shown, when the copy pool is on. */
-  readonly phrase?: string
-  /** Tools completed in the current turn. */
-  readonly toolCount: number
-  /** Milliseconds since the current turn started (0 when idle). */
-  readonly turnElapsedMs: number
-  /** Wall-clock time (epoch ms) the current phase started, for animations. */
-  readonly phaseStartedAt: number
-}
-
-/** The `activity/status` phase vocabulary, exported for wire consumers. */
-export type { ActivityPhase }
-
-declare module '@deepseek-ai/dsh-session/types' {
-  interface SessionEventMap {
-    /**
-     * Log-only UI snapshot of the model's working activity (thinking copy,
-     * running tool, turn elapsed). Never a surface event: UIs render it, the
-     * model never sees it.
-     * @param data - The rendered status snapshot.
-     */
-    'activity/status': ActivityStatusEvent
-  }
-}
+/**
+ * `activity/status` session event — a log-only, non-surface snapshot of the
+ * model's current working activity, published by this plugin for any UI
+ * consumer (Web client, telemetry, …). It never enters derived model history
+ * (no `surfaceOp`), so it cannot leak into prompts; UIs render it like
+ * `todo/write` or `plan/mode`.
+ * @module @deepseek-ai/dsh-working-activity/events
+ */
+
+import type { ActivityPhase } from './status.js'
+
+/** Durable payload of one `activity/status` snapshot. */
+export interface ActivityStatusEvent {
+  /** Which activity phase the model is in. */
+  readonly phase: ActivityPhase
+  /** Human-readable status line (plain text, no ANSI). */
+  readonly line: string
+  /** Short label of the current work, when any. */
+  readonly label?: string
+  /** Detail fragment (path / command / pattern), when any. */
+  readonly detail?: string
+  /** The playful phrase currently shown, when the copy pool is on. */
+  readonly phrase?: string
+  /** Tools completed in the current turn. */
+  readonly toolCount: number
+  /** Milliseconds since the current turn started (0 when idle). */
+  readonly turnElapsedMs: number
+  /** Wall-clock time (epoch ms) the current phase started, for animations. */
+  readonly phaseStartedAt: number
+}
+
+/** The `activity/status` phase vocabulary, exported for wire consumers. */
+export type { ActivityPhase }
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * Log-only UI snapshot of the model's working activity (thinking copy,
+     * running tool, turn elapsed). Never a surface event: UIs render it, the
+     * model never sees it.
+     * @param data - The rendered status snapshot.
+     */
+    'activity/status': ActivityStatusEvent
+  }
+}

package/src/frames.ts

@@ -0,0 +1,138 @@
+/**
+ * Working-activity indicator frame presets — the single home for every
+ * spinner animation, ported from the pi working-activity extension
+ * (`FRAME_PRESETS`) plus the dsh-tui additions (moon8 / rainbow / whale
+ * family / clock / traffic lights). Consumers (TUI row, Web slot) render the
+ * current frame next to the live working line; the preset name is chosen by
+ * the UI and persisted in `working-activity.json` (`frames` key).
+ *
+ * `\uFE0E` forces text rendering so Windows never paints the glyphs as color
+ * emoji (the green-block problem); emoji presets (moon8, clock, whales)
+ * deliberately omit it to keep colorful rendering on modern terminals.
+ * @module @deepseek-ai/dsh-working-activity/frames
+ */
+
+/** Text-variant selector: keep symbols monochrome on Windows. */
+const TE = '\uFE0E'
+
+/** One working-activity preset: the frame sequence and the per-frame interval. */
+export interface FramePreset {
+  readonly frames: readonly string[]
+  readonly intervalMs: number
+}
+
+/** Named working-activity frame presets, keyed by preset name (`claude`, `moon`, `sand`, ...). */
+export const FRAME_PRESETS: Record<string, FramePreset> = {
+  // Claude Code's real sequence: · ✢ * ✶ ✻ ✽ forward + backward.
+  claude: {
+    frames: ['·', `✢${TE}`, '*', `✶${TE}`, `✻${TE}`, `✽${TE}`, `✻${TE}`, `✶${TE}`, '*', `✢${TE}`],
+    intervalMs: 150,
+  },
+  star2: { frames: [`✶${TE}`, `✸${TE}`, `✹${TE}`, `✺${TE}`, `✹${TE}`, `✷${TE}`], intervalMs: 140 },
+  sand: {
+    frames: ['⠁', '⠂', '⠄', '⡀', '⡈', '⡐', '⡠', '⣀', '⣁', '⣂', '⣄', '⣌', '⣔', '⣤', '⣥', '⣦', '⣮', '⣶', '⣷', '⣿', '⡿', '⠿', '⢟', '⠟', '⡛', '⠛', '⠫', '⢋', '⠋', '⠍', '⡉', '⠉', '⠑', '⠡', '⢁'],
+    intervalMs: 120,
+  },
+  triangle: { frames: ['◢', '◣', '◤', '◥'], intervalMs: 180 },
+  box: { frames: ['▖', '▘', '▝', '▗'], intervalMs: 180 },
+  box2: { frames: ['▌', '▀', '▐', '▄'], intervalMs: 180 },
+  corners: { frames: ['◰', '◳', '◲', '◱'], intervalMs: 190 },
+  point: { frames: ['∙∙∙', '●∙∙', '∙●∙', '∙∙●', '∙∙∙'], intervalMs: 190 },
+  layer: { frames: ['-', '=', '≡'], intervalMs: 220 },
+  flip: { frames: ['_', '_', '_', '-', '`', '`', "'", '´', '-', '_', '_', '_'], intervalMs: 140 },
+  aesthetic: {
+    frames: ['▰▱▱▱▱▱▱', '▰▰▱▱▱▱▱', '▰▰▰▱▱▱▱', '▰▰▰▰▱▱▱', '▰▰▰▰▰▱▱', '▰▰▰▰▰▰▱', '▰▰▰▰▰▰▰', '▰▱▱▱▱▱▱'],
+    intervalMs: 140,
+  },
+  hamburger: { frames: ['☱', '☲', '☴'], intervalMs: 220 },
+  moon: { frames: ['◐', '◓', '◑', '◒'], intervalMs: 240 },
+  // kimi-code MoonLoader 同款：8 帧 emoji 月相，120ms 一帧，比半圆版更丝滑。
+  // 不带 \uFE0E：保留彩色 emoji 渲染（Windows Terminal 等现代终端效果最佳）。
+  moon8: { frames: ['🌑', '🌒', '🌓', '🌔', '🌕', '🌖', '🌗', '🌘'], intervalMs: 120 },
+  // 鲸鱼喷水：🐳 固定，水柱升起（· → | → ║）再回落，顶珠 ° 模拟水花（对齐 pi 版）。
+  'whale-spout': {
+    frames: ['🐳  ', '🐳° ', '🐳|°', '🐳║°', '🐳|°', '🐳° ', '🐳  '],
+    intervalMs: 160,
+  },
+  // 鲸鱼转圈：🐳 + 环绕方向指示（逆时针转圈语义，对齐 pi 版）。
+  'whale-spin': {
+    frames: ['🐳→', '🐳↘', '🐳↓', '🐳↙', '🐳←', '🐳↖', '🐳↑', '🐳↗'],
+    intervalMs: 150,
+  },
+  // 鲸鱼吐泡泡：🐳 固定，泡泡从头顶冒出（大泡 ○ 先行、小泡 ∘ 跟上）向右飘走。
+  'whale-bubbles': {
+    frames: ['🐳  ', '🐳○ ', '🐳 ○', '🐳  ', '🐳∘ ', '🐳 ∘', '🐳  '],
+    intervalMs: 170,
+  },
+  // 时钟：12 个整点表盘循环（🕛 → 🕚），emoji 彩色渲染（同 moon8，不带 \uFE0E）。
+  clock: {
+    frames: ['🕛', '🕐', '🕑', '🕒', '🕓', '🕔', '🕕', '🕖', '🕗', '🕘', '🕙', '🕚'],
+    intervalMs: 300,
+  },
+  // 红绿灯：🔴 → 🟡 → 🟢 循环，一轮 1.2s，节奏从容。
+  traffic_lights: {
+    frames: ['🔴', '🟡', '🟢'],
+    intervalMs: 400,
+  },
+  comet: {
+    frames: ['●    ', ' ●   ', '  ●  ', '   ● ', '    ●', '   ● ', '  ●  ', ' ●   '],
+    intervalMs: 160,
+  },
+  breathe: { frames: ['▁', '▃', '▅', '▇', '▅', '▃'], intervalMs: 210 },
+  dots: { frames: ['⣾', '⣷', '⣯', '⣟', '⡿', '⢿', '⣻', '⣽'], intervalMs: 140 },
+  arrow: { frames: ['←', '↖', '↑', '↗', '→', '↘', '↓', '↙'], intervalMs: 160 },
+  spark: { frames: ['·', '∘', '°', '✧', '°', '∘'], intervalMs: 240 },
+  bar: { frames: ['▏', '▎', '▍', '▌', '▋', '▊', '▉', '█', '▉', '▊', '▋', '▌', '▍', '▎'], intervalMs: 120 },
+  braille: { frames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'], intervalMs: 120 },
+  arc: { frames: ['◜', '◠', '◝', '◞', '◡', '◟'], intervalMs: 160 },
+  circle: { frames: ['◴', '◷', '◶', '◵'], intervalMs: 190 },
+  grow: { frames: ['.', 'o', 'O', '0', 'O', 'o'], intervalMs: 210 },
+  noise: { frames: ['▓', '▒', '░', '▒'], intervalMs: 160 },
+  bounce: { frames: ['⠁', '⠂', '⠄', '⡀', '⢀', '⠠', '⠐', '⠈'], intervalMs: 140 },
+  rainbow: {
+    frames: ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█', '▇', '▆', '▅', '▄', '▃', '▂'],
+    intervalMs: 120,
+  },
+  // 双端进度条往返（pi 版独有，补全并集）。
+  bar2: {
+    frames: [
+      '[    ]', '[=   ]', '[==  ]', '[=== ]', '[ ===]',
+      '[  ==]', '[   =]', '[    ]', '[   =]', '[  ==]',
+      '[ ===]', '[=== ]', '[==  ]', '[=   ]',
+    ],
+    intervalMs: 140,
+  },
+  dqpb: { frames: ['d', 'q', 'p', 'b'], intervalMs: 210 },
+  toggle: { frames: ['⊶', '⊷'], intervalMs: 300 },
+}
+
+/** The default preset (moon8: the smoothest of the emoji moons). */
+export const DEFAULT_PRESET = 'moon8'
+
+/** Every selectable preset name, `random` first (the pi selector order). */
+export const PRESET_NAMES: readonly string[] = ['random', ...Object.keys(FRAME_PRESETS)]
+
+/**
+ * Whether `name` selects a known preset or `random`.
+ * @param name - Candidate preset name.
+ * @returns True when the name resolves to a preset.
+ */
+export function isPresetName(name: string): boolean {
+  return name === 'random' || Object.hasOwn(FRAME_PRESETS, name)
+}
+
+/**
+ * Resolve a preset name (`random` picks one per process).
+ * @param name - Preset name, or undefined for the default.
+ * @returns The matching preset; unknown or absent names fall back to the default.
+ */
+export function resolvePreset(name: string | undefined): FramePreset {
+  if (name === 'random') {
+    const names = Object.keys(FRAME_PRESETS)
+    // FRAME_PRESETS is non-empty by construction, so any random index is in
+    // range and the lookup always lands on a preset.
+    const pick = names[Math.floor(Math.random() * names.length)]
+    return FRAME_PRESETS[pick]
+  }
+  return FRAME_PRESETS[name ?? ''] ?? FRAME_PRESETS[DEFAULT_PRESET]
+}