dsh-plugin 0.1.1 → 1.0.0

package/lib/types/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * dsh-plugin host entry: mounts the Plugin Hub HTTP routes once the host
+ * web server service is available. The browser bundle (src/client) talks to
+ * these same-origin routes to perform real installs from inside the app.
+ */
+import { type LoaderHandle } from './services/install.ts';
+import { type WebServerService } from './http/routes.ts';
+export declare const name = "dsh-plugin";
+export interface Config {
+    /** DSH profile that owns plugin mutations. Defaults to the booted profile. */
+    profile?: string;
+}
+/** The subset of the cordis host context this plugin touches. */
+interface HostContext {
+    webServer: WebServerService;
+    /** 运行中 loader：卸载成功后主动移除条目、立即生效（宿主未提供时卸载仍需重启） */
+    loader?: LoaderHandle;
+    inject(services: string[], callback: (host: HostContext) => void): void;
+    effect(callback: () => void, label?: string): void;
+}
+/**
+ * Mount the Plugin Hub routes after the web server service becomes available.
+ * @param ctx - cordis host context.
+ * @param config - optional profile override.
+ */
+export declare function apply(ctx: HostContext, config?: Config): void;
+export {};

package/lib/types/services/install-types.d.ts

@@ -0,0 +1,63 @@
+/** 安装/卸载运行时的公共类型与常量（无依赖，供各服务模块复用）。 */
+/** 一个 pnpm 安装子进程的结果快照。 */
+export interface InstallResult {
+    exitCode: number | null;
+    timedOut: boolean;
+    error: string | null;
+    stdout: string;
+    stderr: string;
+}
+export interface InstallTask {
+    id: number;
+    /** 操作目标：`github:<owner>/<repo>`（安装）或 npm 包名（卸载），冲突/恢复时需要展示给用户 */
+    target: string;
+    action: 'add' | 'remove';
+    /** 队列语义：pending 排队中 / running 执行中 / done / failed / cancelled（用户取消） */
+    status: 'pending' | 'running' | 'done' | 'failed' | 'cancelled';
+    timedOut: boolean;
+    exitCode: number | null;
+    /** 0-100 估算进度：解析 pnpm 的 `Progress: resolved…` 输出，阶段行兜底 */
+    progress: number;
+    /** Newest output lines first (consumer shows the tail). */
+    lines: string[];
+}
+/** 子进程启动参数（复用宿主 dsh 入口，或回退到 PATH 上的 `dsh`）。 */
+export interface Invocation {
+    file: string;
+    prefixArgs: string[];
+    cwd: string;
+    useShell: boolean;
+}
+/** 排队中的变更任务及其启动参数。 */
+export interface QueueItem {
+    task: InstallTask;
+    options: {
+        action: 'add' | 'remove';
+        profile: string;
+        target: string;
+        timeoutMs?: number;
+        env?: NodeJS.ProcessEnv;
+    };
+}
+/**
+ * 安装成功但宿主尚未重启的插件（待重启后生效）。纯内存态：宿主进程一重启
+ * 它自然清空，正好等于「重启后提醒消失」的语义，无需任何重启探测。
+ */
+export interface PendingRestart {
+    /** `github:<owner>/<repo>` 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
+    target: string;
+    /** 待重启语义：install 装完等挂载生效 / uninstall 卸完等清理 loader 残留 */
+    kind: 'install' | 'uninstall';
+    /** 任务完成时刻（epoch ms） */
+    at: number;
+}
+/** Grammar of an accepted `github:<owner>/<repo>` install target. */
+export declare const REPO_RE: RegExp;
+/** Grammar of an npm package name (used for uninstall targets). */
+export declare const PACKAGE_RE: RegExp;
+/** 捕获输出上限：stdout/stderr 各保留尾部 N 字节。 */
+export declare const CAPTURE_LIMIT_BYTES: number;
+/** Max output lines kept per task (newest wins). */
+export declare const MAX_TASK_LINES = 200;
+/** Max tracked tasks; oldest finished tasks are dropped first. */
+export declare const MAX_TASKS = 50;

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

@@ -0,0 +1,18 @@
+/**
+ * Install runner 的统一出口：执行真实插件变更（spawn 官方 dsh CLI 子进程）。
+ * 实现按职责拆分在同目录子模块，本文件只做公共 API 的 re-export，保持外部
+ * import 面稳定（routes.ts / index.ts 仍从 `services/install.ts` 引入）。
+ *
+ * 模块划分：
+ *  - install-types.ts  公共类型与常量
+ *  - pending-restart.ts  待重启列表内存态管理
+ *  - loader.ts          运行中 loader 的读取与卸载即时停用
+ *  - profile.ts         宿主 profile / 目标校验 / allowBuilds 写入
+ *  - task-queue.ts      任务注册表 + FIFO 队列 worker + 子进程生命周期
+ */
+export type { InstallResult, InstallTask, Invocation, PendingRestart, QueueItem } from './install-types.ts';
+export type { LoaderHandle } from './loader.ts';
+export { addPendingRestart, clearPendingRestart, listPendingRestarts } from './pending-restart.ts';
+export { dumpLoaderEntries, removeLoadedEntry } from './loader.ts';
+export { addAllowBuildsKey, githubTarget, parseAllowBuildsKey, readProfileArg, validPackageName } from './profile.ts';
+export { activeTask, cancelTask, getTask, hasQueuedTarget, hasRunningTask, runPluginMutation, startPluginMutation } from './task-queue.ts';

package/lib/types/services/installed-versions.d.ts

@@ -0,0 +1,14 @@
+export interface InstalledVersionRecord {
+    /** 安装时的目录最新 release 版本（无 release 的仓库为空串） */
+    version: string;
+    /** 安装时的仓库最近更新时间（ISO，GitHub pushed_at）；无 release 仓库的更新依据 */
+    updatedAt: string;
+    installedAt: string;
+}
+export type InstalledVersionTable = Record<string, InstalledVersionRecord>;
+export declare function versionsFilePath(profile: string): string;
+export declare function readInstalledVersions(profile: string): InstalledVersionTable;
+/** Record the catalog signals (version + repo updated time) present at install time for one repo. */
+export declare function recordInstalledVersion(profile: string, repo: string, version: string, updatedAt: string): void;
+/** Forget the recorded version for one repo (called on uninstall). */
+export declare function removeInstalledVersion(profile: string, repo: string): void;

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

@@ -0,0 +1,43 @@
+/**
+ * 运行中 loader 的读取与停用：卸载成功后对匹配条目做 live-disable，
+ * 使卸载立即生效（刷新页面不再加载已卸载的 client bundle，也无需重启）。
+ */
+/**
+ * 运行中 loader 的最小接口：卸载成功后即时移除条目用。
+ * 对应官方 `ctx.loader`（cordis-plugin-loader 的 Loader 服务）的读取面与移除面。
+ * 移除方式：对匹配条目 live-disable（`entry.update({ disabled: true })`），
+ * 而不是 `loader.remove(id)` —— disable 走 Entry.update 的 disabled 分支，不触发
+ * tree.write()（不会把运行态条目烘焙回 cordis.yml），也不依赖嵌套子树的 id 解析。
+ */
+export interface LoaderHandle {
+    /** 遍历当前插件树的全部条目（含嵌套子树）。 */
+    entries(): Iterable<{
+        id: string;
+        options: {
+            id?: string;
+            name?: string;
+            disabled?: boolean | null;
+        };
+        /** live-disable 一个条目（官方 Entry.update，force=true 覆盖初始化竞态）。 */
+        update(options: {
+            disabled: boolean | null;
+        }, create?: boolean, force?: boolean): Promise<void>;
+    }>;
+    /** 停止并移除一个条目（官方 Loader API：resolve → EntryGroup.remove → tree.write）。 */
+    remove(id: string): Promise<void>;
+}
+/** 运行中 loader 的全部条目（id + options.name），诊断用。 */
+export declare function dumpLoaderEntries(loader: LoaderHandle | undefined): Array<{
+    id: string;
+    name?: string;
+}>;
+/**
+ * 卸载成功后从运行中 loader 停用指定包的条目，使卸载立即生效（刷新页面不再
+ * 加载已卸载的 client bundle，也无需重启）。做法：按 name 扫描
+ * `loader.entries()`（含嵌套子树），对每个匹配条目
+ * `entry.update({ disabled: true })` 做 live-disable —— fiber 被 dispose，
+ * client-modules 对账后不再把它写进 `__DSH_BOOT__`，页面刷新即恢复。
+ * 返回 true = 无需重启（条目已停用，或本就没加载过）；false = 未能停用，
+ * 需登记「待重启清理」兜底。宿主关键包（@deepseek-ai/* 与本插件自身）一律跳过。
+ */
+export declare function removeLoadedEntry(loader: LoaderHandle, name: string): Promise<boolean>;

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,76 @@
+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[];
+}
+/** 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;
+}): 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 a
+ * git-hosted package's `prepare` script is blocked by pnpm's allowBuilds
+ * gate (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`), read the exact allowlist
+ * key pnpm printed, write it 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.0.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))),
+  )
+}