@logictan/dsh-config-manager 0.1.60

package/src/client/common/Icon.tsx

@@ -0,0 +1,129 @@
+/**
+ * 图标原语 —— 基于 lucide-react 的统一图标层（Workbench Design System）。
+ *
+ * 取代散落的文本符号图标（▣ ⇥ ⇤ ⇅ ⟳ ◷ ⓘ ⭳ ⌕ ✕ ⧉ →），解决跨平台字形宽度/基线
+ * 漂移与视觉重量不一致问题。所有图标统一：
+ *   - 尺寸由 `size` 控制（默认 14px，对齐正文行高）；
+ *   - 描边 strokeWidth 统一 1.75（克制、精致，匹配高密度开发者工具观感）；
+ *   - 颜色继承 currentColor（跟随父级文字色 / data-danger / hover 等语义）；
+ *   - vertical-align 居中，与相邻文字基线对齐。
+ *
+ * 用法：<Icon name="download" /> 或具名导出 <DownloadIcon />。
+ * 不引入第二套视觉体系：颜色走 currentColor → 父级 --dsw-* token。
+ */
+import type { CSSProperties } from 'react'
+import type { LucideIcon } from 'lucide-react'
+// 体积纪律：从各图标独立模块路径导入（非 `lucide-react` 桶导出），保证 rolldown 在 cjs
+// 单文件打包下精确 tree-shake——只打入用到的 ~18 个图标，避免整库 1500+ 全量进 client.js。
+import ArrowRight from 'lucide-react/dist/esm/icons/arrow-right.mjs'
+import CheckCircle from 'lucide-react/dist/esm/icons/check-circle.mjs'
+import ChevronDown from 'lucide-react/dist/esm/icons/chevron-down.mjs'
+import ChevronRight from 'lucide-react/dist/esm/icons/chevron-right.mjs'
+import Clock from 'lucide-react/dist/esm/icons/clock.mjs'
+import CircleAlert from 'lucide-react/dist/esm/icons/circle-alert.mjs'
+import Copy from 'lucide-react/dist/esm/icons/copy.mjs'
+import DatabaseBackup from 'lucide-react/dist/esm/icons/database-backup.mjs'
+import Download from 'lucide-react/dist/esm/icons/download.mjs'
+import Eye from 'lucide-react/dist/esm/icons/eye.mjs'
+import FolderInput from 'lucide-react/dist/esm/icons/folder-input.mjs'
+import HardDriveDownload from 'lucide-react/dist/esm/icons/hard-drive-download.mjs'
+import Info from 'lucide-react/dist/esm/icons/info.mjs'
+import MessageSquare from 'lucide-react/dist/esm/icons/message-square.mjs'
+import PackageCheck from 'lucide-react/dist/esm/icons/package-check.mjs'
+import Pencil from 'lucide-react/dist/esm/icons/pencil.mjs'
+import RefreshCw from 'lucide-react/dist/esm/icons/refresh-cw.mjs'
+import RotateCw from 'lucide-react/dist/esm/icons/rotate-cw.mjs'
+import Search from 'lucide-react/dist/esm/icons/search.mjs'
+import Trash2 from 'lucide-react/dist/esm/icons/trash-2.mjs'
+import TriangleAlert from 'lucide-react/dist/esm/icons/triangle-alert.mjs'
+import Upload from 'lucide-react/dist/esm/icons/upload.mjs'
+import X from 'lucide-react/dist/esm/icons/x.mjs'
+
+/** 语义图标名 → Lucide 组件映射（单一事实来源）。 */
+const ICONS = {
+  backup: HardDriveDownload,
+  export: Upload,
+  import: FolderInput,
+  sync: RefreshCw,
+  refresh: RotateCw,
+  activity: Clock,
+  clock: Clock,
+  about: Info,
+  info: Info,
+  message: MessageSquare,
+  pencil: Pencil,
+  close: X,
+  delete: Trash2,
+  download: Download,
+  inspect: Search,
+  view: Eye,
+  copy: Copy,
+  arrowRight: ArrowRight,
+  chevronRight: ChevronRight,
+  chevronDown: ChevronDown,
+  preview: Eye,
+  snapshot: DatabaseBackup,
+  ok: PackageCheck,
+  check: CheckCircle,
+  warn: TriangleAlert,
+  error: CircleAlert,
+} as const satisfies Record<string, LucideIcon>
+
+export type IconName = keyof typeof ICONS
+
+export interface IconProps {
+  name: IconName
+  /** 像素尺寸（默认 14，对齐 12.5px 正文行高） */
+  size?: number
+  /** 描边粗细（默认 1.75） */
+  strokeWidth?: number
+  className?: string
+  style?: CSSProperties
+  /** 无障碍：装饰性图标默认 aria-hidden；需语义时由父级 aria-label 承担 */
+  decorative?: boolean
+}
+
+/**
+ * 统一图标（lucide-react）。颜色继承 currentColor，尺寸/描边集中控制。
+ */
+export function Icon({ name, size = 14, strokeWidth = 1.75, className, style, decorative = true }: IconProps) {
+  const Cmp = ICONS[name]
+  return (
+    <Cmp
+      size={size}
+      strokeWidth={strokeWidth}
+      className={className}
+      style={{ verticalAlign: 'middle', flex: 'none', ...style }}
+      aria-hidden={decorative || undefined}
+      focusable={false}
+    />
+  )
+}
+
+/* —— 具名导出（调用处可读性优先） —— */
+export const BackupIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="backup" {...p} />
+export const ExportIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="export" {...p} />
+export const ImportIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="import" {...p} />
+export const SyncIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="sync" {...p} />
+export const RefreshIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="refresh" {...p} />
+export const ActivityIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="activity" {...p} />
+export const ClockIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="clock" {...p} />
+export const AboutIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="about" {...p} />
+export const MessageIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="message" {...p} />
+export const PencilIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="pencil" {...p} />
+export const CloseIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="close" {...p} />
+export const DeleteIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="delete" {...p} />
+export const DownloadIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="download" {...p} />
+export const InspectIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="inspect" {...p} />
+export const ViewIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="view" {...p} />
+export const CopyIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="copy" {...p} />
+export const ArrowRightIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="arrowRight" {...p} />
+export const ChevronRightIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="chevronRight" {...p} />
+export const ChevronDownIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="chevronDown" {...p} />
+export const PreviewIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="preview" {...p} />
+export const SnapshotIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="snapshot" {...p} />
+export const OkIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="ok" {...p} />
+export const CheckIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="check" {...p} />
+export const WarnIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="warn" {...p} />
+export const ErrorIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="error" {...p} />
+export const InfoIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="info" {...p} />

package/src/client/common/Modal.tsx

@@ -0,0 +1,173 @@
+/**
+ * Modal —— 基于 @radix-ui/react-dialog 的统一弹窗原语（Workbench Design System）。
+ *
+ * 取代项目里散落的两套弹窗实现：
+ *   1. ConfirmDialog（手写 focus trap / Esc / 焦点还原）；
+ *   2. 各页内联 dialogMask+dialogCard（无 focus trap、Esc 行为不一致）。
+ * 统一后获得 Radix 成熟的无障碍能力：
+ *   - 自动 focus trap（Tab 循环限制在弹窗内，disabled/隐藏元素跳过）；
+ *   - Esc 关闭（可禁用）、遮罩点击关闭（可禁用）、初始焦点与关闭后焦点还原；
+ *   - aria-modal / role=dialog、body 滚动锁定、Portal 渲染到 document.body（脱离宿主
+ *     settings 弹窗的层叠上下文，z-index 由 Radix 内容层统一管理）。
+ *
+ * 视觉沿用既有 --dsw-* token 类（dialogMask/dialogCard/dialogHeader/dialogBody/...），
+ * 不引入第二套视觉体系；仅把「行为/a11y」交给 Radix，外观仍由 config-manager.module.css 控制。
+ *
+ * 用法：
+ *   <Modal open={open} onClose={close} title="标题" wide>
+ *     <Modal.Header onClose={close} />   // 可选：带关闭按钮的标题行
+ *     <Modal.Body scroll>…内容…</Modal.Body>
+ *     <Modal.Footer>…按钮…</Modal.Footer>
+ *   </Modal>
+ */
+import { useEffect, useState } from 'react'
+import type { CSSProperties, ReactNode, Ref } from 'react'
+import * as Dialog from '@radix-ui/react-dialog'
+import { CloseIcon } from './Icon.tsx'
+import css from '../config-manager.module.css'
+
+/**
+ * 插件根节点 id（渲染在 `ConfigManagerSection` 的最外层 div 上），同时是 Radix Portal 的挂载容器。
+ *
+ * 为什么不能挂 `document.body`（Radix 默认）：宿主设置弹窗的 overlay 是
+ * `position: fixed; z-index: 1000`，插件弹窗若挂到 body 就成了它的**兄弟**，
+ * 自身 z-index 100/101 远低于 1000 → 弹窗被整个盖住、肉眼完全不可见；
+ * 而 Radix 在 modal 打开时已经把 `document.body` 置为 `pointer-events: none`，
+ * 于是表现为「打开备份与迁移后整页点不动，必须先在屏幕上点一下才行」——
+ * 那一下点击正是关掉这个"透明弹窗"的 outside-pointerdown。
+ *
+ * 把 Portal 容器指回插件根节点，弹窗就重新落在宿主弹窗自己的层叠上下文内
+ * （与 Radix 迁移前内联渲染 `dialogMask` 的层级语义一致），遮罩与卡片正常可见可点。
+ */
+export const MODAL_ROOT_ID = 'dsh-config-manager-root'
+
+export interface ModalProps {
+  /** 是否打开（受控） */
+  open: boolean
+  /** 关闭回调（Esc / 遮罩点击 / 关闭按钮触发） */
+  onClose: () => void
+  /** 弹窗 accessible name（aria-label） */
+  title?: string
+  /** 宽变体（480px，用于计划预览/差异查看等密集内容） */
+  wide?: boolean
+  /** busy 时禁用一切关闭途径（防执行中误关） */
+  busy?: boolean
+  /** Radix 打开时的初始焦点重定向（如 ConfirmDialog 把焦点派发到取消按钮）。
+   *  Radix 传入的是可 preventDefault 的 DOM Event。 */
+  onOpenAutoFocus?: (e: Event) => void
+  /** 卡片额外内联样式（如 ReleaseNotes 的自定义宽度/最大高度）；常规布局仍走 CSS 类 */
+  cardStyle?: CSSProperties
+  children?: ReactNode
+}
+
+/**
+ * 统一弹窗容器（Radix Dialog）。busy 时禁用 Esc 与遮罩关闭。
+ */
+export function Modal({ open, onClose, title, wide, busy, onOpenAutoFocus, cardStyle, children }: ModalProps) {
+  // Portal 容器在挂载后再解析一次：Modal 与根节点可能在同一次 commit 中渲染，
+  // 首次求值时根节点尚未进 DOM（届时回退 Radix 的 document.body）。
+  const [container, setContainer] = useState<HTMLElement | null>(null)
+  useEffect(() => {
+    setContainer(document.getElementById(MODAL_ROOT_ID))
+  }, [])
+
+  return (
+    <Dialog.Root
+      open={open}
+      onOpenChange={(next) => {
+        // busy 时拒绝关闭（Radix 通过 onOpenChange(false) 表达 Esc/遮罩关闭意图）
+        if (!next && busy === true) return
+        if (!next) onClose()
+      }}
+    >
+      <Dialog.Portal container={container ?? undefined}>
+        <Dialog.Overlay className={css.dialogMask} />
+        <Dialog.Content
+          className={`${css.dialogContentCenter} ${css.dialogCard}${wide === true ? ` ${css.dialogWide}` : ''}`}
+          style={cardStyle}
+          aria-label={title}
+          onOpenAutoFocus={onOpenAutoFocus}
+          // busy 时阻止 Radix 默认的 Esc/外部指针关闭（双保险，配合 onOpenChange 守卫）
+          onEscapeKeyDown={(e) => { if (busy === true) e.preventDefault() }}
+          onPointerDownOutside={(e) => { if (busy === true) e.preventDefault() }}
+          onInteractOutside={(e) => { if (busy === true) e.preventDefault() }}
+        >
+          {children}
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  )
+}
+
+/* ---------------- 子部件（纯样式装配，无逻辑） ---------------- */
+
+export interface ModalHeaderProps {
+  /** 标题文本（同时作为可视标题） */
+  title: string
+  /** 关闭按钮回调（缺省不渲染关闭按钮） */
+  onClose?: () => void
+  /** 关闭按钮 disabled（如 busy） */
+  closeDisabled?: boolean
+  /** 标题行右侧额外内容（如徽章/合计） */
+  trailing?: ReactNode
+}
+
+/** 弹窗标题行（可选关闭按钮 + 右侧 trailing）。 */
+function ModalHeader({ title, onClose, closeDisabled, trailing }: ModalHeaderProps) {
+  if (onClose === undefined && trailing === undefined) {
+    return <div className={css.dialogHeader}>{title}</div>
+  }
+  return (
+    <div className={css.dialogHeaderRow}>
+      <span className={css.dialogHeader}>{title}</span>
+      {trailing}
+      {onClose !== undefined && (
+        <Dialog.Close asChild>
+          <button
+            type="button"
+            className={`${css.iconBtn} ${css.dialogClose}`}
+            aria-label="关闭"
+            disabled={closeDisabled === true}
+          >
+            <CloseIcon size={14} />
+          </button>
+        </Dialog.Close>
+      )}
+    </div>
+  )
+}
+
+export interface ModalBodyProps {
+  children?: ReactNode
+  /** 限高内滚变体（长内容安全） */
+  scroll?: boolean
+  /** 正文容器 ref（如 ReleaseNotes 无限滚动需要监听滚动位置） */
+  innerRef?: Ref<HTMLDivElement>
+  /** 滚动回调（配合 innerRef 实现无限加载等） */
+  onScroll?: () => void
+  /** 正文额外内联样式（如自定义 maxHeight/gap）；常规布局仍走 CSS 类 */
+  style?: CSSProperties
+}
+
+/** 弹窗正文区。 */
+function ModalBody({ children, scroll, innerRef, onScroll, style }: ModalBodyProps) {
+  return (
+    <div
+      ref={innerRef}
+      className={scroll === true ? `${css.dialogBody} ${css.dialogBodyScroll}` : css.dialogBody}
+      onScroll={onScroll}
+      style={style}
+    >
+      {children}
+    </div>
+  )
+}
+
+/** 弹窗底部按钮区（actionRow 右对齐）。 */
+function ModalFooter({ children }: { children?: ReactNode }) {
+  return <div className={`${css.actionRow} ${css.dialogFooter}`}>{children}</div>
+}
+
+Modal.Header = ModalHeader
+Modal.Body = ModalBody
+Modal.Footer = ModalFooter

package/src/client/common/ToastViewport.tsx

@@ -0,0 +1,73 @@
+/**
+ * ToastViewport —— 全局通知的渲染宿主（右下角堆叠）。
+ *
+ * 挂载在 `ConfigManagerSection` 根部（与 `.drawerPanel` 同级），而不是 Portal 到 body：
+ * 宿主设置弹窗 overlay 为 `position: fixed; z-index: 1000`（见 Modal.tsx 的
+ * MODAL_ROOT_ID 说明），任何挂到 body 的固定层都会被它盖住而"隐形"。
+ * 因此本组件用 `position: absolute` 贴合插件根节点（`.section` 已 position: relative），
+ * 天然落在宿主弹窗自己的层叠上下文内。
+ *
+ * 交互：
+ *   - 每条可点 × 手动关闭；悬停整条时**暂停**自动消失（正在读的内容不会跑掉），
+ *     移开后按原时长重新计时。
+ *   - 容器 `pointer-events: none`，仅卡片自身 `pointer-events: auto`：
+ *     通知不遮挡下方页面的点击（右下角常压着状态栏 / 列表）。
+ *   - aria-live="polite" + role="status"：屏幕阅读器播报但不打断。
+ *
+ * 视觉：走 Workbench Design System 既有 t​o​k​en（`--dsw-*`）+ Badge/Banner 的四态语义色，
+ * 不引入第二套配色。
+ */
+import { useSyncExternalStore } from 'react'
+import type { TranslateNS } from '../client-types.ts'
+import { CheckIcon, CloseIcon, ErrorIcon, InfoIcon, WarnIcon } from './Icon.tsx'
+import { IconButton } from './ui.tsx'
+import { toastStore } from './toast-store.ts'
+import type { ToastKind } from './toast-types.ts'
+import css from '../config-manager.module.css'
+
+export interface ToastViewportProps {
+  /** 关闭按钮的无障碍文案（由 S​h​e​l​l 注​入的 i18n）。 */
+  t: TranslateNS<'config-manager'>
+}
+
+/** kind → 图标（与 Badge / Banner 四态同源语义）。 */
+function ToastGlyph({ kind }: { kind: ToastKind }) {
+  switch (kind) {
+    case 'ok': return <CheckIcon size={14} />
+    case 'warn': return <WarnIcon size={14} />
+    case 'error': return <ErrorIcon size={14} />
+    case 'info': return <InfoIcon size={14} />
+  }
+}
+
+/**
+ * 右下角通知视口。无通知时渲染 null（不进 DOM）。
+ */
+export function ToastViewport({ t }: ToastViewportProps) {
+  const snapshot = useSyncExternalStore(toastStore.subscribe, toastStore.getSnapshot)
+
+  if (snapshot.items.length === 0) return null
+
+  return (
+    <div className={css.toastViewport} role="status" aria-live="polite">
+      {snapshot.items.map((item) => (
+        <div
+          key={item.id}
+          className={css.toast}
+          data-kind={item.kind}
+          // 悬停暂停自动消失（读完再走）；移开按原时长重新计时
+          onMouseEnter={() => { toastStore.pauseTimer(item.id) }}
+          onMouseLeave={() => { toastStore.resetTimer(item.id) }}
+        >
+          <span className={css.toastGlyph} aria-hidden="true"><ToastGlyph kind={item.kind} /></span>
+          <span className={css.toastText}>{item.text}</span>
+          <IconButton
+            icon={<CloseIcon size={12} />}
+            label={t('common.close')}
+            onClick={() => { toastStore.dismiss(item.id) }}
+          />
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/client/common/toast-store.test.ts

@@ -0,0 +1,192 @@
+/**
+ * toast-store 单测：状态机行为（去重 / 上限 / 计时 / 手动关闭 / 空文案）。
+ *
+ * 计时器全部走注​入的假实现（`schedule`/`cancel`），因此测试**零真实等待**、
+ * 结果确定（不受 CI 负载影响）。同时用 subscribe 计数验证「无变更不通知订阅者」——
+ * 该性质直接决定 React 端不会因悬停暂停而重渲染。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { ToastStore, DEFAULT_DURATION_MS } from './toast-store.ts'
+
+/** 可控的假计时器：手动 `runDue()` 推进。 */
+function makeClock() {
+  let now = 0
+  let seq = 0
+  const pending = new Map<number, { at: number, fn: () => void }>()
+  return {
+    schedule: (fn: () => void, ms: number): number => {
+      const id = ++seq
+      pending.set(id, { at: now + ms, fn })
+      return id
+    },
+    cancel: (handle: unknown): void => { pending.delete(handle as number) },
+    /** 推进 now 毫秒并触发所有到期任务。 */
+    runDue(ms: number): void {
+      now += ms
+      for (const [id, task] of [...pending]) {
+        if (task.at <= now) {
+          pending.delete(id)
+          task.fn()
+        }
+      }
+    },
+    get pendingCount(): number { return pending.size },
+  }
+}
+
+function makeStore(maxVisible?: number) {
+  const clock = makeClock()
+  const store = new ToastStore({ maxVisible, schedule: clock.schedule, cancel: clock.cancel })
+  return { store, clock }
+}
+
+test('toast: push 入队并通知订阅者，getSnapshot 返回该条', () => {
+  const { store } = makeStore()
+  let notified = 0
+  store.subscribe(() => { notified += 1 })
+
+  const id = store.push('ok', '已保存')
+
+  assert.ok(id > 0)
+  assert.equal(notified, 1)
+  assert.deepEqual(store.getSnapshot().items.map((t) => t.text), ['已保存'])
+})
+
+test('toast: 空/纯空白文案被忽略（不入队、不通知）', () => {
+  const { store } = makeStore()
+  let notified = 0
+  store.subscribe(() => { notified += 1 })
+
+  assert.equal(store.push('ok', ''), 0)
+  assert.equal(store.push('ok', '   \n\t '), 0)
+  assert.equal(store.getSnapshot().items.length, 0)
+  assert.equal(notified, 0, '空文案不得触发订阅通知');
+})
+
+test('toast: 同 kind+text 重复 push 不新增条目（防连点刷屏）', () => {
+  const { store } = makeStore()
+  const first = store.push('ok', '已导出')
+  const second = store.push('ok', '已导出')
+
+  assert.equal(first, second, '应复用同一条目 id')
+  assert.equal(store.getSnapshot().items.length, 1)
+})
+
+test('toast: 同文案不同 kind 视为两条（语义不同）', () => {
+  const { store } = makeStore()
+  store.push('ok', '完成')
+  store.push('error', '完成')
+  assert.equal(store.getSnapshot().items.length, 2)
+})
+
+test('toast: 到期自动消失', () => {
+  const { store, clock } = makeStore()
+  store.push('ok', '临时提示')
+  assert.equal(store.getSnapshot().items.length, 1)
+
+  clock.runDue(DEFAULT_DURATION_MS.ok - 1)
+  assert.equal(store.getSnapshot().items.length, 1, '未到期不得消失')
+
+  clock.runDue(1)
+  assert.equal(store.getSnapshot().items.length, 0, '到期应自动移除')
+})
+
+test('toast: durationMs=0 表示常驻，不自动消失', () => {
+  const { store, clock } = makeStore()
+  store.push('error', '需手动关闭', 0)
+
+  clock.runDue(10 * 60 * 1000)
+  assert.equal(store.getSnapshot().items.length, 1, '常驻通知不得被计时清掉')
+  assert.equal(clock.pendingCount, 0, '常驻通知不应占用计时器')
+})
+
+test('toast: 超过同屏上限挤掉最旧一条，并释放其计时器', () => {
+  const { store, clock } = makeStore(3)
+  store.push('ok', 'a')
+  store.push('ok', 'b')
+  store.push('ok', 'c')
+  assert.equal(store.getSnapshot().items.length, 3)
+
+  store.push('ok', 'd')
+
+  assert.deepEqual(store.getSnapshot().items.map((t) => t.text), ['b', 'c', 'd'])
+  // 4 条各自排定过计时；a 被挤掉后其计时器必须被取消 → 只剩 3 个
+  assert.equal(clock.pendingCount, 3, '被挤掉的条目必须清掉计时器（防泄漏）')
+})
+
+test('toast: dismiss 手动关闭并清掉计时器', () => {
+  const { store, clock } = makeStore()
+  const id = store.push('ok', '关闭我')
+  assert.equal(clock.pendingCount, 1)
+
+  store.dismiss(id)
+
+  assert.equal(store.getSnapshot().items.length, 0)
+  assert.equal(clock.pendingCount, 0)
+  assert.equal(store.dismiss(id), undefined, '重复 dismiss 应为安全 no-op')
+})
+
+test('toast: pauseTimer 取消计时但保留条目，resetTimer 重新计时', () => {
+  const { store, clock } = makeStore()
+  const id = store.push('info', '悬停暂停')
+  assert.equal(clock.pendingCount, 1)
+
+  // 悬停：只停表，不动条目、不产生新快照
+  let notified = 0
+  store.subscribe(() => { notified += 1 })
+  store.pauseTimer(id)
+  assert.deepEqual(store.getSnapshot().items.map((t) => t.text), ['悬停暂停'])
+  assert.equal(clock.pendingCount, 0)
+  assert.equal(notified, 0, '暂停不应触发重渲染')
+
+  clock.runDue(10 * 60 * 1000)
+  assert.equal(store.getSnapshot().items.length, 1, '暂停期间不得消失')
+
+  // 移开：按原时长重新计时
+  store.resetTimer(id)
+  assert.equal(clock.pendingCount, 1)
+  clock.runDue(DEFAULT_DURATION_MS.info)
+  assert.equal(store.getSnapshot().items.length, 0)
+})
+
+test('toast: clear 清空全部并释放全部计时器', () => {
+  const { store, clock } = makeStore()
+  store.push('ok', 'a')
+  store.push('warn', 'b')
+  assert.equal(clock.pendingCount, 2)
+
+  store.clear()
+
+  assert.equal(store.getSnapshot().items.length, 0)
+  assert.equal(clock.pendingCount, 0)
+})
+
+test('toast: getSnapshot 引用稳定（相同内容不产生新对象，避免 React 死循环）', () => {
+  const { store } = makeStore()
+  const before = store.getSnapshot()
+  assert.equal(store.getSnapshot(), before, '无变更时快照引用必须一致')
+
+  store.push('ok', 'x')
+  const after = store.getSnapshot()
+  assert.notEqual(after, before, '有变更时应换新引用')
+
+  store.pauseTimer(store.getSnapshot().items[0]!.id)
+  assert.equal(store.getSnapshot(), after, '暂停计时不改变快照')
+})
+
+test('toast: 订阅退订后不再收到通知', () => {
+  const { store } = makeStore()
+  let notified = 0
+  const off = store.subscribe(() => { notified += 1 })
+  store.push('ok', 'one')
+  off()
+  store.push('ok', 'two')
+  assert.equal(notified, 1)
+})
+
+test('toast: 默认时长按语义分级（错误比成功停留更久）', () => {
+  assert.ok(DEFAULT_DURATION_MS.error > DEFAULT_DURATION_MS.ok)
+  assert.ok(DEFAULT_DURATION_MS.warn > DEFAULT_DURATION_MS.ok)
+  assert.equal(DEFAULT_DURATION_MS.ok > 0, true, '成功提示须自动消失')
+})