@zakim24/electron-liquid-glass 1.1.1

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Meridius Labs
+
+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,247 @@
+# electron-liquid-glass
+
+<div align="center">
+
+<img width="387" alt="image" src="https://github.com/user-attachments/assets/3c3c9ea6-2663-4292-b812-a630c2c3f65b" />
+
+![npm](https://img.shields.io/npm/v/electron-liquid-glass)
+![npm downloads](https://img.shields.io/npm/dm/electron-liquid-glass)
+![GitHub](https://img.shields.io/github/license/meridius-labs/electron-liquid-glass)
+![Platform](https://img.shields.io/badge/platform-macOS-blue)
+![Node](https://img.shields.io/node/v/electron-liquid-glass)
+
+**Modern macOS glass effects for Electron applications**
+
+_🪄 NATIVE `NSGlassEffectView` integration with ZERO CSS hacks_
+
+[Installation](#-installation) • [Quick Start](#-quick-start) • [API](#-api-reference) • [Examples](examples/) • [Contributing](#-contributing)
+
+</div>
+
+---
+
+## ✨ Features
+
+- 🪟 **Native Glass Effects** - Real `NSGlassEffectView` integration, not CSS approximations
+- ⚡ **Zero Configuration** - Works out of the box with any Electron app
+- 🎨 **Fully Customizable** - Corner radius, tint colors, and glass variants
+- 📦 **Modern Package** - Dual ESM/CommonJS support with TypeScript declarations
+- 🔧 **Pre-built Binaries** - No compilation required for standard setups
+- 🌙 **Auto Dark Mode** - Automatically adapts to system appearance changes
+
+## 🚀 Installation
+
+```bash
+# npm
+npm install electron-liquid-glass
+
+# yarn
+yarn add electron-liquid-glass
+
+# pnpm
+pnpm add electron-liquid-glass
+
+# bun
+bun add electron-liquid-glass
+```
+
+### Requirements
+
+- **macOS 26+** (Tahoe or later)
+- **Electron 30+**
+- **Node.js 22+**
+
+> **Note**: This package only works on macOS. On other platforms, it provides safe no-op fallbacks.
+
+## 🎯 Quick Start
+
+### Basic Usage
+
+```javascript
+import { app, BrowserWindow } from "electron";
+import liquidGlass from "electron-liquid-glass";
+
+app.whenReady().then(() => {
+  const win = new BrowserWindow({
+    width: 800,
+    height: 600,
+
+    vibrancy: false, // <-- ❌❌❌ do NOT set vibrancy alongside with liquid glass, it will override and look blurry
+
+    transparent: true, // <-- This MUST be true
+  });
+
+  win.setWindowButtonVisibility(true); // <-- ✅ This is required to show the window buttons
+
+  win.loadFile("index.html");
+
+  /**
+   * 🪄 Apply glass effect after content loads 🪄
+   */
+  win.webContents.once("did-finish-load", () => {
+    // 🪄 Apply effect, get handle
+    const glassId = liquidGlass.addView(win.getNativeWindowHandle(), {
+      /* options */
+    });
+
+    // Experimental, undocumented private APIs
+    liquidGlass.unstable_setVariant(glassId, 2);
+  });
+});
+```
+
+### TypeScript Usage
+
+```typescript
+import { BrowserWindow } from "electron";
+import liquidGlass, { GlassOptions } from "electron-liquid-glass";
+
+const options: GlassOptions = {
+  cornerRadius: 16, // (optional)
+  tintColor: "#44000010", // black tint (optional)
+  opaque: true, // add opaque background behind glass (optional)
+};
+
+liquidGlass.addView(window.getNativeWindowHandle(), options);
+```
+
+## 📚 API Reference
+
+### `liquidGlass.addView(handle, options?)`
+
+Applies a glass effect to an Electron window.
+
+**Parameters:**
+
+- `handle: Buffer` - The native window handle from `BrowserWindow.getNativeWindowHandle()`
+- `options?: GlassOptions` - Configuration options
+
+**Returns:** `number` - A unique view ID for future operations
+
+### `GlassOptions`
+
+```typescript
+interface GlassOptions {
+  cornerRadius?: number; // Corner radius in pixels (default: 0)
+  tintColor?: string; // Hex color with optional alpha (#RRGGBB or #RRGGBBAA)
+  opaque?: boolean; // Add opaque background behind glass (default: false)
+}
+```
+
+---
+
+### UNDOCUMENTED EXPERIMENTAL METHODS
+
+> ⚠️ **Warning**: DO NOT USE IN PROD. These methods use private macOS APIs and may change in future versions.
+
+```typescript
+// Glass variants (number) (0-15, 19 are functional)
+liquidGlass.unstable_setVariant(glassId, 2);
+
+// Scrim overlay (0 = off, 1 = on)
+liquidGlass.unstable_setScrim(glassId, 1);
+
+// Subdued state (0 = normal, 1 = subdued)
+liquidGlass.unstable_setSubdued(glassId, 1);
+```
+
+## 🔧 Development
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/meridius-labs/electron-liquid-glass.git
+cd electron-liquid-glass
+
+# Install dependencies
+bun install
+
+# Build native module
+bun run build:native
+
+# Build TypeScript library
+bun run build
+
+# Build everything
+bun run build:all
+```
+
+### Rebuilding for Custom Electron
+
+If you're using a custom Electron version:
+
+```bash
+npx electron-rebuild -f -w electron-liquid-glass
+```
+
+### Project Structure
+
+```
+electron-liquid-glass/
+├── src/                 # Native C++ source code
+│   ├── glass_effect.mm  # Objective-C++ implementation
+│   └── liquidglass.cc   # Node.js addon bindings
+├── js/                  # TypeScript source
+│   ├── index.ts         # Main library code
+│   └── native-loader.ts # Native module loader
+├── dist/                # Built library (generated)
+├── examples/            # Example applications
+└── prebuilds/          # Pre-built binaries
+```
+
+## 🏗️ How It Works
+
+1. **Native Integration**: Uses Objective-C++ to create `NSGlassEffectView` instances
+2. **View Hierarchy**: Inserts glass views behind your web content, not over it
+3. **Automatic Updates**: Listens for system appearance changes to keep effects in sync
+4. **Memory Management**: Properly manages native view lifecycle
+
+### Technical Details
+
+- **Primary**: Uses `NSGlassEffectView` API when available
+- **Fallback**: Falls back to public `NSVisualEffectView` on older systems
+- **Performance**: Minimal overhead, native rendering performance
+- **Compatibility**: Works with all Electron window configurations
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes and test thoroughly
+4. Commit with conventional commits: `git commit -m "feat: add amazing feature"`
+5. Push and create a Pull Request
+
+### Reporting Issues
+
+- Use the [issue tracker](https://github.com/meridius-labs/electron-liquid-glass/issues)
+- Include your macOS version, Electron version, and Node.js version
+- Provide a minimal reproduction case when possible
+
+## 📋 Roadmap
+
+- [ ] **View Management** - Remove and update existing glass views
+
+## 🙏 Acknowledgments
+
+- Apple's private `NSGlassEffectView` API documentation (reverse-engineered)
+- The Electron team for excellent native integration capabilities
+- Contributors and users who help improve this library
+
+## 📄 License
+
+MIT © [Meridius Labs](https://github.com/meridius-labs) 2025
+
+---
+
+<div align="center">
+
+**Made with ❤️ for the Electron community**
+
+[⭐ Star on GitHub](https://github.com/meridius-labs/electron-liquid-glass) • [🐛 Report Bug](https://github.com/meridius-labs/electron-liquid-glass/issues) • [💡 Request Feature](https://github.com/meridius-labs/electron-liquid-glass/issues)
+
+</div>

package/dist/index.cjs

@@ -0,0 +1,129 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let events = require("events");
+events = __toESM(events);
+let child_process = require("child_process");
+child_process = __toESM(child_process);
+let url = require("url");
+url = __toESM(url);
+let path = require("path");
+path = __toESM(path);
+
+//#region js/variants.ts
+const GlassMaterialVariant = {
+	regular: 0,
+	clear: 1,
+	dock: 2,
+	appIcons: 3,
+	widgets: 4,
+	text: 5,
+	avplayer: 6,
+	facetime: 7,
+	controlCenter: 8,
+	notificationCenter: 9,
+	monogram: 10,
+	bubbles: 11,
+	identity: 12,
+	focusBorder: 13,
+	focusPlatter: 14,
+	keyboard: 15,
+	sidebar: 16,
+	abuttedSidebar: 17,
+	inspector: 18,
+	control: 19,
+	loupe: 20,
+	slider: 21,
+	camera: 22,
+	cartouchePopover: 23
+};
+
+//#endregion
+//#region js/native-loader.ts
+const __filename$1 = (0, url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
+const __dirname$1 = (0, path.dirname)(__filename$1);
+const nodeGypBuild = require("node-gyp-build");
+var native_loader_default = nodeGypBuild((0, path.join)(__dirname$1, ".."));
+
+//#endregion
+//#region js/index.ts
+var LiquidGlass = class extends events.EventEmitter {
+	_addon;
+	_isGlassSupported;
+	GlassMaterialVariant = GlassMaterialVariant;
+	constructor() {
+		super();
+		try {
+			if (!this.isMacOS()) return;
+			this._addon = new native_loader_default.LiquidGlassNative();
+		} catch (err) {
+			console.error("electron-liquid-glass failed to load its native addon – liquid glass functionality will be disabled.", err);
+		}
+	}
+	isMacOS() {
+		return process.platform === "darwin";
+	}
+	/**
+	* Check if liquid glass is supported on the current platform
+	* @returns true if liquid glass is supported on the current platform
+	*/
+	isGlassSupported() {
+		if (this._isGlassSupported !== void 0) return this._isGlassSupported;
+		const supported = this.isMacOS() && Number((0, child_process.execSync)("sw_vers -productVersion").toString().trim().split(".")[0]) >= 26;
+		this._isGlassSupported = supported;
+		return supported;
+	}
+	/**
+	* Wrap the Electron window with a glass / vibrancy view.
+	*
+	* ⚠️ Will gracefully fall back to legacy macOS blur if liquid glass is not supported.
+	* @param handle BrowserWindow.getNativeWindowHandle()
+	* @param options Glass effect options
+	* @returns id – can be used for future API (remove/update), -1 if not supported
+	*/
+	addView(handle, options = {}) {
+		if (!Buffer.isBuffer(handle)) throw new Error("[liquidGlass.addView] handle must be a Buffer");
+		if (!this._addon) return -1;
+		return this._addon.addView(handle, options);
+	}
+	setVariant(id, variant) {
+		if (!this._addon || typeof this._addon.setVariant !== "function") return;
+		this._addon.setVariant(id, variant);
+	}
+	unstable_setVariant(id, variant) {
+		this.setVariant(id, variant);
+	}
+	unstable_setScrim(id, scrim) {
+		if (!this._addon || typeof this._addon.setScrimState !== "function") return;
+		this._addon.setScrimState(id, scrim);
+	}
+	unstable_setSubdued(id, subdued) {
+		if (!this._addon || typeof this._addon.setSubduedState !== "function") return;
+		this._addon.setSubduedState(id, subdued);
+	}
+};
+const liquidGlass = new LiquidGlass();
+var js_default = liquidGlass;
+
+//#endregion
+module.exports = js_default;

package/dist/index.d.cts

@@ -0,0 +1,71 @@
+import { EventEmitter } from "events";
+
+//#region js/variants.d.ts
+type GlassMaterialVariant = number;
+declare const GlassMaterialVariant: {
+  readonly regular: 0;
+  readonly clear: 1;
+  readonly dock: 2;
+  readonly appIcons: 3;
+  readonly widgets: 4;
+  readonly text: 5;
+  readonly avplayer: 6;
+  readonly facetime: 7;
+  readonly controlCenter: 8;
+  readonly notificationCenter: 9;
+  readonly monogram: 10;
+  readonly bubbles: 11;
+  readonly identity: 12;
+  readonly focusBorder: 13;
+  readonly focusPlatter: 14;
+  readonly keyboard: 15;
+  readonly sidebar: 16;
+  readonly abuttedSidebar: 17;
+  readonly inspector: 18;
+  readonly control: 19;
+  readonly loupe: 20;
+  readonly slider: 21;
+  readonly camera: 22;
+  readonly cartouchePopover: 23;
+};
+//#endregion
+//#region js/index.d.ts
+interface GlassOptions {
+  cornerRadius?: number;
+  tintColor?: string;
+  opaque?: boolean;
+}
+interface LiquidGlassNative {
+  addView(handle: Buffer, options: GlassOptions): number;
+  setVariant(id: number, variant: GlassMaterialVariant): void;
+  setScrimState(id: number, scrim: number): void;
+  setSubduedState(id: number, subdued: number): void;
+}
+declare class LiquidGlass extends EventEmitter {
+  private _addon?;
+  private _isGlassSupported;
+  readonly GlassMaterialVariant: typeof GlassMaterialVariant;
+  constructor();
+  private isMacOS;
+  /**
+  * Check if liquid glass is supported on the current platform
+  * @returns true if liquid glass is supported on the current platform
+  */
+  isGlassSupported(): boolean;
+  /**
+  * Wrap the Electron window with a glass / vibrancy view.
+  *
+  * ⚠️ Will gracefully fall back to legacy macOS blur if liquid glass is not supported.
+  * @param handle BrowserWindow.getNativeWindowHandle()
+  * @param options Glass effect options
+  * @returns id – can be used for future API (remove/update), -1 if not supported
+  */
+  addView(handle: Buffer, options?: GlassOptions): number;
+  private setVariant;
+  unstable_setVariant(id: number, variant: GlassMaterialVariant): void;
+  unstable_setScrim(id: number, scrim: number): void;
+  unstable_setSubdued(id: number, subdued: number): void;
+}
+declare const liquidGlass: LiquidGlass;
+//#endregion
+export { GlassOptions, LiquidGlassNative, liquidGlass as default };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { EventEmitter } from "events";
+
+//#region js/variants.d.ts
+type GlassMaterialVariant = number;
+declare const GlassMaterialVariant: {
+  readonly regular: 0;
+  readonly clear: 1;
+  readonly dock: 2;
+  readonly appIcons: 3;
+  readonly widgets: 4;
+  readonly text: 5;
+  readonly avplayer: 6;
+  readonly facetime: 7;
+  readonly controlCenter: 8;
+  readonly notificationCenter: 9;
+  readonly monogram: 10;
+  readonly bubbles: 11;
+  readonly identity: 12;
+  readonly focusBorder: 13;
+  readonly focusPlatter: 14;
+  readonly keyboard: 15;
+  readonly sidebar: 16;
+  readonly abuttedSidebar: 17;
+  readonly inspector: 18;
+  readonly control: 19;
+  readonly loupe: 20;
+  readonly slider: 21;
+  readonly camera: 22;
+  readonly cartouchePopover: 23;
+};
+//#endregion
+//#region js/index.d.ts
+interface GlassOptions {
+  cornerRadius?: number;
+  tintColor?: string;
+  opaque?: boolean;
+}
+interface LiquidGlassNative {
+  addView(handle: Buffer, options: GlassOptions): number;
+  setVariant(id: number, variant: GlassMaterialVariant): void;
+  setScrimState(id: number, scrim: number): void;
+  setSubduedState(id: number, subdued: number): void;
+}
+declare class LiquidGlass extends EventEmitter {
+  private _addon?;
+  private _isGlassSupported;
+  readonly GlassMaterialVariant: typeof GlassMaterialVariant;
+  constructor();
+  private isMacOS;
+  /**
+  * Check if liquid glass is supported on the current platform
+  * @returns true if liquid glass is supported on the current platform
+  */
+  isGlassSupported(): boolean;
+  /**
+  * Wrap the Electron window with a glass / vibrancy view.
+  *
+  * ⚠️ Will gracefully fall back to legacy macOS blur if liquid glass is not supported.
+  * @param handle BrowserWindow.getNativeWindowHandle()
+  * @param options Glass effect options
+  * @returns id – can be used for future API (remove/update), -1 if not supported
+  */
+  addView(handle: Buffer, options?: GlassOptions): number;
+  private setVariant;
+  unstable_setVariant(id: number, variant: GlassMaterialVariant): void;
+  unstable_setScrim(id: number, scrim: number): void;
+  unstable_setSubdued(id: number, subdued: number): void;
+}
+declare const liquidGlass: LiquidGlass;
+//#endregion
+export { GlassOptions, LiquidGlassNative, liquidGlass as default };

package/dist/index.js

@@ -0,0 +1,107 @@
+import { createRequire } from "node:module";
+import { EventEmitter } from "events";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+//#region rolldown:runtime
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+//#endregion
+//#region js/variants.ts
+const GlassMaterialVariant = {
+	regular: 0,
+	clear: 1,
+	dock: 2,
+	appIcons: 3,
+	widgets: 4,
+	text: 5,
+	avplayer: 6,
+	facetime: 7,
+	controlCenter: 8,
+	notificationCenter: 9,
+	monogram: 10,
+	bubbles: 11,
+	identity: 12,
+	focusBorder: 13,
+	focusPlatter: 14,
+	keyboard: 15,
+	sidebar: 16,
+	abuttedSidebar: 17,
+	inspector: 18,
+	control: 19,
+	loupe: 20,
+	slider: 21,
+	camera: 22,
+	cartouchePopover: 23
+};
+
+//#endregion
+//#region js/native-loader.ts
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const nodeGypBuild = __require("node-gyp-build");
+var native_loader_default = nodeGypBuild(join(__dirname, ".."));
+
+//#endregion
+//#region js/index.ts
+var LiquidGlass = class extends EventEmitter {
+	_addon;
+	_isGlassSupported;
+	GlassMaterialVariant = GlassMaterialVariant;
+	constructor() {
+		super();
+		try {
+			if (!this.isMacOS()) return;
+			this._addon = new native_loader_default.LiquidGlassNative();
+		} catch (err) {
+			console.error("electron-liquid-glass failed to load its native addon – liquid glass functionality will be disabled.", err);
+		}
+	}
+	isMacOS() {
+		return process.platform === "darwin";
+	}
+	/**
+	* Check if liquid glass is supported on the current platform
+	* @returns true if liquid glass is supported on the current platform
+	*/
+	isGlassSupported() {
+		if (this._isGlassSupported !== void 0) return this._isGlassSupported;
+		const supported = this.isMacOS() && Number(execSync("sw_vers -productVersion").toString().trim().split(".")[0]) >= 26;
+		this._isGlassSupported = supported;
+		return supported;
+	}
+	/**
+	* Wrap the Electron window with a glass / vibrancy view.
+	*
+	* ⚠️ Will gracefully fall back to legacy macOS blur if liquid glass is not supported.
+	* @param handle BrowserWindow.getNativeWindowHandle()
+	* @param options Glass effect options
+	* @returns id – can be used for future API (remove/update), -1 if not supported
+	*/
+	addView(handle, options = {}) {
+		if (!Buffer.isBuffer(handle)) throw new Error("[liquidGlass.addView] handle must be a Buffer");
+		if (!this._addon) return -1;
+		return this._addon.addView(handle, options);
+	}
+	setVariant(id, variant) {
+		if (!this._addon || typeof this._addon.setVariant !== "function") return;
+		this._addon.setVariant(id, variant);
+	}
+	unstable_setVariant(id, variant) {
+		this.setVariant(id, variant);
+	}
+	unstable_setScrim(id, scrim) {
+		if (!this._addon || typeof this._addon.setScrimState !== "function") return;
+		this._addon.setScrimState(id, scrim);
+	}
+	unstable_setSubdued(id, subdued) {
+		if (!this._addon || typeof this._addon.setSubduedState !== "function") return;
+		this._addon.setSubduedState(id, subdued);
+	}
+};
+const liquidGlass = new LiquidGlass();
+var js_default = liquidGlass;
+
+//#endregion
+export { js_default as default };

package/js/index.ts

@@ -0,0 +1,117 @@
+import { EventEmitter } from "events";
+import { execSync } from "child_process";
+import { GlassMaterialVariant } from "./variants.js";
+
+// Load the native addon using the 'bindings' module
+// This will look for the compiled .node file in various places
+import native from "./native-loader.js";
+
+export interface GlassOptions {
+  cornerRadius?: number;
+  tintColor?: string;
+  opaque?: boolean;
+}
+
+export interface LiquidGlassNative {
+  addView(handle: Buffer, options: GlassOptions): number;
+  setVariant(id: number, variant: GlassMaterialVariant): void;
+  setScrimState(id: number, scrim: number): void;
+  setSubduedState(id: number, subdued: number): void;
+}
+
+// Create a nice JavaScript wrapper
+class LiquidGlass extends EventEmitter {
+  private _addon?: LiquidGlassNative;
+  private _isGlassSupported: boolean | undefined;
+
+  // Instance property for easy access to variants
+  readonly GlassMaterialVariant: typeof GlassMaterialVariant =
+    GlassMaterialVariant;
+
+  constructor() {
+    super();
+
+    try {
+      if (!this.isMacOS()) {
+        return;
+      }
+
+      // Native addon uses liquid glass (macOS 26+)
+      // or falls back to legacy blur as needed.
+      this._addon = new native.LiquidGlassNative();
+    } catch (err) {
+      console.error(
+        "electron-liquid-glass failed to load its native addon – liquid glass functionality will be disabled.",
+        err
+      );
+    }
+  }
+
+  private isMacOS(): boolean {
+    return process.platform === "darwin";
+  }
+
+  /**
+   * Check if liquid glass is supported on the current platform
+   * @returns true if liquid glass is supported on the current platform
+   */
+  public isGlassSupported(): boolean {
+    if (this._isGlassSupported !== undefined) return this._isGlassSupported;
+
+    const supported =
+      this.isMacOS() &&
+      Number(
+        execSync("sw_vers -productVersion").toString().trim().split(".")[0]
+      ) >= 26;
+
+    this._isGlassSupported = supported;
+    return supported;
+  }
+
+  /**
+   * Wrap the Electron window with a glass / vibrancy view.
+   *
+   * ⚠️ Will gracefully fall back to legacy macOS blur if liquid glass is not supported.
+   * @param handle BrowserWindow.getNativeWindowHandle()
+   * @param options Glass effect options
+   * @returns id – can be used for future API (remove/update), -1 if not supported
+   */
+  addView(handle: Buffer, options: GlassOptions = {}): number {
+    if (!Buffer.isBuffer(handle)) {
+      throw new Error("[liquidGlass.addView] handle must be a Buffer");
+    }
+
+    if (!this._addon) {
+      // unavailable on this platform
+      return -1;
+    }
+
+    return this._addon.addView(handle, options);
+  }
+
+  private setVariant(id: number, variant: GlassMaterialVariant): void {
+    if (!this._addon || typeof this._addon.setVariant !== "function") return;
+    this._addon.setVariant(id, variant);
+  }
+
+  unstable_setVariant(id: number, variant: GlassMaterialVariant): void {
+    this.setVariant(id, variant);
+  }
+
+  unstable_setScrim(id: number, scrim: number): void {
+    if (!this._addon || typeof this._addon.setScrimState !== "function") return;
+    this._addon.setScrimState(id, scrim);
+  }
+
+  unstable_setSubdued(id: number, subdued: number): void {
+    if (!this._addon || typeof this._addon.setSubduedState !== "function")
+      return;
+    this._addon.setSubduedState(id, subdued);
+  }
+}
+
+// Create and export the singleton instance
+// The class constructor handles platform checks internally
+const liquidGlass: LiquidGlass = new LiquidGlass();
+
+export default liquidGlass;

package/js/native-loader.ts

@@ -0,0 +1,10 @@
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+// ESM-compatible way to get __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// node-gyp-build smartly resolves prebuilds as well as local builds.
+const nodeGypBuild = require("node-gyp-build");
+export default nodeGypBuild(join(__dirname, ".."));

package/js/variants.ts

@@ -0,0 +1,28 @@
+export type GlassMaterialVariant = number;
+
+export const GlassMaterialVariant = {
+  regular: 0,
+  clear: 1,
+  dock: 2,
+  appIcons: 3,
+  widgets: 4,
+  text: 5,
+  avplayer: 6,
+  facetime: 7,
+  controlCenter: 8,
+  notificationCenter: 9,
+  monogram: 10,
+  bubbles: 11,
+  identity: 12,
+  focusBorder: 13,
+  focusPlatter: 14,
+  keyboard: 15,
+  sidebar: 16,
+  abuttedSidebar: 17,
+  inspector: 18,
+  control: 19,
+  loupe: 20,
+  slider: 21,
+  camera: 22,
+  cartouchePopover: 23,
+} as const;

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@zakim24/electron-liquid-glass",
+  "version": "1.1.1",
+  "description": "macOS glass / vibrancy wrapper for Electron BrowserWindow",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Meridius-Labs/electron-liquid-glass.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Meridius-Labs/electron-liquid-glass/issues"
+  },
+  "homepage": "https://github.com/Meridius-Labs/electron-liquid-glass#readme",
+  "author": "Meridius Labs",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "js",
+    "src",
+    "build/Release/*.node",
+    "prebuilds/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "build:native": "prebuildify --napi --strip --tag-armv --arch=arm64 && prebuildify --napi --strip --arch=x64",
+    "build:all": "bun run build:native && bun run build",
+    "clean": "rimraf build prebuilds dist",
+    "prepack": "bun run build:all",
+    "dev": "bun run build:all && run-p watch-examples start",
+    "watch-examples": "tsc -w --project tsconfig.examples.json",
+    "start": "bun x electronmon ./dist-examples/electron.js",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major",
+    "version:prerelease": "npm version prerelease",
+    "release": "bun run build:all && npm publish",
+    "release:dry": "bun run build:all && npm publish --dry-run"
+  },
+  "keywords": [
+    "electron",
+    "macos",
+    "vibrancy",
+    "glass",
+    "nsvisualeffectview"
+  ],
+  "gypfile": false,
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "bindings": "^1.5.0",
+    "node-addon-api": "^8.4.0"
+  },
+  "optionalDependencies": {
+    "node-gyp-build": "^4"
+  },
+  "devDependencies": {
+    "@3c1u/bun-run-all": "^0.1.2",
+    "@types/node": "^20",
+    "electron": "^38",
+    "node-gyp": "^11.2.0",
+    "prebuildify": "^5",
+    "rimraf": "^5",
+    "tsdown": "^0.12.8",
+    "typescript": "^5"
+  },
+  "packageManager": "bun@1.2.23"
+}

package/src/glass_effect.mm

@@ -0,0 +1,256 @@
+#include "../include/Common.h"
+#include <napi.h>
+#import <objc/runtime.h>
+#import <objc/message.h>
+#include <string>
+#include <cctype>
+
+#ifdef PLATFORM_OSX
+#import <AppKit/AppKit.h>
+
+// Simple registry so JS can still address a view by numeric id.
+static std::map<int, NSView *> g_glassViews;
+static int g_nextViewId = 0;
+
+// Keys for objc-associated views on a container
+static const void *kGlassEffectKey = &kGlassEffectKey;
+static const void *kBackgroundViewKey = &kBackgroundViewKey;
+
+// Utility: convert #RRGGBB or #RRGGBBAA to NSColor* (sRGB)
+static NSColor* ColorFromHexNSString(NSString* hex)
+{
+  NSString* cleaned = [[hex stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]] uppercaseString];
+  if ([cleaned hasPrefix:@"#"]) cleaned = [cleaned substringFromIndex:1];
+  if (cleaned.length != 6 && cleaned.length != 8) return nil;
+
+  unsigned int rgba = 0;
+  NSScanner* scanner = [NSScanner scannerWithString:cleaned];
+  if (![scanner scanHexInt:&rgba]) return nil;
+
+  CGFloat r,g,b,a;
+  if (cleaned.length == 6) {
+    r = ((rgba & 0xFF0000) >> 16) / 255.0;
+    g = ((rgba & 0x00FF00) >> 8)  / 255.0;
+    b =  (rgba & 0x0000FF)        / 255.0;
+    a = 1.0;
+  } else {
+    r = ((rgba & 0xFF000000) >> 24) / 255.0;
+    g = ((rgba & 0x00FF0000) >> 16) / 255.0;
+    b = ((rgba & 0x0000FF00) >> 8)  / 255.0;
+    a =  (rgba & 0x000000FF)        / 255.0;
+  }
+  return [NSColor colorWithRed:r green:g blue:b alpha:a];
+}
+
+#define RUN_ON_MAIN(block)                                  \
+  if ([NSThread isMainThread]) {                            \
+    block();                                                \
+  } else {                                                  \
+    dispatch_sync(dispatch_get_main_queue(), block);        \
+  }
+
+/*!
+ * AddGlassEffectView
+ * -----------------
+ * Creates an `NSGlassEffectView` (private) and inserts it behind the contentView
+ * of the supplied Electron window. The handle received from JavaScript is the
+ * pointer to the Cocoa `NSView` that backs the BrowserWindow. The view is
+ * retained in a small registry so that we can manipulate or remove it later if
+ * required. The function returns an integer identifier that can be used from
+ * JavaScript.
+ *
+ * Returns –1 on error.
+ */
+extern "C" int AddGlassEffectView(unsigned char *buffer, bool opaque) {
+  if (!buffer) {
+    return -1;
+  }
+
+  __block int resultId = -1;
+
+  RUN_ON_MAIN(^{
+    NSView *rootView = *reinterpret_cast<NSView **>(buffer);
+    if (!rootView) return;
+
+    // Find the proper container - avoid NSThemeFrame
+    NSView *container = rootView;
+
+    // Remove previous glass and background views (if any)
+    NSView *oldGlass = objc_getAssociatedObject(container, kGlassEffectKey);
+    if (oldGlass) [oldGlass removeFromSuperview];
+    
+    NSView *oldBackground = objc_getAssociatedObject(container, kBackgroundViewKey);
+    if (oldBackground) [oldBackground removeFromSuperview];
+
+    NSRect bounds = container.bounds;
+
+    NSBox *backgroundView = nil;
+    
+
+    NSView *glass = nil;
+    Class glassCls = NSClassFromString(@"NSGlassEffectView");
+    if (glassCls) {
+      /**
+      * GLASS VIEW
+      */
+      glass = [[glassCls alloc] initWithFrame:bounds];
+
+      if (opaque) {
+        // Create a background view behind the glass view using NSBox for proper background color
+        backgroundView = [[NSBox alloc] initWithFrame:bounds];
+        backgroundView.autoresizingMask = NSViewWidthSizable | NSViewHeightSizable;
+        backgroundView.boxType = NSBoxCustom;
+        backgroundView.borderType = NSNoBorder;
+        backgroundView.fillColor = [NSColor windowBackgroundColor];
+        backgroundView.wantsLayer = YES;
+        
+        
+        // Add the background view first (bottom layer)
+        [container addSubview:backgroundView positioned:NSWindowBelow relativeTo:nil];
+      }
+    } else {
+      /**
+      * FALLBACK VISUAL EFFECT VIEW
+      */
+      NSVisualEffectView *visual = [[NSVisualEffectView alloc] initWithFrame:bounds];
+      visual.autoresizingMask = NSViewWidthSizable | NSViewHeightSizable;
+      visual.blendingMode = NSVisualEffectBlendingModeBehindWindow;
+      visual.material = NSVisualEffectMaterialUnderWindowBackground;
+      visual.state = NSVisualEffectStateActive;
+      glass = visual;
+    }
+
+    // Ensure autoresize if we created a private glass view too
+    glass.autoresizingMask = NSViewWidthSizable | NSViewHeightSizable;
+
+    // Add the glass view (positioned relative to background view if opaque, or below everything if not)
+    if (opaque && backgroundView) {
+      [container addSubview:glass positioned:NSWindowAbove relativeTo:backgroundView];
+    } else {
+      [container addSubview:glass positioned:NSWindowBelow relativeTo:nil];
+    }
+    
+    // Associate views with the container for cleanup
+    objc_setAssociatedObject(container, kGlassEffectKey, glass, OBJC_ASSOCIATION_RETAIN);
+    if (backgroundView) {
+      objc_setAssociatedObject(container, kBackgroundViewKey, backgroundView, OBJC_ASSOCIATION_RETAIN);
+    } else {
+      objc_setAssociatedObject(container, kBackgroundViewKey, nil, OBJC_ASSOCIATION_ASSIGN);
+    }
+
+ 
+
+    int id = g_nextViewId++;
+    g_glassViews[id] = glass;
+    resultId = id;
+  });
+
+  return resultId;
+}
+
+// Configure glass view by id
+extern "C" void ConfigureGlassView(int viewId, double cornerRadius, const char* tintHex) {
+  RUN_ON_MAIN(^{
+    auto it = g_glassViews.find(viewId);
+    if (it == g_glassViews.end()) return;
+    NSView* glass = it->second;
+
+    // Corner radius via CALayer
+    glass.wantsLayer = YES;
+    glass.layer.cornerRadius = cornerRadius;
+    glass.layer.masksToBounds = YES;
+
+    // corner radius for the background view
+    NSView* container = glass.superview;
+    NSView* backgroundView = objc_getAssociatedObject(container, kBackgroundViewKey);
+    if (backgroundView) {
+      backgroundView.wantsLayer = YES;
+      backgroundView.layer.cornerRadius = cornerRadius;
+      backgroundView.layer.masksToBounds = YES;
+    }
+
+    if (tintHex && strlen(tintHex) > 0) {
+      NSString* hex = [NSString stringWithUTF8String:tintHex];
+      NSColor* c = ColorFromHexNSString(hex);
+      if (c && [glass respondsToSelector:@selector(setTintColor:)]) {
+        [(id)glass setTintColor:c];
+      } else if (c) {
+        glass.layer.backgroundColor = c.CGColor;
+      }
+    }
+  });
+}
+
+// -----------------------------------------------------------------------------
+// Dynamically set private properties on a previously created glass view
+// -----------------------------------------------------------------------------
+
+// Helper that converts a C-string key (e.g. "variant") into the Objective-C
+// selector for its private setter (e.g. set_variant:). It automatically adds
+// the leading underscore when missing.
+static SEL SetterFromKey(const std::string &key, bool privateVariant) {
+  std::string name;
+  if (privateVariant) {
+    // ensure leading underscore
+    if (!key.empty() && key.front() != '_')
+      name = "_" + key;
+    else
+      name = key;
+    name = "set" + name;
+  } else {
+    // camel-case public variant: set + CapitalizedFirst + rest
+    if (key.empty()) return nil;
+    name = "set";
+    name += toupper(key[0]);
+    name += key.substr(1);
+  }
+  name += ":";
+  return sel_registerName(name.c_str());
+}
+
+static SEL ResolveSetter(id obj, const char* cKey) {
+  if (!cKey) return nil;
+  std::string key(cKey);
+  if (key.empty()) return nil;
+  // Try private style first (set_<key>:)
+  SEL sel = SetterFromKey(key, true);
+  if ([obj respondsToSelector:sel]) return sel;
+  // Then try public style (setKey:)
+  sel = SetterFromKey(key, false);
+  if ([obj respondsToSelector:sel]) return sel;
+  return nil;
+}
+
+extern "C" void SetGlassViewIntProperty(int viewId, const char* key, long long value) {
+#ifdef PLATFORM_OSX
+  RUN_ON_MAIN(^{
+    auto it = g_glassViews.find(viewId);
+    if (it == g_glassViews.end()) return;
+    NSView* glass = it->second;
+
+    SEL sel = ResolveSetter(glass, key);
+    if (!sel) return;
+    if ([glass respondsToSelector:sel]) {
+      ((void (*)(id, SEL, long long))objc_msgSend)(glass, sel, value);
+    }
+  });
+#endif
+}
+
+extern "C" void SetGlassViewStringProperty(int viewId, const char* key, const char* value) {
+#ifdef PLATFORM_OSX
+  RUN_ON_MAIN(^{
+    auto it = g_glassViews.find(viewId);
+    if (it == g_glassViews.end()) return;
+    NSView* glass = it->second;
+
+    SEL sel = ResolveSetter(glass, key);
+    if (!sel) return;
+    if ([glass respondsToSelector:sel]) {
+      NSString* val = value ? [NSString stringWithUTF8String:value] : @"";
+      ((void (*)(id, SEL, id))objc_msgSend)(glass, sel, val);
+    }
+  });
+#endif
+}
+#endif // PLATFORM_OSX 

package/src/liquidglass.cc

@@ -0,0 +1,139 @@
+#include <napi.h>
+#include <string>
+
+#ifdef __APPLE__
+extern "C" int AddGlassEffectView(unsigned char *buffer, bool opaque);
+extern "C" void ConfigureGlassView(int viewId, double cornerRadius, const char *tintHex);
+extern "C" void SetGlassViewIntProperty(int viewId, const char *key, long long value);
+extern "C" void SetGlassViewStringProperty(int viewId, const char *key, const char *value);
+#endif
+
+// Create a class that will be exposed to JavaScript
+class LiquidGlassNative : public Napi::ObjectWrap<LiquidGlassNative>
+{
+public:
+  // This static method defines the class for JavaScript
+  static Napi::Object Init(Napi::Env env, Napi::Object exports)
+  {
+    // Define the JavaScript class with method(s)
+    Napi::Function func = DefineClass(env, "LiquidGlassNative", {InstanceMethod("addView", &LiquidGlassNative::AddView), InstanceMethod("setVariant", &LiquidGlassNative::SetVariant), InstanceMethod("setScrimState", &LiquidGlassNative::SetScrimState), InstanceMethod("setSubduedState", &LiquidGlassNative::SetSubduedState)});
+
+    // Create a persistent reference to the constructor
+    Napi::FunctionReference *constructor = new Napi::FunctionReference();
+    *constructor = Napi::Persistent(func);
+    env.SetInstanceData(constructor);
+
+    // Set the constructor on the exports object
+    exports.Set("LiquidGlassNative", func);
+    return exports;
+  }
+
+  // Constructor
+  LiquidGlassNative(const Napi::CallbackInfo &info)
+      : Napi::ObjectWrap<LiquidGlassNative>(info) {}
+
+private:
+  // New AddView method
+  Napi::Value AddView(const Napi::CallbackInfo &info)
+  {
+    Napi::Env env = info.Env();
+
+    if (info.Length() < 1 || !info[0].IsBuffer())
+    {
+      Napi::TypeError::New(env, "Expected first argument to be a Buffer returned by getNativeWindowHandle()").ThrowAsJavaScriptException();
+      return env.Null();
+    }
+
+    double radius = 0.0;
+    std::string tint;
+    bool opaque = false;
+    if (info.Length() >= 2 && info[1].IsObject())
+    {
+      auto obj = info[1].As<Napi::Object>();
+      if (obj.Has("cornerRadius") && obj.Get("cornerRadius").IsNumber())
+      {
+        radius = obj.Get("cornerRadius").As<Napi::Number>().DoubleValue();
+      }
+      if (obj.Has("tintColor") && obj.Get("tintColor").IsString())
+      {
+        tint = obj.Get("tintColor").As<Napi::String>().Utf8Value();
+      }
+      if (obj.Has("opaque") && obj.Get("opaque").IsBoolean())
+      {
+        opaque = obj.Get("opaque").As<Napi::Boolean>().Value();
+      }
+    }
+
+    auto buffer = info[0].As<Napi::Buffer<unsigned char>>();
+
+#ifdef __APPLE__
+    int viewId = AddGlassEffectView(buffer.Data(), opaque);
+    if (viewId >= 0)
+    {
+      ConfigureGlassView(viewId, radius, tint.c_str());
+    }
+    return Napi::Number::New(env, viewId);
+#else
+    // Not supported on this platform yet
+    return Napi::Number::New(env, -1);
+#endif
+  }
+
+  Napi::Value SetVariant(const Napi::CallbackInfo &info)
+  {
+    Napi::Env env = info.Env();
+    if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsNumber())
+    {
+      Napi::TypeError::New(env, "Expected (id:number, variant:number)").ThrowAsJavaScriptException();
+      return env.Null();
+    }
+    int id = info[0].As<Napi::Number>().Int32Value();
+    long long variant = info[1].As<Napi::Number>().Int64Value();
+    ApplyIntProp(id, "variant", variant);
+    return env.Undefined();
+  }
+
+  Napi::Value SetScrimState(const Napi::CallbackInfo &info)
+  {
+    Napi::Env env = info.Env();
+    if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsNumber())
+    {
+      Napi::TypeError::New(env, "Expected (id:number, scrim:number)").ThrowAsJavaScriptException();
+      return env.Null();
+    }
+    int id = info[0].As<Napi::Number>().Int32Value();
+    long long scrim = info[1].As<Napi::Number>().Int64Value();
+    ApplyIntProp(id, "scrimState", scrim);
+    return env.Undefined();
+  }
+
+  Napi::Value SetSubduedState(const Napi::CallbackInfo &info)
+  {
+    Napi::Env env = info.Env();
+    if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsNumber())
+    {
+      Napi::TypeError::New(env, "Expected (id:number, subdued:number)").ThrowAsJavaScriptException();
+      return env.Null();
+    }
+    int id = info[0].As<Napi::Number>().Int32Value();
+    long long subd = info[1].As<Napi::Number>().Int64Value();
+    ApplyIntProp(id, "subduedState", subd);
+    return env.Undefined();
+  }
+
+  static void ApplyIntProp(int id, const char *key, long long v)
+  {
+#ifdef __APPLE__
+    SetGlassViewIntProperty(id, key, v);
+#endif
+  }
+};
+
+// Initialize the addon
+Napi::Object Init(Napi::Env env, Napi::Object exports)
+{
+  return LiquidGlassNative::Init(env, exports);
+}
+
+// Register the initialization function
+NODE_API_MODULE(liquidglass, Init)