@mzzsfy/dsh-context-manager 0.1.0

package/test/client-fork-family.test.mjs

@@ -0,0 +1,48 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const CLIENT_SRC = readFileSync(fileURLToPath(new URL('../src/client.js', import.meta.url)), 'utf8')
+
+// F1 家族版本环 的客户端契约(源码切片锁定):
+// - 数据源是 sessions.list 快照行(parentSessionId),零新 RPC
+// - 单成员家族/快照缺失不注入
+// - 箭头跳转经 sessions.open(纯打开,不 fork)
+// - 计数器防重复注入,停用 fork 时随 removeAll 一并清除
+
+test('源码契约:家族环数据源为 sessions.list 快照(零新 RPC)', () => {
+  assert.ok(CLIENT_SRC.includes('sessions.list.getSnapshot()'), '家族投影应读会话列表快照')
+  assert.ok(CLIENT_SRC.includes('parent.parentId'), '投影应按快照行 parentId 建链(快照字段名与 wire 不同)')
+})
+
+test('源码契约:快照行主键为 id(与服务 wire 字段名不同源)', () => {
+  const slice = CLIENT_SRC.slice(CLIENT_SRC.indexOf('function sessionFamilyMap'), CLIENT_SRC.indexOf('function familyRing'))
+  assert.ok(slice.includes('item.id'), '快照行主键应取 id')
+})
+
+test('源码契约:编排派生会话(subagent)剔除出家族投影', () => {
+  const slice = CLIENT_SRC.slice(CLIENT_SRC.indexOf('function sessionFamilyMap'), CLIENT_SRC.indexOf('function familyRing'))
+  assert.ok(slice.includes("item.origin === 'subagent'"), 'subagent 会话不是用户的 fork 版本,应整行剔除')
+})
+
+test('源码契约:单成员家族与快照缺失不注入计数器', () => {
+  const slice = CLIENT_SRC.slice(CLIENT_SRC.indexOf('// 家族版本环'), CLIENT_SRC.indexOf('function jumpFamilyMember'))
+  assert.ok(slice.includes('ring && ring.total >= 2'), '成员不足 2 不注入')
+  assert.ok(slice.includes('actionsRow.querySelector'), '注入前应查重')
+})
+
+test('源码契约:箭头跳转经 sessions.open 且不 fork', () => {
+  const jump = CLIENT_SRC.slice(CLIENT_SRC.indexOf('function jumpFamilyMember'), CLIENT_SRC.indexOf('if (typeof MutationObserver'))
+  assert.ok(jump.includes('openFn(target)'), '跳转应调用 open 通道')
+  assert.ok(jump.includes('target !== current.sessionId'), '目标为自身时不切换')
+})
+
+test('源码契约:家族环标记与清除齐备(停用开关一并移除)', () => {
+  assert.ok(CLIENT_SRC.includes("const FAMILY_RING_FLAG = 'data-cx-family-ring'"), '应有家族环标记常量')
+  assert.ok(CLIENT_SRC.includes("querySelectorAll('[' + FORK_BTN_FLAG + ']')"), '清除逻辑存在(环与按钮同排,按钮清除即整排消失)')
+})
+
+test('源码契约:loadFamily 通道旧宿主降级返回 null', () => {
+  assert.ok(CLIENT_SRC.includes('typeof sessions.list.getSnapshot'), '快照面应以能力探测守门')
+})

package/test/client-fork.test.mjs

@@ -0,0 +1,251 @@
+// 对话 fork 接线测试:加载真实 src/client.js,断言 dock 注册条件、锚点映射构建、
+// 注入契约与 fork 服务组装。锚点通道:remote.session.follow 开场帧(自带回溯窗口
+// 内的事件与 seq)建立轮号→{ 结束 seq, 首问文本 } 映射;namespace 就绪由点分
+// inject 门控。
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const CLIENT_SRC = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+
+// follow 开场帧桩:async-iterable,首个 snapshot 帧后即挂起(break 触发 return,
+// 桩记录退订以证明「取到开场即断开」)
+function followStub(records) {
+  const state = { returned: false }
+  const frames = (async function* generate() {
+    try {
+      yield { type: 'snapshot', cursor: 99, records }
+      await new Promise(() => {})
+    } finally {
+      state.returned = true
+    }
+  })()
+  return { frames, state }
+}
+
+function loadClient({ sessions, remoteSession } = {}) {
+  const modules = []
+  const registered = []
+  const windowStub = { __ModuleLoader__: { load: (module) => modules.push(module) }, addEventListener: () => {} }
+  const reactStub = {
+    useState: (value) => [value, () => {}],
+    useEffect: () => {},
+    useRef: (value) => ({ current: value }),
+    createElement: () => null,
+  }
+  const requireStub = (name) => {
+    if (name === '@mzzsfy/dsh-toast/client') return { show: () => 0 }
+    return reactStub
+  }
+  const factory = new Function('window', 'require', 'document', CLIENT_SRC + '\n;return null')
+  factory(
+    windowStub,
+    requireStub,
+    { createElement: () => ({ style: {}, remove() {} }), head: { appendChild: () => {} }, body: { appendChild: () => {} } },
+  )
+  const mod = modules[0].factory(requireStub)
+  const sessionsStub = sessions || { binding: () => undefined, fork: () => Promise.resolve('child-1'), open: () => {} }
+  const ctx = {
+    get: (name) => (name === 'sessions' ? sessionsStub : {}),
+    effect: () => {},
+    slots: {
+      inject: (name, register) => register(),
+      register: (options, component) => registered.push({ options, component }),
+    },
+    remote: { session: remoteSession },
+  }
+  mod.apply(ctx)
+  return { registered }
+}
+
+function findForkEntry({ sessions, remoteSession } = {}) {
+  const { registered } = loadClient({ sessions, remoteSession })
+  const entries = registered.filter((item) => item.options.name === 'conversation.input.dock')
+  const entry = entries.find((item) => item.options.id === 'context-manager-fork')
+  return { entry, entries }
+}
+
+const EMPTY_FOLLOW = { follow: () => followStub([]).frames }
+
+test('inject 点分声明 remote.namespace(规约:禁止 apply 内同步探测 remote 面)', () => {
+  const declared = CLIENT_SRC.match(/inject: \[([^\]]*)\]/)
+  assert.ok(declared, 'client.js 缺 inject 声明')
+  const names = declared[1].split(',').map((item) => item.trim().replace(/'/g, '')).filter(Boolean)
+  assert.ok(names.includes('remote'), 'inject 必须声明 remote')
+  assert.ok(names.includes('remote.session'), 'inject 必须点分声明 remote.session(cordis 门控 namespace 就绪)')
+})
+
+test('Given sessions 服务与 remote.session.follow 齐备, When apply, Then 注册 fork dock 条目', () => {
+  const { entry } = findForkEntry({ remoteSession: EMPTY_FOLLOW })
+  assert.ok(entry, 'fork dock 条目未注册')
+  assert.equal(entry.options.order, 24, 'fork 条目应排在官方队列(20)/撤回(25)邻近位')
+  assert.equal(typeof entry.component, 'function', 'fork dock 条目缺组件')
+})
+
+test('Given sessions 服务缺 fork/open(旧宿主), When apply, Then fork 条目不注册且其余保留', () => {
+  const { entry, entries } = findForkEntry({
+    sessions: { binding: () => undefined },
+    remoteSession: EMPTY_FOLLOW,
+  })
+  assert.equal(entry, undefined, 'sessions 无 fork 时 fork 条目不应注册')
+  assert.ok(entries.some((item) => item.options.id === 'context-manager-steer'), '撤回条目不应被 fork 门控阻塞')
+  assert.ok(entries.some((item) => item.options.id === 'context-manager-history'), '历史条目不应被 fork 门控阻塞')
+})
+
+test('Given dock inject, Then 返回 forkSession(loadTurnEnds 通道)且按会话寻址', async () => {
+  const forkCalls = []
+  const openCalls = []
+  const { entry } = findForkEntry({
+    sessions: { binding: () => undefined, fork: (opts) => { forkCalls.push(opts); return Promise.resolve('child-9') }, open: (id) => { openCalls.push(id) } },
+    remoteSession: EMPTY_FOLLOW,
+  })
+  const props = entry.options.inject('s1')
+  assert.equal(typeof props.forkSession, 'function', 'inject 未返回 forkSession')
+  assert.equal(typeof props.loadTurnEnds, 'function', 'inject 未返回 loadTurnEnds')
+  const childId = await props.forkSession({ sessionId: 's1', atSeq: 7, increaseTitle: true })
+  assert.deepEqual(forkCalls, [{ sessionId: 's1', atSeq: 7, increaseTitle: true }])
+  assert.deepEqual(openCalls, ['child-9'], 'fork 成功后应 open 子会话')
+  assert.equal(childId, 'child-9', 'forkSession 应解析出子会话 id')
+})
+
+test('Given open 失败, When forkSession, Then 分叉成功事实不被推翻(childId 照常解析)', async () => {
+  const forkCalls = []
+  const { entry } = findForkEntry({
+    sessions: {
+      binding: () => undefined,
+      fork: (opts) => { forkCalls.push(opts); return Promise.resolve('child-7') },
+      open: () => Promise.reject(new Error('open down')),
+    },
+    remoteSession: EMPTY_FOLLOW,
+  })
+  const props = entry.options.inject('s1')
+  const childId = await props.forkSession({ sessionId: 's1', atSeq: 3 })
+  assert.equal(childId, 'child-7', 'open 失败不得把已成功的分叉上报为失败')
+})
+
+test('Given loadTurnEnds, Then 轮映射按 data.turn 登记结束 seq 与该轮首条用户文本,缺失按序计数', async () => {
+  const records = [
+    { event: { type: 'user/message', seq: 1, data: {} } },
+    { event: { type: 'turn/start', seq: 2, data: { turn: 0 } } },
+    { event: { type: 'user/message', seq: 3, data: { source: { kind: 'user' }, content: [{ type: 'text', text: '第一问' }] } } },
+    { event: { type: 'turn/end', seq: 4, data: { turn: 0 } } },
+    { event: { type: 'assistant/message', seq: 5, data: {} } },
+    { event: { type: 'turn/start', seq: 6, data: { turn: 1 } } },
+    { event: { type: 'user/message', seq: 7, data: { source: { kind: 'user' }, content: [{ type: 'text', text: '第二问' }] } } },
+    { event: { type: 'turn/end', seq: 9, data: {} } },
+    { event: { type: 'turn/end', seq: 20, data: { turn: 5 } } },
+  ]
+  const follow = followStub(records)
+  const { entry } = findForkEntry({ remoteSession: { follow: () => follow.frames } })
+  const props = entry.options.inject('s1')
+  const map = await props.loadTurnEnds()
+  assert.ok(map instanceof Map)
+  assert.deepEqual(map.get(0), { seq: 4, text: '第一问', open: false })
+  assert.deepEqual(map.get(1), { seq: 9, text: '第二问', open: false }, 'data 无 turn 号按出现顺序计数')
+  assert.deepEqual(map.get(5), { seq: 20, text: null, open: false }, '无用户文本的轮 text 为 null')
+  assert.equal(map.size, 3)
+})
+
+test('Given 轮内插话(user 消息后又有 user 消息), When loadTurnEnds, Then 取本轮首条', async () => {
+  const records = [
+    { event: { type: 'turn/start', seq: 1, data: { turn: 0 } } },
+    { event: { type: 'user/message', seq: 2, data: { source: { kind: 'user' }, content: [{ type: 'text', text: '首问' }] } } },
+    { event: { type: 'user/message', seq: 3, data: { source: { kind: 'user' }, content: [{ type: 'text', text: '插话' }] } } },
+    { event: { type: 'turn/end', seq: 4, data: { turn: 0 } } },
+  ]
+  const { entry } = findForkEntry({ remoteSession: { follow: () => followStub(records).frames } })
+  const map = await entry.options.inject('s1').loadTurnEnds()
+  assert.equal(map.get(0).text, '首问')
+})
+
+test('Given 开场帧取得, When loadTurnEnds 完成, Then follow 流已断开(不消费 live 帧)', async () => {
+  const follow = followStub([{ event: { type: 'turn/end', seq: 2, data: { turn: 0 } } }])
+  const { entry } = findForkEntry({ remoteSession: { follow: () => follow.frames } })
+  const props = entry.options.inject('s1')
+  const map = await props.loadTurnEnds()
+  assert.equal(map.get(0).seq, 2)
+  // 退订经微任务链收敛:loadTurnEnds 解析时 for-await break 已触发 iterator.return
+  await new Promise((resolve) => setTimeout(resolve, 0))
+  assert.ok(follow.state.returned, '取到开场帧后应断开 follow 流')
+})
+
+test('Given follow 失败, When loadTurnEnds, Then 异常向上传播(组件侧降级不注入)', async () => {
+  const { entry } = findForkEntry({ remoteSession: { follow: () => { throw new Error('gateway down') } } })
+  const props = entry.options.inject('s1')
+  await assert.rejects(props.loadTurnEnds(), /gateway down/)
+})
+
+// 注入契约(源码级守卫):锚点属性/按钮标记/官方类名克隆/清理/点分门控必须存在
+test('ForkDock 注入契约:轮号锚点属性、按钮标记、防重标记与卸载清理齐备', () => {
+  assert.ok(CLIENT_SRC.includes("TURN_ATTR = 'data-chat-turn'"), 'fork 锚点必须使用官方轮号标记')
+  assert.ok(CLIENT_SRC.includes('data-cx-fork'), '应有自家按钮标记防重复注入')
+  assert.ok(CLIENT_SRC.includes("querySelectorAll('[' + TURN_ATTR + ']')"), '应按轮号标记扫描消息气泡')
+  assert.ok(CLIENT_SRC.includes("FLOW_KIND_ATTR = 'data-chat-flow-kind'"), '应识别官方气泡语义类型标记')
+  assert.ok(CLIENT_SRC.includes("getAttribute(FLOW_KIND_ATTR) !== 'user'"), '只注入用户输入气泡(官方分支按钮驻留轮尾,语义互补不重叠)')
+  assert.ok(CLIENT_SRC.includes('increaseTitle: true'), 'fork 请求应递增子会话标题')
+  assert.ok(CLIENT_SRC.includes('observer.disconnect()'), '卸载应断开观察')
+  assert.ok(CLIENT_SRC.includes("remote.follow({ address: { kind: 'session', sessionId }"), '锚点必须按会话寻址 follow 开场帧')
+  assert.ok(CLIENT_SRC.includes("frame.type === 'snapshot'"), '映射构建必须取自 follow 开场帧')
+  // 图标与官方同源:fill 细路径单 path 形态(官方 IconBranchOutline16)
+  const forkSvgSlice = CLIENT_SRC.slice(CLIENT_SRC.indexOf('function forkSvg('), CLIENT_SRC.indexOf('// 注入按钮标记'))
+  assert.ok(forkSvgSlice.includes("path.setAttribute('fill-rule', 'evenodd')"), 'fork 图标应为官方 fill 细路径形态')
+  assert.ok(forkSvgSlice.includes("svg.setAttribute('stroke'") === false, 'fork 图标不应是自绘描边形态')
+})
+
+// 重试语义:分叉到该轮之前(锚点 = 前一轮 turn/end seq),该轮用户输入回填子会话输入框
+test('ForkDock 重试契约:锚点前移取前一轮、pending 草稿通道、子会话挂载回填齐备', () => {
+  assert.ok(CLIENT_SRC.includes("boundary.seq + 1") === false, '不应复刻宿主实现细节')
+  assert.ok(CLIENT_SRC.includes('atSeq: previousEntry.seq'), 'fork 请求锚点必须是前一轮(重试该轮本身不带入)')
+  assert.ok(CLIENT_SRC.includes('pendingForkDrafts.set(childId, { text: currentEntry.text, autoSubmit: autoResendOn })'), 'fork resolve 后必须按子会话 id 登记该轮首问(autoSubmit 跟随开关)')
+  assert.ok(CLIENT_SRC.includes('pendingForkDrafts.get(sessionId)'), '子会话挂载应按会话 id 消费草稿')
+  assert.ok(CLIENT_SRC.includes('pendingForkDrafts.delete(sessionId)'), '草稿消费后应清除')
+  assert.ok(CLIENT_SRC.includes('inputActions.setDraft(text)'), '回填必须经宿主 inputActions.setDraft')
+  assert.ok(CLIENT_SRC.includes('forkRetryText'), '文本提取必须与 core 镜像同源')
+})
+
+test('Given fork 成功, When 点击重试, Then 请求锚点为前一轮 seq 且草稿登记到子会话', async () => {
+  const forkCalls = []
+  const setDraftCalls = []
+  const records = [
+    { event: { type: 'turn/start', seq: 1, data: { turn: 0 } } },
+    { event: { type: 'user/message', seq: 2, data: { source: { kind: 'user' }, content: [{ type: 'text', text: '第一问' }] } } },
+    { event: { type: 'turn/end', seq: 3, data: { turn: 0 } } },
+    { event: { type: 'turn/start', seq: 4, data: { turn: 1 } } },
+    { event: { type: 'user/message', seq: 5, data: { source: { kind: 'user' }, content: [{ type: 'text', text: '第二问' }] } } },
+    { event: { type: 'turn/end', seq: 6, data: { turn: 1 } } },
+  ]
+  const { entry } = findForkEntry({
+    sessions: { binding: () => undefined, fork: (opts) => { forkCalls.push(opts); return Promise.resolve('child-1') }, open: () => {} },
+    remoteSession: { follow: () => followStub(records).frames },
+  })
+  const props = entry.options.inject('s1')
+  const map = await props.loadTurnEnds()
+  // 锚点前移:重试轮 1 → boundary 取轮 0 的 turn/end seq(不含轮 1)
+  assert.equal(map.get(1).seq, 6, '轮 1 结束 seq')
+  assert.equal(map.get(0).seq, 3, '前一轮(轮 0)结束 seq——重试轮 1 的 fork 锚点')
+  assert.equal(map.get(1).text, '第二问', '重试文本取本轮首问')
+})
+
+test('Given fork 失败(未知 code), When 点击重试, Then toast 透传映射文案且不登记草稿', async () => {
+  const toasts = []
+  const forkCalls = []
+  const records = [
+    { event: { type: 'turn/start', seq: 1, data: { turn: 0 } } },
+    { event: { type: 'user/message', seq: 2, data: { source: { kind: 'user' }, content: [{ type: 'text', text: '第一问' }] } } },
+    { event: { type: 'turn/end', seq: 3, data: { turn: 0 } } },
+  ]
+  const { entry } = findForkEntry({
+    sessions: {
+      binding: () => undefined,
+      fork: (opts) => { forkCalls.push(opts); return Promise.reject({ code: 'gateway/internal', message: 'gateway/internal: boom' }) },
+      open: () => {},
+    },
+    remoteSession: { follow: () => followStub(records).frames },
+  })
+  const props = entry.options.inject('s1')
+  await props.loadTurnEnds()
+  assert.ok(forkCalls.length === 0, '未点击不得发起 fork')
+})

package/test/client-help.test.mjs

@@ -0,0 +1,58 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const CLIENT_SRC = readFileSync(fileURLToPath(new URL('../src/client.js', import.meta.url)), 'utf8')
+
+// 设置项悬停说明契约:说明常量必须存在且逐项挂到对应开关(开关行工厂调用位)。
+// 断言以工厂调用为锚:行文本与说明常量必须出现在同一 switchRow(...) 调用内,
+// 防常量互换挂载或挂错行仍通过
+test('源码契约:三项设置的悬停说明齐备且挂到对应控件', () => {
+  const TITLES = {
+    HISTORY_SWITCH_TITLE: '历史输入浮层开关',
+    STEER_SWITCH_TITLE: '插话撤回开关',
+    FORK_SWITCH_TITLE: '对话 fork 开关',
+    FORK_AUTO_RESEND_SWITCH_TITLE: '分叉后自动重发开关',
+  }
+  for (const [name, label] of Object.entries(TITLES)) {
+    assert.ok(CLIENT_SRC.includes('const ' + name + ' ='), '缺悬停说明常量 ' + name)
+  }
+  const rowAnchors = [
+    { constant: 'HISTORY_SWITCH_TITLE', text: "'历史输入浮层(Alt+↑)'", label: TITLES.HISTORY_SWITCH_TITLE },
+    { constant: 'STEER_SWITCH_TITLE', text: "'插话撤回'", label: TITLES.STEER_SWITCH_TITLE },
+    { constant: 'FORK_SWITCH_TITLE', text: "'对话 fork'", label: TITLES.FORK_SWITCH_TITLE },
+    { constant: 'FORK_AUTO_RESEND_SWITCH_TITLE', text: "'分叉后自动重发'", label: TITLES.FORK_AUTO_RESEND_SWITCH_TITLE },
+  ]
+  for (const { constant, text, label } of rowAnchors) {
+    // 限定长度的跨行窗口而非单行 [^\n]*:合法的多行格式化(prettier)不误报,
+    // 常量与行文本漂移出同一调用(>200 字符)仍会被检出
+    const escaped = text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const mounted = new RegExp('switchRow\\([\\s\\S]{0,200}' + escaped + '[\\s\\S]{0,200}' + constant).test(CLIENT_SRC)
+    assert.ok(mounted, label + ' 未挂对应悬停说明(常量与行文本不在同一工厂调用内)')
+  }
+})
+
+// 说明文案与行为同源的抽样锁定:核心语义缺失即为文案回归
+test('源码契约:悬停说明覆盖各设置的关键行为语义', () => {
+  assert.ok(CLIENT_SRC.includes('←/→ 切换范围'), '历史说明缺范围切换语义')
+  assert.ok(CLIENT_SRC.includes('刷新页面生效'), '开关说明缺刷新生效提示')
+  assert.ok(CLIENT_SRC.includes('含附件的插话不可撤回'), '撤回说明缺附件限制')
+  assert.ok(CLIENT_SRC.includes('进行中的轮(回复尚未完成)'), 'fork 说明缺进行中轮可分叉语义')
+  assert.ok(CLIENT_SRC.includes('停止本会话该轮未完成的回复'), 'fork 说明缺进行中轮分叉后止损语义')
+  assert.ok(CLIENT_SRC.includes('无文本输入的轮'), 'fork 说明缺纯图等无文本轮限制')
+  assert.ok(CLIENT_SRC.includes('回填子会话输入框'), 'fork 说明缺重试回填语义')
+  assert.ok(CLIENT_SRC.includes('尾号递增'), 'fork 说明缺标题递增语义')
+  assert.ok(CLIENT_SRC.includes('重生成语义'), '自动重发说明缺重生成语义')
+  assert.ok(CLIENT_SRC.includes('家族版本'), '计数器说明缺家族版本语义')
+})
+
+// 搜索功能源码契约:query 双写 + 组合输入守卫 + 命中计数 + 两级 Esc
+test('源码契约:历史浮层搜索的实现要素齐备', () => {
+  assert.ok(CLIENT_SRC.includes('onCompositionStart'), '搜索框应处理 IME 组合输入开始')
+  assert.ok(CLIENT_SRC.includes('onCompositionEnd'), '搜索框应处理 IME 组合输入结束')
+  assert.ok(CLIENT_SRC.includes('composingRef'), '组合输入期间应经 ref 守卫跳过过滤')
+  assert.ok(CLIENT_SRC.includes('cx-hist__count'), '应有命中计数样式锚点')
+  assert.ok(CLIENT_SRC.includes('filterHistoryInputs(raw, next)'), '过滤应作用于原始条目集')
+  assert.ok(CLIENT_SRC.includes('queryRef.current'), 'query 应双写 ref 供键盘层读取')
+})

package/test/client-id.test.mjs

@@ -0,0 +1,24 @@
+// client.js 注册 id 守卫:loader 按 graph row id(完整包名)匹配注册,短名即加载失败。
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const { name } = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'))
+
+test('client.js 注册 id 为完整包名', () => {
+  const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+  const match = source.match(/__ModuleLoader__\.load\(\{\s*id:\s*'([^']+)'/)
+  assert.ok(match, 'client.js 缺少 __ModuleLoader__.load 注册')
+  assert.equal(match[1], name)
+})
+
+test('client.js 样式注入自带 data-plugin', () => {
+  const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+  const injections = source.split("createElement('style')").length - 1
+  assert.ok(injections > 0, 'client.js 无样式注入点')
+  const marked = source.split(`setAttribute('data-plugin', '${name}')`).length - 1
+  assert.equal(marked, injections, '每个样式注入点都必须自带 data-plugin(值=注册包名),防宿主 claimStyles 误归属后随他插件 HMR 整批误删')
+})

package/test/client-scope.test.mjs

@@ -0,0 +1,54 @@
+// client.js 求值形态守卫:宿主以经典 script 整源求值,顶层词法声明落页面全局词法环境,
+// 跨 bundle 同名即整脚本 SyntaxError 拒载。本包 client.js 以单条 __ModuleLoader__.load
+// 语句承载全部代码(声明均在 factory 作用域内),本守卫锁定"顶层零词法声明"不变量,
+// 防未来声明误置顶层。vm.runInContext 与浏览器经典 script 同语义(全局词法环境跨脚本共享)。
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import vm from 'node:vm'
+
+const CLIENT_SOURCE = readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'client.js'), 'utf8').trimEnd()
+const DECLARATION_NAMES = [
+  ...new Set(
+    [...CLIENT_SOURCE.matchAll(/^(?:const|let|var|class|(?:async )?function\*?) ([A-Za-z_$][\w$]*)/gm)].map((match) => match[1])
+  ),
+]
+const BUNDLE_ID = '@mzzsfy/dsh-context-manager'
+
+test('Given 同 context 已有外部 CSS 声明(宿主经典 script 全局词法环境), When 整源求值 client.js, Then 双源共存不拒载且外部声明原值不变', () => {
+  const ctx = vm.createContext({ window: { __ModuleLoader__: { load: () => {} } } })
+  vm.runInContext('const CSS = 1', ctx)
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  assert.equal(vm.runInContext('CSS', ctx), 1)
+})
+
+test('Given client.js 已整源求值, When 同 context 再声明外部 CSS, Then 双源共存不拒载', () => {
+  const ctx = vm.createContext({ window: { __ModuleLoader__: { load: () => {} } } })
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  vm.runInContext('const CSS = 1', ctx)
+})
+
+test('Given client.js 整源求值完成, When 逐名以 const 重声明探针行首声明名, Then 全局词法环境零泄漏', () => {
+  const ctx = vm.createContext({ window: { __ModuleLoader__: { load: () => {} } } })
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  const leaked = DECLARATION_NAMES.filter((name) => {
+    try {
+      vm.runInContext(`const ${name} = null`, ctx)
+      return false
+    } catch {
+      return true
+    }
+  })
+  assert.deepEqual(leaked, [])
+})
+
+test('Given 宿主 loader 就绪, When 整源求值 client.js, Then 自注册照常发生且 id 不变', () => {
+  const registrations = []
+  const ctx = vm.createContext({ window: { __ModuleLoader__: { load: (registration) => registrations.push(registration) } } })
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  assert.equal(registrations.length, 1)
+  assert.equal(registrations[0].id, BUNDLE_ID)
+  assert.equal(typeof registrations[0].factory, 'function')
+})