npm package: @neoframe/electron-window-corner-addon
Description: Native macOS window corner radius addon for Electron
Author: Innei
Latest version: 0.1.4

# Electron Window Corner Addon

A native macOS window corner radius addon for Electron applications that provides rounded corners and vibrancy effects.

## Features

- ✨ **Native Window Corners** - Add native macOS-style rounded corners to Electron windows
- 🌈 **Vibrancy Effects** - Support for multiple macOS vibrancy materials
- 🎨 **Dark Mode Support** - Automatic adaptation to system theme changes
- ⚡ **High Performance** - Implemented with native Swift and C++
- 🔧 **TypeScript Support** - Complete type definitions included
- 🪟 **Real-time Configuration** - Dynamic corner radius and effect adjustment

## Requirements

- **OS**: macOS 10.15+ (Catalina and above)
- **Node.js**: 16.0.0+
- **Electron**: 35.0.0+
- **Architecture**: x64, arm64 (supports Intel and Apple Silicon)

## Installation

### npm
```bash
npm install electron-window-corner-addon
```

### pnpm
```bash
pnpm add electron-window-corner-addon
```

### yarn
```bash
yarn add electron-window-corner-addon
```

## Basic Usage

### Import the Module
```typescript
import { WindowCorner, VibrancyMaterial, EffectState } from 'electron-window-corner-addon'
import { BrowserWindow } from 'electron'
```

### Create a Window with Rounded Corners
```typescript
// Create a transparent window
const window = new BrowserWindow({
  width: 800,
  height: 600,
  frame: false,
  transparent: true,
  titleBarStyle: 'hiddenInset',
  webPreferences: {
    // your webPreferences
  }
})

// Apply corner radius and vibrancy effect
WindowCorner.setCornerRadius(
  window,
  24, // Corner radius in pixels
  VibrancyMaterial.UNDER_WINDOW_BACKGROUND, // Vibrancy material
  EffectState.ACTIVE // Effect state
)
```

## API Reference

### WindowCorner.setCornerRadius()

Set corner radius and vibrancy effect for a window.

```typescript
WindowCorner.setCornerRadius(
  view: BrowserWindow,
  radius?: number,
  vibrancyMaterial?: VibrancyMaterialType,
  effectState?: EffectStateType
): boolean
```

**Parameters:**
- `view` - Electron BrowserWindow instance
- `radius` - Corner radius in pixels (default: 32)
- `vibrancyMaterial` - Vibrancy material (default: 'under-window-background')
- `effectState` - Effect state (default: 'active')

**Returns:** `true` if successful, `false` if failed

### WindowCorner.getCornerRadius()

Get the current corner radius of a window.

```typescript
WindowCorner.getCornerRadius(view: BrowserWindow): number
```

**Returns:** Current corner radius, or `-1` if not set or error occurred

### Other Methods

```typescript
// Check if the module is available (macOS only)
WindowCorner.isAvailable(): boolean

// Set debug mode
WindowCorner.setDebugMode(enabled: boolean): void

// Get debug mode status
WindowCorner.getDebugMode(): boolean
```

## Vibrancy Materials

```typescript
enum VibrancyMaterial {
  TITLEBAR = 'titlebar',                           // Title bar
  SELECTION = 'selection',                         // Selection
  MENU = 'menu',                                   // Menu
  POPOVER = 'popover',                            // Popover
  SIDEBAR = 'sidebar',                            // Sidebar
  HEADER_VIEW = 'header-view',                    // Header view
  SHEET = 'sheet',                                // Sheet
  WINDOW_BACKGROUND = 'window-background',         // Window background
  HUD_WINDOW = 'hudWindow',                       // HUD window
  FULL_SCREEN_UI = 'full-screen-ui',              // Full screen UI
  TOOL_TIP = 'tool-tip',                          // Tool tip
  CONTENT_BACKGROUND = 'content-background',       // Content background
  UNDER_WINDOW_BACKGROUND = 'under-window-background' // Under window background (recommended)
}
```

## Effect States

```typescript
enum EffectState {
  ACTIVE = 'active',                              // Active state
  INACTIVE = 'inactive',                          // Inactive state
  FOLLOWS_WINDOW_ACTIVE_STATE = 'followsWindowActiveState' // Follows window active state
}
```

## Complete Example

```typescript
import { app, BrowserWindow } from 'electron'
import { WindowCorner, VibrancyMaterial, EffectState } from 'electron-window-corner-addon'

async function createWindow() {
  // Create window
  const mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    frame: false,
    transparent: true,
    titleBarStyle: 'hiddenInset',
    webPreferences: {
      nodeIntegration: false,
      contextIsolation: true
    }
  })

  // Check module availability
  if (WindowCorner.isAvailable()) {
    console.log('WindowCorner module is available')
    
    // Enable debug mode (optional)
    WindowCorner.setDebugMode(true)
    
    // Apply corner radius effect
    const success = WindowCorner.setCornerRadius(
      mainWindow,
      28, // 28px corner radius
      VibrancyMaterial.UNDER_WINDOW_BACKGROUND,
      EffectState.ACTIVE
    )
    
    if (success) {
      console.log('Corner radius effect applied successfully')
      
      // Get current corner radius
      const currentRadius = WindowCorner.getCornerRadius(mainWindow)
      console.log(`Current corner radius: ${currentRadius}px`)
    } else {
      console.log('Failed to apply corner radius effect')
    }
  } else {
    console.log('WindowCorner module not available (may not be macOS)')
  }

  // Load application
  await mainWindow.loadFile('index.html')
  
  // Show window
  mainWindow.show()
}

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

## Recommended CSS

For the best visual effect, use the following styles in your HTML/CSS:

```css
body {
  margin: 0;
  padding: 0;
  background: transparent;
  /* Avoid white background flashing */
  -webkit-app-region: drag; /* Make entire window draggable */
}

/* Ensure content areas are not draggable */
.content {
  -webkit-app-region: no-drag;
}

/* Optimize for dark mode */
@media (prefers-color-scheme: dark) {
  body {
    color: #ffffff;
  }
}
```

## Testing & Debugging

This project includes an interactive testing tool:

```bash
# Run test interface
npm test
```

This will open a test window where you can adjust corner radius, vibrancy materials, and effect states in real-time.

## Build Notes

### Development Build
```bash
# Install dependencies
npm install

# Build TypeScript
npm run build:ts

# Build native module (macOS only)
npm run build:native

# Complete build
npm run build
```

### Clean Build Files
```bash
npm run clean
```

## Known Limitations

1. **macOS Only** - This addon only works on macOS systems
2. **Requires Transparent Window** - Window must be set to `transparent: true`
3. **Requires Frameless Window** - Recommended to use `frame: false` or `titleBarStyle: 'hiddenInset'`

## Troubleshooting

### Corner Effect Not Showing
1. Ensure window is set to `transparent: true`
2. Check if running on macOS system
3. Ensure native module is compiled correctly

### Build Failures
1. Ensure Xcode Command Line Tools are installed
2. Check Node.js version is >= 16.0.0
3. Try reinstalling dependencies: `rm -rf node_modules && npm install`

### Debug Information
```typescript
// Enable debug mode to see detailed logs
WindowCorner.setDebugMode(true)

// Check module status
console.log('Module available:', WindowCorner.isAvailable())
console.log('Debug mode:', WindowCorner.getDebugMode())
```

## Acknowledgments

Special thanks to [@STRRL](https://github.com/STRRL) for his valuable insights and contributions to the native macOS window corner radius solution. His work and expertise in macOS development have been instrumental in making this project possible.

Be sure to check out his amazing AI chat assistant for macOS: [Haye AI](https://haye.ai/) - A private macOS AI assistant that lets you experience top-tier models like DeepSeek R1, GPT-4.1, o3, Claude-3.7, and Gemini-2.5 in a single app.

## License

2025 © Innei, Released under the MIT License.

> [Personal Website](https://innei.in/) · GitHub [@Innei](https://github.com/innei/)