dsh-plugin 0.1.1 → 1.1.0

package/lib/types/services/npm-resolve.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 反查 repo（`owner/repo`）对应的官方 npm 包名；未命中、网络异常或超时返回 null。
+ * 返回 null 不代表仓库一定没有 npm 包，只代表本次未能确认 —— 调用方应保留
+ * 原有错误路径，反查只是额外的一次尝试。
+ */
+export declare function resolveNpmPackage(repo: string): Promise<string | null>;

package/lib/types/services/pending-restart.d.ts

@@ -0,0 +1,13 @@
+/** 待重启列表的内存态管理（宿主进程一重启自然清空）。 */
+import type { PendingRestart } from './install-types.ts';
+/**
+ * 登记一条待重启记录（同一目标去重）。
+ * - 卸载：目标刚装完未重启（已有待重启记录）→ 宿主从未加载过它，卸完磁盘已干净、
+ *   loader 无残留，无需再提醒重启，直接移除该条；否则（此前已被宿主加载过）登记「卸载后待重启清理」。
+ * - 安装：已有记录则刷新为安装语义（如卸载后未重启又重装），否则新登记。
+ */
+export declare function addPendingRestart(target: string, kind: 'install' | 'uninstall'): void;
+/** 当前待重启列表快照（副本，消费方不会污染内部数组）。 */
+export declare function listPendingRestarts(): PendingRestart[];
+/** 清除某目标的待重启记录（卸载已即时生效、无需重启时调用）。 */
+export declare function clearPendingRestart(target: string): void;

package/lib/types/services/preflight.d.ts

@@ -0,0 +1,6 @@
+/** 预检结果：ok=false 表示分发改入口文件缺失，missing 为该文件在包内的相对路径。 */
+export interface PreflightResult {
+    ok: boolean;
+    missing: string | null;
+}
+export declare function preflightTarget(target: string): Promise<PreflightResult>;

package/lib/types/services/profile.d.ts

@@ -0,0 +1,24 @@
+/** Resolve the active profile from the booted CLI args, falling back to `web`. */
+export declare function readProfileArg(fallback?: string): string;
+/** Resolve a profile directory (`DSH_HOME` or `~/.dsh`). */
+export declare function profileDirectory(profile: string): string;
+/** Build a safe `github:<owner>/<repo>` target, or null when the repo is unsafe. */
+export declare function githubTarget(repo: string): string | null;
+/** Validate an npm package name (uninstall target grammar). */
+export declare function validPackageName(name: string): boolean;
+/**
+ * The exact `allowBuilds` key pnpm printed in its
+ * `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` hint. For `github:` installs pnpm
+ * matches against `name@<resolved fetch URL>` — the URL it actually fetches,
+ * e.g. `https://codeload.github.com/<owner>/<repo>/tar.gz/<commit>` — not the
+ * `git+ssh://`/branch spec. A bare name or a `git+` spec does not match, so
+ * the only reliable key is the one pnpm prints verbatim. Null when absent.
+ */
+export declare function parseAllowBuildsKey(output: string): string | null;
+/**
+ * Add one `allowBuilds` entry to the profile's pnpm-workspace.yaml, merging
+ * with existing entries and leaving the rest of the yaml intact. Broken
+ * placeholder entries (pnpm's failed-install bug writes a literal
+ * `set this to true or false` value) are dropped on rewrite.
+ */
+export declare function addAllowBuildsKey(profile: string, key: string): void;

package/lib/types/services/progress.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pure progress-estimation helpers shared by the install runner.
+ *
+ * The dsh CLI wraps pnpm, which refreshes its `Progress: …` line in place
+ * with carriage returns, so raw output arrives as a stream of partial
+ * fragments. These helpers normalize one fragment into a clean terminal
+ * line and map it onto a 0-100 estimate; keeping them free of I/O makes the
+ * estimation logic directly unit-testable (see tests/progress.test.ts).
+ */
+/** Strip the `[out]` / `[err]` source prefix and ANSI escape sequences. */
+export declare function cleanLine(raw: string): string;
+/**
+ * Estimate 0-100 progress from one CLI output line. pnpm emits
+ * `Progress: resolved N, reused X, downloaded Y, added Z` during the fetch
+ * phase; resolution/install phase lines bump the estimate towards done.
+ */
+export declare function estimateProgress(line: string): number;

package/lib/types/services/task-queue.d.ts

@@ -0,0 +1,82 @@
+import type { InstallResult, InstallTask } from './install-types.ts';
+import type { LoaderHandle } from './loader.ts';
+/** Snapshot of a task (keeps the live object untouched by consumers). */
+export declare function getTask(id: number): InstallTask | undefined;
+export interface ActiveTaskInfo {
+    id: number;
+    target: string;
+    action: 'add' | 'remove';
+    status: 'pending' | 'running';
+    progress: number;
+    lines: string[];
+    /** 尝试过的安装方式（npm 反查 + 实际执行命令）：失败时前端 issue 预填需要 */
+    attempts: string[];
+}
+/** All non-terminal tasks in queue order (running first, then pending). Lets the client resume a queue after a page reload. */
+export declare function activeTask(): ActiveTaskInfo[];
+/**
+ * True while a mutation child process is still alive. The concurrent slot is
+ * keyed off the live child set rather than task.status: cancelling a running
+ * task flips its status immediately, but the child may still be shutting down
+ * (the close event lands later) — the slot must stay held until then, otherwise
+ * a new task would start while the old pnpm still runs in the same profile dir.
+ */
+export declare function hasRunningTask(): boolean;
+/** Whether the target already has a non-terminal task in the queue (install/uninstall dedupe). */
+export declare function hasQueuedTarget(target: string): boolean;
+/**
+ * Cancel a queued or running task.
+ * - pending: removed from the queue immediately (never spawned).
+ * - running: kills the child process; the queue worker then picks the next one.
+ * Returns false when the task is unknown or already finished.
+ */
+export declare function cancelTask(id: number): boolean;
+/**
+ * Enqueue a plugin mutation and return its task. Tasks run strictly serially:
+ * the queue worker starts the next one only after the previous finishes.
+ * Progress is visible through `getTask(id)` / `activeTask()` until done.
+ */
+export declare function startPluginMutation(options: {
+    action: 'add' | 'remove';
+    profile: string;
+    target: string;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    /** 待重启行的展示目标（owner/repo）：卸载时用于把 npm 包名映射回仓库名 */
+    displayTarget?: string;
+    /** 运行中 loader：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
+    uninstallLoader?: LoaderHandle;
+    /** 入队前已尝试的安装方式（npm registry 反查等）：失败提 Issue 时如实展示；实际执行的命令由 spawn 时追加 */
+    attempts?: string[];
+}): InstallTask;
+/**
+ * 安装后校验已装包的入口文件（package.json 的 main / exports["."].default）是否真实存在。
+ * git: 分发常不提交构建产物（lib/ 等），pnpm 装完没有报错，但宿主重启加载插件树时会
+ * ERR_MODULE_NOT_FOUND 直接崩溃、网页打不开 —— 这里在登记「待重启」前就把这类残缺包拦下。
+ * 返回 { name, missing }：name 为空表示无法定位目标包（跳过校验）；missing 为缺失的入口路径。
+ */
+export declare function verifyInstalledEntry(profile: string, target: string): {
+    name: string | null;
+    missing: string | null;
+};
+/**
+ * Run a plugin mutation with one recovery path: when `add` fails because
+ * pnpm's allowBuilds gate blocks a build script — either the git-hosted
+ * package's own `prepare` (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`, key from
+ * the printed key@url hint) or a dependency's native build
+ * (`ERR_PNPM_IGNORED_BUILDS`, key = the listed name@version) — write the
+ * exact keys into the profile's pnpm-workspace.yaml and retry once.
+ * Other failures fall through to the single-spawn result.
+ */
+export declare function runPluginMutation(options: {
+    action: 'add' | 'remove';
+    profile: string;
+    target: string;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    task?: InstallTask;
+    /** 待重启行的展示目标（owner/repo）：卸载时用于把 npm 包名映射回仓库名 */
+    displayTarget?: string;
+    /** 运行中 loader：卸载成功后主动移除条目、立即生效（缺失时卸载仍需重启清理） */
+    uninstallLoader?: LoaderHandle;
+}): Promise<InstallResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "0.1.1",
+  "version": "1.1.0",
   "description": "A community plugin marketplace for DeepSeek Harness, built to the official plugin spec — browse, search and install 4000+ human-curated community plugins without leaving the app. · DeepSeek Harness 社区插件市场（遵循官方开发规范）：4000+ 人工精选社区插件，每日更新。",
   "type": "module",
   "main": "lib/index.js",
@@ -11,6 +11,17 @@
     "url": "git+https://github.com/dshplugin/dsh-plugin-hub.git"
   },
   "homepage": "https://dsh-plugin.org",
+  "bugs": {
+    "url": "https://github.com/dshplugin/dsh-plugin-hub/issues"
+  },
+  "author": "DSH-Plugin Hub contributors",
+  "funding": {
+    "type": "custom",
+    "url": "https://dsh-plugin.org"
+  },
+  "engines": {
+    "node": ">=22.6"
+  },
   "keywords": [
     "deepseek",
     "deepseek-harness",
@@ -29,11 +40,21 @@
     "open-source"
   ],
   "scripts": {
-    "build": "npm run build:client",
-    "build:client": "tsdown && node scripts/normalize-client-banner.mjs",
-    "readme:stats": "node scripts/sync-readme-stats.mjs",
-    "typecheck": "tsc -p tsconfig.client.json --noEmit",
-    "check": "npm run typecheck && npm run build",
+    "build": "npm run build:server && npm run build:client",
+    "build:server": "rm -rf lib && tsc -p tsconfig.server.json",
+    "build:client": "tsdown && node scripts/tools/normalize-client-banner.mjs",
+    "readme:stats": "node scripts/tools/sync-readme-stats.mjs",
+    "reload": "bash scripts/run/reload-dsh.sh",
+    "dev": "bash scripts/run/dev-dsh.sh",
+    "test": "node --test",
+    "test:watch": "node --test --watch",
+    "typecheck": "npm run typecheck:client && npm run typecheck:server && npm run typecheck:test",
+    "typecheck:client": "tsc -p tsconfig.client.json --noEmit",
+    "typecheck:server": "tsc -p tsconfig.server.json --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
+    "check": "npm run typecheck && npm run test && npm run build",
+    "verify:release": "node scripts/tools/verify-release.mjs",
+    "prepublishOnly": "npm run verify:release",
     "prepack": "npm run build"
   },
   "dependencies": {},

package/src/client/components/CatalogControls.tsx

@@ -0,0 +1,104 @@
+/**
+ * Toolbar above the list: search input + sort dropdown + installed / not
+ * installed filter buttons + the notifications entry. All buttons share the
+ * same size (24px high, like the notification entry button).
+ */
+import { createElement as h, Fragment } from 'react'
+import type { FormEvent } from 'react'
+import styles from '../styles/Header.module.css'
+import type { Translate } from '../types.ts'
+import { SORTS } from '../lib/catalog.ts'
+import type { SortKey } from '../lib/catalog.ts'
+import { Dropdown } from './Dropdown.tsx'
+
+export function CatalogControls({ query, setQuery, sort, setSort, installedFilter, setInstalledFilter, installedCount, notInstalledCount, t, resultText, noticeCount, onOpenNotifications }: {
+  query: string
+  setQuery: (value: string) => void
+  sort: SortKey
+  setSort: (value: SortKey) => void
+  installedFilter: 'all' | 'installed' | 'notInstalled'
+  setInstalledFilter: (value: 'all' | 'installed' | 'notInstalled') => void
+  installedCount: number
+  notInstalledCount: number
+  t: Translate
+  resultText: string | null
+  noticeCount: number
+  onOpenNotifications: () => void
+}) {
+  return h(Fragment, null,
+    h('div', { className: styles.searchRow },
+      h('input', {
+        className: styles.search,
+        type: 'search',
+        placeholder: t('search'),
+        value: query,
+        spellCheck: false,
+        onInput: (e: FormEvent<HTMLInputElement>) =>
+          setQuery((e.target as HTMLInputElement).value),
+      }),
+    ),
+    h('div', { className: styles.controls },
+      // 筛选结果数：位于排序下拉之前，选中分类后提示「筛选出 N 条插件」；
+      // 数字单独等宽显示并预留 5 位宽度，数字变化时整行不左右跳动
+      resultText ? h('span', { className: styles.filterResults },
+        ...resultText.split(/(\d+)/).map((part, i) =>
+          /^\d+$/.test(part)
+            ? h('span', { key: i, className: styles.resultCount }, part)
+            : part)) : null,
+      // 全部 / 已安装 / 未安装：互斥单选组，点击直接切换选中态，「全部」即默认恢复项；
+      // 已安装/未安装计数跟随当前分类，为 0 时置灰不可点
+      h('button', {
+        className: installedFilter === 'all'
+          ? styles.installedBtnActive
+          : styles.installedBtn,
+        onClick: () => setInstalledFilter('all'),
+        title: t('filterAllHint'),
+        'aria-pressed': installedFilter === 'all',
+      }, t('all')),
+      // 排序下拉框：紧跟「全部」之后，按需切换排序方式
+      Dropdown<SortKey>({
+        value: sort,
+        options: SORTS.map((key) => ({ value: key, label: t(key) })),
+        onChange: setSort,
+      }),
+      h('button', {
+        className: installedFilter === 'installed'
+          ? styles.installedBtnActive
+          : installedCount === 0
+            ? styles.installedBtnDisabled
+            : styles.installedBtn,
+        onClick: () => setInstalledFilter('installed'),
+        disabled: installedCount === 0,
+        title: installedCount === 0 ? t('filterInstalledNone') : t('filterInstalledHint'),
+        'aria-pressed': installedFilter === 'installed',
+      },
+        t('installed'),
+        h('span', {
+          className: installedFilter === 'installed' ? styles.segCountActive : styles.segCount,
+        }, installedCount)),
+      h('button', {
+        className: installedFilter === 'notInstalled'
+          ? styles.installedBtnActive
+          : notInstalledCount === 0
+            ? styles.installedBtnDisabled
+            : styles.installedBtn,
+        onClick: () => setInstalledFilter('notInstalled'),
+        disabled: notInstalledCount === 0,
+        title: notInstalledCount === 0 ? t('filterNotInstalledNone') : t('filterNotInstalledHint'),
+        'aria-pressed': installedFilter === 'notInstalled',
+      },
+        t('notInstalled'),
+        h('span', {
+          className: installedFilter === 'notInstalled' ? styles.segCountActive : styles.segCount,
+        }, notInstalledCount)),
+      // 通知中心入口：整行控件最右侧、贴右对齐；有任何通知时右上角悬浮红圈白字计数；
+      // 按钮文字用短文案（notificationsBtn），避免英文长标题挤占工具栏空间被截断
+      h('button', {
+        className: styles.failBtn,
+        onClick: onOpenNotifications,
+        title: t('notificationsHint'),
+        'aria-label': t('notificationsHint'),
+      }, t('notificationsBtn'), noticeCount > 0 ? h('span', { className: styles.failBadge }, noticeCount) : null),
+    ),
+  )
+}

package/src/client/components/CatalogHeader.tsx

@@ -0,0 +1,78 @@
+/**
+ * Section header: brand title row (H1 + open-site button) + tagline, followed
+ * by the purple ad banner that promotes the catalog stats.
+ */
+import { createElement as h, Fragment } from 'react'
+import styles from '../styles/Header.module.css'
+import type { Translate } from '../types.ts'
+import { GITHUB_URL, PLUGIN_VERSION, SITE_URL } from '../lib/catalog.ts'
+import { GitHubIcon, LogoIcon } from './icons.tsx'
+
+export function CatalogHeader({ t, langPath, statsTotal, statsVerified, onToggleLang }: {
+  t: Translate
+  langPath: string
+  statsTotal: number
+  statsVerified: number
+  onToggleLang: () => void
+}) {
+  return h(Fragment, null,
+    h('div', { className: styles.header },
+      // 第一行：logo + 标题（官网链接）与 GitHub 源码图标同行，GitHub 顶到标题行末尾
+      h('div', { className: styles.headerTitleRow },
+        h('a', {
+          className: styles.brandTitle,
+          href: `${SITE_URL}${langPath}`,
+          target: '_blank',
+          rel: 'noopener noreferrer',
+          title: t('openHint'),
+          'aria-label': t('openHint'),
+        },
+          h(LogoIcon),
+          h('h1', { className: styles.title },
+            t('title'),
+            h('span', { className: styles.version }, ` v${PLUGIN_VERSION}`),
+          ),
+        ),
+        // 右侧控件组：语言切换 + GitHub 源码图标（独立链接，brandTitle 是官网 <a> 不能嵌套），
+        // 一起 space-between 顶到标题行最右
+        h('div', { className: styles.headerRight },
+          // 语言切换：按钮文字始终显示「要切到的语言」，点击即切，无需图标
+          h('button', {
+            className: styles.langBtn,
+            type: 'button',
+            onClick: onToggleLang,
+            title: t('toggleLangHint'),
+            'aria-label': t('toggleLangHint'),
+          }, langPath === 'zh/' ? 'EN' : '中文'),
+          h('a', {
+            className: styles.githubLink,
+            href: GITHUB_URL,
+            target: '_blank',
+            rel: 'noopener noreferrer',
+            title: t('githubHint'),
+            'aria-label': t('githubHint'),
+          }, h(GitHubIcon)),
+        ),
+      ),
+      // 第二行：副标题仍是官网链接，点击跳 dsh-plugin.org
+      h('a', {
+        className: styles.taglineLink,
+        href: `${SITE_URL}${langPath}`,
+        target: '_blank',
+        rel: 'noopener noreferrer',
+        title: t('openHint'),
+      },
+        h('div', { className: styles.tagline }, t('tagline', { total: statsTotal, verified: statsVerified })),
+      ),
+    ),
+    h('a', {
+      className: styles.adBanner,
+      href: `${SITE_URL}${langPath}`,
+      target: '_blank',
+      rel: 'noopener noreferrer',
+    },
+    h('span', { className: styles.adBadge }, t('adBadge')),
+    h('span', { className: styles.adText }, t('ad', { total: statsTotal, verified: statsVerified })),
+    h('span', { className: styles.adArrow }, '\u2197')),
+  )
+}

package/src/client/components/CatalogList.tsx

@@ -0,0 +1,75 @@
+/**
+ * Catalog list: the scrollable container with the loading / failed / empty
+ * states, the plugin cards, and the count footer. Resets scroll position when
+ * the category or install-status filter changes so the replaced content is
+ * not mistaken for a no-op update.
+ */
+import { createElement as h, useEffect, useRef } from 'react'
+import styles from '../styles/List.module.css'
+import type { HubPlugin, LocaleId, Translate } from '../types.ts'
+import { SITE_URL } from '../lib/catalog.ts'
+import { PluginCard } from './PluginCard.tsx'
+
+export function CatalogList({ plugins, failed, visible, total, t, langPath, reload, category, installedFilter, copied, installedName, installedVersion, hasUpdate, langKey, onInstall, onUninstall }: {
+  plugins: HubPlugin[] | null
+  failed: boolean
+  visible: HubPlugin[]
+  total: number
+  t: Translate
+  langPath: string
+  reload: () => void
+  category: string
+  installedFilter: 'all' | 'installed' | 'notInstalled'
+  copied: string | null
+  installedName: (p: HubPlugin) => string | null
+  installedVersion: (p: HubPlugin) => string | null
+  hasUpdate: (p: HubPlugin) => boolean
+  langKey: LocaleId
+  onInstall: (p: HubPlugin, opts?: { update?: boolean }) => void
+  onUninstall: (p: HubPlugin) => void
+}) {
+  /** 列表滚动容器：分类/搜索切换后列表内容替换但 scrollTop 保留，会让用户误以为列表没更新，需重置回顶部 */
+  const listRef = useRef<HTMLDivElement | null>(null)
+
+  useEffect(() => {
+    listRef.current?.scrollTo({ top: 0 })
+  }, [category, installedFilter])
+
+  return h('div', { className: styles.body },
+    h('div', { ref: listRef, className: styles.list },
+      plugins === null && !failed && h('div', { className: styles.state }, t('loading')),
+      failed && h('div', { className: styles.state },
+        h('div', { className: styles.stateTitle }, t('failed')),
+        h('div', { className: styles.stateDesc }, t('failedDesc')),
+        h('button', { className: styles.retryBtn, onClick: () => reload() }, t('retry')),
+      ),
+      plugins !== null && !failed && visible.length === 0 && h('div', { className: styles.state },
+        h('div', { className: styles.stateTitle }, t('noResult')),
+        h('div', { className: styles.stateDesc }, t('noResultDesc')),
+      ),
+      plugins !== null && !failed && visible.map((p) => h(PluginCard, {
+        // 唯一 key：数据重构后同一 slug 可能对应多个作者仓库，仅用 slug 会撞 key，
+        // 导致切换分类时 React 复用旧 DOM、列表不刷新。
+        key: p.ownerSlug ? `${p.ownerSlug}/${p.slug}` : p.slug,
+        plugin: p,
+        copied,
+        installedName,
+        installedVersion,
+        hasUpdate,
+        t,
+        langKey,
+        langPath,
+        onInstall,
+        onUninstall,
+      })),
+    ),
+    plugins !== null && !failed && h('div', { className: styles.footer },
+      h('a', {
+        className: styles.footLink,
+        href: `${SITE_URL}${langPath}`,
+        target: '_blank',
+        rel: 'noopener noreferrer',
+      }, t('browseAll', { n: total })),
+    ),
+  )
+}

package/src/client/components/CategoryTabs.tsx

@@ -0,0 +1,35 @@
+/**
+ * Category tabs: an "all" chip followed by one chip per catalog category.
+ * The "all" chip carries the total plugin count; the per-category chips
+ * carry no counts so their widths stay uniform.
+ */
+import { createElement as h } from 'react'
+import styles from '../styles/Header.module.css'
+import type { LocaleId } from '../types.ts'
+import { CATEGORY_ORDER, CATEGORY_SHORT_LABELS, categoryLabel } from '../lib/catalog.ts'
+
+export function CategoryTabs({ category, setCategory, allLabel, totalCount, langKey }: {
+  category: string
+  setCategory: (value: string) => void
+  allLabel: string
+  totalCount: number
+  langKey: LocaleId
+}) {
+  return h('div', { className: styles.tabs },
+    // 第一个按钮固定为「全部」：展示全部分类，直接显示插件总数；
+    // 其余分类按钮不带数量，保持排版整齐
+    h('button', {
+      key: 'all',
+      className: category === 'all' ? styles.tabActive : styles.tab,
+      onClick: () => setCategory('all'),
+    },
+      allLabel,
+      h('span', { className: styles.tabCount }, totalCount)),
+    CATEGORY_ORDER.map((id) => h('button', {
+      key: id,
+      className: category === id ? styles.tabActive : styles.tab,
+      onClick: () => setCategory(id),
+    },
+    categoryLabel(CATEGORY_SHORT_LABELS, id, langKey))),
+  )
+}

package/src/client/components/Dropdown.tsx

@@ -0,0 +1,80 @@
+/**
+ * Custom dropdown (native <select> replacement).
+ *
+ * macOS/浏览器原生下拉无法跟随宿主主题，这里自绘：触发器按钮 + 绝对定位面板，
+ * 点外部/Esc 关闭；选项 hover 加重底色、激活项深色实心高亮，全部走 --dsw-alias-* 主题变量。
+ */
+import { createElement as h, useEffect, useRef, useState } from 'react'
+import type { JSX } from 'react'
+import styles from '../styles/Dropdown.module.css'
+import { ChevronDownIcon } from './icons.tsx'
+
+export interface DropdownOption<T extends string> {
+  value: T
+  label: string
+  /** 可选计数徽标（如「已安装 12」） */
+  count?: number
+}
+
+interface DropdownProps<T extends string> {
+  value: T
+  options: DropdownOption<T>[]
+  onChange: (value: T) => void
+  title?: string
+}
+
+export function Dropdown<T extends string>({ value, options, onChange, title }: DropdownProps<T>): JSX.Element {
+  const [open, setOpen] = useState(false)
+  const rootRef = useRef<HTMLDivElement | null>(null)
+
+  // 面板展开时：点面板外部或按 Esc 关闭。
+  useEffect(() => {
+    if (!open) return
+    const onDoc = (e: MouseEvent) => {
+      if (rootRef.current && !rootRef.current.contains(e.target as Node)) setOpen(false)
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false)
+    }
+    document.addEventListener('mousedown', onDoc)
+    document.addEventListener('keydown', onKey)
+    return () => {
+      document.removeEventListener('mousedown', onDoc)
+      document.removeEventListener('keydown', onKey)
+    }
+  }, [open])
+
+  const current = options.find((o) => o.value === value)
+
+  return h('div', { className: styles.dropdown, ref: rootRef },
+    h('button', {
+      className: styles.dropdownBtn,
+      type: 'button',
+      title,
+      'aria-haspopup': 'listbox',
+      'aria-expanded': open,
+      onClick: () => setOpen((v) => !v),
+    },
+      h('span', { className: styles.dropdownLabel }, current?.label ?? value),
+      h('span', { className: open ? styles.dropdownArrowOpen : styles.dropdownArrow }, h(ChevronDownIcon)),
+    ),
+    open && h('div', { className: styles.dropdownPanel, role: 'listbox' },
+      options.map((o) => h('button', {
+        key: o.value,
+        type: 'button',
+        role: 'option',
+        'aria-selected': o.value === value,
+        className: o.value === value ? styles.dropdownItemActive : styles.dropdownItem,
+        onClick: () => {
+          onChange(o.value)
+          setOpen(false)
+        },
+      },
+        h('span', { className: styles.dropdownItemLabel }, o.label),
+        typeof o.count === 'number'
+          ? h('span', { className: o.value === value ? styles.dropdownCountActive : styles.dropdownCount }, o.count)
+          : null,
+      )),
+    ),
+  )
+}