@mzzsfy/dsh-toast 0.2.1 → 0.2.3

package/MECHANISM.md

@@ -1,6 +1,6 @@
 # dsh-toast 装载机制原理
 
-本文记录公共 client 依赖包(dsh-toast 为参考实现)不进 profile 表层 manifest 却能被安装、解析、装载的完整原理。规约条目见 AGENTS.md「公共 client 依赖包规约」与「profile 链接」第 4 条;本文是其推导与实证依据。
+本文记录公共 client 依赖包(dsh-toast 为参考实现)不进 profile 表层 manifest 却能被安装、解析、装载的完整原理。规约条目见 `DEVELOPMENT/client-dependency.md` 与 `DEVELOPMENT/profile-link.md` 第 4 条;本文是其推导与实证依据。
 
 ## 问题:市场为什么曾显示它
 

package/README.md

@@ -63,3 +63,7 @@ toast('回合完成', { holdMs: 6 * 1000 })            // 自定义展示期
 - 样式全部取宿主 `--dsw-*` 令牌且带就近 fallback(宿主升级更名令牌时降级为可用默认形态,不静默失效);样式挂宿主文档级、幂等且内容变化原位替换,容器在场时随每次挂载自愈
 - store 位于模块闭包单例;渲染容器惰性自举、幂等、自愈(旧 root 卸载后重建),容器带代际标记防 HMR 两代互拆;不依赖宿主生命周期
 - react / react-dom/client 由宿主平台模块表提供,peerDependencies 声明 react 与 react-dom
+
+## dsh 版本兼容
+
+公共依赖包,由消费方(dsh-cron-board 等)代挂装载,三版本装载层均正常,无独立激活单元。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-toast",
   "description": "全局浮出通知 Toast 库:多条并存栈式展示,自动消失与常驻确认两种生命周期;普通 npm 依赖(非 dsh 插件),由消费插件的 cordis.patch.yml 代挂宿主占位条目",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -120,15 +120,19 @@ window.__ModuleLoader__.load({
 
     // ---- 渲染:容器直挂 body,不依赖宿主生命周期 ----
 
-    // 样式内容原位比对:一致跳过,不一致(HMR 新代 CSS 变化)原位替换
+    // 样式内容原位比对:一致跳过,不一致(HMR 新代 CSS 变化)原位替换;
+    // 在位节点无论新旧一律幂等补 data-plugin,防历史代残留缺标记被宿主 claimStyles 误归属
     function ensureStyle() {
       const stale = document.getElementById(STYLE_ID)
       if (stale !== null) {
         if (stale.textContent !== CSS) stale.textContent = CSS
+        stale.setAttribute('data-plugin', '@mzzsfy/dsh-toast')
         return
       }
       const style = document.createElement('style')
       style.id = STYLE_ID
+      // 自带 data-plugin:缺失时宿主 claimStyles 会把它归属给后续材质化插件,其 HMR 重建即误删
+      style.setAttribute('data-plugin', '@mzzsfy/dsh-toast')
       style.textContent = CSS
       document.head.appendChild(style)
     }

package/test/manifest-form.test.mjs

@@ -0,0 +1,51 @@
+// 公共依赖包形态守卫:本包不声明 dsh.bundle.patch、不自带 cordis.patch.yml、
+// 不进 profile 表层 manifest 依赖行与装载层。表层 dependencies 行是插件市场
+// 「已安装」列表的唯一数据源(全量展示,仅过滤官方内盒),本包一旦被显式
+// add 写入表层行,市场即把它当插件展示——该现象曾出现并已修复(表层数行
+// 由 dev-link 对公共依赖包一律删除),此测试把约束固化为机器断言防回归。
+// 规约见 DEVELOPMENT/client-dependency.md 与 DEVELOPMENT/profile-link.md 第 4 条,
+// 机制推导见本包 MECHANISM.md。
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { existsSync, readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const PKG_NAME = '@mzzsfy/dsh-toast'
+// profile 路径与 scripts/dev-link.mjs 同构;不存在(如 CI)时终态用例跳过
+const PROFILE_MANIFEST = join(homedir(), '.dsh', 'profiles', 'web', 'package.json')
+
+test('package.json 不声明 dsh.bundle.patch,维持公共依赖包身份', () => {
+  const manifest = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'))
+  assert.equal(
+    manifest.dsh?.bundle?.patch, undefined,
+    '声明 dsh.bundle.patch 即成为插件包:官方 reconcile 会将其入 dsh.profile.bundles,dev-link 也失去删表层行的依据',
+  )
+})
+
+test('不自带 cordis.patch.yml,装载靠消费方代挂占位', () => {
+  assert.equal(
+    existsSync(join(PKG_ROOT, 'cordis.patch.yml')), false,
+    '公共依赖包禁止自带 patch;client 进入模块表由消费插件 cordis.patch.yml 代挂占位条目承载',
+  )
+})
+
+test('profile 表层 dependencies 无本包行,市场已装列表不可见', (t) => {
+  if (!existsSync(PROFILE_MANIFEST)) return t.skip('本机无 profile,终态由 dev-link 维护')
+  const manifest = JSON.parse(readFileSync(PROFILE_MANIFEST, 'utf8').replace(/^\uFEFF/, ''))
+  assert.equal(
+    manifest.dependencies?.[PKG_NAME], undefined,
+    '表层依赖行存在即市场已装列表展示本包;安装由消费方 dependencies 声明承载,表层行一律删除',
+  )
+})
+
+test('profile dsh.profile.bundles 无本包,不进宿主装载层', (t) => {
+  if (!existsSync(PROFILE_MANIFEST)) return t.skip('本机无 profile,终态由 dev-link 维护')
+  const manifest = JSON.parse(readFileSync(PROFILE_MANIFEST, 'utf8').replace(/^\uFEFF/, ''))
+  assert.equal(
+    manifest.dsh?.profile?.bundles?.includes(PKG_NAME), false,
+    '公共依赖包无宿主半区可载,入装载层即「装而不载」的伪插件形态',
+  )
+})

package/test/mount.test.mjs

@@ -22,7 +22,7 @@ function makeState() {
 function makeDocument(state) {
   const byId = state.byId
   const createElement = (tag) => {
-    const node = { tag, id: '', style: {}, writes: 0, remove() { byId.delete(this.id) } }
+    const node = { tag, id: '', style: {}, writes: 0, attrs: {}, setAttribute(name, value) { this.attrs[name] = value }, remove() { byId.delete(this.id) } }
     Object.defineProperty(node, 'textContent', {
       get() { return node._text || '' },
       set(value) { node._text = value; node.writes += 1 },
@@ -94,6 +94,8 @@ test('首次 show 惰性挂载:容器挂 body、样式挂 head', () => {
   assert.notEqual(state.byId.get(HOST_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')
+  const styleNode = state.headChildren.find((node) => node.id === STYLE_ID)
+  assert.equal(styleNode.attrs['data-plugin'], '@mzzsfy/dsh-toast', '样式自带 data-plugin,防宿主 claimStyles 误归属后随他插件 HMR 整批误删')
 })
 
 test('重复 show 幂等:容器只创建一次,样式一致零写入', () => {
@@ -260,10 +262,13 @@ test('样式内容不一致原位替换:节点不重建,内容与写入计数还
   // 模拟 HMR 期间 CSS 变更或旧代残留:在位样式内容与本代不一致
   // (直写 _text 绕过写入计数,只统计实现侧的写入)
   styleNode._text = '/* 残留的旧代样式 */'
+  // 模拟修复前旧代注入的无标记残留:原位替换须幂等补标记
+  delete styleNode.attrs['data-plugin']
   mod.show('触发替换')
   assert.equal(state.byId.get(STYLE_ID), styleNode, '样式节点原位保留')
   assert.equal(styleNode.writes, 2, '替换恰新增一次写入')
   assert.equal(styleNode.textContent, currentCss, '内容还原为当前 CSS')
+  assert.equal(styleNode.attrs['data-plugin'], '@mzzsfy/dsh-toast', '原位替换路径幂等补 data-plugin')
 })
 
 test('CSS 内容齐备:选择器、变体、动画与减弱动态块', () => {