@mzzsfy/dsh-settings-nav-icons 0.1.5 → 0.3.0

package/README.md

@@ -6,20 +6,34 @@ DeepSeek Harness 纯前端插件:设置弹窗左侧导航与 dsh-market 插件
 
 | 场景 | 行为 |
 |---|---|
-| 分区当前是官方齿轮 | 改写官方 svg 内部内容为专属图形(声明 → 内置映射 → 关键词 → 哈希) |
+| 分区当前是官方齿轮 | 改写官方 svg 内部内容为专属图形(用户覆盖 → 声明 → 内置映射 → 关键词 → 哈希) |
 | 分区当前非齿轮(官方原生图标 / 第三方插件供给的图标) | 不干预,映射或声明命中也不例外 |
+| 右键导航分区 | 打开图标编辑浮层:保存/清除用户覆盖(localStorage 持久),非法值行内提示 |
+| 左侧导航分区溢出(弹窗高度不足) | 列表区域滚动,标题固定;官方无滚动机制,溢出被弹窗裁剪致底部分区不可达 |
 | 市场卡片头像槽(有名称锚) | 按插件名取图替换作者头像/字母色块 |
-| 语言切换导致 label 变化 | 已改写的分区按新 label 重新取图改写 |
+| 语言切换导致 label 变化 | 已改写的分区按新 label 重新取图改写;双语分区覆盖/声明按等价组跨语言命中 |
 | 面板关闭后重新打开 / 会话切换 | 新渲染的齿轮自动再改写 |
 | 声明变更(注册新值/撤销) | 受影响分区 svg 内容就地重写,头像槽重新取图 |
 | 插件卸载 | 观察器随 `ctx.effect` 销毁,重载页面即恢复官方默认 |
 
 改写采用**内容制**:直接替换官方齿轮 svg 的内部内容,不新建节点、不动属性——节点、class、DOM 位置全部保持官方原样,其他插件针对官方图标的 CSS(如按 `> svg:first-child` 隐藏、伪元素 mask 叠加)照常作用于改写结果,不会出现双图标。
 
+## 用户自定义覆盖
+
+右键点击设置弹窗左侧导航任意分区,弹出图标编辑浮层:
+
+- 输入内置 glyph 名(见下表)或完整 16×16 `<svg>` 字符串,「保存」即时生效并写入 localStorage(`__navicUserIcons`),刷新页面后仍然生效
+- 「清除」删除该分区覆盖,回到默认取图管线;Esc 或点击浮层外部关闭
+- 浮层展示当前取图来源(用户覆盖 / 插件声明 / 内置映射 / 自动推导)与当前图标预览
+- 覆盖值与声明走同一安全门(未知 glyph 拒绝、svg 过闸),存储值被篡改时该键跳过,不直通注入
+- 官方双语分区(通用设置 / General)的覆盖与声明按等价组生效:写在任一语言键,两种语言下都命中;保存/清除/重写均按组内全键触达,两侧同步
+
+插件卸载后浮层与样式随生命周期销毁;localStorage 中的覆盖数据不影响官方 UI,重装即恢复。
+
 ## 取图优先级
 
 ```
-外部声明(register) → 内置映射(ICONS) → 名称关键词(NAME_RULES) → 稳定哈希备用池(FALLBACK)
+用户覆盖(localStorage) → 外部声明(register) → 内置映射(ICONS) → 名称关键词(NAME_RULES) → 稳定哈希备用池(FALLBACK)
 ```
 
 - **外部声明**:其他插件运行时注册自己的 label/插件名 → 图标,优先级最高(见下节)。
@@ -39,7 +53,7 @@ window.__navicIcons.register({ '消息通知': 'bell' })
 ;(window.__navicIconQueue ??= []).push({ '消息通知': 'bell' })
 ```
 
-- 键:分区显示文本(设置导航)或插件名(dsh-market 卡片)。两域共用一张表,同名时以先命中者生效,键请取不易与官方分区撞名的插件名。
+- 键:分区显示文本(设置导航)或插件名(dsh-market 卡片)。两域共用一张表,同名时以先命中者生效,键请取不易与官方分区撞名的插件名。官方双语分区按等价组解析:任一语言 label 作键,两种语言下均命中(消除语言切换的声明键漂移)。
 - 值:内置 glyph 名(`tune/theme/bot/market/cube/mcp/shield/cards/plan/bell/wrench/archive/spark/layers/tag/grid/git/search/term/chart/code/doc/db/flow/globe/lock/image/zap`)或完整 16×16 `<svg>` 字符串。svg 字符串过安全门:完整开标签(大小写不敏感,拒绝 `<svgx` 残串)且单根闭合(首个 `</svg>` 后不得再有内容,堵尾缀活动 HTML);不带 `on*` 事件属性(`\b` 前界堵斜杠分隔绕过)、不带 `<script>`/`<style>`(内联样式全文档生效且 @import 可外联)/`<foreignObject>`/SMIL 动画(`<animate>`/`<set>` 等)载体;不带 `href`/`xlink:href` 及 `attributeName="href"` 注入(16×16 静态图标无合法引用/动画场景,外联请求一并封死);不带 `javascript:`(纵深);长度 ≤4096 字符;glyph 名查表经 `typeof` 收口,原型链成员不可能被注入。
 - 声明值经归一化后写入注册表;同值重复注册幂等短路;非法值(未知 glyph/被安全门拒绝/非字符串)撤销该键声明,该分区回到内置映射或关键词/哈希默认管线,已改写的 nav svg 内容就地重写。
 - 声明持久化在 `window.__navicIconDeclarations`:本插件 client 半区热重载会重跑工厂而生产者不重发注册,持久层让重装实例恢复声明,页面刷新随 window 释放。
@@ -64,11 +78,12 @@ window.__navicIcons.register({ '消息通知': 'bell' })
 
 ## 实现要点
 
+- 导航滚动补偿:官方 navList 高度随内容撑开,弹窗(overflow hidden)裁掉溢出且无滚动途径,分区一多底部不可达。插件启动时向 head 注入一条样式规则(navList `flex:1 1 0 + min-height:0 + overflow-y:auto + scrollbar-width:thin`),样式表形态对弹窗关闭重开等任意 React 重渲染持续生效;卸载即移除,零残留。类名锚定与图标改写同策略(`VOzbGW_` 哈希前缀字面量)。
 - 实现边界:`settings.*` 子槽位的声明权与渲染权均被原版 `dsh-client-ui-settings-general` 条目占用——`renderSlot` 只授予声明了 `children` 的条目(dsh-client-ui-renderer),而 Slot 声明全局唯一、重复声明即 `already declared`,因此任何插件都无法在保留设置页内容的前提下接管 Shell 重绘导航。DOM 观察是唯一不依赖官方契约变更的路径(dream-skin 与 dsh-better-sidebar 各自内置了同原理的一次性 hack)。
 - 匹配锚点:分区显示文本而非分区 id——id 不进 DOM,文本是唯一稳定可见锚点;CSS Modules 哈希类名(`VOzbGW_*`)取字面量。label 一律 trim 后匹配,空白 label 直接跳过。
 - 内容改写制:决策只对官方齿轮(齿轮路径前缀 `M14.0861` 识别)生效,`applyDecision` 写官方 svg 的 `innerHTML` 并把记账(`data-navic` = label)落在官方 svg 自身;不新建节点、不改属性、不驱动 style。React 安全性依据:官方 nav 图标是静态子树,重渲染前后 element 引用相等即 bailout,改写内容稳定存活(0.1.x 的 NotFoundError 仅源于 remove 节点本身);升级残留的旧注入节点(`data-navic="1"`)在改写前清除。改写后的 svg 非齿轮且带记账,与"未处理的官方原生非齿轮 svg"靠记账区分——因此声明变更不删记账,由 `registerIcons` 对命中键的 nav svg 以 `resolveForLabel` 全链(声明 → 内置映射 → 关键词 → 哈希)就地重写内容,头像槽(非 svg 节点)仍走清账重贴。
 - 市场卡片头像槽记账为插件名,IMG/DIV 同构处理:原节点隐藏、注入图标跟随(不触碰 React 受管子树),换名重贴按父容器范围清理旧注入、不误删外来兄弟。
-- 生命周期:单个 `MutationObserver` 常驻 `document.body`(`childList` + `subtree` + `characterData`;childList 通道仅元素级变更放行,characterData 通道按目标域精确放行——label 与市场卡片名所在行内的文本改写才唤醒,流式正文等域外文本变更不唤醒),变更去抖到 `requestAnimationFrame` 扫描,单元格与头像槽合并为单次全文档遍历,扫描结束 `takeRecords` 消除自产写入回波;`ctx.effect` 持有,卸载即断开并取消已排定帧,已停止实例的注册入口短路、不驱动 DOM。观察器句柄挂 window 代际槽(HMR 重评估先拆上一代观察器与在途帧),帧句柄与槽同步(跨代取消真实可达)。常驻全文档观察是已知性能取舍:装饰性插件的目标域(设置弹窗/市场卡片)无稳定根锚点,两级观察的回归风险大于收益。
+- 生命周期:单个 `MutationObserver` 常驻 `document.body`(`childList` + `subtree` + `characterData`;childList 通道仅元素级变更放行,characterData 通道按目标域精确放行——label 与市场卡片名所在行内的文本改写才唤醒,流式正文等域外文本变更不唤醒),变更去抖到 `requestAnimationFrame` 扫描,单元格与头像槽合并为单次全文档遍历,扫描结束 `takeRecords` 消除自产写入回波;`ctx.effect` 持有,卸载即断开并取消已排定帧,已停止实例的注册入口短路、不驱动 DOM。观察器句柄、在途帧与滚动样式元素挂 window 代际槽(HMR 重评估先拆上一代三者,滚动样式对旧版槽缺字段宽松判空),帧句柄与槽同步(跨代取消真实可达)。常驻全文档观察是已知性能取舍:装饰性插件的目标域(设置弹窗/市场卡片)无稳定根锚点,两级观察的回归风险大于收益。
 - 纯逻辑层(映射表 + 改写决策)在 `src/logic.mjs`,`src/client.js` 内嵌同源实现,`node --test` 以同一套场景对两份实现做 parity 验证(全表 deepEqual + 决策函数逐函数源码对比),另有编排层契约测试(注册校验/队列三态与时序/生命周期/头像槽编排/异常隔离)与四生产者样板契约测试。
 
 ## 安装
@@ -85,7 +100,7 @@ node scripts/dev-link.mjs dsh-settings-nav-icons
 
 前提:profile `package.json` 的 dependencies 有本包 semver 行、`dsh.profile.bundles` 有本包名(未发布包 registry 拉取会失败,junction 覆盖 node_modules 物理目录后启动只走 realpath)。junction 会被 `pnpm install` / `dsh plugin add` 抹掉,之后重跑本脚本即可。
 
-重启 dsh 后设置面板即生效;无设置项。
+重启 dsh 后设置面板即生效;设置项即「用户自定义覆盖」的右键浮层,无独立设置页。
 
 ## 升级 / 卸载
 
@@ -104,7 +119,7 @@ pnpm --dir packages/dsh-settings-nav-icons test
 node --test packages/dsh-settings-nav-icons/test/*.test.mjs
 ```
 
-覆盖:上表全部行为场景(齿轮强补 / 非齿轮不动 / svg 记账幂等与 label 重写 / trim 与空 label / 无 svg 降级 / 内容改写与不建节点 / 0.1.x 残留清理 / 声明安全门 / 撤销回退取图链 / 关键词边界 / 头像槽 img+div)、映射表契约、双实现全量同源 parity、client.js 注册 id 守卫、编排层契约(注册校验 / 就地重写 / 队列三态 / 生命周期 / 异常隔离 / 持久层恢复)、四生产者样板契约。
+覆盖:上表全部行为场景(齿轮强补 / 非齿轮不动 / svg 记账幂等与 label 重写 / trim 与空 label / 无 svg 降级 / 内容改写与不建节点 / 0.1.x 残留清理 / 声明安全门 / 撤销回退取图链 / 关键词边界 / 头像槽 img+div / 导航滚动样式注入与卸载)、映射表契约、双实现全量同源 parity、client.js 注册 id 守卫、编排层契约(注册校验 / 就地重写 / 队列三态 / 生命周期 / 异常隔离 / 持久层恢复)、用户覆盖(localStorage 恢复安全门 / 右键浮层保存与非法行内提示 / 清除回默认管线 / 等价组双语触达 / 浮层开闭)、别名等价查询(lookupWithAlias / aliasKeysOf / iconSourceOf)、四生产者样板契约。
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-settings-nav-icons",
   "description": "设置弹窗导航分区与插件市场卡片图标替换:按分区显示文本把回退齿轮换成专属图形,市场卡片头像槽换成插件图标,DOM 观察实现,卸载后重载页面恢复官方图标",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -12,6 +12,272 @@ window.__ModuleLoader__.load({
     const SELECTOR_LABEL = '.VOzbGW_navLabel'
     const ATTR_MARK = 'data-navic'
 
+    // 恢复路径内容刷新:页面刷新后 DOM 全新无此需求;HMR 热重载复用旧 DOM,
+    // 记账与 label 相同会被 replacePass 幂等跳过,恢复的声明/覆盖必须就地重算。
+    function refreshMarkedContent() {
+      const keys = []
+      for (const el of document.querySelectorAll('[' + ATTR_MARK + ']')) {
+        const key = el.dataset.navic
+        if (key !== undefined && key !== '' && key !== '1' && keys.indexOf(key) < 0) keys.push(key)
+      }
+      if (keys.length === 0) return
+      rewriteTouched(keys)
+    }
+
+    // ---- 用户逐分区覆盖:localStorage 持久层 + 右键浮层 UI ----
+
+    // 覆盖持久化跨会话存活(localStorage),与声明持久层(window 属性,页面级)
+    // 的差异:声明服务于热重载恢复,覆盖服务于用户长期自定义。恢复走同一
+    // resolveIcon 安全门收口,被篡改的存储不直通注入。
+    const USER_STORE_KEY = '__navicUserIcons'
+
+    function restoreUserOverrides() {
+      let raw
+      try {
+        raw = window.localStorage.getItem(USER_STORE_KEY)
+      } catch (error) {
+        console.warn('[nav-icons] 用户覆盖存储不可读,已跳过', error)
+        return
+      }
+      if (typeof raw !== 'string' || raw === '') return
+      let saved
+      try {
+        saved = JSON.parse(raw)
+      } catch (error) {
+        console.warn('[nav-icons] 用户覆盖存储解析失败,已跳过', error)
+        return
+      }
+      if (saved === null || typeof saved !== 'object' || Array.isArray(saved)) return
+      for (const key of Object.keys(saved)) {
+        if (key === '__proto__' || key === '1' || key.length > KEY_MAX_CHARS) continue
+        try {
+          if (resolveIcon(saved[key]) !== undefined) USER_OVERRIDES[key] = saved[key]
+        } catch (error) {
+          console.warn('[nav-icons] 用户覆盖键 ' + key + ' 恢复失败,已跳过', error)
+        }
+      }
+    }
+
+    function persistUserOverrides() {
+      try {
+        window.localStorage.setItem(USER_STORE_KEY, JSON.stringify(Object.assign({}, USER_OVERRIDES)))
+      } catch (error) {
+        console.warn('[nav-icons] 用户覆盖存储不可写', error)
+      }
+    }
+
+    // 覆盖写入/清除:值 undefined 视为清除(等价组全键删除);非法值返回 false
+    // 交由浮层行内提示,不落库不重贴。变更后按等价组全键触达重写。
+    function setUserOverride(key, value) {
+      if (!active) return false
+      if (key === '' || key === '__proto__' || key === '1' || key.length > KEY_MAX_CHARS) return false
+      if (value === undefined || value === null) {
+        let cleared = false
+        for (const k of aliasKeysOf(key)) {
+          if (USER_OVERRIDES[k] !== undefined) {
+            delete USER_OVERRIDES[k]
+            cleared = true
+          }
+        }
+        if (cleared) {
+          persistUserOverrides()
+          rewriteTouched(aliasKeysOf(key))
+          schedule()
+        }
+        return true
+      }
+      let resolved
+      try {
+        resolved = resolveIcon(value)
+      } catch (error) {
+        return false
+      }
+      if (resolved === undefined) return false
+      let changed = false
+      for (const k of aliasKeysOf(key)) {
+        if (k !== key && USER_OVERRIDES[k] !== undefined) {
+          delete USER_OVERRIDES[k]
+          changed = true
+        }
+      }
+      // 存原始输入(与声明表同语义,glyph 名回填浮层可读),查询侧过闸展开
+      if (USER_OVERRIDES[key] !== value) {
+        USER_OVERRIDES[key] = value
+        changed = true
+      }
+      if (changed) {
+        persistUserOverrides()
+        rewriteTouched(aliasKeysOf(key))
+        schedule()
+      }
+      return true
+    }
+
+    // 覆盖浮层:右键 nav 单元格打开,单例常驻 body,随插件 stop 移除。
+    // 类名全仓唯一前缀 sni-(dsh-settings-nav-icons 缩写),样式随启动注入。
+    const OVERLAY_CLASS = 'sni-ov'
+    const OVERLAY_CSS =
+      '.' + OVERLAY_CLASS + '{position:fixed;z-index:2147483647;width:264px;padding:10px;' +
+      'border-radius:8px;color-scheme:light dark;background:light-dark(#ffffff,#1f1f1f);' +
+      'color:light-dark(#111111,#eeeeee);box-shadow:0 4px 16px rgba(0,0,0,.28);' +
+      'font:12px/1.5 system-ui,sans-serif}' +
+      '.' + OVERLAY_CLASS + '__title{font-weight:600;margin-bottom:2px;word-break:break-all}' +
+      '.' + OVERLAY_CLASS + '__src{opacity:.65;margin-bottom:6px}' +
+      '.' + OVERLAY_CLASS + '__input{width:100%;box-sizing:border-box;margin-bottom:4px;' +
+      'padding:4px 6px;border:1px solid rgba(128,128,128,.5);border-radius:6px;' +
+      'background:transparent;color:inherit;font:inherit}' +
+      '.' + OVERLAY_CLASS + '__input:focus-visible{outline:2px solid #4d6bfe;outline-offset:-1px}' +
+      '.' + OVERLAY_CLASS + '__bad{display:none;color:#d5484c;margin-bottom:4px}' +
+      '.' + OVERLAY_CLASS + '__bad--on{display:block}' +
+      '.' + OVERLAY_CLASS + '__cur{display:flex;align-items:center;gap:6px;margin-bottom:8px;' +
+      'opacity:.9}' +
+      '.' + OVERLAY_CLASS + '__row{display:flex;gap:6px;justify-content:flex-end}' +
+      '.' + OVERLAY_CLASS + '__btn{padding:4px 12px;border:1px solid rgba(128,128,128,.5);' +
+      'border-radius:6px;background:transparent;color:inherit;font:inherit;cursor:pointer}' +
+      '.' + OVERLAY_CLASS + '__btn:hover{border-color:#4d6bfe}' +
+      '.' + OVERLAY_CLASS + '__btn:focus-visible{outline:2px solid #4d6bfe;outline-offset:1px}' +
+      '.' + OVERLAY_CLASS + '__btn--primary{background:#4d6bfe;border-color:#4d6bfe;color:#ffffff}'
+
+    const SOURCE_LABELS = {
+      user: '用户覆盖',
+      declared: '插件声明',
+      builtin: '内置映射',
+      derived: '自动推导',
+    }
+
+    let overlayStyle = null
+    let overlay = null
+    let overlayCell = null
+
+    function removeOverlay() {
+      if (overlay === null) return
+      overlay.remove()
+      overlay = null
+      overlayCell = null
+      if (slot !== null) slot.overlayEl = null
+    }
+
+    // 就地取当前覆盖原文作输入框回填:等价组任一侧键命中都回填。
+    function overlayInputValue(label) {
+      const hit = lookupWithAlias(USER_OVERRIDES, label)
+      return hit === undefined ? '' : hit
+    }
+
+    function openOverlay(cell) {
+      const labelNode = cell.querySelector(SELECTOR_LABEL)
+      if (labelNode === null) return
+      const label = (labelNode.textContent || '').trim()
+      if (label === '') return
+      removeOverlay()
+      overlayCell = cell
+      overlay = document.createElement('div')
+      overlay.className = OVERLAY_CLASS
+      const title = document.createElement('div')
+      title.className = OVERLAY_CLASS + '__title'
+      title.textContent = label
+      const src = document.createElement('div')
+      src.className = OVERLAY_CLASS + '__src'
+      src.textContent = '当前来源:' + (SOURCE_LABELS[iconSourceOf(label)] || SOURCE_LABELS.derived)
+      const cur = document.createElement('span')
+      cur.className = OVERLAY_CLASS + '__cur'
+      cur.innerHTML = resolveForLabel(label)
+      cur.title = '当前图标'
+      const input = document.createElement('input')
+      input.className = OVERLAY_CLASS + '__input'
+      input.placeholder = 'glyph 名或完整 <svg>(留空不清除,用清除按钮)'
+      input.value = overlayInputValue(label)
+      const bad = document.createElement('div')
+      bad.className = OVERLAY_CLASS + '__bad'
+      bad.textContent = '非法值:须为内置 glyph 名或过安全门的 16×16 <svg>'
+      const row = document.createElement('div')
+      row.className = OVERLAY_CLASS + '__row'
+      const clearBtn = document.createElement('button')
+      clearBtn.className = OVERLAY_CLASS + '__btn'
+      clearBtn.textContent = '清除'
+      const saveBtn = document.createElement('button')
+      saveBtn.className = OVERLAY_CLASS + '__btn ' + OVERLAY_CLASS + '__btn--primary'
+      saveBtn.textContent = '保存'
+      row.appendChild(clearBtn)
+      row.appendChild(saveBtn)
+      overlay.appendChild(title)
+      overlay.appendChild(src)
+      overlay.appendChild(cur)
+      overlay.appendChild(input)
+      overlay.appendChild(bad)
+      overlay.appendChild(row)
+      document.body.appendChild(overlay)
+      if (slot !== null) slot.overlayEl = overlay
+      input.focus()
+      saveBtn.addEventListener('click', function () {
+        if (setUserOverride(label, input.value)) removeOverlay()
+        else bad.classList.add(OVERLAY_CLASS + '__bad--on')
+      })
+      clearBtn.addEventListener('click', function () {
+        setUserOverride(label, undefined)
+        removeOverlay()
+      })
+    }
+
+    // 文档级监听:右键开浮层、浮层外点击/Escape 关闭;start 挂载,stop 卸载。
+    let contextHandler = null
+    let pointerHandler = null
+    let keyHandler = null
+
+    function installOverlayListeners() {
+      contextHandler = function (event) {
+        const target = event.target
+        const cell = target != null && typeof target.closest === 'function'
+          ? target.closest(SELECTOR_CELL)
+          : null
+        if (cell === null) return
+        event.preventDefault()
+        openOverlay(cell)
+      }
+      pointerHandler = function (event) {
+        if (overlay === null) return
+        const target = event.target
+        if (target != null && typeof target.closest === 'function'
+          && target.closest('.' + OVERLAY_CLASS) !== null) return
+        removeOverlay()
+      }
+      keyHandler = function (event) {
+        if (overlay === null) return
+        if (event.key === 'Escape') removeOverlay()
+      }
+      document.addEventListener('contextmenu', contextHandler)
+      document.addEventListener('pointerdown', pointerHandler)
+      document.addEventListener('keydown', keyHandler)
+    }
+
+    function uninstallOverlayListeners() {
+      if (contextHandler !== null) document.removeEventListener('contextmenu', contextHandler)
+      if (pointerHandler !== null) document.removeEventListener('pointerdown', pointerHandler)
+      if (keyHandler !== null) document.removeEventListener('keydown', keyHandler)
+      contextHandler = null
+      pointerHandler = null
+      keyHandler = null
+    }
+
+    function installOverlayStyle() {
+      overlayStyle = document.createElement('style')
+      overlayStyle.textContent = OVERLAY_CSS
+      document.head.appendChild(overlayStyle)
+      if (slot !== null) slot.overlayStyle = overlayStyle
+    }
+
+    function uninstallOverlayStyle() {
+      if (overlayStyle === null) return
+      overlayStyle.remove()
+      overlayStyle = null
+      if (slot !== null) slot.overlayStyle = null
+    }
+
+    // ---- 设置导航滚动补偿:官方 navList 高度随内容撑开,溢出被 panel hidden
+    // 裁剪且无滚动机制,分区一多底部即不可达。样式表形态一次注入,对弹窗重开
+    // 等任意 React 重渲染持续生效;类名锚定与上方单元格同策略(哈希前缀字面量)。
+
+    const NAVLIST_SCROLL_CSS = '.VOzbGW_navList{flex:1 1 0;min-height:0;overflow-y:auto;scrollbar-width:thin}'
+
     /* LOGIC-BEGIN */
     // 纯逻辑层:图标映射 + 单元格替换决策,与 src/logic.mjs 同源,由 parity 测试保证。
 
@@ -183,10 +449,59 @@ window.__ModuleLoader__.load({
       ['zap|flash|fast|quick|boost|speed|turbo', ZAP],
     ].map(function (pair) { return { re: new RegExp('(^|[^a-z])(' + pair[0] + ')([^a-z]|$)'), icon: pair[1] } })
 
-    // 插件名/分区 label 两级取图:外部声明 → 关键词主题图 → 稳定哈希备用池。
+    // 用户逐分区覆盖注册表:取图链最前端,值经 resolveIcon 归一化,持久化由
+    // 编排层落 localStorage(纯逻辑层不触碰存储)。
+    const USER_OVERRIDES = Object.create(null)
+
+    // 官方双语分区等价组:组内任一语言 label 作声明/覆盖键,组内其他语言取图时
+    // 同样命中(消除语言切换下声明键漂移)。仅收官方现有展示形态,不发明未知 id。
+    const ALIAS_GROUPS = [
+      ['通用设置', 'General'],
+    ]
+
+    // 表查询的别名等价扩展:先按原键直查,再沿等价组用同组成员试查。
+    // 表为 Object.create(null) 帧装,继承成员不可达。
+    function lookupWithAlias(table, label) {
+      const direct = table[label]
+      if (direct !== undefined) return direct
+      for (const group of ALIAS_GROUPS) {
+        if (group.indexOf(label) < 0) continue
+        for (const member of group) {
+          if (member === label) continue
+          const hit = table[member]
+          if (hit !== undefined) return hit
+        }
+      }
+      return undefined
+    }
+
+    // 键的等价组展开:自身 + 所属组内其他成员;不入组的键只返回自身。
+    // 覆盖写入/清除与就地重写按该范围触达,保证双语分区两侧状态一致。
+    function aliasKeysOf(label) {
+      const keys = [label]
+      for (const group of ALIAS_GROUPS) {
+        if (group.indexOf(label) < 0) continue
+        for (const member of group) {
+          if (member !== label && keys.indexOf(member) < 0) keys.push(member)
+        }
+      }
+      return keys
+    }
+
+    // 插件名/分区 label 两级取图:用户覆盖 → 外部声明 → 关键词主题图 → 稳定哈希备用池。
+    // 表值为原始声明(glyph 名或 svg),命中后过 resolveIcon 归一化展开;归一化失败
+    // (声明值被撤销/存储被篡改)视为该层未命中,继续下一层。
     function themedIcon(name) {
-      const declared = resolveIcon(DECLARED_ICONS[name])
-      if (declared !== undefined) return declared
+      const overridden = lookupWithAlias(USER_OVERRIDES, name)
+      if (overridden !== undefined) {
+        const resolved = resolveIcon(overridden)
+        if (resolved !== undefined) return resolved
+      }
+      const declared = lookupWithAlias(DECLARED_ICONS, name)
+      if (declared !== undefined) {
+        const resolved = resolveIcon(declared)
+        if (resolved !== undefined) return resolved
+      }
       const n = name.toLowerCase()
       for (const rule of NAME_RULES) {
         if (rule.re.test(n)) return rule.icon
@@ -194,16 +509,33 @@ window.__ModuleLoader__.load({
       return FALLBACK[poolIndexOf(name)]
     }
 
-    // 分区取图全链:声明 → 内置映射 → 关键词/哈希兜底。decide 与声明变更就地
-    // 重写共用;撤销内置分区声明时回退必须含内置映射,否则卡死在哈希图。
+    // 分区取图全链:用户覆盖 → 声明(含别名) → 内置映射 → 关键词/哈希兜底。decide
+    // 与声明/覆盖变更就地重写共用;撤销时回退必须含内置映射,否则卡死在哈希图。
     function resolveForLabel(label) {
-      const declared = resolveIcon(DECLARED_ICONS[label])
-      if (declared !== undefined) return declared
+      const overridden = lookupWithAlias(USER_OVERRIDES, label)
+      if (overridden !== undefined) {
+        const resolved = resolveIcon(overridden)
+        if (resolved !== undefined) return resolved
+      }
+      const declared = lookupWithAlias(DECLARED_ICONS, label)
+      if (declared !== undefined) {
+        const resolved = resolveIcon(declared)
+        if (resolved !== undefined) return resolved
+      }
       const mapped = ICONS[label]
       if (mapped !== undefined) return mapped
       return themedIcon(label)
     }
 
+    // 当前 label 的取图来源:用户覆盖 / 插件声明 / 内置映射 / 关键词与哈希推导。
+    // 与 resolveForLabel 同序遍历,供覆盖浮层展示当前生效层。
+    function iconSourceOf(label) {
+      if (lookupWithAlias(USER_OVERRIDES, label) !== undefined) return 'user'
+      if (lookupWithAlias(DECLARED_ICONS, label) !== undefined) return 'declared'
+      if (ICONS[label] !== undefined) return 'builtin'
+      return 'derived'
+    }
+
     // 市场卡片头像槽决策:img(作者头像)与 div(字母色块)同构处理——原子节点隐藏,
     // 插件图标注入跟随。记账值 = 插件名,换名重贴由该比较驱动。
     function decideAvatar(av, name) {
@@ -300,7 +632,6 @@ window.__ModuleLoader__.load({
     }
 
     /* LOGIC-END */
-
     // ---- 市场卡片 DOM 锚点(css-modules 哈希前缀随版本变,按后缀匹配) ----
 
     const SELECTOR_AV = '[class$="_av"]'
@@ -445,18 +776,47 @@ window.__ModuleLoader__.load({
       }
       if (touched.length === 0) return
       persistDeclarations()
-      // 声明变更就地生效:nav svg(记账为分区/插件名)直接重写内容且记账保留——
-      // 改写后的 svg 非齿轮,清账会让 isGear 判定失配卡死;头像槽(非 svg 节点)
-      // 清账后走 decideAvatar 重贴。'1' 为注入纯标记,不命中声明键。
+      rewriteTouched(touched)
+      schedule()
+    }
+
+    // 键命中元素就地重写:nav svg(记账为分区/插件名)直接重写内容且记账保留——
+    // 改写后的 svg 非齿轮,清账会让 isGear 判定失配卡死;头像槽(非 svg 节点)
+    // 清账后走 decideAvatar 重贴。'1' 为注入纯标记,不命中声明/覆盖键。
+    // 触达键先按等价组展开:声明/覆盖写在哪一侧语言键,双语分区两侧都立即生效。
+    function rewriteTouched(touched) {
+      const expanded = []
+      for (const key of touched) {
+        for (const k of aliasKeysOf(key)) {
+          if (expanded.indexOf(k) < 0) expanded.push(k)
+        }
+      }
       for (const el of document.querySelectorAll('[' + ATTR_MARK + ']')) {
-        if (touched.indexOf(el.dataset.navic) < 0) continue
+        if (expanded.indexOf(el.dataset.navic) < 0) continue
         if (el.tagName === 'svg') {
           el.innerHTML = svgInner(resolveForLabel(el.dataset.navic))
         } else {
           delete el.dataset.navic
         }
       }
-      schedule()
+    }
+
+    // 滚动样式元素:start 注入 head,stop 移除,引用即状态源,幂等无守卫分支;
+    // 同挂代际槽, HMR 重评估 stop 未跑时由新实例代拆
+    let scrollStyle = null
+
+    function installScrollStyle() {
+      scrollStyle = document.createElement('style')
+      scrollStyle.textContent = NAVLIST_SCROLL_CSS
+      document.head.appendChild(scrollStyle)
+      if (slot !== null) slot.scrollStyle = scrollStyle
+    }
+
+    function uninstallScrollStyle() {
+      if (scrollStyle === null) return
+      scrollStyle.remove()
+      scrollStyle = null
+      if (slot !== null) slot.scrollStyle = null
     }
 
     // 队列直通桩属主守卫:stop 仅复位本实例所置桩,乱序清理不覆盖新实例运行态
@@ -485,20 +845,33 @@ window.__ModuleLoader__.load({
       if (previous !== undefined) {
         if (previous.observer !== null) previous.observer.disconnect()
         if (previous.rafId !== 0) cancelAnimationFrame(previous.rafId)
+        // 宽松判空:槽是跨代码版本通道,旧版槽缺新字段(undefined)
+        if (previous.scrollStyle != null) previous.scrollStyle.remove()
+        if (previous.overlayStyle != null) previous.overlayStyle.remove()
+        if (previous.overlayEl != null) previous.overlayEl.remove()
       }
-      slot = { observer: null, rafId: 0 }
+      slot = { observer: null, rafId: 0, scrollStyle: null, overlayStyle: null, overlayEl: null }
       window[SLOT_KEY] = slot
-      // 可抛步骤(声明恢复/队列排水)先于观察器挂载,失败不产生孤儿扫描器
+      // 可抛步骤(覆盖/声明恢复、队列排水、样式注入)先于观察器挂载,失败不产生孤儿扫描器
+      installOverlayStyle()
+      installScrollStyle()
+      restoreUserOverrides()
       restoreDeclarations()
       drainQueue()
       observer = new MutationObserver(onMutations)
       observer.observe(document.body, { childList: true, subtree: true, characterData: true })
       slot.observer = observer
+      installOverlayListeners()
+      refreshMarkedContent()
       replacePass()
     }
 
     function stop() {
       active = false
+      uninstallOverlayListeners()
+      removeOverlay()
+      uninstallOverlayStyle()
+      uninstallScrollStyle()
       if (observer !== null) {
         observer.disconnect()
         observer = null

package/src/logic.mjs

@@ -195,10 +195,20 @@ export const NAME_RULES = [
   ['zap|flash|fast|quick|boost|speed|turbo', ZAP],
 ].map(function (pair) { return { re: new RegExp('(^|[^a-z])(' + pair[0] + ')([^a-z]|$)'), icon: pair[1] } })
 
-// 插件名/分区 label 两级取图:外部声明 → 关键词主题图 → 稳定哈希备用池。
+// 插件名/分区 label 两级取图:用户覆盖 → 外部声明 → 关键词主题图 → 稳定哈希备用池。
+// 表值为原始声明(glyph 名或 svg),命中后过 resolveIcon 归一化展开;归一化失败
+// (声明值被撤销/存储被篡改)视为该层未命中,继续下一层。
 export function themedIcon(name) {
-  const declared = resolveIcon(DECLARED_ICONS[name])
-  if (declared !== undefined) return declared
+  const overridden = lookupWithAlias(USER_OVERRIDES, name)
+  if (overridden !== undefined) {
+    const resolved = resolveIcon(overridden)
+    if (resolved !== undefined) return resolved
+  }
+  const declared = lookupWithAlias(DECLARED_ICONS, name)
+  if (declared !== undefined) {
+    const resolved = resolveIcon(declared)
+    if (resolved !== undefined) return resolved
+  }
   const n = name.toLowerCase()
   for (const rule of NAME_RULES) {
     if (rule.re.test(n)) return rule.icon
@@ -206,16 +216,33 @@ export function themedIcon(name) {
   return FALLBACK[poolIndexOf(name)]
 }
 
-// 分区取图全链:声明 → 内置映射 → 关键词/哈希兜底。decide 与声明变更就地
-// 重写共用;撤销内置分区声明时回退必须含内置映射,否则卡死在哈希图。
+// 分区取图全链:用户覆盖 → 声明(含别名) → 内置映射 → 关键词/哈希兜底。decide
+// 与声明/覆盖变更就地重写共用;撤销时回退必须含内置映射,否则卡死在哈希图。
 export function resolveForLabel(label) {
-  const declared = resolveIcon(DECLARED_ICONS[label])
-  if (declared !== undefined) return declared
+  const overridden = lookupWithAlias(USER_OVERRIDES, label)
+  if (overridden !== undefined) {
+    const resolved = resolveIcon(overridden)
+    if (resolved !== undefined) return resolved
+  }
+  const declared = lookupWithAlias(DECLARED_ICONS, label)
+  if (declared !== undefined) {
+    const resolved = resolveIcon(declared)
+    if (resolved !== undefined) return resolved
+  }
   const mapped = ICONS[label]
   if (mapped !== undefined) return mapped
   return themedIcon(label)
 }
 
+// 当前 label 的取图来源:用户覆盖 / 插件声明 / 内置映射 / 关键词与哈希推导。
+// 与 resolveForLabel 同序遍历,供覆盖浮层展示当前生效层。
+export function iconSourceOf(label) {
+  if (lookupWithAlias(USER_OVERRIDES, label) !== undefined) return 'user'
+  if (lookupWithAlias(DECLARED_ICONS, label) !== undefined) return 'declared'
+  if (ICONS[label] !== undefined) return 'builtin'
+  return 'derived'
+}
+
 // 市场卡片头像槽决策:img(作者头像)与 div(字母色块)同构处理——原子节点隐藏,
 // 插件图标注入跟随。记账值 = 插件名,换名重贴由该比较驱动。
 export function decideAvatar(av, name) {
@@ -255,6 +282,45 @@ export const ICONS = {
 // 继承成员;污染面收敛在 window.__navicIcons 单一命名空间。
 export const DECLARED_ICONS = Object.create(null)
 
+// 用户逐分区覆盖注册表:取图链最前端,值经 resolveIcon 归一化,持久化由
+// 编排层落 localStorage(纯逻辑层不触碰存储)。
+export const USER_OVERRIDES = Object.create(null)
+
+// 官方双语分区等价组:组内任一语言 label 作声明/覆盖键,组内其他语言取图时
+// 同样命中(消除语言切换下声明键漂移)。仅收官方现有展示形态,不发明未知 id。
+export const ALIAS_GROUPS = [
+  ['通用设置', 'General'],
+]
+
+// 表查询的别名等价扩展:先按原键直查,再沿等价组用同组成员试查。
+// 表为 Object.create(null) 帧装,继承成员不可达。
+export function lookupWithAlias(table, label) {
+  const direct = table[label]
+  if (direct !== undefined) return direct
+  for (const group of ALIAS_GROUPS) {
+    if (group.indexOf(label) < 0) continue
+    for (const member of group) {
+      if (member === label) continue
+      const hit = table[member]
+      if (hit !== undefined) return hit
+    }
+  }
+  return undefined
+}
+
+// 键的等价组展开:自身 + 所属组内其他成员;不入组的键只返回自身。
+// 覆盖写入/清除与就地重写按该范围触达,保证双语分区两侧状态一致。
+export function aliasKeysOf(label) {
+  const keys = [label]
+  for (const group of ALIAS_GROUPS) {
+    if (group.indexOf(label) < 0) continue
+    for (const member of group) {
+      if (member !== label && keys.indexOf(member) < 0) keys.push(member)
+    }
+  }
+  return keys
+}
+
 // 单元格改写判定(内容改写制):不新建 svg、不动属性,直接把官方齿轮 svg 的
 // 内部内容改写为本插件图标;记账迁到官方 svg 自身(dataset.navic = label),
 // 节点与 class/位置等属性保持官方原样,第三方对官方图标的 CSS/选择器处理

package/test/orchestration.test.mjs

@@ -16,6 +16,7 @@ const SELECTOR_AV = '[class$="_av"]'
 const SELECTOR_ALL = SELECTOR_CELL + ',' + SELECTOR_AV
 const SELECTOR_MARKED = '[data-navic]'
 const SELECTOR_LABEL = '.VOzbGW_navLabel'
+const NAVLIST_SCROLL_CSS = '.VOzbGW_navList{flex:1 1 0;min-height:0;overflow-y:auto;scrollbar-width:thin}'
 
 function fakeRaf() {
   const pending = new Map()
@@ -28,10 +29,21 @@ function fakeRaf() {
   }
 }
 
+// 浮层桩内递归找节点:按钮嵌在 row 子层
+function overlayFind(root, pred) {
+  for (const node of root.children) {
+    if (pred(node)) return node
+    const hit = overlayFind(node, pred)
+    if (hit) return hit
+  }
+  return null
+}
+
 // 官方 svg 桩:gear=true 模拟官方齿轮路径,否则为无路径原生图形;内容改写制下
 // applyDecision 直接写 innerHTML(桩以 innerHTML 属性承接)与 dataset.navic
 function makeOfficialSvg({ gear = true } = {}) {
   const svg = {
+    tagName: 'svg',
     dataset: { navic: '' },
     style: { display: '' },
     innerHTML: '',
@@ -68,6 +80,7 @@ function makeCell(label, { gear = true, navic = '' } = {}) {
   cell.official = official
   cell.svgs.push(official)
   cell.matches = (sel) => sel !== SELECTOR_AV
+  cell.closest = (sel) => (sel === SELECTOR_CELL ? cell : null)
   cell.querySelector = (sel) => (sel === SELECTOR_LABEL ? { textContent: label } : null)
   cell.querySelectorAll = (sel) => {
     if (sel === 'svg') return cell.svgs
@@ -113,6 +126,55 @@ function fakeDocument() {
     marked: [],
     cells: [],
     avatars: [],
+    // 生命周期事件序:锁定"样式注入先于观察器挂载"的顺序契约
+    events: [],
+    head: {
+      children: [],
+      appendChild(el) { doc.head.children.push(el); doc.events.push('style') },
+    },
+    createdStyles: [],
+    listeners: {},
+    createElement(tag) {
+      const el = {
+        tag,
+        textContent: '',
+        children: [],
+        className: '',
+        value: '',
+        placeholder: '',
+        innerHTML: '',
+        appendChild(child) { el.children.push(child) },
+        focus() { el.focused = true },
+        addEventListener(type, fn) { el.handlers[type] = fn },
+        handlers: {},
+        classList: {
+          add(cls) { el.classes.add(cls) },
+          remove(cls) { el.classes.delete(cls) },
+        },
+        classes: new Set(),
+        remove() {
+          const list = doc.bodyChildren
+          const at = list.indexOf(el)
+          if (at >= 0) list.splice(at, 1)
+          doc.createdStyles.splice(doc.createdStyles.indexOf(el), 1)
+          doc.head.children.splice(doc.head.children.indexOf(el), 1)
+        },
+      }
+      if (tag === 'style') doc.createdStyles.push(el)
+      return el
+    },
+    bodyChildren: [],
+    addEventListener(type, fn) {
+      ;(doc.listeners[type] ??= []).push(fn)
+    },
+    removeEventListener(type, fn) {
+      const list = doc.listeners[type] ?? []
+      const at = list.indexOf(fn)
+      if (at >= 0) list.splice(at, 1)
+    },
+    dispatch(type, event) {
+      for (const fn of [...(doc.listeners[type] ?? [])]) fn(event)
+    },
     querySelectorAll(sel) {
       if (sel === SELECTOR_ALL) return [...doc.cells, ...doc.avatars]
       if (sel === SELECTOR_CELL) return doc.cells
@@ -121,6 +183,7 @@ function fakeDocument() {
       return []
     },
   }
+  doc.body.appendChild = (el) => { doc.bodyChildren.push(el) }
   return doc
 }
 
@@ -136,7 +199,7 @@ function loadClient() {
       this.cb = cb
       observers.push(this)
     }
-    observe(...args) { observed.push(args) }
+    observe(...args) { observed.push(args); if (doc.events) doc.events.push('observe') }
     disconnect() { observed.length = 0 }
     takeRecords() { return [] }
   }
@@ -144,6 +207,11 @@ function loadClient() {
     __ModuleLoader__: { load(mod) { win.__loaded = mod } },
     requestAnimationFrame: raf.requestAnimationFrame,
     cancelAnimationFrame: raf.cancelAnimationFrame,
+    localStorage: {
+      map: new Map(),
+      getItem(k) { return win.localStorage.map.has(k) ? win.localStorage.map.get(k) : null },
+      setItem(k, v) { win.localStorage.map.set(k, String(v)) },
+    },
   }
   const doc = fakeDocument()
   new Function('window', 'document', 'MutationObserver', 'requestAnimationFrame', 'cancelAnimationFrame', 'console', src)(
@@ -174,6 +242,61 @@ test('boot 观察:body 目标与三开关齐全,卸载后断开', () => {
   assert.equal(observed.length, 0, '卸载后 disconnect')
 })
 
+test('启动样式:覆盖浮层样式与滚动样式注入 head,卸载移除,重装恢复,先于观察器挂载', () => {
+  const { win, doc, observed } = loadClient()
+  assert.equal(doc.createdStyles.length, 0, '启动前无注入')
+  const unload = boot(win.__loaded, doc)
+  try {
+    assert.equal(doc.createdStyles.length, 2, '恰两次注入(浮层+滚动)')
+    assert.ok(doc.createdStyles.some((el) => el.textContent.includes('sni-ov')), '浮层样式随启动注入')
+    assert.ok(doc.createdStyles.some((el) => el.textContent === NAVLIST_SCROLL_CSS), '滚动规则与实现同源')
+    assert.equal(doc.head.children.length, 2, '样式挂载在 head')
+    assert.deepEqual(doc.events, ['style', 'style', 'observe'], '样式注入先于观察器挂载')
+    unload()
+    assert.equal(doc.createdStyles.length, 0, '卸载后移除')
+    assert.equal(doc.head.children.length, 0, 'head 无残留')
+    const unload2 = boot(win.__loaded, doc)
+    try {
+      assert.equal(doc.createdStyles.length, 2, '重装恢复注入')
+    } finally {
+      unload2()
+    }
+    assert.equal(doc.createdStyles.length, 0, '二次卸载移除')
+  } finally {
+    unload()
+  }
+})
+
+test('启动样式代际:HMR 不卸载重评估由新实例代拆,旧形槽跨版本容忍', () => {
+  // HMR 路径:旧实例未 stop 直接二次 boot(新实例读槽代拆上一代样式)
+  const { win, doc } = loadClient()
+  const unload1 = boot(win.__loaded, doc)
+  const oldStyles = [...doc.createdStyles]
+  const unload2 = boot(win.__loaded, doc)
+  try {
+    assert.equal(doc.createdStyles.length, 2, '代拆后恰两份样式')
+    assert.equal(doc.head.children.length, 2, 'head 无旧代残留')
+    for (const old of oldStyles) {
+      assert.ok(!doc.createdStyles.includes(old), '旧代样式被替换')
+    }
+    unload2()
+    assert.equal(doc.createdStyles.length, 0, '新实例卸载后干净')
+  } finally {
+    unload1()
+    unload2()
+  }
+
+  // 升级路径:上一代是旧版本槽(无 scrollStyle/overlayStyle 字段),代拆不得抛错
+  const { win: win2, doc: doc2 } = loadClient()
+  win2[Symbol.for('@mzzsfy/dsh-settings-nav-icons')] = { observer: null, rafId: 0 }
+  const unload3 = boot(win2.__loaded, doc2)
+  try {
+    assert.equal(doc2.createdStyles.length, 2, '旧形槽不阻塞注入')
+  } finally {
+    unload3()
+  }
+})
+
 test('registerIcons 输入校验:数组与空值拒收', () => {
   const { win, doc, raf } = loadClient()
   const unload = boot(win.__loaded, doc)
@@ -486,6 +609,137 @@ test('语言切换端到端:characterData 域内变更经回调触发重贴', ()
   }
 })
 
+// 用户覆盖:恢复走安全门、写入幂等/非法拒绝、等价组全键触达、localStorage 持久往返
+test('用户覆盖:启动从 localStorage 恢复,非法键值跳过', () => {
+  const { win, doc } = loadClient()
+  doc.cells.push(makeCell('插件市场'))
+  win.localStorage.map.set('__navicUserIcons', JSON.stringify({
+    '插件市场': 'bell',
+    '坏 glyph': 'no-such-glyph',
+    '活动 html': '<svg><script>alert(1)</script></svg>',
+    '1': 'bell',
+    __proto__: 'bell',
+    '超长键': 'x'.repeat(4097),
+  }))
+  const unload = boot(win.__loaded, doc)
+  try {
+    const market = doc.cells[0]
+    assert.equal(market.official.dataset.navic, '插件市场')
+    assert.ok(market.official.innerHTML.includes('M8 2.2'), '合法覆盖生效(bell 内容)')
+    assert.ok(!doc.marked.some((el) => el.dataset.navic === '坏 glyph'), '未知 glyph 不入表')
+    assert.ok(!doc.marked.some((el) => el.dataset.navic === '活动 html'), '安全门拒绝直通')
+  } finally {
+    unload()
+  }
+})
+
+test('用户覆盖:右键浮层保存/非法行内提示/清除,持久化往返,卸载后重装恢复', () => {
+  const { win, doc, raf } = loadClient()
+  doc.cells.push(makeCell('插件市场'))
+  const unload = boot(win.__loaded, doc)
+  try {
+    const cell = doc.cells[0]
+    doc.marked.push(cell.official)
+    // 右键打开浮层:preventDefault + 单例 + 输入聚焦
+    const evt = { target: cell, preventDefault() { evt.prevented = true } }
+    doc.dispatch('contextmenu', evt)
+    assert.ok(evt.prevented, '右键默认菜单被阻止')
+    const overlay = doc.bodyChildren[doc.bodyChildren.length - 1]
+    assert.ok(overlay.className.includes('sni-ov'), '浮层挂 body')
+    const input = overlayFind(overlay, (n) => n.tag === 'input')
+    const save = overlayFind(overlay, (n) => n.tag === 'button' && n.textContent === '保存')
+    const clear = overlayFind(overlay, (n) => n.tag === 'button' && n.textContent === '清除')
+    assert.ok(input && save && clear, '浮层含输入与双按钮')
+    assert.equal(input.focused, true, '打开即聚焦')
+    // 非法值:行内提示,不落库
+    input.value = 'no-such-glyph'
+    save.handlers.click()
+    const bad = overlayFind(overlay, (n) => (n.classes ?? new Set()).size > 0)
+    assert.ok(bad && [...bad.classes].some((c) => c.includes('__bad--on')), '非法值行内提示')
+    assert.equal(win.localStorage.map.get('__navicUserIcons'), undefined, '非法值不持久化')
+    // 合法保存:落库 + 单元格就地重写 + 浮层关闭
+    input.value = 'bell'
+    save.handlers.click()
+    assert.ok(!doc.bodyChildren.includes(overlay), '保存成功关闭浮层')
+    assert.ok(cell.official.innerHTML.includes('M8 2.2'), '覆盖内容生效')
+    const saved = JSON.parse(win.localStorage.map.get('__navicUserIcons'))
+    assert.ok(saved['插件市场'], '覆盖持久化')
+    // 再开浮层:回填当前覆盖值;清除:回默认管线 + 删键
+    doc.dispatch('contextmenu', { target: cell, preventDefault() {} })
+    const overlay2 = doc.bodyChildren[doc.bodyChildren.length - 1]
+    const input2 = overlayFind(overlay2, (n) => n.tag === 'input')
+    const clear2 = overlayFind(overlay2, (n) => n.tag === 'button' && n.textContent === '清除')
+    assert.equal(input2.value, 'bell', '回填当前覆盖原文(glyph 名)')
+    clear2.handlers.click()
+    assert.equal(win.localStorage.map.get('__navicUserIcons'), '{}', '清除后持久化为空表')
+    assert.ok(!cell.official.innerHTML.includes('M8 2.2'), '清除后回默认管线(店面图标)')
+    assert.ok(doc.bodyChildren.indexOf(overlay2) < 0, '清除关闭浮层')
+    // 浮层外点击与 Escape 关闭
+    doc.dispatch('contextmenu', { target: cell, preventDefault() {} })
+    const overlay3 = doc.bodyChildren[doc.bodyChildren.length - 1]
+    doc.dispatch('pointerdown', { target: cell })
+    assert.ok(!doc.bodyChildren.includes(overlay3), '外部点击关闭')
+    doc.dispatch('contextmenu', { target: cell, preventDefault() {} })
+    const overlay4 = doc.bodyChildren[doc.bodyChildren.length - 1]
+    doc.dispatch('keydown', { key: 'Escape' })
+    assert.ok(!doc.bodyChildren.includes(overlay4), 'Escape 关闭')
+    // 卸载重装:localStorage 覆盖恢复生效
+    win.localStorage.map.set('__navicUserIcons', JSON.stringify({ '插件市场': 'bell' }))
+  } finally {
+    unload()
+  }
+  const unload2 = boot(win.__loaded, doc)
+  try {
+    assert.ok(doc.cells[0].official.innerHTML.includes('M8 2.2'), '重装恢复用户覆盖')
+  } finally {
+    unload2()
+  }
+})
+
+test('用户覆盖:别名等价键写入/清除,双语分区两侧触达', () => {
+  const { win, doc } = loadClient()
+  // 双语两格均按齿轮改写链记账:'通用设置' 与 'General' 各持内置映射
+  doc.cells.push(makeCell('通用设置'))
+  doc.cells.push(makeCell('General'))
+  const unload = boot(win.__loaded, doc)
+  try {
+    const zhCell = doc.cells[0]
+    const enCell = doc.cells[1]
+    doc.marked.push(zhCell.official, enCell.official)
+    doc.dispatch('contextmenu', { target: zhCell, preventDefault() {} })
+    const overlay = doc.bodyChildren[doc.bodyChildren.length - 1]
+    const input = overlayFind(overlay, (n) => n.tag === 'input')
+    const save = overlayFind(overlay, (n) => n.tag === 'button' && n.textContent === '保存')
+    input.value = 'bell'
+    save.handlers.click()
+    assert.equal(JSON.parse(win.localStorage.map.get('__navicUserIcons'))['通用设置'], 'bell', '按打开侧语言键落库')
+    assert.ok(zhCell.official.innerHTML.includes('M8 2.2'), '中文侧覆盖生效')
+    assert.ok(enCell.official.innerHTML.includes('M8 2.2'), '英文侧等价触达重写')
+    // 清除:等价组全键删除,两侧回各语言内置映射
+    doc.dispatch('contextmenu', { target: enCell, preventDefault() {} })
+    const overlay2 = doc.bodyChildren[doc.bodyChildren.length - 1]
+    assert.ok(overlayFind(overlay2, (n) => n.tag === 'input').value === 'bell', '英文侧打开回填中文键覆盖')
+    const clear2 = overlayFind(overlay2, (n) => n.tag === 'button' && n.textContent === '清除')
+    clear2.handlers.click()
+    assert.equal(JSON.parse(win.localStorage.map.get('__navicUserIcons'))['通用设置'], undefined, '清除走等价组全键')
+    assert.ok(!zhCell.official.innerHTML.includes('M8 2.2'), '中文侧回内置映射')
+    assert.ok(!enCell.official.innerHTML.includes('M8 2.2'), '英文侧回内置映射')
+  } finally {
+    unload()
+  }
+})
+
+test('用户覆盖:非 nav 单元格右键不弹浮层', () => {
+  const { win, doc } = loadClient()
+  const unload = boot(win.__loaded, doc)
+  try {
+    doc.dispatch('contextmenu', { target: doc.avatars[0], preventDefault() {} })
+    assert.equal(doc.bodyChildren.length, 0, '头像槽右键无浮层')
+  } finally {
+    unload()
+  }
+})
+
 // 声明侧契约:四个生产者包的注册样板(先探测入口、数组态入队),改契约须同步五处。
 // 包脱离 monorepo 布局(发布态)时跳过:无兄弟包源码可读。
 test('生产者样板契约:四包注册走 __navicIcons/__navicIconQueue', () => {

package/test/parity.test.mjs

@@ -26,7 +26,7 @@ function clientLogic() {
   }
   const factory = new Function(
     'ATTR_MARK', 'SELECTOR_LABEL',
-    section + '; return { ICONS, DECLARED_ICONS, FALLBACK, GLYPHS, GEAR_PATH, SVG_MAX_CHARS, STROKE_ATTRS, NAME_RULES, ATTR_MARK, SELECTOR_LABEL, poolIndexOf, resolveIcon, svgInner, resolveForLabel, themedIcon, decide, applyDecision, decideAvatar, applyAvatar };',
+    section + '; return { ICONS, DECLARED_ICONS, USER_OVERRIDES, ALIAS_GROUPS, FALLBACK, GLYPHS, GEAR_PATH, SVG_MAX_CHARS, STROKE_ATTRS, NAME_RULES, ATTR_MARK, SELECTOR_LABEL, poolIndexOf, resolveIcon, svgInner, resolveForLabel, themedIcon, iconSourceOf, lookupWithAlias, aliasKeysOf, decide, applyDecision, decideAvatar, applyAvatar };',
   )
   return factory(pick('ATTR_MARK'), pick('SELECTOR_LABEL'))
 }
@@ -285,6 +285,51 @@ function defineScenarios(prefix, L) {
     assert.equal(themedIcon('git-notify'), themedIcon('git'), 'git 先于 notify')
   })
 
+  test(prefix + '别名等价:双语分区任一语言键命中,组外键不受影响', () => {
+    const { USER_OVERRIDES, lookupWithAlias, aliasKeysOf } = L
+    try {
+      USER_OVERRIDES['通用设置'] = 'bell'
+      assert.equal(lookupWithAlias(USER_OVERRIDES, 'General'), 'bell', '反向等价命中')
+      assert.equal(lookupWithAlias(USER_OVERRIDES, '通用设置'), 'bell', '正向直查')
+      assert.equal(aliasKeysOf('General').length, 2, '等价组键展开为双语两侧')
+      assert.deepEqual(aliasKeysOf('插件市场'), ['插件市场'], '组外键只返回自身')
+    } finally {
+      delete USER_OVERRIDES['通用设置']
+    }
+  })
+
+  test(prefix + '用户覆盖插到取图链最前,撤销后回声明/内置/推导管线', () => {
+    const { USER_OVERRIDES, DECLARED_ICONS, ICONS, resolveForLabel, resolveIcon, iconSourceOf } = L
+    try {
+      DECLARED_ICONS['插件市场'] = 'git'
+      assert.equal(resolveForLabel('插件市场'), resolveIcon('git'), '基线:声明命中')
+      assert.equal(iconSourceOf('插件市场'), 'declared')
+      USER_OVERRIDES['插件市场'] = 'bell'
+      assert.equal(resolveForLabel('插件市场'), resolveIcon('bell'), '覆盖压过声明')
+      assert.equal(iconSourceOf('插件市场'), 'user')
+      delete USER_OVERRIDES['插件市场']
+      assert.equal(resolveForLabel('插件市场'), resolveIcon('git'), '撤销覆盖回声明')
+      delete DECLARED_ICONS['插件市场']
+      assert.equal(resolveForLabel('插件市场'), ICONS['插件市场'], '再撤声明回内置映射')
+      assert.equal(iconSourceOf('插件市场'), 'builtin')
+      assert.equal(iconSourceOf('无任何命中的分区'), 'derived', '无命中归推导')
+    } finally {
+      delete USER_OVERRIDES['插件市场']
+      delete DECLARED_ICONS['插件市场']
+    }
+  })
+
+  test(prefix + '覆盖的别名等价:覆盖写在任一语言键,双语 label 都命中且来源为 user', () => {
+    const { USER_OVERRIDES, resolveForLabel, resolveIcon, iconSourceOf } = L
+    try {
+      USER_OVERRIDES['General'] = 'search'
+      assert.equal(resolveForLabel('通用设置'), resolveIcon('search'), '反向 label 命中覆盖')
+      assert.equal(iconSourceOf('通用设置'), 'user')
+    } finally {
+      delete USER_OVERRIDES['General']
+    }
+  })
+
   test(prefix + '头像槽:原子节点隐藏记账,换名清旧注入不误删外来兄弟', () => {
     const { decideAvatar, applyAvatar } = L
     const removed = []
@@ -351,6 +396,9 @@ test('两份实现常量同源', () => {
   assert.equal(logic.SELECTOR_LABEL, client.SELECTOR_LABEL, 'label 选择器同源(精确匹配桩防子串容忍)')
   assert.equal(logic.GEAR_PATH, client.GEAR_PATH)
   assert.equal(logic.SVG_MAX_CHARS, client.SVG_MAX_CHARS)
+  assert.deepEqual(logic.ALIAS_GROUPS, client.ALIAS_GROUPS, '别名组同源')
+  assert.equal(Object.keys(logic.USER_OVERRIDES).length, 0, '用户覆盖表初始为空(logic 侧)')
+  assert.equal(Object.keys(client.USER_OVERRIDES).length, 0, '用户覆盖表初始为空(client 侧)')
 })
 
 test('两份实现 ICONS/GLYPHS/FALLBACK 全量同源', () => {
@@ -380,7 +428,7 @@ test('LOGIC 段与 logic.mjs 决策函数逐函数源码一致(归一化注释
     .replace(/\/\*[\s\S]*?\*\//g, '')
     .replace(/\/\/[^\n]*/g, '')
     .replace(/\s+/g, '')
-  for (const name of ['resolveIcon', 'svgInner', 'resolveForLabel', 'themedIcon', 'decide', 'applyDecision', 'decideAvatar', 'applyAvatar', 'poolIndexOf']) {
+  for (const name of ['resolveIcon', 'svgInner', 'resolveForLabel', 'themedIcon', 'iconSourceOf', 'lookupWithAlias', 'aliasKeysOf', 'decide', 'applyDecision', 'decideAvatar', 'applyAvatar', 'poolIndexOf']) {
     assert.equal(
       normalize(client[name].toString()),
       normalize(logic[name].toString()),