### Run Development Server

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/CONTRIBUTING.md

Start the development server to run the example application and test changes.

```bash
bun run dev
```

--------------------------------

### Install electron-liquid-glass

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/README.md

Install the library using npm.

```bash
npm install electron-liquid-glass
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/CONTRIBUTING.md

Install project dependencies using the Bun package manager.

```bash
bun install
```

--------------------------------

### Example Usage of GlassOptions

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/types.md

Demonstrates how to create and use a `GlassOptions` object when adding a view with `electron-liquid-glass`. Ensure the `electron-liquid-glass` library is imported.

```typescript
import liquidGlass, { GlassOptions } from "electron-liquid-glass";

const options: GlassOptions = {
  cornerRadius: 24,
  tintColor: "#00000020",  // Black with 20% opacity
  opaque: true,
};

const glassId = liquidGlass.addView(window.getNativeWindowHandle(), options);
```

--------------------------------

### Example Usage of RUN_ON_MAIN Macro

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/native-implementation.md

Demonstrates how to use the RUN_ON_MAIN macro to execute UI-related code on the main thread.

```cpp
RUN_ON_MAIN(^{ 
  // All NSView modifications here
});
```

--------------------------------

### Build Electron Liquid Glass from Source

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/README.md

Follow these steps to clone the repository, install dependencies, and build the native module and TypeScript library. Use `bun run build:all` to build everything.

```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
```

--------------------------------

### Configure Glass Effect with TypeScript

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/README.md

TypeScript example demonstrating how to apply a glass effect with custom options like corner radius, tint color, and opacity. Requires importing `GlassOptions`.

```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);
```

--------------------------------

### Configure BrowserWindow for electron-liquid-glass

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/configuration.md

This example demonstrates the essential BrowserWindow configuration for enabling the glass effect. Ensure `transparent` is true and `vibrancy` is false. The `frame: false` option is recommended for full window transparency.

```typescript
import { BrowserWindow } from "electron";

const win = new BrowserWindow({
  width: 800,
  height: 600,
  transparent: true,    // ✅ Required
  vibrancy: false,      // ✅ Do not set to anything else
  frame: false,         // 🔄 Recommended
});

win.setWindowButtonVisibility(true);  // Show traffic light buttons if frame: false

win.loadFile("index.html");

win.webContents.once("did-finish-load", () => {
  liquidGlass.addView(win.getNativeWindowHandle(), {
    cornerRadius: 16,
    opaque: true,
  });
});
```

--------------------------------

### Install electron-liquid-glass with npm, yarn, pnpm, or bun

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/README.md

Use your preferred package manager to install the electron-liquid-glass library. This package provides native macOS glass effects for Electron applications.

```bash
# npm
npm install electron-liquid-glass
```

```bash
# yarn
yarn add electron-liquid-glass
```

```bash
# pnpm
pnpm add electron-liquid-glass
```

```bash
# bun
bun add electron-liquid-glass
```

--------------------------------

### Apply Glass to Multiple Windows in Electron

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/usage-patterns.md

This example demonstrates how to manage and apply the glass effect to multiple Electron windows. It uses a Map to track the glass effect IDs for each window and ensures cleanup when a window is closed.

```typescript
import { app, BrowserWindow } from "electron";
import liquidGlass from "electron-liquid-glass";

const windowGlassIds: Map<number, number> = new Map();

function createWindow(id: number): void {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    transparent: true,
    vibrancy: false,
  });

  win.loadFile("index.html");

  win.webContents.once("did-finish-load", () => {
    const glassId = liquidGlass.addView(win.getNativeWindowHandle());
    if (glassId !== -1) {
      windowGlassIds.set(id, glassId);
    }
  });

  // Clean up tracking when window closes
  win.on("closed", () => {
    windowGlassIds.delete(id);
  });
}

// Create windows
let windowCounter = 0;
app.on("activate", () => {
  if (BrowserWindow.getAllWindows().length === 0) {
    createWindow(windowCounter++);
  }
});

// Create initial window
app.whenReady().then(() => {
  createWindow(windowCounter++);
});
```

--------------------------------

### LiquidGlass EventEmitter Example

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/api-reference/liquid-glass.md

Example of how to listen for events emitted by LiquidGlass. Currently, no events are emitted, but the structure is in place for future integrations.

```typescript
import liquidGlass from "electron-liquid-glass";

liquidGlass.on("event-name", (data) => {
  console.log("Event occurred:", data);
});
```

--------------------------------

### Examples of Invalid NAPI Parameter Types

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/errors.md

Shows examples of calling `liquidGlass` functions with non-numeric arguments, which trigger NAPI TypeErrors.

```typescript
liquidGlass.unstable_setVariant("not-a-number", 2)
liquidGlass.unstable_setScrim(glassId, "not-a-number")
liquidGlass.unstable_setSubdued(glassId, "not-a-number")
```

--------------------------------

### HTML Structure for Glass Window Content

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/usage-patterns.md

Example HTML structure for a window utilizing the liquid glass effect. It includes basic styling for content, cards, and buttons, ensuring the background remains transparent to allow the glass effect to show through.

```html
<!DOCTYPE html>
<html>
<head>
  <style>
    body {
      margin: 0;
      padding: 20px;
      background-color: transparent;
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
    }

    .content {
      background-color: rgba(255, 255, 255, 0.1);
      padding: 20px;
      border-radius: 12px;
      backdrop-filter: blur(10px);
    }

    /* The glass effect provides the background blur;
       overlay elements get their own semi-transparent backgrounds */
    .card {
      background-color: rgba(255, 255, 255, 0.15);
      padding: 16px;
      margin: 12px 0;
      border-radius: 8px;
    }

    button {
      background-color: rgba(0, 120, 215, 0.8);
      color: white;
      border: none;
      padding: 8px 16px;
      border-radius: 6px;
      cursor: pointer;
    }

    button:hover {
      background-color: rgba(0, 120, 215, 1);
    }
  </style>
</head>
<body>
  <div class="content">
    <h1>Glass Effect Window</h1>
    <div class="card">
      <p>This window uses the native glass effect</p>
      <button id="variant-btn">Change Variant</button>
    </div>
  </div>
</body>
</html>
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/CONTRIBUTING.md

Clone the repository and navigate into the project directory to begin development.

```bash
git clone https://github.com/your-username/electron-liquid-glass.git
cd electron-liquid-glass
```

--------------------------------

### Build All and Test

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/CONTRIBUTING.md

Build all project components and run the development server to test your changes.

```bash
bun run build:all
bun run dev
```

--------------------------------

### Examples of Invalid Handle Arguments

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/errors.md

Illustrates incorrect ways to call `liquidGlass.addView()` by passing non-Buffer types for the handle argument, which will result in a TypeError.

```typescript
// ❌ These will throw
liquidGlass.addView("not-a-buffer");
liquidGlass.addView(123);
liquidGlass.addView({ handle: "..." });
```

--------------------------------

### TypeScript with Type Safety for Variants

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/api-reference/variants.md

Illustrates type-safe application of variants using TypeScript. This example defines a function that enforces the correct type for the variant parameter.

```typescript
import liquidGlass, { GlassMaterialVariant } from "electron-liquid-glass";

function applyVariant(glassId: number, variant: GlassMaterialVariant): void {
  liquidGlass.unstable_setVariant(glassId, variant);
}

// Type-safe usage
applyVariant(glassId, liquidGlass.GlassMaterialVariant.dock);

// Error at compile time
applyVariant(glassId, "dock");  // ❌ Type error, not a number
```

--------------------------------

### Build Script for Prebuilt Binaries

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/api-reference/native-loader.md

This bash script shows the commands used to build prebuilt binaries for native modules. It utilizes `prebuildify` to create platform-specific archives.

```bash
bun run build:native
# Runs:
# prebuildify --napi --strip --tag-armv --arch=arm64
# prebuildify --napi --strip --arch=x64
```

--------------------------------

### Node-API Module Initialization

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/native-implementation.md

Registers the LiquidGlassNative class constructor with V8 and makes it available as an export. This macro declares the module entry point.

```cpp
Napi::Object Init(Napi::Env env, Napi::Object exports) {
  LiquidGlassNative::Init(env, exports);
  return exports;
}

NODE_API_MODULE(liquidglass, Init)
```

--------------------------------

### Importing LiquidGlass and Options

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/module-graph.md

Demonstrates how to import the LiquidGlass singleton instance and the GlassOptions interface for configuration. These imports are used when integrating the library into an application.

```typescript
import liquidGlass from "electron-liquid-glass";
import { GlassOptions, GlassMaterialVariant } from "electron-liquid-glass";
```

--------------------------------

### Build Native Module

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/CONTRIBUTING.md

Build the native module for the project. This is a prerequisite for running the application.

```bash
bun run build:native
```

--------------------------------

### Enable Logging with electron-liquid-glass

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/README.md

This snippet demonstrates how to add a glass effect to a window and log the resulting glass ID or any errors encountered. Ensure the 'electron-liquid-glass' library is imported.

```typescript
import liquidGlass from "electron-liquid-glass";

try {
  const glassId = liquidGlass.addView(handle);
  console.log("Glass ID:", glassId);
} catch (err) {
  console.error("Glass error:", err);
}
```

--------------------------------

### Minimal Electron Window with Glass Effect

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/usage-patterns.md

Sets up a minimal Electron BrowserWindow with transparency and applies the glass effect using electron-liquid-glass. Ensure `vibrancy` is set to `false` when using glass. The effect is applied after the window content has finished loading.

```typescript
import { app, BrowserWindow } from "electron";
import liquidGlass from "electron-liquid-glass";

app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    transparent: true,      // Required
    vibrancy: false,        // Do NOT use vibrancy with glass
  });

  win.loadFile("index.html");

  // Apply glass effect after content loads
  win.webContents.once("did-finish-load", () => {
    liquidGlass.addView(win.getNativeWindowHandle());
  });
});

app.on("window-all-closed", () => {
  if (process.platform !== "darwin") app.quit();
});
```

--------------------------------

### View Registry and Association Keys (Objective-C++)

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/native-implementation.md

Global state for tracking glass views by ID and keys for associating views with containers for cleanup. Ensure proper cleanup to avoid memory leaks.

```cpp
static std::map<int, NSView *> g_glassViews;
static int g_nextViewId = 0;
```

```cpp
static const void *kGlassEffectKey = &kGlassEffectKey;
static const void *kBackgroundViewKey = &kBackgroundViewKey;
```

--------------------------------

### Check Glass Support After Instantiation

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/errors.md

After creating an instance of the library, check if the glass effect is supported on the current platform. This is useful for falling back to standard window behavior when the native addon fails to load.

```typescript
if (!liquidGlass.isGlassSupported()) {
  console.log("Glass effect not available, falling back to standard Electron window");
}
```

--------------------------------

### React to System Appearance Changes in Main Process

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/usage-patterns.md

Listen for system appearance changes and update window effects accordingly. Note that re-applying tint colors might require window re-creation or future API updates.

```typescript
import { app, BrowserWindow, nativeTheme } from "electron";
import liquidGlass from "electron-liquid-glass";

let win: BrowserWindow | null = null;
let glassId: number | null = null;

function createWindow(): void {
  win = new BrowserWindow({
    width: 800,
    height: 600,
    transparent: true,
    vibrancy: false,
  });

  win.loadFile("index.html");

  win.webContents.once("did-finish-load", () => {
    glassId = liquidGlass.addView(win!.getNativeWindowHandle(), {
      cornerRadius: 16,
      tintColor: nativeTheme.shouldUseDarkColors ? "#00000040" : "#FFFFFF40",
    });
  });
}

// Listen for appearance changes
nativeTheme.on("updated", () => {
  if (win && glassId !== null) {
    // Note: Re-applying with new color would require removeView (not yet implemented)
    // For now, glass automatically adapts via NSGlassEffectView's built-in dark mode support
    win.webContents.send("appearance-changed", {
      isDark: nativeTheme.shouldUseDarkColors,
    });
  }
});

app.whenReady().then(createWindow);
```

--------------------------------

### Instantiate LiquidGlass

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/api-reference/liquid-glass.md

Import and instantiate the LiquidGlass singleton. This is automatically handled by the module.

```typescript
const liquidGlass = new LiquidGlass();
// Automatically instantiated and exported as default
```

--------------------------------

### TypeScript Configuration and Imports

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/configuration.md

Import types and configure options for Electron Liquid Glass. Ensure you have the necessary types available for `GlassOptions` and `GlassMaterialVariant`.

```typescript
import liquidGlass, { GlassOptions, GlassMaterialVariant } from "electron-liquid-glass";

const options: GlassOptions = {
  cornerRadius: 16,
  tintColor: "#44000010",
  opaque: true,
};

const variant: GlassMaterialVariant = liquidGlass.GlassMaterialVariant.dock;
```

--------------------------------

### Public Methods

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/INDEX.md

This section details the public methods available for interacting with the LiquidGlass instance.

```APIDOC
## addView()

### Description
Adds a new view to be rendered with a liquid glass effect.

### Method
`addView`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **Buffer** (Buffer) - Required - The buffer containing the view data.
- **GlassOptions?** (GlassOptions) - Optional - Configuration options for the glass effect.

### Request Example
```javascript
liquidGlass.addView(myBuffer, { cornerRadius: 10, tintColor: "#FF0000" })
```

### Response
#### Success Response (200)
- **number** - The ID of the newly added view.

#### Response Example
```json
1
```
```

```APIDOC
## isGlassSupported()

### Description
Checks if the current environment supports the liquid glass effect.

### Method
`isGlassSupported`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
if (liquidGlass.isGlassSupported()) {
  console.log("Liquid glass is supported!");
}
```

### Response
#### Success Response (200)
- **boolean** - True if liquid glass is supported, false otherwise.

#### Response Example
```json
true
```
```

```APIDOC
## unstable_setVariant(number, number)

### Description
Unstable method to set the glass material variant. Use with caution.

### Method
`unstable_setVariant`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **number** - Required - The ID of the view.
- **number** - Required - The variant ID.

### Request Example
```javascript
liquidGlass.unstable_setVariant(viewId, 5);
```

### Response
#### Success Response (200)
- **void** - This method does not return a value.

#### Response Example
```json
null
```
```

```APIDOC
## unstable_setScrim(number, number)

### Description
Unstable method to set the scrim for a glass effect. Use with caution.

### Method
`unstable_setScrim`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **number** - Required - The ID of the view.
- **number** - Required - The scrim value.

### Request Example
```javascript
liquidGlass.unstable_setScrim(viewId, 100);
```

### Response
#### Success Response (200)
- **void** - This method does not return a value.

#### Response Example
```json
null
```
```

```APIDOC
## unstable_setSubdued(number, number)

### Description
Unstable method to set the subdued state for a glass effect. Use with caution.

### Method
`unstable_setSubdued`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **number** - Required - The ID of the view.
- **number** - Required - The subdued value.

### Request Example
```javascript
liquidGlass.unstable_setSubdued(viewId, 50);
```

### Response
#### Success Response (200)
- **void** - This method does not return a value.

#### Response Example
```json
null
```
```

--------------------------------

### Build Native Module with npm Scripts

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/api-reference/native-loader.md

Scripts for building the native module and TypeScript files. Use `build:native` to build and create prebuilds, or `build:all` for native and TypeScript builds.

```bash
npm run build:native    # Build and create prebuilds
```

```bash
npm run build:all       # Build native + TypeScript
```

--------------------------------

### Load Native Addon with node-gyp-build

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/api-reference/native-loader.md

This snippet uses the 'node-gyp-build' package to locate and load the native addon. It prioritizes pre-built binaries and falls back to locally compiled ones, caching the result for efficiency.

```typescript
const nodeGypBuild = require("node-gyp-build");
export default nodeGypBuild(join(__dirname, ".."));
```

--------------------------------

### Correct Usage of addView with Buffer Handle

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/errors.md

Demonstrates the correct way to call `liquidGlass.addView()` by passing a Buffer obtained from `window.getNativeWindowHandle()`.

```typescript
// ✅ This is correct
const handle = window.getNativeWindowHandle();  // Returns Buffer
liquidGlass.addView(handle);
```

--------------------------------

### Configure Glass View (Objective-C++)

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/native-implementation.md

Configures the corner radius and tint color of an existing glass effect view. Silently fails if the view ID is invalid. Ensure Core Animation is enabled for layer properties.

```cpp
auto it = g_glassViews.find(viewId);
if (it == g_glassViews.end()) return;  // Silently fail if ID invalid
NSView* glass = it->second;
```

```cpp
glass.wantsLayer = YES;  // Enable Core Animation
glass.layer.cornerRadius = cornerRadius;
glass.layer.masksToBounds = YES;  // Clip content to radius
```

```cpp
NSView* backgroundView = objc_getAssociatedObject(container, kBackgroundViewKey);
if (backgroundView) {
  backgroundView.wantsLayer = YES;
  backgroundView.layer.cornerRadius = cornerRadius;
  backgroundView.layer.masksToBounds = YES;
}
```

```cpp
if (tintHex && strlen(tintHex) > 0) {
  NSString* hex = [NSString stringWithUTF8String:tintHex];
  NSColor* c = ColorFromHexNSString(hex);
  if (c && [glass respondsToSelector:@selector(setTintColor:)]) {
    [(id)glass setTintColor:c];  // NSGlassEffectView
  } else if (c) {
    glass.layer.backgroundColor = c.CGColor;  // Fallback
  }
}
```

--------------------------------

### Verify Native Module Loading Path

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/api-reference/native-loader.md

Use this TypeScript snippet to log the resolved path of the 'node-gyp-build' module and check for the presence of the 'LiquidGlassNative' class. This helps confirm that the native module is being loaded correctly.

```typescript
import native from "./native-loader.js";

console.log("Native module loaded from:");
console.log("  Path:", require.resolve("node-gyp-build"));

// Check if LiquidGlassNative is available
if (native.LiquidGlassNative) {
  console.log("LiquidGlassNative class found ✓");
} else {
  console.log("LiquidGlassNative class NOT found ✗");
}
```

--------------------------------

### liquidGlass.addView(handle, options?)

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/README.md

Applies a glass effect to an Electron window. This is the primary method for enabling the glass effect.

```APIDOC
## liquidGlass.addView(handle, options?)

### Description
Applies a glass effect to an Electron window.

### Parameters
#### Path Parameters
- **handle** (Buffer) - Required - The native window handle from `BrowserWindow.getNativeWindowHandle()`
- **options** (GlassOptions) - Optional - Configuration options for the glass effect

### Returns
- **number** - A unique view ID for future operations
```

--------------------------------

### Clean and Build Native Module

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/CONTRIBUTING.md

Clean previous build artifacts and then build the native module. This is useful for ensuring a fresh build.

```bash
# Clean build
bun run clean
bun run build:native
```

--------------------------------

### addView(handle, options?)

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/api-reference/liquid-glass.md

Applies a glass effect to an Electron BrowserWindow by inserting a native NSGlassEffectView (or fallback NSVisualEffectView) behind the window's content. Requires the window to have `transparent: true` and `vibrancy: false`.

```APIDOC
## addView(handle, options?)

### Description
Applies a glass effect to an Electron BrowserWindow by inserting a native `NSGlassEffectView` (or fallback `NSVisualEffectView`) behind the window's content.

### Method
`addView(handle: Buffer, options?: GlassOptions): number`

### Parameters
#### Path Parameters
- **handle** (`Buffer`) - Required - Native window handle from `BrowserWindow.getNativeWindowHandle()`

#### Query Parameters
- **options** (`GlassOptions`) - Optional - Configuration object for glass appearance and behavior
  - **cornerRadius** (`number`) - Optional - Corner radius for the glass effect.
  - **tintColor** (`string`) - Optional - Hex color string for the tint (e.g., "#44000010").
  - **opaque** (`boolean`) - Optional - If `true`, creates an `NSBox` background view beneath the glass.

### Returns
`number` - A unique view ID for future API calls, or `-1` if not supported on current platform.

### Throws
`Error` - If `handle` is not a Buffer.

### Behavior
- On macOS, creates an `NSGlassEffectView` (if available) or falls back to `NSVisualEffectView`.
- Inserts the view behind (NSWindowBelow) the window's content.
- If opaque is `true`, also creates an `NSBox` background view beneath the glass.
- Stores the view in an internal registry by numeric ID.
- Returns `-1` on non-macOS platforms (safe no-op).

### Platform notes
- On macOS 26+ with NSGlassEffectView available: uses native glass API.
- On macOS 11-25 or if NSGlassEffectView unavailable: falls back to NSVisualEffectView with behind-window blending.
- On Windows/Linux: returns `-1`, addon is not loaded.

### Requirements
- Window must have `transparent: true` in BrowserWindow options.
- Window should have `vibrancy: false` (vibrancy will override glass effect).
- Call after `did-finish-load` to ensure content is rendered before glass effect applies.

### Example
```typescript
import { app, BrowserWindow } from "electron";
import liquidGlass from "electron-liquid-glass";

app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    transparent: true,
    vibrancy: false,
  });

  win.loadFile("index.html");
  
  win.webContents.once("did-finish-load", () => {
    const glassId = liquidGlass.addView(win.getNativeWindowHandle(), {
      cornerRadius: 16,
      tintColor: "#44000010",
      opaque: true,
    });
    
    if (glassId !== -1) {
      console.log(`Glass effect applied with ID: ${glassId}`);
    }
  });
});
```
```

--------------------------------

### Basic Usage of electron-liquid-glass

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/README.md

Apply a glass effect to an Electron BrowserWindow. Ensure `transparent` is true and `vibrancy` is not set on the BrowserWindow. The `did-finish-load` event is used to ensure the window is ready before applying the glass effect.

```typescript
import { app, BrowserWindow } from "electron";
import liquidGlass from "electron-liquid-glass";

app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    transparent: true,    // Required
    vibrancy: false,      // Must NOT be set
  });

  win.loadFile("index.html");

  win.webContents.once("did-finish-load", () => {
    const glassId = liquidGlass.addView(win.getNativeWindowHandle(), {
      cornerRadius: 16,
      tintColor: "#44000010",
      opaque: true,
    });
  });
});
```

--------------------------------

### Add Glass View with Minimal Options

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/configuration.md

Use this snippet to apply a glass effect with default settings (no rounding, transparent, no background). Ensure `liquidGlass` is initialized and `handle` is a valid identifier.

```typescript
// Use defaults (no rounding, transparent, no background)
const glassId = liquidGlass.addView(handle);
```

--------------------------------

### Add View using Public API

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/module-graph.md

Use the `addView` method from the default export to add a view. Ensure you import `LiquidGlass` and `GlassOptions` from the 'electron-liquid-glass' package.

```typescript
import liquidGlass, { GlassOptions } from "electron-liquid-glass";
const glassId = liquidGlass.addView(handle, options);
```

--------------------------------

### Check Glass Support Before Applying

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/usage-patterns.md

Creates an Electron BrowserWindow and conditionally applies the glass effect only if the platform supports it. This prevents errors on unsupported systems and provides fallback behavior. The glass effect is applied after the window content has finished loading.

```typescript
import liquidGlass from "electron-liquid-glass";

function createWindowWithGlass(): void {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    transparent: true,
    vibrancy: false,
  });

  win.loadFile("index.html");

  win.webContents.once("did-finish-load", () => {
    // Only apply glass on supported platforms
    if (liquidGlass.isGlassSupported()) {
      const glassId = liquidGlass.addView(win.getNativeWindowHandle());
      console.log(`Glass effect applied with ID: ${glassId}`);
    } else {
      console.log("Glass effects not available, using standard window");
    }
  });
}
```

--------------------------------

### Set Regular, Dock, and Sidebar Variants

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/api-reference/variants.md

Recommended for general-purpose app windows. Use these variants to set the material appearance for standard application windows.

```typescript
liquidGlass.unstable_setVariant(glassId, liquidGlass.GlassMaterialVariant.regular);   // #0
liquidGlass.unstable_setVariant(glassId, liquidGlass.GlassMaterialVariant.dock);       // #2
liquidGlass.unstable_setVariant(glassId, liquidGlass.GlassMaterialVariant.sidebar);    // #16
```

--------------------------------

### Add Glass View with All Options

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/configuration.md

Use this snippet to apply a glass effect with custom corner rounding, tint color, and an opaque background. Ensure `liquidGlass` is initialized and `handle` is a valid identifier.

```typescript
const options = {
  cornerRadius: 16,
  tintColor: "#44000010",  // Black 16% opacity
  opaque: true,
};

const glassId = liquidGlass.addView(handle, options);
```

--------------------------------

### isGlassSupported()

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/api-reference/liquid-glass.md

Checks whether the current system supports native liquid glass rendering. Caches the result after the first call.

```APIDOC
## isGlassSupported()

### Description
Checks whether the current system supports native liquid glass rendering.

### Method
`isGlassSupported(): boolean`

### Parameters
No parameters.

### Returns
`boolean` - `true` if macOS 26+ (Tahoe or later), `false` otherwise.

### Behavior
- Caches the result after first call.
- Calls `sw_vers -productVersion` to check macOS version.
- Returns `false` on non-macOS platforms.

### Example
```typescript
import liquidGlass from "electron-liquid-glass";

if (liquidGlass.isGlassSupported()) {
  console.log("Liquid glass is available on this macOS version");
} else {
  console.log("Liquid glass requires macOS 26+");
}
```
```

--------------------------------

### Verify Native Window Handle

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/README.md

This snippet shows how to retrieve the native window handle and verify if it is a Buffer. This is a crucial step before passing the handle to the liquid glass API.

```typescript
const handle = window.getNativeWindowHandle();
console.log("Handle is Buffer:", Buffer.isBuffer(handle));
```

--------------------------------

### Create Feature Branch

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/CONTRIBUTING.md

Create a new branch for your feature development. Use a descriptive name for the branch.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### ConfigureGlassView

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/native-implementation.md

Configures an existing glass view by setting its corner radius and tint color. It looks up the view by its ID and applies the specified properties.

```APIDOC
## ConfigureGlassView

### Description
Configures an existing glass view by setting its corner radius and tint color. It looks up the view by its ID and applies the specified properties.

### Method
extern "C"

### Signature
void ConfigureGlassView(int viewId, double cornerRadius, const char* tintHex)

### Parameters
#### Path Parameters
- **viewId** (int) - Registry ID from `AddGlassEffectView()`
- **cornerRadius** (double) - Radius in pixels (0 = no rounding)
- **tintHex** (const char*) - Hex color string (#RRGGBB or #RRGGBBAA)

### Implementation Notes
- Looks up the view by ID in the global registry.
- Applies corner radius to both the glass view and its background view if it exists.
- Parses the hex color string and applies it as a tint color or background color.
```

--------------------------------

### LiquidGlass Class Reference

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/INDEX.md

Reference for the main LiquidGlass class, including its constructor, properties, and public methods for interacting with glass effects.

```APIDOC
## LiquidGlass Class

### Description
Provides methods to apply and manage glass effects on views.

### Methods

#### `isGlassSupported()`

- **Description**: Checks if the current platform supports glass effects.
- **Returns**: `boolean` - True if supported, false otherwise.

#### `addView(handle, options?)`

- **Description**: Applies a glass effect to a specified view.
- **Parameters**:
  - **handle** (number) - Required - The unique identifier for the view.
  - **options** (`GlassOptions`?) - Optional - Configuration options for the glass effect.
- **Returns**: `void`

#### `unstable_setVariant(id, variant)`

- **Description**: Changes the appearance variant of an existing glass effect.
- **Parameters**:
  - **id** (number) - Required - The identifier of the glass effect to modify.
  - **variant** (`GlassMaterialVariant`) - Required - The new material variant to apply.
- **Returns**: `void`

#### `unstable_setScrim(id, scrim)`

- **Description**: Toggles the scrim (overlay) for a glass effect.
- **Parameters**:
  - **id** (number) - Required - The identifier of the glass effect.
  - **scrim** (boolean) - Required - True to enable scrim, false to disable.
- **Returns**: `void`

#### `unstable_setSubdued(id, subdued)`

- **Description**: Toggles the subdued state of a glass effect.
- **Parameters**:
  - **id** (number) - Required - The identifier of the glass effect.
  - **subdued** (boolean) - Required - True to set subdued, false otherwise.
- **Returns**: `void`

### Events

- The `LiquidGlass` class is an EventEmitter, allowing you to listen for various events.
```

--------------------------------

### Typed Configuration for Windows with Glass Options

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/usage-patterns.md

Define a typed interface for window configurations, including optional glass effects and material variants. This promotes type safety and better code organization.

```typescript
import { BrowserWindow } from "electron";
import liquidGlass, { GlassOptions, GlassMaterialVariant } from "electron-liquid-glass";

interface WindowConfig {
  glassOptions?: GlassOptions;
  variant?: GlassMaterialVariant;
}

function createConfiguredWindow(config: WindowConfig): number | null {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    transparent: true,
    vibrancy: false,
  });

  win.loadFile("index.html");

  win.webContents.once("did-finish-load", () => {
    const glassId = liquidGlass.addView(
      win.getNativeWindowHandle(),
      config.glassOptions ?? {
        cornerRadius: 12,
        opaque: false,
      }
    );

    if (glassId !== -1 && config.variant !== undefined) {
      liquidGlass.unstable_setVariant(glassId, config.variant);
    }

    return glassId;
  });

  return null;
}

// Usage
const config: WindowConfig = {
  glassOptions: {
    cornerRadius: 16,
    tintColor: "#44000010",
    opaque: true,
  },
  variant: liquidGlass.GlassMaterialVariant.dock,
};

createConfiguredWindow(config);
```

--------------------------------

### GlassOptions Interface

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/README.md

Defines the configuration options available for the `liquidGlass.addView` method.

```APIDOC
## GlassOptions

### Description
Configuration options for the glass effect.

### Fields
- **cornerRadius** (number) - Optional - Corner radius in pixels (default: 0)
- **tintColor** (string) - Optional - Hex color with optional alpha (#RRGGBB or #RRGGBBAA)
- **opaque** (boolean) - Optional - Add opaque background behind glass (default: false)
```

--------------------------------

### LiquidGlassNative Class Methods

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/native-implementation.md

This section details the methods exposed by the LiquidGlassNative class, which act as the bridge between JavaScript and the native macOS implementation. These methods handle view creation, configuration, and state updates.

```APIDOC
## Method: AddView()

### Description
Adds a new glass effect view to the application window. It takes a buffer containing view data and optional configuration options, returning a unique identifier for the created view.

### Method
`AddView(handle: Buffer, options?: GlassOptions): number`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **handle** (Buffer) - Required - A buffer containing the native view data.
- **options** (GlassOptions) - Optional - An object with configuration properties:
  - **cornerRadius** (number) - The corner radius for the glass effect.
  - **tintColor** (string) - The tint color for the glass effect.
  - **opaque** (boolean) - Whether the glass effect should be opaque.

### Request Example
```javascript
const glassId = addon.addView(viewBuffer, { cornerRadius: 10, tintColor: '#FF0000', opaque: true });
```

### Response
#### Success Response (200)
- **viewId** (number) - A non-negative integer representing the unique ID of the created glass view, or -1 if an error occurred or the platform is not macOS.

#### Response Example
```json
1
```

## Method: SetVariant()

### Description
Sets a variant property for a specific glass effect view. This is used to control different visual styles or states of the glass effect.

### Method
`setVariant(glassId: number, variantNumber: number): undefined`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **glassId** (number) - Required - The ID of the glass view to modify.
- **variantNumber** (number) - Required - The variant number to set.

### Request Example
```javascript
addon.setVariant(glassId, 2);
```

### Response
#### Success Response (200)
This method does not return a value (undefined).

#### Response Example
```json
null
```

## Method: SetScrimState()

### Description
Sets the scrim state for a specific glass effect view. The scrim state typically controls the level of dimming or overlay applied to the view.

### Method
`setScrimState(glassId: number, scrimState: number): undefined`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **glassId** (number) - Required - The ID of the glass view to modify.
- **scrimState** (number) - Required - The scrim state value to set.

### Request Example
```javascript
addon.setScrimState(glassId, 1);
```

### Response
#### Success Response (200)
This method does not return a value (undefined).

#### Response Example
```json
null
```

## Method: SetSubduedState()

### Description
Sets the subdued state for a specific glass effect view. This likely controls a visual state where the glass effect is less prominent or visually softened.

### Method
`setSubduedState(glassId: number, subduedState: number): undefined`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **glassId** (number) - Required - The ID of the glass view to modify.
- **subduedState** (number) - Required - The subdued state value to set.

### Request Example
```javascript
addon.setSubduedState(glassId, 0);
```

### Response
#### Success Response (200)
This method does not return a value (undefined).

#### Response Example
```json
null
```
```

--------------------------------

### Handle Native Addon Loading Errors

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/api-reference/native-loader.md

Catch errors when instantiating the native addon. If loading fails, the liquid glass functionality will be disabled and the addon remains undefined.

```typescript
try {
  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
  );
  // this._addon remains undefined
}
```

--------------------------------

### Stage and Commit Changes

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/CONTRIBUTING.md

Stage all changes and commit them with a conventional commit message.

```bash
git add .
git commit -m "feat: add your feature description"
```

--------------------------------

### Build TypeScript Library

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/CONTRIBUTING.md

Build the TypeScript library. This command compiles the TypeScript code into JavaScript.

```bash
bun run build
```

--------------------------------

### Create Window with Dynamic Tint Color

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/usage-patterns.md

Applies a custom tint color to a BrowserWindow using electron-liquid-glass. Ensure the window is transparent and vibrancy is disabled for tinting to work effectively. The tint color is defined in RGBA format and converted to hex.

```typescript
import { BrowserWindow } from "electron";
import liquidGlass, { GlassOptions } from "electron-liquid-glass";

function rgbToHex(r: number, g: number, b: number, a: number = 1): string {
  const toHex = (n: number) => Math.round(n * 255).toString(16).padStart(2, "0");
  return `#${toHex(r)}${toHex(g)}${toHex(b)}${toHex(a)}`;
}

function createWindowWithCustomTint(color: { r: number; g: number; b: number; a: number }): void {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    transparent: true,
    vibrancy: false,
  });

  win.loadFile("index.html");

  win.webContents.once("did-finish-load", () => {
    const tintColor = rgbToHex(color.r, color.g, color.b, color.a);

    const options: GlassOptions = {
      cornerRadius: 16,
      tintColor,
      opaque: true,
    };

    liquidGlass.addView(win.getNativeWindowHandle(), options);
  });
}

// Usage
createWindowWithCustomTint({ r: 0.2, g: 0.4, b: 0.8, a: 0.15 });  // Blue tint
```

--------------------------------

### Safe Usage Pattern for Thread Safety

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/native-implementation.md

Illustrates the correct pattern for calling `addView` from the main thread in Electron. Avoid calling `addView` from background threads to prevent undefined behavior.

```javascript
// From main thread (Electron main process)
const glassId = liquidGlass.addView(handle);

// Not safe:
worker_thread.execute(() => {
  liquidGlass.addView(handle);  // "	Undefined behavior
});
```

--------------------------------

### Apply Custom Glass Styles

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/usage-patterns.md

Use this to apply custom glass effects to a BrowserWindow. Ensure the window is transparent and has frame set to false for full customization. The `did-finish-load` event is a good place to apply these styles.

```typescript
import { BrowserWindow } from "electron";
import liquidGlass, { GlassOptions } from "electron-liquid-glass";

function createStyledWindow(): void {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    transparent: true,
    vibrancy: false,
    frame: false,  // Optional: full custom frame
  });

  win.loadFile("index.html");

  win.webContents.once("did-finish-load", () => {
    const options: GlassOptions = {
      cornerRadius: 16,
      tintColor: "#44000010",  // Black with 10% opacity
      opaque: true,            // Add background behind glass
    };

    const glassId = liquidGlass.addView(win.getNativeWindowHandle(), options);
    if (glassId !== -1) {
      console.log("Custom styled glass applied");
    }
  });
}
```

--------------------------------

### Handle Unsupported Platform with addView

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/errors.md

When `addView` is called on an unsupported platform like Windows or Linux, it returns -1 without throwing an error. This snippet shows how to check for this return value and log a message indicating that the glass effect is not available.

```typescript
const glassId = liquidGlass.addView(handle, options);

if (glassId === -1) {
  console.log("Glass not available on this platform");
  // Application can continue; window renders normally
}
```

--------------------------------

### Cross-Platform Glass Effect Implementation

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/errors.md

This pattern demonstrates how to conditionally apply the glass effect only on macOS ('darwin') by checking the `process.platform`. If the platform is not macOS, it logs a message indicating that glass effects are unavailable.

```typescript
if (process.platform === "darwin") {
  const glassId = liquidGlass.addView(handle, glassOptions);
  console.log(`Glass effect applied with ID: ${glassId}`);
} else {
  console.log("Glass effects only available on macOS");
}
```

--------------------------------

### GlassOptions Configuration

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/README.md

Defines the configurable properties for applying a glass effect to a window.

```APIDOC
### Configuration: GlassOptions

```typescript
interface GlassOptions {
  cornerRadius?: number;      // 0-∞ pixels, default: 0
  tintColor?: string;         // #RRGGBB or #RRGGBBAA
  opaque?: boolean;           // Add background, default: false
}
```

- **cornerRadius**: Sets the radius of the window's corners in pixels. Defaults to 0.
- **tintColor**: Specifies the tint color of the glass effect using hexadecimal format (#RRGGBB or #RRGGBBAA).
- **opaque**: If true, adds a background to the window. Defaults to false.
```

--------------------------------

### GlassOptions

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/types.md

Configuration object for glass effect customization passed to addView().

```APIDOC
## GlassOptions

### Description
Configuration object for glass effect customization passed to `addView()`.

### Fields
#### `cornerRadius`
- **Type**: `number`
- **Required**: No
- **Default**: `0`
- **Description**: Corner radius in pixels. Controls the roundness of the glass view edges via CALayer's `cornerRadius` property. Valid range: 0 to window dimensions.

#### `tintColor`
- **Type**: `string`
- **Required**: No
- **Default**: `—`
- **Description**: Hex color code with optional alpha channel. Formats accepted: `#RRGGBB` or `#RRGGBBAA`. Applied via `setTintColor:` on NSGlassEffectView or as `layer.backgroundColor` on fallback views.

#### `opaque`
- **Type**: `boolean`
- **Required**: No
- **Default**: `false`
- **Description**: When `true`, creates an NSBox background view with `NSColor.windowBackgroundColor` positioned behind the glass. When `false`, only the glass view is added.

### Example
```typescript
import liquidGlass, { GlassOptions } from "electron-liquid-glass";

const options: GlassOptions = {
  cornerRadius: 24,
  tintColor: "#00000020",  // Black with 20% opacity
  opaque: true,
};

const glassId = liquidGlass.addView(window.getNativeWindowHandle(), options);
```

### Behavior Notes
- All fields are optional; omitted fields use defaults.
- `cornerRadius` is applied via CALayer `masksToBounds: YES`.
- `tintColor` parsing is case-insensitive and trims whitespace.
- Invalid hex colors are silently ignored (no error thrown).
- If `opaque: true` but `cornerRadius` is set, both the glass and background views receive the corner radius.
```

--------------------------------

### Handle addView Return Value for Errors

Source: https://github.com/meridius-labs/electron-liquid-glass/blob/main/_autodocs/errors.md

The `addView` method returns -1 if the glass effect cannot be applied, such as when the native addon fails to load or the platform is not supported. Check this return value to gracefully handle cases where the glass effect is not applied.

```typescript
const glassId = liquidGlass.addView(handle, options);
if (glassId === -1) {
  console.log("Glass effect not applied");
}
```