@mzzsfy/dsh-toast 0.1.0 → 0.1.2

package/README.md

@@ -40,23 +40,25 @@ toast('回合完成', { holdMs: 6 * 1000 })            // 自定义展示期
 
 ## API
 
-- `show(text, opts)` → `id`:入栈一条通知。`opts.kind` 为 `'info' | 'ok' | 'error'`(非法归 `info`,默认深色 / 成功绿 / 错误红);`opts.sticky` 真值常驻不自动消失,渲染「知道了」按钮;`opts.holdMs` 正数自定义展示期(默认 4 秒)。`text` 非字符串或为空时忽略并返回 `null`
-- `dismiss(id)`:移除指定条目,幂等
+- `show(text, opts)` → `id`:入栈一条通知。`opts.kind` 为 `'info' | 'ok' | 'error'`(非法归 `info`,默认深色 / 成功绿 / 错误红);`opts.sticky` 真值常驻不自动消失,渲染「知道了」按钮;`opts.holdMs` 有限正值自定义展示期(默认 4 秒,非有限值或超出 setTimeout 钳位上界回落默认)。`text` 非字符串或纯空白时忽略并返回 `null`
+- `dismiss(id)`:移除指定条目并撤销其自动消失计时,幂等
 - `mount()`:显式挂载渲染容器(一般无需调用,首次 `show` 惰性自举)
+- `__test`:非公开 API,仅供本包测试驱动 store 消费,无兼容承诺,消费方禁用
 
 ## 行为规格(BDD)
 
 - Given 库已加载,When `show(text)`,Then 通知顶部居中显示,默认 4 秒后自动消失
-- Given 栈内已有 4 条,When 再入栈一条,Then 最旧条目立即移除(含 sticky,新通知优先)
+- Given 栈内已有 4 条,When 再入栈一条,Then 最旧条目立即移除(含 sticky,新通知优先),被裁条目的自动消失计时同步撤销
 - Given `show(text, {sticky: true})`,Then 通知常驻,点「知道了」或 `dismiss(id)` 后消失
 - Given `kind: 'error'`,Then 红色变体渲染
 - Given 首次 `show`,Then 渲染容器与样式惰性挂载(容器直挂 body,不受设置页全屏层 z-index 遮挡)
-- Given HMR 重载产生同 id 旧容器,When 新代首次挂载,Then 旧容器移除、新容器就位
+- Given HMR 重载产生同 id 旧容器,When 新代首次挂载,Then 旧容器移除、新容器就位;旧代闭包再调 `show`/`mount` 时发现在位容器属更新代际即退避,不拆新代容器
+- Given 容器在场而样式节点被外部移除,When 再次 `show`,Then 样式补挂(容器与样式同级自愈)
 - Given 用户系统开启减弱动态效果,Then 入场动画禁用
 
 ## 实现说明
 
-- 位置顶部居中:不遮挡聊天输入区;容器直挂 body,层级高于设置全屏层
-- 样式全部取宿主 `--dsw-alias-*` 令牌(错误变体文字色除外),双主题自适应;样式挂宿主文档级、幂等且内容变化原位替换
-- store 位于模块闭包单例;渲染容器惰性自举、幂等、自愈(旧 root 卸载后重建),不依赖宿主生命周期
+- 位置顶部居中:不遮挡聊天输入区;容器直挂 body,层级高于设置全屏层(z-index 1100 为对宿主层级的显式假设,宿主层级调整时回归核对)
+- 样式全部取宿主 `--dsw-*` 令牌且带就近 fallback(宿主升级更名令牌时降级为可用默认形态,不静默失效);样式挂宿主文档级、幂等且内容变化原位替换,容器在场时随每次挂载自愈
+- store 位于模块闭包单例;渲染容器惰性自举、幂等、自愈(旧 root 卸载后重建),容器带代际标记防 HMR 两代互拆;不依赖宿主生命周期
 - react / react-dom/client 由宿主平台模块表提供,peerDependencies 声明 react 与 react-dom

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-toast",
   "description": "全局浮出通知 Toast 库:多条并存栈式展示,自动消失与常驻确认两种生命周期;普通 npm 依赖(非 dsh 插件),由消费插件的 cordis.patch.yml 代挂宿主占位条目",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -21,7 +21,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://git.1014.top:83/mzzsfy/dsh-plugin.git"
+    "url": "git+https://github.com/mzzsfy/dsh-plugin.git"
   },
   "engines": {
     "node": ">=22"

package/src/client.js

@@ -3,8 +3,9 @@
 // dsh.client.external require('@mzzsfy/dsh-toast/client') 使用。本包不声明
 // dsh.bundle.patch,不进 profile 插件层;宿主占位条目由消费方 cordis.patch.yml
 // 代挂,本包 client 由此进入客户端模块表。
-// 渲染容器惰性自举:首次 show 挂载,容器与样式幂等,挂载前清同 id 旧代残留
-// (HMR 重载模块后新代自愈,旧代闭包随容器移除失效)。
+// 渲染容器惰性自举:首次 show 挂载,容器与样式幂等,挂载前清同 id 旧代残留。
+// 容器带代际标记:HMR 旧代闭包再调 mount 时发现在位容器属更新代际即退避,
+// 不拆新代容器;旧代迟到通知不可见(一次性告警),刷新页面恢复。
 
 window.__ModuleLoader__.load({
   id: '@mzzsfy/dsh-toast',
@@ -15,21 +16,28 @@ window.__ModuleLoader__.load({
 
     // Toast 持续时长与栈上限:展示期定值;突发事件裁剪最旧条目
     const TOAST_HOLD_MS = 4 * 1000
+    // setTimeout 延迟的规范钳位上界:超出即被浏览器钳到上界本身(约 24.8 天),
+    // 非 sticky 条目将近乎永久驻留且无关闭按钮,超界值一律回落默认
+    const HOLD_MS_MAX = 2 ** 31 - 1
     const TOAST_MAX = 4
     const KINDS = ['info', 'ok', 'error']
     const HOST_ID = 'dsh-toast-host'
     const STYLE_ID = 'dsh-toast-style'
+    // 层级假设的显式化:承诺"高于设置全屏层"绑定此值,宿主层级调整时回归核对
+    const TOAST_Z_INDEX = 1100
 
+    // 令牌 fallback:宿主 dsh 升级更名 --dsw-* 变量时降级为可用默认形态,
+    // 不静默失效为透明底/不可读字
     const CSS = [
-      '.dsh-toast-stack { position:fixed; left:50%; top:16px; transform:translateX(-50%); z-index:1100;',
+      '.dsh-toast-stack { position:fixed; left:50%; top:16px; transform:translateX(-50%); z-index:' + TOAST_Z_INDEX + ';',
       '  display:flex; flex-direction:column; align-items:center; gap:8px; pointer-events:none; }',
-      '.dsh-toast { pointer-events:auto; background:var(--dsw-alias-toast-bg); color:var(--dsw-alias-label-primary-inverted);',
-      '  font:var(--dsw-font-xs-13); padding:8px 14px; border-radius:10px; box-shadow:var(--dsw-shadow-lv2);',
-      '  animation:dsh-toast-in 0.18s ease-out; max-width:520px; display:flex; align-items:center; gap:10px; }',
-      '.dsh-toast--ok { background:var(--dsw-alias-state-success-primary); color:var(--dsw-alias-label-primary-inverted); }',
-      '.dsh-toast--error { background:var(--dsw-alias-state-error-primary); color:#fff; }',
+      '.dsh-toast { pointer-events:auto; background:var(--dsw-alias-toast-bg, rgba(32,33,36,.92)); color:var(--dsw-alias-label-primary-inverted, #fff);',
+      '  font:var(--dsw-font-xs-13, 13px/1.5 system-ui, sans-serif); padding:8px 14px; border-radius:10px; box-shadow:var(--dsw-shadow-lv2, 0 2px 8px rgba(0,0,0,.25));',
+      '  animation:dsh-toast-in 0.18s ease-out; max-width:520px; max-height:60vh; overflow:auto; overflow-wrap:anywhere; display:flex; align-items:safe center; gap:10px; }',
+      '.dsh-toast--ok { background:var(--dsw-alias-state-success-primary, #1a7f37); color:var(--dsw-alias-label-primary-inverted, #fff); }',
+      '.dsh-toast--error { background:var(--dsw-alias-state-error-primary, #d93025); color:#fff; }',
       '.dsh-toast__close { border:0; background:transparent; cursor:pointer; color:inherit;',
-      '  font:var(--dsw-font-xs-strong-13); padding:0 2px; opacity:.8; }',
+      '  font:var(--dsw-font-xs-strong-13, 13px system-ui, sans-serif); padding:0 2px; opacity:.8; }',
       '.dsh-toast__close:hover { opacity:1; }',
       '@keyframes dsh-toast-in { from { transform:translateY(-8px); opacity:0; } to { transform:translateY(0); opacity:1; } }',
       '@media (prefers-reduced-motion: reduce) { .dsh-toast { animation:none; } }',
@@ -51,30 +59,52 @@ window.__ModuleLoader__.load({
       return KINDS.indexOf(kind) >= 0 ? kind : 'info'
     }
 
-    // 展示期:sticky 常驻不计时;非 sticky 取调用方正值,否则默认
+    // 展示期:sticky 常驻不计时;非 sticky 取调用方有限正值,否则默认
+    // (Infinity / 超钳位上界的值经浏览器 WebIDL 钳为约 24.8 天,近乎永久驻留,
+    // 与展示期意图相反,必须拦;Node 语义才是溢出钳 1ms,勿混)
     function resolveHoldMs(opts) {
       const holdMs = opts && opts.holdMs
-      return typeof holdMs === 'number' && holdMs > 0 ? holdMs : TOAST_HOLD_MS
+      return typeof holdMs === 'number' && Number.isFinite(holdMs) && holdMs > 0 && holdMs <= HOLD_MS_MAX ? holdMs : TOAST_HOLD_MS
     }
 
-    // 幂等移除:未命中不产生新快照,不触发重渲染
+    // 幂等移除:未命中零分配早退;命中先撤销自动消失计时,不入滞留空转
     function dismiss(id) {
-      const next = items.filter((item) => item.id !== id)
-      if (next.length === items.length) return
-      items = next
+      const item = items.find((entry) => entry.id === id)
+      if (item === undefined) return
+      if (item.timer !== undefined) {
+        clearTimeout(item.timer)
+        item.timer = undefined
+      }
+      items = items.filter((entry) => entry.id !== id)
       emit()
     }
 
-    // 入栈即返回单调 id;超上限裁最旧(含 sticky,极端场景下错误提示让位于新通知);
-    // 非 sticky 条目入栈即挂自动消失计时,经条目引用持 id,与裁剪无关
+    const clearTimer = (entry) => {
+      if (entry.timer !== undefined) {
+        clearTimeout(entry.timer)
+        entry.timer = undefined
+      }
+    }
+
+    // 入栈即返回单调 id;超上限裁最旧(含 sticky,极端场景下错误提示让位于新通知),
+    // 被裁条目的自动消失计时同步撤销;非 sticky 条目入栈即挂自动消失计时
     function show(text, opts) {
-      if (typeof text !== 'string' || text === '') return null
+      if (typeof text !== 'string' || text.trim() === '') return null
       const sticky = Boolean(opts && opts.sticky)
-      const entry = { id: ++seq, text, kind: normalizeKind(opts && opts.kind), sticky }
-      items = items.concat([entry]).slice(-TOAST_MAX)
+      const entry = { id: ++seq, text, kind: normalizeKind(opts && opts.kind), sticky, timer: undefined }
+      const merged = items.concat(entry)
+      if (merged.length > TOAST_MAX) {
+        for (const dropped of merged.slice(0, merged.length - TOAST_MAX)) clearTimer(dropped)
+      }
+      items = merged.slice(-TOAST_MAX)
       emit()
-      mount()
-      if (!sticky) setTimeout(() => dismiss(entry.id), resolveHoldMs(opts))
+      // 挂载失败不抛给消费方:条目已在 store,后续 show 的自愈重建会补展示
+      try {
+        mount()
+      } catch (error) {
+        console.warn('dsh-toast: 容器挂载失败,待下次触发自愈: ' + (error instanceof Error ? error.message : String(error)))
+      }
+      if (!sticky) entry.timer = setTimeout(() => dismiss(entry.id), resolveHoldMs(opts))
       return entry.id
     }
 
@@ -101,15 +131,33 @@ window.__ModuleLoader__.load({
       document.head.appendChild(style)
     }
 
-    // 容器自愈:本代容器在场即幂等;否则清理一切旧容器(本代被外部移除的、
-    // HMR 上一代残留的),逐个卸载 React root(detached 树不再续渲染)后移除重建
+    // 代际标记:window 级自增,旧代闭包经共享载体比对在位容器代际决定接管或退避
+    const GEN = (window.__dshToastGen = (window.__dshToastGen || 0) + 1)
+
+    // 容器自愈:本代容器在场即幂等(样式顺带自愈);在位容器属更新代际则本代
+    // 退避不动 DOM(一次性告警,迟到通知静默蒸发是排障盲区);否则清理旧容器
+    // (本代被外部移除的、HMR 上一代残留的、无归属标记的外部同 id 节点),
+    // 逐个卸载 React root(detached 树不再续渲染)后移除重建
     let root = null
     let host = null
+    let retireWarned = false
     function mount() {
-      if (root !== null && document.getElementById(HOST_ID) === host) return
-      for (const stale of new Set([host, document.getElementById(HOST_ID)])) {
+      const inPlace = document.getElementById(HOST_ID)
+      if (root !== null && inPlace === host) {
+        ensureStyle()
+        return
+      }
+      if (inPlace !== null && inPlace.__toastGen !== undefined && inPlace.__toastGen > GEN) {
+        if (!retireWarned) {
+          retireWarned = true
+          console.warn('dsh-toast: 本代已退役(在位容器属更新代际),本次通知不可见,请刷新页面恢复')
+        }
+        return
+      }
+      for (const stale of new Set([host, inPlace])) {
         if (stale === null) continue
         if (stale.__toastRoot !== undefined) stale.__toastRoot.unmount()
+        else console.warn('dsh-toast: 移除无归属标记的同 id 容器(外部或其他代际残留)')
         stale.remove()
       }
       ensureStyle()
@@ -118,6 +166,7 @@ window.__ModuleLoader__.load({
       document.body.appendChild(host)
       root = createRoot(host)
       host.__toastRoot = root
+      host.__toastGen = GEN
       root.render(React.createElement(ToastHost))
     }
 
@@ -147,7 +196,8 @@ window.__ModuleLoader__.load({
       // 导出呈插件形态;缺 apply 即判 invalid plugin 拖垮整树。装载体为空:容器
       // 惰性自举在首次 show 时发生,无需生命周期介入
       apply() {},
-      __test: { show, dismiss, source, normalizeKind, resolveHoldMs, getItems: () => items },
+      // 非公开 API,仅供本包测试驱动 store 消费,无兼容承诺,消费方禁用
+      __test: { show, dismiss, source, normalizeKind, resolveHoldMs, getItems: () => items.slice() },
     }
   },
 })

package/test/client-id.test.mjs

@@ -1,5 +1,7 @@
 // client.js 自注册格式守卫:ModuleLoader id 必须与 npm 包名一致,
-// 宿主按包名解析 client bundle。
+// 宿主按包名解析 client bundle;factory 返回值必须呈插件形态(含空 apply),
+// 缺 apply 即被浏览器 cordis loader 判 invalid plugin 拖垮整树。
+// 宿主入口 index.js 同锁:仅空 apply 形态,不带 name/inject。
 import test from 'node:test'
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
@@ -14,3 +16,32 @@ test('client.js 以本包名注册 ModuleLoader 模块', () => {
   assert.ok(match, 'client.js 缺少 __ModuleLoader__.load 注册')
   assert.equal(match[1], '@mzzsfy/dsh-toast')
 })
+
+test('factory 执行后返回值含空 apply 与公开 API', () => {
+  const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+  const modules = []
+  const windowStub = { __ModuleLoader__: { load: (module) => modules.push(module) } }
+  const reactStub = { useSyncExternalStore: () => [], createElement: () => null }
+  const requireStub = (name) => (name === 'react-dom/client' ? { createRoot: () => ({ render() {} }) } : reactStub)
+  const docStub = {
+    getElementById: () => null,
+    createElement: () => ({ id: '', style: {}, remove() {} }),
+    head: { appendChild: () => {} },
+    body: { appendChild: () => {} },
+  }
+  const factory = new Function('window', 'require', 'document', source + '\n;return null')
+  factory(windowStub, requireStub, docStub)
+  assert.equal(modules.length, 1, 'client.js 模块未被捕获')
+  const mod = modules[0].factory(requireStub)
+  assert.equal(typeof mod.apply, 'function', '缺 apply 即 invalid plugin 拖垮整树')
+  assert.equal(typeof mod.show, 'function')
+  assert.equal(typeof mod.dismiss, 'function')
+  assert.equal(typeof mod.mount, 'function')
+})
+
+test('宿主入口 index.js 仅空 apply 形态,不带 name/inject', () => {
+  const source = readFileSync(join(PKG_ROOT, 'src', 'index.js'), 'utf8')
+  assert.match(source, /export function apply\(\) \{\}/)
+  assert.doesNotMatch(source, /export const name/, '带 name 的命名空间形态经装载链被判 invalid plugin')
+  assert.doesNotMatch(source, /export const inject/, '带 inject 的命名空间形态经装载链被判 invalid plugin')
+})

package/test/mount.test.mjs

@@ -1,6 +1,8 @@
 // 挂载自愈测试:首次 show 惰性挂容器与样式;重复 show 幂等;外部移除与 HMR
-// 旧代残留均在下一次挂载时卸 root 重建;样式内容不一致原位替换。
+// 旧代残留均在下一次挂载时卸 root 重建;样式内容不一致原位替换、一致跳过零写入;
+// 代际退避:更新代际容器在场时旧代 mount 不拆台。
 // 加载真实 src/client.js 驱动完整 DOM 交互路径(mock.timers 冻结自动消失计时)。
+// 渲染层用记录型 createElement 产 vnode 树,断言类名/role/按钮接线。
 import test from 'node:test'
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
@@ -10,67 +12,108 @@ import { mock } from 'node:test'
 
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
 
-const reactStub = {
-  useSyncExternalStore: () => [],
-  createElement: () => null,
-}
-
 function makeState() {
-  return { byId: new Map(), bodyAppends: 0, appended: [] }
+  return { byId: new Map(), bodyAppends: 0, appended: [], headChildren: [], bodyChildren: [], warns: [], window: undefined }
 }
 
+// head/body 目的地分开记录,样式挂载位置契约可测;
+// textContent 经 setter 计数,一致跳过的零写入可断言;
+// console.warn 捕获供无归属节点清理留痕断言
 function makeDocument(state) {
   const byId = state.byId
-  return {
+  const createElement = (tag) => {
+    const node = { tag, id: '', style: {}, writes: 0, remove() { byId.delete(this.id) } }
+    Object.defineProperty(node, 'textContent', {
+      get() { return node._text || '' },
+      set(value) { node._text = value; node.writes += 1 },
+    })
+    return node
+  }
+  const doc = {
     getElementById: (id) => byId.get(id) ?? null,
-    createElement: (tag) => ({ tag, id: '', textContent: '', style: {}, remove() { byId.delete(this.id) } }),
-    head: { appendChild: (node) => byId.set(node.id, node) },
+    createElement,
+    head: { appendChild: (node) => { state.headChildren.push(node); byId.set(node.id, node) } },
     body: {
-      appendChild: (node) => { state.bodyAppends += 1; state.appended.push(node); byId.set(node.id, node) },
+      appendChild: (node) => { state.bodyAppends += 1; state.appended.push(node); state.bodyChildren.push(node); byId.set(node.id, node) },
     },
   }
+  state.doc = doc
+  return doc
+}
+
+// 渲染记录型 stub:createElement 产 vnode 树,useSyncExternalStore 取真实快照,
+// 使 ToastHost/ToastItem 产物可断言;modRef 延迟解引用加载产物
+function makeRenderReactStub(modRef) {
+  return {
+    useSyncExternalStore: () => (modRef.current !== null ? modRef.current.__test.source.getSnapshot() : []),
+    createElement: (type, props, ...children) => ({ type, props: props || null, children }),
+  }
 }
 
-function loadModule(docState) {
+function loadModule(docState, reactStub = { useSyncExternalStore: () => [], createElement: () => null }) {
   const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
   const modules = []
-  const windowStub = { __ModuleLoader__: { load: (module) => modules.push(module) } }
+  // window 跨 loadModule 复用:代际计数(window.__dshToastGen)随真实 HMR 同样递增;
+  // load 回调重绑本次数组,捕获本次加载的模块
+  if (docState.window === undefined) docState.window = { __ModuleLoader__: { load: () => {} } }
+  docState.window.__ModuleLoader__.load = (module) => modules.push(module)
   const roots = []
+  const warns = docState.warns
   const createRoot = (host) => {
-    const root = { host, renderCalls: 0, unmounted: false, render() { this.renderCalls += 1 }, unmount() { this.unmounted = true } }
+    const root = { host, renderCalls: 0, vnode: null, unmounted: false, render(vnode) { this.renderCalls += 1; this.vnode = vnode }, unmount() { this.unmounted = true } }
     roots.push(root)
     return root
   }
   const requireStub = (name) => (name === 'react-dom/client' ? { createRoot } : reactStub)
-  const factory = new Function('window', 'require', 'document', source + '\n;return null')
-  factory(windowStub, requireStub, makeDocument(docState))
+  const factory = new Function('window', 'require', 'document', 'console', source + '\n;return null')
+  const consoleStub = { warn: (message) => warns.push(message), log: () => {} }
+  factory(docState.window, requireStub, makeDocument(docState), consoleStub)
   assert.equal(modules.length, 1, 'client.js 模块未被捕获')
   const mod = modules[0].factory(requireStub)
   return { mod, roots }
 }
 
+function loadRenderModule(docState) {
+  const modRef = { current: null }
+  const result = loadModule(docState, makeRenderReactStub(modRef))
+  modRef.current = result.mod
+  return result
+}
+
 const HOST_ID = 'dsh-toast-host'
 const STYLE_ID = 'dsh-toast-style'
 
 test.beforeEach(() => { mock.timers.enable({ apis: ['setTimeout'] }) })
 test.afterEach(() => { mock.timers.reset() })
 
-test('首次 show 惰性挂载:容器与样式就位', () => {
+test('首次 show 惰性挂载:容器挂 body、样式挂 head', () => {
   const state = makeState()
   const { mod } = loadModule(state)
   assert.equal(state.byId.get(HOST_ID), undefined, '加载即挂载是错误的(应惰性)')
   mod.show('触发挂载')
   assert.notEqual(state.byId.get(HOST_ID), undefined)
-  assert.notEqual(state.byId.get(STYLE_ID), undefined)
+  assert.equal(state.headChildren.some((node) => node.id === STYLE_ID), true, '样式挂宿主文档级')
+  assert.equal(state.bodyChildren.some((node) => node.id === HOST_ID), true, '容器直挂 body')
 })
 
-test('重复 show 幂等:容器只创建一次', () => {
+test('重复 show 幂等:容器只创建一次,样式一致零写入', () => {
   const state = makeState()
   const { mod } = loadModule(state)
   mod.show('一')
+  const styleNode = state.byId.get(STYLE_ID)
+  assert.equal(styleNode.writes, 1, '创建时写入一次')
   mod.show('二')
   assert.equal(state.bodyAppends, 1, '容器只 append 一次')
-  assert.equal(state.byId.get(HOST_ID), state.appended[0])
+  assert.equal(styleNode.writes, 1, '同代内容一致跳过,零写入')
+})
+
+test('样式被外部移除后自愈:容器在场也补挂', () => {
+  const state = makeState()
+  const { mod } = loadModule(state)
+  mod.show('建立')
+  state.byId.get(STYLE_ID).remove()
+  mod.show('再触发')
+  assert.notEqual(state.byId.get(STYLE_ID), undefined, '幂等路径顺带样式自愈')
 })
 
 test('外部移除容器后重建:旧 root 卸载,新容器就位', () => {
@@ -99,16 +142,110 @@ test('HMR 跨代自愈:新代首挂卸载旧代 root 并重建容器', () => {
   assert.equal(second.roots[0].host, state.byId.get(HOST_ID), '新 root 绑定新容器')
 })
 
-test('样式内容不一致原位替换:HMR 新代 CSS 变化即生效', () => {
+test('代际退避:更新代际容器在场时,旧代 mount 不拆台且告警留痕', () => {
+  const state = makeState()
+  const first = loadModule(state)
+  first.mod.show('旧代建立')
+  const second = loadModule(state)
+  second.mod.show('新代接管')
+  const hostSecond = state.byId.get(HOST_ID)
+  const rootSecond = second.roots[0]
+  const appendsBefore = state.bodyAppends
+
+  // 旧代闭包持引用再调 show/mount:发现更新代际在场,退避不动 DOM
+  first.mod.show('旧代迟条')
+  assert.equal(state.byId.get(HOST_ID), hostSecond, '新代容器未被拆除')
+  assert.equal(rootSecond.unmounted, false, '新代 root 未被卸载')
+  assert.equal(state.bodyAppends, appendsBefore, '无重建')
+  assert.equal(state.warns.filter((message) => message.includes('已退役')).length, 1, '退役告警恰一次')
+  first.mod.show('旧代再迟')
+  assert.equal(state.warns.filter((message) => message.includes('已退役')).length, 1, '告警限频不风暴')
+
+  // 新代继续 show 正常服务
+  second.mod.show('新代续条')
+  assert.equal(state.bodyAppends, appendsBefore, '新代容器仍幂等在场')
+})
+
+test('双 stale 清理:闭包旧容器与外部同 id 节点同轮被清,无标记节点留痕', () => {
+  const state = makeState()
+  const { mod, roots } = loadModule(state)
+  mod.show('建立')
+  const closureHost = state.byId.get(HOST_ID)
+  assert.equal(roots.length, 1)
+
+  // 外部无标记同 id 节点顶替在位容器:闭包 host 与陌生节点同时非空
+  const alien = state.doc.createElement('div')
+  alien.id = HOST_ID
+  state.byId.set(HOST_ID, alien)
+  mod.show('触发双清')
+
+  assert.equal(roots[0].unmounted, true, '闭包容器 root 卸载')
+  assert.notEqual(state.byId.get(HOST_ID), alien, '陌生节点被清走')
+  assert.notEqual(state.byId.get(HOST_ID), closureHost, '闭包容器被移除重建')
+  assert.equal(state.warns.filter((message) => message.includes('无归属标记')).length, 1, '陌生节点清理留痕一次')
+})
+
+test('mount 直调:空 store 显式挂载,连调幂等', () => {
+  const state = makeState()
+  const { mod } = loadModule(state)
+  mod.mount()
+  mod.mount()
+  assert.equal(state.bodyAppends, 1, '直调幂等')
+  assert.notEqual(state.byId.get(HOST_ID), undefined)
+  assert.notEqual(state.byId.get(STYLE_ID), undefined)
+})
+
+test('渲染产物:栈容器类名、变体类、role 与 sticky 按钮接线', () => {
+  const state = makeState()
+  const { mod, roots } = loadRenderModule(state)
+  mod.show('普通', { kind: 'ok' })
+  const stickyId = mod.show('常驻', { kind: 'error', sticky: true })
+
+  const root = roots[roots.length - 1]
+  assert.equal(typeof root.vnode.type, 'function', 'render 收到 ToastHost 元素')
+  const tree = root.vnode.type()
+  assert.equal(tree.type, 'div')
+  assert.equal(tree.props.className, 'dsh-toast-stack')
+
+  const items = tree.children.flat()
+  const okItem = items.find((vnode) => vnode.props.item.text === '普通')
+  const okTree = okItem.type(okItem.props)
+  assert.equal(okTree.props.className, 'dsh-toast dsh-toast--ok')
+  assert.equal(okTree.props.role, 'alert')
+  assert.equal(okTree.children[1], null, '非 sticky 无按钮')
+
+  const stickyItem = items.find((vnode) => vnode.props.item.text === '常驻')
+  const stickyTree = stickyItem.type(stickyItem.props)
+  assert.equal(stickyTree.props.className, 'dsh-toast dsh-toast--error')
+  const button = stickyTree.children[1]
+  assert.equal(button.type, 'button')
+  assert.equal(button.props.className, 'dsh-toast__close')
+  button.props.onClick()
+  assert.equal(mod.__test.getItems().some((item) => item.id === stickyId), false, '按钮接线 dismiss 生效')
+})
+
+test('样式内容不一致原位替换:节点不重建,内容与写入计数还原', () => {
   const state = makeState()
   const { mod } = loadModule(state)
   mod.show('建立样式')
   const styleNode = state.byId.get(STYLE_ID)
   const currentCss = styleNode.textContent
-  // 模拟旧代残留:DOM 中样式内容与本代 CSS 不一致(HMR 改了 CSS 数组)
-  styleNode.textContent = '/* 残留的旧代样式 */'
-  const second = loadModule(state)
-  second.mod.show('触发重建路径')
+  assert.equal(styleNode.writes, 1)
+  // 模拟 HMR 期间 CSS 变更或旧代残留:在位样式内容与本代不一致
+  // (直写 _text 绕过写入计数,只统计实现侧的写入)
+  styleNode._text = '/* 残留的旧代样式 */'
+  mod.show('触发替换')
   assert.equal(state.byId.get(STYLE_ID), styleNode, '样式节点原位保留')
-  assert.equal(styleNode.textContent, currentCss, '内容恢复为当前 CSS')
+  assert.equal(styleNode.writes, 2, '替换恰新增一次写入')
+  assert.equal(styleNode.textContent, currentCss, '内容还原为当前 CSS')
+})
+
+test('CSS 内容齐备:选择器、变体、动画与减弱动态块', () => {
+  const state = makeState()
+  const { mod } = loadModule(state)
+  mod.show('建立样式')
+  const css = state.byId.get(STYLE_ID).textContent
+  for (const needle of ['.dsh-toast-stack', '.dsh-toast {', '.dsh-toast--ok', '.dsh-toast--error', '.dsh-toast__close', '@keyframes dsh-toast-in', 'animation:dsh-toast-in', 'prefers-reduced-motion']) {
+    assert.ok(css.includes(needle), 'CSS 缺少 ' + needle)
+  }
 })

package/test/toast.test.mjs

@@ -128,3 +128,72 @@ test('subscribe:入栈与移除均通知订阅者', () => {
   mod.__test.show('不再通知')
   assert.equal(calls, 2)
 })
+
+test('holdMs 边界:非有限正值一律回落默认', () => {
+  const mod = loadModule()
+  assert.equal(mod.__test.resolveHoldMs({ holdMs: 0 }), 4 * 1000)
+  assert.equal(mod.__test.resolveHoldMs({ holdMs: '500' }), 4 * 1000)
+  assert.equal(mod.__test.resolveHoldMs({ holdMs: Number.NaN }), 4 * 1000)
+  // Infinity 经浏览器 WebIDL 钳为约 24.8 天近乎永久驻留,与展示期意图相反,必须回落
+  assert.equal(mod.__test.resolveHoldMs({ holdMs: Number.POSITIVE_INFINITY }), 4 * 1000)
+  assert.equal(mod.__test.resolveHoldMs({ holdMs: 2 ** 31 }), 4 * 1000, '超 setTimeout 钳位上界回落')
+})
+
+test('默认展示期:独立字面量断言 4 秒', () => {
+  const mod = loadModule()
+  mod.__test.show('默认')
+  mock.timers.tick(4 * 1000 - 1)
+  assert.equal(mod.__test.getItems().length, 1, '展示期内未消失')
+  mock.timers.tick(1)
+  assert.equal(mod.__test.getItems().length, 0, '展示期满消失')
+})
+
+test('kind: error 合法直通', () => {
+  const mod = loadModule()
+  mod.__test.show('错误', { kind: 'error' })
+  assert.equal(mod.__test.getItems()[0].kind, 'error')
+})
+
+test('纯空白 text 拒绝,非空白正常入栈', () => {
+  const mod = loadModule()
+  assert.equal(mod.__test.show('   '), null)
+  assert.equal(mod.__test.show('\t\n'), null)
+  assert.equal(mod.__test.getItems().length, 0)
+  const id = mod.__test.show(' 带前后空格的内容 ')
+  assert.notEqual(id, null, '含非空白字符的文本照常入栈')
+})
+
+test('sticky 被裁剪:栈满后新条目仍挤掉最旧 sticky', () => {
+  const mod = loadModule()
+  for (let index = 1; index <= 4; index += 1) mod.__test.show('常驻' + index, { sticky: true })
+  mod.__test.show('新条目')
+  const items = mod.__test.getItems()
+  assert.equal(items.length, 4)
+  assert.equal(items[0].text, '常驻2', '最旧 sticky 被裁剪')
+  assert.equal(items[items.length - 1].text, '新条目')
+})
+
+test('被裁条目计时同步撤销:条目引用上的 timer 句柄清空', () => {
+  const mod = loadModule()
+  mod.__test.show('将被裁剪')
+  // getItems 为浅拷贝,entry 对象同引用,可直接断言 timer 字段
+  const dropped = mod.__test.getItems()[0]
+  assert.notEqual(dropped.timer, undefined, '入栈即挂计时')
+  for (let index = 1; index <= 4; index += 1) mod.__test.show('常驻' + index, { sticky: true })
+  assert.equal(dropped.timer, undefined, '裁剪路径撤销计时')
+  const snapshot = mod.__test.source.getSnapshot()
+  mock.timers.tick(4 * 1000)
+  assert.equal(mod.__test.source.getSnapshot(), snapshot, '无滞留计时副作用')
+})
+
+test('dismiss 撤销自动消失计时:句柄清空,移除后再推进无滞留副作用', () => {
+  const mod = loadModule()
+  const id = mod.__test.show('手动移除')
+  const entry = mod.__test.getItems()[0]
+  assert.notEqual(entry.timer, undefined, '入栈即挂计时')
+  mod.__test.dismiss(id)
+  assert.equal(entry.timer, undefined, 'dismiss 路径撤销计时')
+  mock.timers.tick(4 * 1000)
+  assert.equal(mod.__test.getItems().length, 0)
+  assert.equal(mod.__test.source.getSnapshot().length, 0)
+})