@hicccc77/electron-liquid-glass 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hicccc77
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# Electron-Liquid-Glass
+
+Windows 全局原生低延迟「液态玻璃」背景面板，for Electron。
+
+Low-latency native liquid glass backdrop panels for Electron apps, powered by DXGI Desktop Duplication + D3D11 + DirectComposition.
+
+把液态玻璃渲染为一个全局独立的原生窗口，放在你的 Electron 窗口正下方作为实时背景层。
+
+![真实渲染效果：Electron 通知窗口（内容层）+ 原生玻璃面板（折射层）](https://raw.githubusercontent.com/hicccc77/electron-liquid-glass/main/docs/demo.png)
+
+> 真实渲染截图（非合成图）：通知卡片为 Electron 透明窗口，卡片背后的折射、模糊、色散与驱动文字反色的亮度采样全部来自本模块的原生面板。
+
+## 特性
+
+- **真折射，非毛玻璃**：圆角矩形 SDF 透镜位移，边缘可见清晰的背景折射与色散，中心通透
+- **6ms 级响应**：DXGI 零拷贝拿 GPU 桌面纹理，D3D11 渲染，DirectComposition 直接上屏，全程不落 CPU
+- **深度节能**：事件驱动——桌面不动不画、脏区不相交不画、无面板自动休眠
+- **自适应反色支持**：内置亮度带采样（均值色 + luma p15/p85），重绘驱动、与画面同帧推送（上限 ~60Hz），驱动上层文字明暗自适应
+- **z 序锚定**：面板自动钉在指定 Electron 窗口正下方，并周期性重申（防其他置顶窗口插队）
+- **防自采集回环**：`WDA_EXCLUDEFROMCAPTURE` 把面板从一切屏幕捕获中排除
+- **零 Electron 侵入**：纯 N-API 原生模块 + 命令队列，跨 Electron 版本 ABI 稳定，任何 Electron 应用可直接接入
+
+## 原理
+
+```
+DXGI Desktop Duplication（零拷贝 GPU 桌面纹理，仅画面变化时出帧）
+  → D3D11 三趟着色（半分辨率可分离高斯模糊 ×2 → 圆角 SDF 透镜位移 + RGB 色散 + 饱和度 + 圆角 AA）
+  → DirectComposition 预乘 alpha 交换链直接上屏（不经过 DWM 重定向位图）
+```
+
+- 全链路在一个独立工作线程 + GPU 上完成，无像素跨进程/跨线程拷贝
+- 面板窗口 `WS_EX_NOREDIRECTIONBITMAP + WS_EX_TRANSPARENT + WS_EX_NOACTIVATE`（鼠标穿透、不抢焦点、不进任务栏）
+- JS 侧所有调用经命令队列异步投递到工作线程，天然线程安全
+- 分层协作：本面板负责「玻璃背后的世界」（折射/模糊/色散），你的 Electron 透明窗口负责「玻璃表面」（文字、高光、描边、tint）
+
+```
+┌─ Electron 透明窗口（内容层：文字 / 高光 / 边框）─┐   ← 你的应用
+│  ┌─ 原生玻璃面板（折射层，钉在正下方）────────┐  │   ← 本模块
+│  │      实时折射的桌面背景                    │  │
+└──┴────────────────────────────────────────────┴──┘
+```
+
+## 系统要求
+
+| 平台 | 支持状态 |
+|---|---|
+| Windows 10 2004 (build 19041)+ |  完整支持 |
+| Windows 更旧版本 | `isSupported()` 返回 `false`（缺少 `WDA_EXCLUDEFROMCAPTURE`） |
+| macOS / Linux | 模块可正常安装加载，`isSupported()` 返回 `false`，请回退到你自己的方案（如 Chromium 桌面流 + WebGL）；macOS 原生后端（ScreenCaptureKit + Metal）在路线图中 |
+
+## 安装
+
+```bash
+npm install @hicccc77/electron-liquid-glass
+```
+
+npm 包内置 win32-x64 预编译二进制（N-API 8，跨 Electron / Node 版本 ABI 稳定），**安装零编译、无需任何构建工具链**；非 Windows 平台上没有预编译产物时模块自动降级（`isSupported()` 返回 `false`），同样不触发编译。
+
+Electron 打包（electron-builder）注意把 `.node` 解包出 asar：
+
+```jsonc
+"build": { "asarUnpack": ["node_modules/@hicccc77/electron-liquid-glass/**/*"] }
+```
+
+从源码构建（仓库检出，Windows）：需要 Node.js 18+、VS Build Tools（C++ 桌面工作负载）+ Python，`npm run build` 产出 `build/Release`，`npm run prebuilds` 产出随包分发的 `prebuilds/win32-x64`。
+
+## 快速上手（Electron 主进程）
+
+```js
+const { screen } = require('electron')
+const glass = require('@hicccc77/electron-liquid-glass')
+
+if (glass.isSupported()) {
+  const dpr = screen.getPrimaryDisplay().scaleFactor
+  const panel = glass.createPanel({
+    // 屏幕物理像素
+    x: 1560, y: 40, width: 344, height: 96,
+    cornerRadius: 20, blurSigma: 5,
+    displacementScale: 70, aberrationIntensity: 2, saturation: 1.4,
+    dpr,
+    anchorWindow: myToastWindow,          // 面板钉在该 BrowserWindow 正下方
+    lumaBands: [                          // 自适应反色的亮度采样带（面板本地物理像素）
+      { id: 0, x: 0, y: 0, width: 344, height: 48 },
+      { id: 1, x: 0, y: 48, width: 344, height: 48 }
+    ],
+    onLuma: bands => {
+      // bands = { '0': { r, g, b, darkTail, lightTail }, '1': ... }
+      // 均值 RGB + luma p15/p85（gamma 域 0~255）。重绘驱动：
+      // 背景变化的同一帧推送（上限 ~60Hz），桌面静止时不推送
+      // 据此切换上层文字的明暗配色
+    }
+  })
+
+  panel.show(120)                          // 淡入 120ms
+  panel.setBounds({ x, y, width, height }) // 跟随窗口移动/改尺寸
+  panel.hide(240)                          // 淡出
+  panel.destroy()
+} else {
+  // 回退：Chromium 桌面流 + WebGL 折射管线，或静态 backdrop-filter
+}
+```
+
+上层窗口只需把玻璃区域留透明（Electron `transparent: true` 天然满足），自己绘制文字/描边/高光/tint 等内容层，折射背景由本面板提供。
+
+## API
+
+完整类型见 [`index.d.ts`](index.d.ts)。所有面板方法线程安全。
+
+| 方法 | 说明 |
+|---|---|
+| `isSupported()` | 当前环境是否可用（Windows 10 2004+ 且原生二进制已构建） |
+| `createPanel(options)` | 创建面板，返回句柄；不可用时返回 `null` |
+| `panel.show(fadeMs?)` / `panel.hide(fadeMs?)` | 淡入 / 淡出（`0` = 立即） |
+| `panel.setBounds(bounds)` | 移动 / 改尺寸（物理像素） |
+| `panel.setParams(params)` | 更新视觉参数（圆角、模糊、位移、色散、饱和度） |
+| `panel.anchor(windowOrHwnd)` | 重新钉到某窗口正下方（接受 `BrowserWindow` 或 HWND Buffer） |
+| `panel.setLumaBands(bands)` / `panel.onLuma(cb)` | 更新亮度采样带 / 回调 |
+| `panel.destroy()` | 销毁面板 |
+| `shutdown()` | 停止工作线程并销毁所有面板 |
+
+## 实测（1080p，动态背景，Windows 11）
+
+| 指标 | Chromium 流方案（getUserMedia + WebGL） | 本模块 |
+|---|---|---|
+| 感知位置滞后（中位 / p90） | 77ms / 89ms | **6ms / 6ms** |
+| 满载 CPU 增量（主+GPU+渲染进程合计） | ~1.5% | **~0.3%** |
+| 静止桌面开销 | 持续采集出帧 | **0**（事件驱动） |
+| 首帧启动 | ~80-300ms（getUserMedia 协商） | **<150ms**（面板常驻复用后为 0） |
+| 40 轮通知压测 | — | 面板 1 建 81 复用，内存零增长，零异常 |
+
+测量方法：同帧差分法——同一帧屏幕采集内对比玻璃呈现内容与背景真值条纹的计数差，两个时间戳均来自绘制时刻，结果与探针自身延迟无关。
+
+## 源码结构
+
+```
+src/
+├── addon.cc       N-API 绑定层（参数解析、亮度回调线程安全投递）
+├── session.cc/h   调度中枢：独占工作线程跑「采集→渲染→上屏」闭环、命令队列、节能策略
+├── capture.cc/h   DXGI Desktop Duplication 采集（零拷贝 GPU 纹理 + 脏区）
+├── renderer.cc/h  D3D11 三趟玻璃管线 + 亮度带直方图采样
+├── panel.cc/h     DirectComposition 无重定向位图窗口、淡入淡出、z 序锚定、捕获排除
+├── d3d_utils.cc/h 设备创建辅助
+└── addon_stub.cc  非 Windows 桩（isSupported() = false）
+```
+
+## 已知限制
+
+- 目前仅 Windows 有原生实现（macOS ScreenCaptureKit + Metal 后端在路线图中，API 已按平台后端可插拔设计）
+- 面板排除于截屏/录屏（`WDA_EXCLUDEFROMCAPTURE` 的语义，与内容保护窗口一致）
+- 安全桌面（UAC / 锁屏）期间采集暂停，返回后自动恢复
+- 多显示器：采集会话跟随首个可见面板所在显示器；跨屏移动面板会自动重建会话
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * electron-liquid-glass
+ * Windows 原生低延迟液态玻璃背景面板（DXGI Desktop Duplication + D3D11 + DirectComposition）
+ *
+ * 所有坐标与尺寸均为屏幕物理像素。
+ */
+
+/** 玻璃视觉参数（长度单位：物理像素） */
+export interface GlassEffectParams {
+    /** 圆角半径，默认 20 */
+    cornerRadius?: number
+    /** 高斯模糊σ，默认 5 */
+    blurSigma?: number
+    /** 边缘位移强度（70 = 标准强度），默认 70 */
+    displacementScale?: number
+    /** RGB 色散强度（0~3），默认 2 */
+    aberrationIntensity?: number
+    /** 饱和度增益，默认 1.4 */
+    saturation?: number
+    /**
+     * 采样区相对面板的偏移。常规玻璃保持 0；
+     * 非 0 时面板折射别处内容（测量/特效场景）
+     */
+    sourceOffsetX?: number
+    sourceOffsetY?: number
+}
+
+/** 亮度采样带（矩形为面板本地物理像素） */
+export interface LumaBand {
+    id: number
+    x: number
+    y: number
+    width: number
+    height: number
+}
+
+/** 亮度带统计：玻璃模糊层的均值色 + luma p15/p85（0~255） */
+export interface LumaBandStats {
+    r: number
+    g: number
+    b: number
+    darkTail: number
+    lightTail: number
+}
+
+export interface CreatePanelOptions extends GlassEffectParams {
+    x: number
+    y: number
+    width: number
+    height: number
+    /** 显示器缩放系数（内部几何常量按此缩放），默认 1 */
+    dpr?: number
+    /**
+     * 从屏幕捕获（截屏/录屏/DDA/WGC）中排除面板，默认 true。
+     * 必须保持 true 才能避免自采集反馈回路；仅测试可关。
+     */
+    excludeFromCapture?: boolean
+    /** 把面板 z 序钉在该窗口正下方（Electron BrowserWindow 或 HWND Buffer） */
+    anchorWindow?: unknown
+    /** 亮度采样带（配合 onLuma 做自适应文字反色） */
+    lumaBands?: LumaBand[]
+    /**
+     * 亮度回调：bands 为 { [bandId]: LumaBandStats }。
+     * 重绘驱动：面板下方内容变化的同一帧推送（上限 ~60Hz），桌面静止时不推送
+     */
+    onLuma?: (bands: Record<string, LumaBandStats>) => void
+}
+
+export interface GlassPanel {
+    readonly id: number
+    /** 显示并淡入（默认 120ms） */
+    show(fadeMs?: number): void
+    /** 淡出并隐藏（默认 100ms；0 = 立即） */
+    hide(fadeMs?: number): void
+    destroy(): void
+    setBounds(bounds: { x: number; y: number; width: number; height: number }): void
+    /** 更新视觉参数（传完整参数对象，缺省字段回落默认值） */
+    setParams(params: GlassEffectParams): void
+    anchor(windowOrHwnd: unknown): void
+    setLumaBands(bands: LumaBand[]): void
+    onLuma(cb: (bands: Record<string, LumaBandStats>) => void): void
+}
+
+/** 当前环境是否支持原生玻璃（Windows 10 2004+ 且原生二进制已构建） */
+export function isSupported(): boolean
+
+/** 创建玻璃面板；原生不可用时返回 null（调用方应回退） */
+export function createPanel(options: CreatePanelOptions): GlassPanel | null
+
+/** 停止工作线程并销毁所有面板（进程退出前自动调用） */
+export function shutdown(): void

package/index.js

@@ -0,0 +1,77 @@
+// electron-liquid-glass JS 入口：原生模块加载守护 + 面板对象封装。
+// node-gyp-build 依次尝试 prebuilds/<platform>-<arch>（npm 分发的预编译产物，
+// N-API 8，无需使用者本地编译）与 build/Release（仓库内开发构建）。
+// 原生不可用（非 Windows、系统过旧、无预编译产物）时 isSupported() 返回 false，
+// 调用方据此回退自己的方案（如 Chromium 屏幕采集管线）。
+let native = null
+try {
+    native = require('node-gyp-build')(__dirname)
+} catch {
+    native = null
+}
+
+const panels = new Map()
+let lumaHooked = false
+
+function ensureLumaDispatch() {
+    if (lumaHooked || !native) return
+    lumaHooked = true
+    native.setLumaCallback((panelId, bands) => {
+        const panel = panels.get(panelId)
+        if (panel && panel._onLuma) panel._onLuma(bands)
+    })
+}
+
+function isSupported() {
+    return Boolean(native && native.isSupported())
+}
+
+/**
+ * 创建玻璃面板（所有长度均为物理像素；dpr 用于内部几何常量缩放）。
+ * 返回面板句柄对象；原生不可用时返回 null。
+ */
+function createPanel(options) {
+    if (!isSupported()) return null
+    const { onLuma, lumaBands, anchorWindow, ...config } = options
+    if (anchorWindow) config.anchorHwnd = resolveHwnd(anchorWindow)
+
+    const id = native.createPanel(config)
+    const panel = {
+        id,
+        _onLuma: onLuma ?? null,
+        show(fadeMs = 120) { native.showPanel(id, fadeMs) },
+        hide(fadeMs = 100) { native.hidePanel(id, fadeMs) },
+        destroy() {
+            panels.delete(id)
+            native.destroyPanel(id)
+        },
+        setBounds(bounds) { native.setPanelBounds(id, bounds) },
+        setParams(params) { native.setPanelParams(id, params) },
+        anchor(windowOrHwnd) { native.anchorPanel(id, resolveHwnd(windowOrHwnd)) },
+        setLumaBands(bands) { native.setLumaBands(id, bands) },
+        onLuma(cb) { panel._onLuma = cb }
+    }
+    panels.set(id, panel)
+    if (lumaBands) native.setLumaBands(id, lumaBands)
+    if (onLuma) ensureLumaDispatch()
+    return panel
+}
+
+// 接受 Electron BrowserWindow 或 getNativeWindowHandle() 的 Buffer
+function resolveHwnd(windowOrHwnd) {
+    if (!windowOrHwnd) return null
+    if (Buffer.isBuffer(windowOrHwnd)) return windowOrHwnd
+    if (typeof windowOrHwnd.getNativeWindowHandle === 'function') {
+        return windowOrHwnd.getNativeWindowHandle()
+    }
+    return null
+}
+
+function shutdown() {
+    // 非 Windows 的桩实现只导出 isSupported/osBuild，其余入口必须判空
+    if (native && typeof native.shutdown === 'function') native.shutdown()
+    panels.clear()
+    lumaHooked = false
+}
+
+module.exports = { isSupported, createPanel, shutdown, _native: native }

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hicccc77/electron-liquid-glass",
+  "version": "0.1.1",
+  "description": "Low-latency native liquid glass backdrop panels for Electron apps (Windows: DXGI Desktop Duplication + D3D11 + DirectComposition)",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "author": "hicccc77",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hicccc77/electron-liquid-glass.git"
+  },
+  "homepage": "https://github.com/hicccc77/electron-liquid-glass#readme",
+  "bugs": {
+    "url": "https://github.com/hicccc77/electron-liquid-glass/issues"
+  },
+  "keywords": [
+    "electron",
+    "liquid-glass",
+    "glassmorphism",
+    "backdrop",
+    "blur",
+    "native",
+    "directcomposition",
+    "desktop-duplication",
+    "d3d11",
+    "windows"
+  ],
+  "scripts": {
+    "install": "node scripts/install-guard.cjs",
+    "build": "node-gyp rebuild",
+    "prebuilds": "prebuildify --napi --strip",
+    "prepublishOnly": "node scripts/check-prebuilds.cjs"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.5.0",
+    "node-gyp-build": "^4.8.4"
+  },
+  "devDependencies": {
+    "prebuildify": "^6.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "prebuilds/",
+    "scripts/install-guard.cjs",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/scripts/install-guard.cjs

@@ -0,0 +1,15 @@
+// 显式 install 脚本：覆盖 npm 对含 binding.gyp 仓库的隐式 "node-gyp rebuild" 注入。
+// npm 分发的 tarball 只带预编译产物（prebuilds/），不含源码与 binding.gyp：
+// - 命中当前平台的 prebuild：直接通过（零编译）
+// - 未命中（如 macOS/Linux）：安静降级，运行时 isSupported() 返回 false
+// 任何情况下 exit 0，绝不在使用者的 npm install 阶段失败或触发编译
+try {
+    const resolved = require('node-gyp-build').path(require('path').join(__dirname, '..'))
+    console.log('[electron-liquid-glass] prebuild ready:', resolved)
+} catch {
+    console.log(
+        '[electron-liquid-glass] no prebuild for ' + process.platform + '-' + process.arch +
+        ', isSupported() will return false (see README for fallback guidance)'
+    )
+}
+process.exit(0)