dsh-mpkg-wallpaper 3.7.2 → 3.7.3

package/README.en.md

@@ -69,7 +69,7 @@ A plugin for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harn
 - Based on CSS `backdrop-filter`: semi-transparent + blur + edge highlight (**no longer the WebGL refraction version** — WebGL was removed in v3.6.0, see below). Four toggles:
   - **lgTest (test mode)**: keeps only wallpaper + floating + layout, and overrides no DSH token (otherwise a translucent base makes the chat box transparent without blur)
   - **lgComposer / lgSidebar / lgHeader**: add a liquid-glass overlay to the message-bubble area / sidebar / title bar respectively (the sidebar can only be semi-transparent + edge highlight because of the settings dialog's render hierarchy — it **cannot** use backdrop-filter, or it would squash the settings dialog into the sidebar — historical pitfall)
-- **History**: early versions used real WebGL refraction (`lib/liquid-glass/` library + `liquid-glass-bundle.js` 107KB); v3.6.0 removed the WebGL runtime (unstable + large) in favor of pure CSS. `lib/liquid-glass/*.js` and `liquid-glass-bundle.js` still ship (`files: ["lib"]`) but are **no longer referenced by the client**; the host still serves the `/api/mpkg-wallpaper/lg` route (no callers). the host-side static route is a **live path** (`/api/mpkg-wallpaper/lg/<file>.js` really `readFileSync`s `lib/liquid-glass/<file>`), and the `tools/liquid-demo/` demo page now uses that same mount (P-122). `tools/liquid-demo/` stays in the repo only and is **not shipped** (`files` excludes `tools/`). So they are **not dead files**; removing them is a release-surface decision (review: `docs/LIQUID-GLASS-DEDUP.md`).
+- **History**: early versions used real WebGL refraction (`lib/liquid-glass/` library + `liquid-glass-bundle.js` 107KB); v3.6.0 removed the WebGL runtime (unstable + large) in favor of pure CSS. `lib/liquid-glass/*.js` and `liquid-glass-bundle.js` **stay in the repo but have been moved off the publish surface** (negative `files` patterns `!lib/liquid-glass/**` + `!lib/liquid-glass-bundle.js` ⇒ **not shipped in the npm package**, P-127) and are **no longer referenced by the client** (`lgModule` is declared but never assigned). The host-side static route is still a **live path** (`/api/mpkg-wallpaper/lg/<file>.js` really `readFileSync`s `lib/liquid-glass/<file>`; in-repo development/demos are unaffected), and the `tools/liquid-demo/` demo page uses that same mount (P-122). `tools/liquid-demo/` stays in the repo only and is **not shipped** (`files` excludes `tools/`). So they are **not dead files**; **being off the publish surface means those 10 files are no longer distributed ⇒ the MIT attribution obligation surface disappears**, while the repo keeps all 10 and still records their 10 sha256 sums (`THIRD-PARTY.md` §1.3; numbers and gates: `docs/PUBLISH-SURFACE-LIQUID-GLASS.md` P-127).
 
 **🎬 Lens & picture**
 - Lens zoom (10–2000%) & pan, brightness (50–150%), light sharpen, Deep diving background box
@@ -230,9 +230,9 @@ without anyone noticing locally. Gate step 12 turns that into a machine-checkabl
 (`node tools/style-scope-guard.mjs`):
 
 * **It uses the real artifact**: `buildCss` is never re-implemented. `tools/_stub.mjs` loads `lib/client.js`
-  in Node and calls the plugin's own `__mpwBuildCss(patch)` over **600+ setting combinations** (613 today:
-  defaults / each boolean alone / all 512 combinations of the 9 core switches / the `bsCompat` family /
-  numeric 0 and 100 / no wallpaper / lgTest), then parses every generated rule, including `@media` / `@supports` nesting.
+  in Node and calls the plugin's own `__mpwBuildCss(patch)` over **600+ setting combinations** (the run prints
+  the exact count; 615 this round: defaults / each boolean alone / all 512 combinations of the 9 core switches /
+  the `bsCompat` family / numeric 0 and 100 / no wallpaper / lgTest), then parses every generated rule, including `@media` / `@supports` nesting.
 * **Verdict**: every selector must hit our own markers (`.mpw*` / `[data-mpw*]` / `#mpw-*`) or a **registered**
   host/third-party scope. The `bsCompat` block that deliberately targets third-party DOM
   (`[data-dsh-better-sidebar] …`) is allowed **only because it is declared** in the allow-list with a reason and a
@@ -283,7 +283,10 @@ check: `node tools/switch-wiring-test.mjs` (gate step 2):
 * non-boolean features (`accent` / `aquaTextEnhance` must change the output); `themeColor` is
   "always-emitted CSS + runtime attribute gate", so the check asserts the gate rules exist instead;
 * switches **proven dead** go into `KNOWN_DEAD` and are listed on every run (two-way assertion: fixing one
-  requires deleting its entry). That list drove the first fix: **`lgCss` (pure CSS/SVG liquid glass) never ran at
+  requires deleting its entry). **The table is now empty** (`lgCss`/`sessionFollow` fixed, `glassWindow` retired
+  and deleted); **retired** switches are instead guarded by section A0 ("0 dangling references in the source +
+  0 orphan key in either dictionary"), each with a permanent mutation that must go red.
+  That list drove the first fix: **`lgCss` (pure CSS/SVG liquid glass) never ran at
   all** — the block referenced `bdSupported` while the `const` was declared after it, i.e. a same-scope TDZ
   `ReferenceError` swallowed by the outer `catch { /* liquid glass failure must not affect other styles */ }`
   (the catch is kept; it now only fires on real failures). The criteria are two-way: `lgCss:true` must emit the
@@ -292,8 +295,17 @@ check: `node tools/switch-wiring-test.mjs` (gate step 2):
   toggle and copy but nothing read `section.sessionFollow`; implemented per the **user-visible copy** (on = follow
   that opacity, off = **back to the host's original colour**), default unchanged, asserted in
   `tools/switch-wiring-test.mjs` section A4 (three two-way assertions in both default and unified-blur contexts;
-  the "remove the read" mutation must go red). The third, `glassWindow`, stays registered and unchanged (copy
-  without implementation) — see [`docs/TOKEN-NAMESPACE.md`](docs/TOKEN-NAMESPACE.md) §3b. **`bsCompat` (the better-sidebar adaptation master switch) now defaults to on** (ruled 2026-09-18): the
+  the "remove the read" mutation must go red). The third, `glassWindow`, was handled under the user's policy of
+  **"no copy that is visible but unclickable"**: it had **no toggle row (nobody could see it) and no read point
+  (nothing to click)**, while the feature its copy promised is already delivered by `settingsBlur` (settings-panel
+  blur) plus `dialogBlur`/`popoverBlur` ⇒ its copy and field were **deleted** rather than wired (wiring would add
+  a second switch for the same element and make the settings panel a backdrop root). Six deletion sites
+  (2 i18n lines each in zh/en + the `lgTest` preset default + the reset defaults + `BACKUP_FIELDS` + the import
+  `boolFields`; the export/sanitise lists are deleted **in lockstep** so an imported backup cannot fall through to
+  the "unregistered type" passthrough) — asserted in section **A0** of `tools/switch-wiring-test.mjs`
+  (0 hits in the source + 0 hits in both dictionaries) with the permanent mutation
+  `retired-glasswindow-copy-restored` required to go red; the default-context CSS is **sha256-identical**
+  before and after. See [`docs/TOKEN-NAMESPACE.md`](docs/TOKEN-NAMESPACE.md) §3b. **`bsCompat` (the better-sidebar adaptation master switch) now defaults to on** (ruled 2026-09-18): the
   bottom-panel float adaptation is settled on real devices, so a default of off meant nobody ever saw it.
   Existing users are migrated **only if they never set it explicitly**; anyone who turned it off by hand is
   **never overridden** (the write path stamps a `bsCompatUserSet` marker; the migration itself does not).
@@ -311,6 +323,31 @@ check: `node tools/switch-wiring-test.mjs` (gate step 2):
   Neither assertion was relaxed.
 * discrimination proof: reverting either gate back under `aquaOn` must turn the audit red.
 
+## Pre-commit gate (a few seconds, 2026-09-19 / P-129)
+
+The audit above (plus the panel-rendering regression) is now available as a **few-second pre-commit** — four
+seconds before a commit is enough to stop the two failure classes that **have really happened here several
+times**: "the switch isn't wired" and "the panel no longer renders".
+
+```sh
+cd dsh-mpkg-wallpaper
+git config core.hooksPath .githooks    # install (this clone only; git config --unset core.hooksPath to remove)
+git commit --no-verify                 # bypass once
+MPW_SKIP_PRECOMMIT=1 git commit -m …   # bypass once (the script's own explicit escape hatch, always exit 0)
+```
+
+* **What runs**: `tools/panel-smoke.mjs` (panel rendering + language dictionaries, ~0.3 s) and
+  `tools/switch-wiring-test.mjs` (every switch must really change the output + retired switches with 0 dangling
+  references + 7 discrimination mutations, ~2.5 s), **serially**, **2.8–3.9 s** total across repeated runs.
+* **What does not run**: the 12 steps of `tools/check.sh` (step 3 is the 1115-combination CSS matrix, step 9
+  onwards needs headless Firefox) stay **out** of pre-commit — a minute-long gate in pre-commit only makes people
+  afraid to commit. The full gate is still `bash tools/check.sh` (or CI).
+* **It does not block development**: installing is explicit (not installing changes nothing); if the staged
+  changes touch no artifact path (no `lib/`, `tools/`, `package.json`) it **skips**; a missing `node` or script
+  prints one line and exits 0; on failure it prints the red lines verbatim and tells you how to bypass — it never
+  edits files and never auto-fixes.
+* **Details, every measured output and the unverified items**: [`docs/PRE-COMMIT.md`](docs/PRE-COMMIT.md).
+
 ## Video-wallpaper transcoding: a **misjudgement** + resource caps (2026-09-17, item 1)
 
 > User report: "I'm not using transcoding, my wallpaper is a **video-class mpkg**, the
@@ -545,8 +582,8 @@ dsh-mpkg-wallpaper/
 │   ├── web-wallpaper.js # web wallpapers: content-first type detection + WE API shim source + entry-HTML injection + CORS policy (MIT, self-written)
 │   ├── client.js     # browser: mpkg parsing + settings page + bg DOM + blur suite + library + time-variation/web options + playback control/power saving
 │   ├── pkg-extract.js# scene.pkg static-frame/layer extraction (PKG+LZ4+TEX, MIT, from elysia395)
-│   ├── liquid-glass/ # WebGL liquid-glass library (**leftover, no runtime ref**; CSS version since v3.6.0)
-│   └── liquid-glass-bundle.js # liquid-glass bundle (107KB, **not referenced by the client**; byte-rebuildable from the kept sources, sha256 db50361c…)
+│   ├── liquid-glass/ # WebGL liquid-glass library (**leftover, not shipped**; no runtime ref; CSS version since v3.6.0)
+│   └── liquid-glass-bundle.js # liquid-glass bundle (107KB, **not shipped**; not referenced by the client; byte-rebuildable from the kept sources, sha256 db50361c…)
 ├── tools/            # gates/tests/benches + lg build/inline scripts + liquid-demo page (for developers)
 │                     # audio scan: audio-scan-bench.mjs (timing table) / audio-scan-test.mjs (spec assertions · no full inflate · cache)
 │                     #             scene-audio-route-test.mjs (/raw Range + probe route + security)
@@ -555,6 +592,8 @@ dsh-mpkg-wallpaper/
 │                     #                      bundle-equivalence-test.mjs (gate step 11: same route assertions on source and bundle + mutation controls)
 │                     # style scope: style-scope-guard.mjs (gate step 12: every injected CSS rule must hit .mpw*/[data-mpw*];
 │                     #              host/third-party scopes must be registered in the allow-list with a reason + docs pointer)
+│                     # pre-commit: pre-commit.sh (a few seconds: panel-smoke + switch-wiring, with path filtering and
+│                     #              bypass hatches; paired with ../.githooks/pre-commit — see README / docs/PRE-COMMIT.md)
 │                     # note: the research-era Python tools (unmpkg/tex2png/mdl_explorer/xref) were
 │                     #       **deleted (GPL lineage unresolved, 2026-09-16)** — see `../docs/COPYING-RULES.md` §6
 ├── dist/             # build output (**not committed**, gitignored): dsh-mpkg-wallpaper.bundle.mjs (Option 4, generated on demand)
@@ -564,8 +603,8 @@ dsh-mpkg-wallpaper/
 ├── README.en.md      # English
 └── THIRD-PARTY.md    # third-party provenance / clean-room record (shipped, MIT-side attribution)
 ```
-> Note: `lib/liquid-glass/` and `lib/liquid-glass-bundle.js` still ship in the npm package because of `files: ["lib"]`, but the **client no longer references them** (WebGL was removed in v3.6.0 in favor of the CSS version); the host still serves the `/api/mpkg-wallpaper/lg` route (no callers). Local backups such as `lib/client.js.bak-*` are excluded by the negative `files` patterns (`!lib/**/*.bak*`) and are **not shipped** — enforced by section ⑨ of `tools/integrity-check.mjs`.
-> Why `dist/` is **not committed**: it is a pure derivative of `lib/*.js` (an inlined artifact) that duplicates tracked sources byte for byte, and two builds are byte-identical (machine-asserted in `tools/bundle-equivalence-test.mjs` §②); committing it would only create drift ("edited lib, forgot to rebuild") . By contrast `lib/liquid-glass-bundle.js` **is** committed because it *used to be* a **runtime input** (base64 written into `lib/client.js` by `tools/inline-lg-bundle.mjs`) — ⚠ **measured 2026-09-18: that link is dead**: neither `LG_BUNDLE_B64` nor `LG_BUNDLE_SRC` exists in `lib/client.js` (the only `B64` hit is a comment), and both inline tools now fail with "missing placeholder". It is therefore currently **neither referenced by the client nor a runtime input**; it merely ships via `files: ["lib"]` and can be rebuilt **byte-identically** from the kept sources. `dist/` is also outside the `files` whitelist, so the npm package never carries it.
+> Note: `lib/liquid-glass/` and `lib/liquid-glass-bundle.js` **have been moved off the publish surface** (negative `files` patterns `!lib/liquid-glass/**` + `!lib/liquid-glass-bundle.js`, P-127 ⇒ **not in the npm package**; measured 22 files/1 626 235 B → 12 files/1 389 781 B), yet **all of them stay in the repo**, and the **client no longer references them** (WebGL was removed in v3.6.0 in favor of the CSS version); the host still keeps the `/api/mpkg-wallpaper/lg` route (live path, no callers; in-repo development/demos unaffected, an npm-installed copy returns 404 by design). Local backups such as `lib/client.js.bak-*` are likewise excluded by negative `files` patterns (`!lib/**/*.bak*`) and are **not shipped**; both are guarded by **two-way** machine assertions in section ⑨ of `tools/integrity-check.mjs` ("not on the publish surface" **and** "none of them may disappear from the repo").
+> Why `dist/` is **not committed**: it is a pure derivative of `lib/*.js` (an inlined artifact) that duplicates tracked sources byte for byte, and two builds are byte-identical (machine-asserted in `tools/bundle-equivalence-test.mjs` §②); committing it would only create drift ("edited lib, forgot to rebuild") . By contrast `lib/liquid-glass-bundle.js` **is** committed because it *used to be* a **runtime input** (base64 written into `lib/client.js` by `tools/inline-lg-bundle.mjs`) — ⚠ **measured 2026-09-18: that link is dead**: neither `LG_BUNDLE_B64` nor `LG_BUNDLE_SRC` exists in `lib/client.js` (the only `B64` hit is a comment), and both inline tools now fail with "missing placeholder". It is therefore currently **neither referenced by the client nor a runtime input**; it **stays in the repo** (off the npm package since P-127) and can be rebuilt **byte-identically** from the kept sources. `dist/` is also outside the `files` whitelist, so the npm package never carries it.
 
 ## Acknowledgements
 

package/README.md

@@ -71,7 +71,7 @@
 - 基于 CSS `backdrop-filter` 的半透明 + 模糊 + 边缘高光（**不再是 WebGL 折射版**——WebGL 液态玻璃已在 v3.6.0 移除，见下）。分四个开关：
   - **lgTest（测试模式）**：只保留壁纸 + 悬浮 + 布局，不覆盖任何 DSH token（否则背景读半透明会让聊天框透明无模糊）
   - **lgComposer / lgSidebar / lgHeader**：分别给聊天气泡区、侧边栏、标题栏加液态玻璃叠加层（侧边栏因设置弹窗渲染层级限制，只能做半透明 + 边缘高光，**不能加 backdrop-filter**，否则会把设置弹窗压缩进侧边栏——历史踩坑）
-- **历史说明**：早期版本用的是 WebGL 真折射（`lib/liquid-glass/` 库 + `liquid-glass-bundle.js` 107KB）；因不稳定且体积大，v3.6.0 已删掉 WebGL 运行时，改用纯 CSS 版。`lib/liquid-glass/*.js`、`liquid-glass-bundle.js` 仍在仓库并**随包发布**（`files: ["lib"]`），**客户端已无任何引用**，但**宿主端那条静态托管路由是活路径**（`/api/mpkg-wallpaper/lg/<file>.js` 命中时真的 `readFileSync` 读 `lib/liquid-glass/<file>`），`tools/liquid-demo/` 的演示页也改走同一条挂载（P-122）。`tools/liquid-demo/` 只留在仓库、**不进发布包**（`files` 白名单不含 `tools/`）。⇒ 它们**不是死文件**，删与否属发布面决定（复核见 `docs/LIQUID-GLASS-DEDUP.md`）。
+- **历史说明**：早期版本用的是 WebGL 真折射（`lib/liquid-glass/` 库 + `liquid-glass-bundle.js` 107KB）；因不稳定且体积大，v3.6.0 已删掉 WebGL 运行时，改用纯 CSS 版。`lib/liquid-glass/*.js`、`liquid-glass-bundle.js` **仍在仓库、但已移出发布面**（`files` 负向模式 `!lib/liquid-glass/**` + `!lib/liquid-glass-bundle.js` ⇒ **不进 npm 包**，P-127）：**客户端已无任何引用**（`lgModule` 只声明、从未赋值），但**宿主端那条静态托管路由仍是活路径**（`/api/mpkg-wallpaper/lg/<file>.js` 命中时真的 `readFileSync` 读 `lib/liquid-glass/<file>`；仓库内开发/演示照旧），`tools/liquid-demo/` 的演示页也走同一条挂载（P-122）。`tools/liquid-demo/` 只留在仓库、**不进发布包**（`files` 白名单不含 `tools/`）。⇒ 它们**不是死文件**；**移出发布面 ⇒ 不再分发这 10 个文件 ⇒ MIT 署名义务面随之消失**，但仓库内**一个不少**、仍如实登记 10 个 sha256（`THIRD-PARTY.md` §1.3；发布面数字与判据见 `docs/PUBLISH-SURFACE-LIQUID-GLASS.md` P-127）。
 
 **🎬 镜头与画面**
 - 镜头缩放（10–2000%）与平移、画面亮度（50–150%）、轻度锐化、Deep diving 背景框
@@ -249,8 +249,8 @@
 门禁第 12 步把它变成会变红的机器判据（`node tools/style-scope-guard.mjs`）：
 
 * **拿真实产物**：不重写 `buildCss`，用 `tools/_stub.mjs` 在 Node 里跑 `lib/client.js`，调用插件自己暴露的
-  `__mpwBuildCss(patch)`，按源码里的 `boolFields`/`numFields` 自动枚举 **600+ 组设置**（当前 613：默认段 /
-  每个布尔开关单独开 / 核心 9 开关全 512 组合 / bsCompat 家族 / 数值 0 与 100 / 无壁纸 / lgTest），
+  `__mpwBuildCss(patch)`，按源码里的 `boolFields`/`numFields` 自动枚举 **600+ 组设置**（实跑会打印条数；
+  本轮 615：默认段 / 每个布尔开关单独开 / 核心 9 开关全 512 组合 / bsCompat 家族 / 数值 0 与 100 / 无壁纸 / lgTest），
   再对生成出来的 CSS 逐条解析（含 `@media`/`@supports`）。
 * **判据**：每条规则的选择器必须命中我们自己的标记（`.mpw*` / `[data-mpw*]` / `#mpw-*`），或命中**已登记**的
   宿主/第三方作用域——`bsCompat` 那句故意打第三方 DOM 的 `[data-dsh-better-sidebar] …` 也在其列，
@@ -292,6 +292,8 @@
 * 非布尔功能（`accent`/`aquaTextEnhance` 设值必须改变产物）；`themeColor` 属"CSS 常驻 + 运行时属性门控"，
   判据改为断言门控规则确实在产物里。
 * **已证实失效**的开关进 `KNOWN_DEAD` 并在每次运行时显式列出（双向断言：修好了必须从表里删）。
+  **该表现已清空**（`lgCss`/`sessionFollow` 已修好、`glassWindow` 已退役删除）；**退役**（删掉）的开关改由
+  A0 段看住"源码 0 悬空引用 + zh/en 两套字典 0 孤儿文案"，各配一条常驻变异（加回去必须变红）。
   本轮据此修掉了第 1 条：**`lgCss`（纯 CSS/SVG 液态玻璃）整块从未执行** —— 块内引用 `bdSupported`，
   而该 const 声明在它之后 ⇒ 同一函数作用域 TDZ `ReferenceError`，被外层
   `catch { /* 液态玻璃失败不得影响其它样式 */ }` 吞掉（catch 原样保留，现在只在真的失败时才起作用）。
@@ -300,7 +302,13 @@
   第 2 条也修了：**`sessionFollow`（新会话按钮跟随面板不透明度）**——设置页有开关 + 文案，但全仓无人读
   `section.sessionFollow`；按**用户可见文案**实现（开 = 跟随那条透明度，关 = **回到宿主原色**），默认档不变，
   判据在 `tools/switch-wiring-test.mjs` 的 A4 段（默认档 + 统一虚化档各 3 条双向断言；变异「把读取删掉」必红）。
-  第 3 条 `glassWindow` 仍登记未改（只有文案没有实现），详见
+  第 3 条 `glassWindow` 已按**用户政策「不留看得见却点不动」**处理：它**既无 toggleRow（没人看得见）、
+  也无读取点（点不动）**，而文案承诺的功能已由 `settingsBlur`（设置面板虚化）+ `dialogBlur`/`popoverBlur`
+  覆盖 ⇒ **删文案 + 删字段**（不接线，避免多出第二个管同一元素的开关、也避免把设置面板变成 backdrop root）。
+  删除点 6 处（zh/en i18n 各 2 行 + `lgTest` 预设默认值 + 重置默认值 + `BACKUP_FIELDS` + 导入 `boolFields`，
+  导出/净化**同步删**以免导入备份时落进"未登记类型"兜底）；判据在 `tools/switch-wiring-test.mjs` 的 **A0 段**
+  （源码 0 命中 + zh/en 两套字典 0 命中）+ 常驻变异 `retired-glasswindow-copy-restored` 必红；
+  删前删后**默认档产物 sha256 逐字节相同**。详见
   [`docs/TOKEN-NAMESPACE.md`](docs/TOKEN-NAMESPACE.md) §3b。
   **`bsCompat`（better-sidebar 适配总开关）默认已改为开**（2026-09-18 用户裁定）：底部面板悬浮适配已真机定案，
   默认关 = 没人看得见；存量用户**只在"从没显式设过"时**被迁移，**手动关过的绝不覆盖**（写入口打
@@ -315,6 +323,26 @@
   （`(headerBlur || unifyTint) && headerBg`，与 `css-matrix` 断言 7 同口径）—— 两条断言都没放宽。
 * 分辨力自证：把 `accent` / `aquaTextEnhance` 的门控改回被 `aquaOn` 包住 ⇒ 必须变红（两条变异）。
 
+## 提交前门禁（秒级 pre-commit，2026-09-19 / P-129）
+
+上面这条审计（以及面板渲染回归）已经抽成**秒级 pre-commit**，**提交前 4 秒**就能拦住"开关没接线""面板渲染坏了"这两类**已经真实发生过多次**的事故：
+
+```sh
+cd dsh-mpkg-wallpaper
+git config core.hooksPath .githooks    # 装载（只影响本机 clone；git config --unset core.hooksPath 卸载）
+git commit --no-verify                 # 单次绕过
+MPW_SKIP_PRECOMMIT=1 git commit -m …   # 单次绕过（走脚本内显式口，恒 exit 0）
+```
+
+* **跑什么**：`tools/panel-smoke.mjs`（面板渲染 + 语言字典，~0.3 s）+ `tools/switch-wiring-test.mjs`
+  （每个开关必须真的改变产物 + 退役开关 0 悬空引用 + 7 条分辨力变异自证，~2.5 s），**串行**，多次实测合计
+  **2.8–3.9 s**。
+* **不跑什么**：`tools/check.sh` 的 12 步（第 3 步 1115 组 CSS 矩阵、第 9 步起无头 Firefox）**不进** pre-commit
+  —— 分钟级门禁塞进 pre-commit 只会让人"改一行不敢提交"。完整门禁仍是 `bash tools/check.sh`（或 CI）。
+* **不阻塞开发**：装载是显式的（不装零影响）；暂存区只动了非产物路径（无 `lib/`·`tools/`·`package.json`）⇒ **直接跳过**；
+  缺 `node`/缺脚本 ⇒ 打印一句就 `exit 0`；失败会**原样打印红行**并提示绕过方式，不改文件、不自动 fix。
+* **细节、全部实测输出与未证实项**：[`docs/PRE-COMMIT.md`](docs/PRE-COMMIT.md)。
+
 ## 视频壁纸转码：判定是"误判" + 资源上限（2026-09-17，第 1 条）
 
 > 用户原话：「我现在并没有使用视频转码，我用的是 **video 类的 mpkg**，然后**解码帧率无上限**，
@@ -541,8 +569,8 @@ dsh-mpkg-wallpaper/
 │   ├── web-interaction.js # 网页壁纸交互（第 11 条）：坐标换算/事件整形/交互模式状态机/舞台契约（MIT，自写；语义参照 webwallgl）
 │   ├── client.js     # 浏览器端：mpkg 解析 + 设置页 + 背景 DOM + 虚化体系 + 壁纸库 + 时间变化/网页设置 + 播放控制/省电
 │   ├── pkg-extract.js# scene.pkg 静态帧/图层提取（PKG+LZ4+TEX，MIT，来自 elysia395）
-│   ├── liquid-glass/ # 液态玻璃 WebGL 库（**遗留**：客户端无引用，宿主仍托管 `/lg` 路由，v3.6.0 已改 CSS 版）
-│   ├── liquid-glass-bundle.js # 液态玻璃打包产物（107KB，**客户端无引用**；可由保留源逐字节重建，sha256 db50361c…）
+│   ├── liquid-glass/ # 液态玻璃 WebGL 库（**遗留 · 不进发布包**：客户端无引用，宿主仍托管 `/lg` 路由，v3.6.0 已改 CSS 版）
+│   ├── liquid-glass-bundle.js # 液态玻璃打包产物（107KB，**不进发布包**；客户端无引用，可由保留源逐字节重建，sha256 db50361c…）
 │   └── THIRD-PARTY.md # 第三方来历/洁净室记录与许可归属（**随包发布**，MIT 侧署名）
 ├── tools/            # 门禁/测试/基准脚本 + lg 构建/内联脚本 + liquid-demo 演示页（供开发者）
 │                     # 音频扫描：audio-scan-bench.mjs（耗时表）/ audio-scan-test.mjs（规格断言 · 不整包解压 · 缓存）
@@ -553,6 +581,8 @@ dsh-mpkg-wallpaper/
 │                     #           bundle-equivalence-test.mjs（门禁第 11 步：同一套路由断言打源码与 bundle + 变异对照）
 │                     # 样式作用域：style-scope-guard.mjs（门禁第 12 步：注入的每条 CSS 规则都必须命中 .mpw*/[data-mpw*]，
 │                     #           宿主/第三方作用域必须登记在允许清单里（带 reason + docs 指针）；裸元素/:root 覆盖判红）
+│                     # 提交前门禁：pre-commit.sh（秒级：panel-smoke + switch-wiring，含路径过滤与绕过口；
+│                     #           配 ../.githooks/pre-commit，装载见 README「提交前门禁」/ docs/PRE-COMMIT.md）
 │                     # 注：研究期的 Python 工具（unmpkg/tex2png/mdl_explorer/xref）
 │                     #     **已删除（GPL 血缘存疑，2026-09-16）**，见 `../docs/COPYING-RULES.md` §6
 ├── dist/             # 构建产物（**不入库**，.gitignore 忽略）：dsh-mpkg-wallpaper.bundle.mjs（方式四用，现生成）
@@ -562,8 +592,8 @@ dsh-mpkg-wallpaper/
 ├── README.md         # 本文件（中文）
 └── README.en.md      # 英文说明
 ```
-> 注：`lib/liquid-glass/`、`lib/liquid-glass-bundle.js` 因 `files: ["lib"]` 仍会打进 npm 包，但**客户端不再引用**（WebGL 已在 v3.6.0 移除，改用 CSS 版）；宿主仍保留 `/api/mpkg-wallpaper/lg` 托管路由（无调用方）。本地备份 `lib/client.js.bak-*` 已被 `files` 负向模式（`!lib/**/*.bak*`）排除，**不进发布包**，由 `tools/integrity-check.mjs` 第 ⑨ 节机器断言把关。
-> `dist/` 为什么**不入库**：它是 `lib/*.js` 的纯派生物（内联产物），与被跟踪源码逐字节重复；两次构建 sha256 逐字节相同（`tools/bundle-equivalence-test.mjs` 第②节机器断言），入库只会制造"改了 lib 忘了重跑 bundle"的漂移。对照：`lib/liquid-glass-bundle.js` **入库**是因为它历史上曾是**运行期输入**（由 `tools/inline-lg-bundle.mjs` 把 base64 写进 `lib/client.js` 的模板常量）——⚠ **2026-09-18 实测该链路已失效**：`lib/client.js` 里 `LG_BUNDLE_B64`/`LG_BUNDLE_SRC` 常量**都不存在**（全文 `B64` 仅 1 处，是注释），两个 inline 工具现在跑会报「缺少占位区」；因此它当前**既不被客户端引用、也不再是运行期输入**，只是随 `files: ["lib"]` 打进包，且可由保留源**逐字节重建**（`node tools/build-lg-bundle.mjs` ⇒ sha256 与入库那份相同）。`dist/` 也不在 `files` 白名单 ⇒ npm 包不夹带。
+> 注：`lib/liquid-glass/`、`lib/liquid-glass-bundle.js` **已移出发布面**（`files` 负向模式 `!lib/liquid-glass/**` + `!lib/liquid-glass-bundle.js`，P-127 ⇒ **不进 npm 包**，实测发布面 22 文件/1 626 235 B → 12 文件/1 389 781 B），但**仓库内一个不少**、**客户端不再引用**（WebGL 已在 v3.6.0 移除，改用 CSS 版）；宿主仍保留 `/api/mpkg-wallpaper/lg` 托管路由（活路径、无调用方；本机开发/演示照旧，从 npm 安装的副本上按设计返回 404）。本地备份 `lib/client.js.bak-*` 同样由 `files` 负向模式（`!lib/**/*.bak*`）排除，**不进发布包**；两者都由 `tools/integrity-check.mjs` 第 ⑨ 节**双向**机器断言把关（"不在发布面" + "仓库内不能少"）。
+> `dist/` 为什么**不入库**：它是 `lib/*.js` 的纯派生物（内联产物），与被跟踪源码逐字节重复；两次构建 sha256 逐字节相同（`tools/bundle-equivalence-test.mjs` 第②节机器断言），入库只会制造"改了 lib 忘了重跑 bundle"的漂移。对照：`lib/liquid-glass-bundle.js` **入库**是因为它历史上曾是**运行期输入**（由 `tools/inline-lg-bundle.mjs` 把 base64 写进 `lib/client.js` 的模板常量）——⚠ **2026-09-18 实测该链路已失效**：`lib/client.js` 里 `LG_BUNDLE_B64`/`LG_BUNDLE_SRC` 常量**都不存在**（全文 `B64` 仅 1 处，是注释），两个 inline 工具现在跑会报「缺少占位区」；因此它当前**既不被客户端引用、也不再是运行期输入**，只是**留在仓库**（P-127 起**不再进包**），且可由保留源**逐字节重建**（`node tools/build-lg-bundle.mjs` ⇒ sha256 与入库那份相同）。`dist/` 也不在 `files` 白名单 ⇒ npm 包不夹带。
 
 ## 致谢
 

package/THIRD-PARTY.md

@@ -42,13 +42,16 @@
 
 > ①(2026-09-18，P-122) 本节按逐副本复核结果重写；复核全过程（引用面/身份/判据/反向自证）见
 > `docs/LIQUID-GLASS-DEDUP.md`。
+> ①(2026-09-19，**P-127**) **发布面变更**：这 10 个文件已用 `files` 负向模式移出发布面 ⇒
+> **不再随包分发**（详见 `docs/PUBLISH-SURFACE-LIQUID-GLASS.md`）。下方"发布面/署名"两处口径已同步；
+> **仓库内 10 个文件一个不少**，sha256 登记照旧。
 
 | 项 | 内容 |
 |---|---|
 | 涉及文件 | `lib/liquid-glass/*.js`（9 文件，129 097 B，5830 行）+ 其派生产物 `lib/liquid-glass-bundle.js`（107 420 B，2611 行） |
 | 出处 | 外部 MIT 项目 **`apple-liquid-glass-webgl`**。**唯一记录是提交 `d13019d`**（2026-08-24）的说明："复用 apple-liquid-glass-webgl（MIT，零依赖）源码 → lib/liquid-glass/ + vendor/" |
-| 许可 | **MIT**（MIT 要求随副本携带版权声明与许可正文） |
-| 发布面 | 随包发布（`files: ["lib"]` 为目录级白名单 ⇒ 上述 10 个文件全部进 npm 包，实测见 `docs/LIQUID-GLASS-DEDUP.md` §1②、§4 第 6 项） |
+| 许可 | **MIT**（MIT 要求**随副本**携带版权声明与许可正文 —— 见下方"署名义务面"） |
+| 发布面 | **不随包发布**（①P-127：`files` 负向模式 `!lib/liquid-glass/**` + `!lib/liquid-glass-bundle.js`；实测发布面 22 文件/1 626 235 B → 12 文件/1 389 781 B，`tools/integrity-check.mjs` 第 ⑨ 节双向断言把关）。**文件仍在仓库内**（旧的"随包发布"登记见 `docs/LIQUID-GLASS-DEDUP.md` §1②、§4 第 6 项，那是 P-127 之前的口径） |
 | 运行期引用 | 宿主路由 `GET /api/mpkg-wallpaper/lg/<file>.js` 在命中时 `readFileSync` 读取 `lib/liquid-glass/<file>`（`lib/index.js:3299-3314`）。客户端**无**调用方（`lib/client.js` 无 `liquid-glass` 引用、无动态 import） |
 | 副本数 | **1 份**（原 `tools/liquid-demo/vendor/` 的 9 文件与 `lib/liquid-glass/` sha256 两两相同 ⇒ 2026-09-18 已删，演示页改为加载唯一一份） |
 
@@ -56,10 +59,22 @@
 对这 9 个文件 + bundle 逐个 grep，`MIT License` / `Copyright (c)` / `Copyright ©` /
 `SPDX-License-Identifier` / `Permission is hereby granted` / `The above copyright`
 命中数**全部为 0**，也没有任何上游 URL（`github`/`http`/`apple-liquid` 命中 0）。
-⇒ 保留副本**不带上游署名**；署名义务目前**只**由本文件 + 提交记录承担。
+⇒ 保留副本**不带上游署名**；署名义务**只**由本文件 + 提交记录承担。
 补法（未做，见 `docs/LIQUID-GLASS-DEDUP.md` §9 第 1 项）：找到上游后把其 LICENSE 正文与版权行
 落到本文件或随附文件。
 
+**署名义务面（①2026-09-19，P-127 后的准确口径）**：MIT 的署名要求是"**随副本**携带版权与许可声明"。
+①P-127 把这 10 个文件**移出发布面** ⇒ **本包不再分发这些副本** ⇒ **该义务面随之消失**
+（`tools/integrity-check.mjs` 第 ⑨ 节逐条断言这 10 个路径**不在** npm 包里）。
+**但这不等于可以不管**：
+
+1. 仓库里**仍保留**这 10 个文件（宿主 `/lg` 路由 + 演示页运行期要读）⇒ 本节继续**如实登记**
+   出处/许可/sha256，并且**如实写明文件内没有版权行**（不粉饰）；
+2. 一旦有人**再分发**它们（fork 后单独打包、再次 vendor 进别的项目、把 `lib/liquid-glass/`
+   加回 `files`），**必须先把上游 LICENSE 正文与版权行补到本文件或随附文件**——
+   上游 URL/commit/版本号至今**未被证实**（`docs/LIQUID-GLASS-DEDUP.md` §9 第 1 项），
+   所以"再分发"这条路目前**走不通**，这也是把版权风险留在仓库内、不随包外发的原因之一。
+
 **sha256 登记（`sha256sum` 实测，2026-09-18；删除副本前对真树取，跑完复核 10/10 未变）**：
 
 ```
@@ -77,7 +92,8 @@ db50361cfd3d860602ddc2ff8bd1b6567ff01f471df1eccb60b3bcbfbbb0cd08  lib/liquid-gla
 
 - `lib/liquid-glass-bundle.js` 是**派生产物**（`tools/build-lg-bundle.mjs` 拼接上面 7 个 V2 文件，
   去 `import`/改写 `export`）：在副本上重跑该工具，产物 sha256 与上表**逐字节相同** ⇒ 无独立信息，
-  但仍在发布白名单内，故保留（理由见 `docs/LIQUID-GLASS-DEDUP.md` §6）。
+  但仍**留在仓库**（P-127 起**不进发布面**），保留理由见 `docs/LIQUID-GLASS-DEDUP.md` §6 与
+  `docs/PUBLISH-SURFACE-LIQUID-GLASS.md` §3。
 - 若将来引入任何**其它**第三方代码（含 GPL-3.0 的渲染器侧代码），**不得**进入本 MIT 包，
   只允许进渲染器并按 `../docs/COPYING-RULES.md` 登记台账。
 

package/lib/client.js

@@ -5961,7 +5961,7 @@ ${selDark} {
 					chatFollow: false, sessionFollow: false, sidebarBlur: false, sidebarBlurAmount: 0,
 					headerBlur: false, headerBlurAmount: 0, headerBg: false, aquaMask: false, aquaTint: false,
 					aquaInk: false, aquaTextEnhance: false, todoBlur: false, clock: false, clock24h: false,
-					clockSec: false, clockDate: false, themeColor: "", accent: "", glassWindow: false,
+					clockSec: false, clockDate: false, themeColor: "", accent: "",
 					// ①(修正) lgTest 测试模式下侧边栏**不透明**（sidebar:false）：用户实测
 					// 测试模式侧边栏透壁纸，界面花、看不清内容。测试模式要的是干净对比界面
 					// （壁纸在右侧聊天区可测玻璃），侧边栏不透明便于看清。
@@ -10014,7 +10014,7 @@ body[data-mpw-modal] [role="dialog"] {
 					hybrid: DEFAULT_HYBRID, roundCompat: DEFAULT_ROUND_COMPAT,
 					rotate: DEFAULT_ROTATE, rotateMin: 5, customDirPath: "", brightness: DEFAULT_BRIGHTNESS, float: DEFAULT_FLOAT,
 					playbackRate: DEFAULT_PLAYBACK_RATE, rotGroups: [], rotGroupId: "", rotSeeded: false,
-					glassColor: "", glassAlpha: 12, glassWindow: false, accent: "", newStyle: false, mute: true,
+					glassColor: "", glassAlpha: 12, accent: "", newStyle: false, mute: true,
 					thinkBg: DEFAULT_THINK_BG,
 					bsCompat: DEFAULT_BS_COMPAT, bsFloat: false, bsFont: false, bsReveal: false, bsAlpha: false, bsAqua: false, bsBottomAvoid: false,
 					enabled: DEFAULT_ENABLED
@@ -10032,7 +10032,7 @@ body[data-mpw-modal] [role="dialog"] {
 				"dialogBlur", "dialogAmount", "popoverBlur", "popoverAmount", "maskBlur", "maskAmount",
 				"unifyTint", "unifyAmount", "sidebarAlpha", "chatFollow", "sessionFollow",
 				"aquaMask", "aquaTint", "aquaInk", "aquaColor", "aquaInkColor", "aquaTextEnhance", "todoBlur",
-				"aquaMaskAlpha", "aquaTintStrength", "themeColor", "accent", "glassColor", "glassAlpha", "glassWindow",
+				"aquaMaskAlpha", "aquaTintStrength", "themeColor", "accent", "glassColor", "glassAlpha",
 				"hybrid", "roundCompat", "rotate", "rotateMin", "rotGroups", "rotGroupId", "rotSeeded",
 				"brightness", "float", "playbackRate", "newStyle", "mute", "thinkBg", "enabled",
 				"forceEnabled", "propEdits", "clock", "clock24h", "clockSec", "clockDate", "clockPos", "clockSize",
@@ -10074,7 +10074,7 @@ body[data-mpw-modal] [role="dialog"] {
 						// ①(修正) 类型校验（评审指出：原实现直接透传，`opacity:"abc"` 会污染设置）：
 						// 数值类必须为有限数、布尔类必须为 boolean、字符串类必须为 string。
 						const numFields = ["opacity", "blur", "zoom", "headerBlurAmount", "headerFrostAmount", "dialogAmount", "popoverAmount", "popoverAlpha", "maskAmount", "unifyAmount", "sidebarAlpha", "aquaMaskAlpha", "aquaTintStrength", "glassAlpha", "lgCssAmount", "rotateMin", "brightness", "playbackRate", "clockSize", "fpsCap", "resMax", "bsRevealAlpha", "sceneWatchdogSecs"]; // ①(批次15) 四处接线③：导入数值净化
-						const boolFields = ["sidebar", "sharp", "headerBlur", "headerBg", "rightSidebarBlur", "dialogBlur", "popoverBlur", "maskBlur", "unifyTint", "chatFollow", "sessionFollow", "aquaMask", "aquaTint", "aquaInk", "aquaTextEnhance", "todoBlur", "hybrid", "roundCompat", "rotate", "float", "newStyle", "mute", "thinkBg", "enabled", "forceEnabled", "clock", "clock24h", "clockSec", "clockDate", "glassWindow", "bsCompat", "bsFloat", "bsFont", "bsReveal", "bsAlpha", "bsAqua", "bsBottomAvoid", "lgTest", "lgCss", "lgComposer", "lgSidebar", "lgHeader", "powPauseHidden", "powPauseBlur", "powPauseBattery", "sceneWatchdog"]; // ①(批次15) 四处接线④：导入布尔净化
+						const boolFields = ["sidebar", "sharp", "headerBlur", "headerBg", "rightSidebarBlur", "dialogBlur", "popoverBlur", "maskBlur", "unifyTint", "chatFollow", "sessionFollow", "aquaMask", "aquaTint", "aquaInk", "aquaTextEnhance", "todoBlur", "hybrid", "roundCompat", "rotate", "float", "newStyle", "mute", "thinkBg", "enabled", "forceEnabled", "clock", "clock24h", "clockSec", "clockDate", "bsCompat", "bsFloat", "bsFont", "bsReveal", "bsAlpha", "bsAqua", "bsBottomAvoid", "lgTest", "lgCss", "lgComposer", "lgSidebar", "lgHeader", "powPauseHidden", "powPauseBlur", "powPauseBattery", "sceneWatchdog"]; // ①(批次15) 四处接线④：导入布尔净化
 						const strFields = ["aquaColor", "aquaInkColor", "themeColor", "accent", "glassColor", "clockPos", "fontColorGrayColor", "sceneDebugParams"]; // ①(批次15) sceneDebugParams 走字符串净化（非法键/值在写入端丢弃）
 						for (const k of BACKUP_FIELDS) {
 							const v = settings[k];
@@ -12364,8 +12364,6 @@ body[data-mpw-modal] [role="dialog"] {
 			"todoBlur": "任务列表磨砂",
 			"glass.title": "液态玻璃（elysia395 方案）",
 			"glass.desc": "设置卡片/弹窗玻璃化：玻璃底色 + 白叠层强度 + 总开关（与 Aqua 其他功能独立，默认关）",
-			"glassWindow": "设置窗口液态玻璃",
-			"glassWindow.desc": "整个设置卡片/弹窗玻璃化（半透明 + 模糊 + 底色 tint）",
 			"glass.accent": "配色（accent）",
 			"glass.accent.hint": "驱动按钮/滑条/选中/链接/发送键等品牌交互元素（与主题颜色分工：它管整体底色）",
 			"glass.color": "玻璃颜色",
@@ -13032,8 +13030,6 @@ body[data-mpw-modal] [role="dialog"] {
 			// ①(P-66 真 bug 修复) 补齐 zh 有、en 缺的 18 个键（缺键 → 英文界面直接显示 key 原文）
 			"glass.title": "Liquid glass (elysia395 approach)",
 			"glass.desc": "Glassmorphism for the settings card/dialog: glass tint + white overlay strength + master switch (independent of the other Aqua features; off by default)",
-			"glassWindow": "Liquid glass on the settings window",
-			"glassWindow.desc": "Turn the whole settings card/dialog into glass (translucent + blur + background tint)",
 			"glass.accent": "Accent color",
 			"glass.accent.hint": "Drives brand interactive elements (buttons/sliders/selection/links/send button); the theme color owns the overall background tint",
 			"glass.color": "Glass color",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mpkg-wallpaper",
-  "version": "3.7.2",
+  "version": "3.7.3",
   "description": "DSH Web 壁纸引擎 Wallpaper Engine mpkg 背景插件：浏览器内直接解析 .mpkg（preview.gif 动态背景/内嵌 mp4 视频/多时段切换），整屏统一虚化/对话框/弹层/遮罩独立虚化、镜头缩放平移、时钟、冲突检测。",
   "private": false,
   "type": "module",
@@ -10,6 +10,8 @@
     "!lib/**/*.bak*",
     "!lib/**/*.tmp*",
     "!lib/**/*.orig",
+    "!lib/liquid-glass/**",
+    "!lib/liquid-glass-bundle.js",
     "icon.svg",
     "cordis.patch.yml",
     "README.md",

package/lib/liquid-glass/geometry.js

@@ -1,229 +0,0 @@
-// CPU mirror of the shape maths in FS_GLASS.
-//
-// The shader is the source of truth for what the glass looks like, but callers
-// also need the same geometry on the CPU: to know which component the pointer
-// is over, and to split a large element list into groups that cannot influence
-// each other. Keeping both in this module - free of any WebGL or DOM
-// dependency - is what makes those rules unit-testable.
-//
-// Every length here is in the same unit as the element coordinates (CSS pixels
-// for the public API). The renderer applies `dpr` separately.
-
-// The glass shader carries the group in uniform arrays of this length.
-export const MAX_GLASS_SHAPES = 16;
-
-// `sdGroup` weights each shape by exp(-(d - nearest) / scale). Past this many
-// multiples of `scale` the contribution is below 1/3000 of a pixel of distance,
-// which is far under the quantisation of the RGBA8 output. Shapes separated by
-// more than that can be shaded in different draw calls without a visible seam.
-const MERGE_INFLUENCE_SCALES = 8;
-
-// Matches the shader: scale = max(mergeRadius * 0.36, 0.01).
-const MERGE_SCALE_RATIO = 0.36;
-
-// Apple's folder corner is capped at 23.5% of the short side.
-const MAX_CORNER_RATIO = 0.235;
-
-export const SHAPE_TYPES = Object.freeze({ rect: 0, folder: 0, pill: 1, circle: 2 });
-
-export function shapeTypeOf(shape) {
-  return SHAPE_TYPES[shape] ?? 0;
-}
-
-/** Corner radius the renderer will use for an element, before `dpr`. */
-export function cornerRadiusOf(element, materialRadius = 0) {
-  const short = Math.min(element.w ?? element.width ?? 0, element.h ?? element.height ?? 0);
-  return Math.min(element.radius ?? materialRadius, short * MAX_CORNER_RATIO);
-}
-
-/** Superellipse rounded box, mirroring `sdSquircle` in the glass shader. */
-export function sdSquircle(px, py, halfX, halfY, radius, exponent) {
-  const qx = Math.abs(px) - halfX + radius;
-  const qy = Math.abs(py) - halfY + radius;
-  const mx = Math.max(qx, 0) + 1e-5;
-  const my = Math.max(qy, 0) + 1e-5;
-  const e = (mx ** exponent + my ** exponent) ** (1 / exponent);
-  return Math.min(Math.max(qx, qy), 0) + e - radius;
-}
-
-/** Mirrors `sdPrimitive`: exact circle, exact capsule, or squircle folder. */
-export function sdPrimitive(px, py, halfX, halfY, shapeType, radius, squircle = 2) {
-  if (shapeType === 2) return Math.hypot(px, py) - Math.min(halfX, halfY);
-  if (shapeType === 1) return sdSquircle(px, py, halfX, halfY, Math.min(halfX, halfY), 2);
-  return sdSquircle(px, py, halfX, halfY, radius, Math.max(squircle, 2));
-}
-
-function toShape(element, material) {
-  const w = element.w ?? element.width ?? element.size ?? 0;
-  const h = element.h ?? element.height ?? element.size ?? w;
-  return {
-    cx: (element.x ?? 0) + w / 2,
-    cy: (element.y ?? 0) + h / 2,
-    halfX: w / 2,
-    halfY: h / 2,
-    type: shapeTypeOf(element.shape),
-    radius: cornerRadiusOf({ ...element, w, h }, material.radius ?? 0),
-  };
-}
-
-/**
- * Signed distance to the fused silhouette of `elements`, in element
- * coordinates. Mirrors `sdAppleShape`, including the global exponential
- * smooth-min, so a hit test agrees with the pixels the shader produced.
- *
- * The smooth-min pulls the surface inward by at most `scale * ln(2)`, which is
- * a quarter of `mergeRadius`. A gap between two components therefore only
- * closes into a bridge while it is narrower than about `mergeRadius / 2`;
- * beyond that the fusion distance only softens the approach.
- */
-export function sdGroup(x, y, elements, material = {}, mergeRadius = material.mergeRadius ?? 0) {
-  if (!elements.length) return Infinity;
-  const shapes = elements.map((element) => toShape(element, material));
-  const squircle = material.squircle ?? 2;
-
-  let nearest = Infinity;
-  const distances = shapes.map((shape) => {
-    const d = sdPrimitive(x - shape.cx, y - shape.cy, shape.halfX, shape.halfY,
-                          shape.type, shape.radius, squircle);
-    if (d < nearest) nearest = d;
-    return d;
-  });
-
-  if (!(mergeRadius >= 0.01) || shapes.length === 1) return nearest;
-
-  const scale = Math.max(mergeRadius * MERGE_SCALE_RATIO, 0.01);
-  let sum = 0;
-  for (const d of distances) sum += Math.exp(-(d - nearest) / scale);
-  return nearest - scale * Math.log(Math.max(sum, 1e-6));
-}
-
-/**
- * The element whose own primitive is nearest to the point, or `null` when the
- * point is outside the fused surface. `tolerance` grows the hit area, which is
- * what a coarse pointer (touch) wants.
- */
-export function hitTestElements(x, y, elements, material = {}, options = {}) {
-  const mergeRadius = options.fusion === false
-    ? 0
-    : (options.mergeRadius ?? material.mergeRadius ?? 0);
-  const tolerance = options.tolerance ?? 0;
-  const squircle = material.squircle ?? 2;
-
-  // Separate elements are separate draw calls. The last one painted owns every
-  // overlapping pixel, regardless of how deeply the point lies inside an older
-  // element. Picking the most-negative distance here would make a large card
-  // steal clicks from a smaller button drawn on top of it.
-  if (options.fusion === false) {
-    for (let i = elements.length - 1; i >= 0; i--) {
-      const shape = toShape(elements[i], material);
-      const d = sdPrimitive(x - shape.cx, y - shape.cy, shape.halfX, shape.halfY,
-                            shape.type, shape.radius, squircle);
-      if (d <= tolerance) return elements[i];
-    }
-    return null;
-  }
-
-  // Mirror the renderer's connected-component splitting and 16-shape chunks.
-  // In particular, do not invent a smooth-union bridge across a chunk boundary
-  // that the GPU cannot draw. Iterate backwards because later passes composite
-  // over earlier ones when separately rendered groups overlap.
-  const groups = groupElements(elements, mergeRadius, MAX_GLASS_SHAPES).groups;
-  for (let groupIndex = groups.length - 1; groupIndex >= 0; groupIndex--) {
-    const group = groups[groupIndex];
-    if (sdGroup(x, y, group, material, mergeRadius) > tolerance) continue;
-
-    let best = null;
-    let bestDistance = Infinity;
-    for (let i = group.length - 1; i >= 0; i--) {
-      const shape = toShape(group[i], material);
-      const d = sdPrimitive(x - shape.cx, y - shape.cy, shape.halfX, shape.halfY,
-                            shape.type, shape.radius, squircle);
-      if (d < bestDistance) {
-        bestDistance = d;
-        best = group[i];
-      }
-    }
-    return best;
-  }
-  return null;
-}
-
-/** Signed distance to the exact silhouette produced by the renderer's passes. */
-export function sdRenderedGroups(
-  x, y, elements, material = {}, mergeRadius = material.mergeRadius ?? 0,
-) {
-  const groups = groupElements(elements, mergeRadius, MAX_GLASS_SHAPES).groups;
-  if (!groups.length) return Infinity;
-  let bestDistance = Infinity;
-  for (const group of groups) {
-    const d = sdGroup(x, y, group, material, mergeRadius);
-    if (d < bestDistance) bestDistance = d;
-  }
-  return bestDistance;
-}
-
-/** Axis-aligned gap between two element boxes; 0 when they overlap. */
-function boxGap(a, b) {
-  const box = (element) => {
-    const w = Number(element.w ?? element.width ?? element.size ?? 0);
-    const h = Number(element.h ?? element.height ?? element.size ?? w);
-    return { x: Number(element.x ?? 0), y: Number(element.y ?? 0), w, h };
-  };
-  const aa = box(a);
-  const bb = box(b);
-  const dx = Math.max(0, Math.max(aa.x - (bb.x + bb.w), bb.x - (aa.x + aa.w)));
-  const dy = Math.max(0, Math.max(aa.y - (bb.y + bb.h), bb.y - (aa.y + aa.h)));
-  return Math.hypot(dx, dy);
-}
-
-/**
- * Split elements into sets that can be shaded independently.
- *
- * Two elements land in the same set when their boxes are close enough for the
- * smooth-min to bridge them. Elements further apart than the influence radius
- * contribute nothing measurable to each other's distance field, so drawing
- * them in separate passes is visually identical to one fused pass.
- */
-export function connectedElementGroups(elements, mergeRadius = 0) {
-  if (elements.length <= 1) return elements.length ? [elements.slice()] : [];
-  const reach = Math.max(0, mergeRadius) * MERGE_SCALE_RATIO * MERGE_INFLUENCE_SCALES;
-
-  const parent = elements.map((_, i) => i);
-  const find = (i) => {
-    while (parent[i] !== i) { parent[i] = parent[parent[i]]; i = parent[i]; }
-    return i;
-  };
-  for (let i = 0; i < elements.length; i++) {
-    for (let j = i + 1; j < elements.length; j++) {
-      if (boxGap(elements[i], elements[j]) <= reach) parent[find(i)] = find(j);
-    }
-  }
-
-  const byRoot = new Map();
-  elements.forEach((element, i) => {
-    const root = find(i);
-    if (!byRoot.has(root)) byRoot.set(root, []);
-    byRoot.get(root).push(element);
-  });
-
-  return [...byRoot.values()];
-}
-
-/**
- * Connected sets, further chunked so no group exceeds the shader's uniform
- * arrays. A chunked set is the only lossy case: shapes that really do influence
- * each other end up in different passes, so callers should surface a warning
- * when `groupElements` reports it.
- */
-export function groupElements(elements, mergeRadius = 0, maxPerGroup = MAX_GLASS_SHAPES) {
-  const connected = connectedElementGroups(elements, mergeRadius);
-  const groups = [];
-  let truncated = false;
-  for (const group of connected) {
-    if (group.length > maxPerGroup) truncated = true;
-    for (let i = 0; i < group.length; i += maxPerGroup) {
-      groups.push(group.slice(i, i + maxPerGroup));
-    }
-  }
-  return { groups, truncated };
-}