socktop-webterm/TRANSPARENCY_GUIDE.md

# Terminal Transparency Guide

## Overview

The terminal now supports transparency, allowing you to see your beautiful background image through the terminal! This uses xterm.js's `allowTransparency` option combined with CSS `backdrop-filter` for a modern, polished look.

## How It Works

The transparency is achieved through three components:

1. **xterm.js `allowTransparency` option** - Enables transparency support
2. **Theme background color with alpha** - Sets the opacity level
3. **CSS backdrop-filter** - Adds optional blur effect

## Current Setup

### Terminal Configuration (JavaScript)

```javascript
var term = new Terminal({
    allowTransparency: true,
    theme: {
        background: "rgba(0, 0, 0, 0.7)", // 70% opaque black
    },
});
```

### Container Styling (CSS)

```css
#terminal {
    background: transparent;
    backdrop-filter: blur(10px); /* Blur effect */
    border: 1px solid rgba(255, 255, 255, 0.2);
    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
}
```

## Customizing Transparency Level

### Option 1: Adjust Terminal Background Opacity

In `templates/term.html`, find the `Terminal` constructor and modify the alpha value:

```javascript
var term = new Terminal({
    allowTransparency: true,
    theme: {
        background: "rgba(0, 0, 0, 0.7)", // Change the last number (0.7)
    },
});
```

**Opacity Values:**
- `0.0` = Fully transparent (you'll see everything through)
- `0.3` = Very transparent (light tint)
- `0.5` = Half transparent (moderate tint)
- `0.7` = Somewhat opaque (recommended, current value)
- `0.9` = Nearly opaque (just a hint of transparency)
- `1.0` = Fully opaque (no transparency)

### Option 2: Change Background Color

You can use any color, not just black:

```javascript
// Dark blue with transparency
background: "rgba(0, 20, 40, 0.7)"

// Dark purple with transparency
background: "rgba(30, 20, 50, 0.7)"

// Dark green with transparency (Matrix style!)
background: "rgba(0, 20, 0, 0.8)"

// Use your theme colors
background: "rgba(48, 52, 70, 0.7)" // Catppuccin Frappe base
```

### Option 3: Adjust Blur Amount

In the CSS, modify the `backdrop-filter` value:

```css
/* No blur - sharp background */
backdrop-filter: none;

/* Light blur */
backdrop-filter: blur(5px);

/* Medium blur (current) */
backdrop-filter: blur(10px);

/* Heavy blur */
backdrop-filter: blur(20px);

/* Blur + brightness adjustment */
backdrop-filter: blur(10px) brightness(0.8);
```

### Option 4: Remove Blur Entirely

If you prefer sharp background with no blur:

```css
#terminal {
    background: transparent;
    backdrop-filter: none; /* Remove this line or set to none */
}
```

## Preset Styles

### Glassy Effect (Recommended)

```javascript
// In Terminal constructor
theme: {
    background: "rgba(0, 0, 0, 0.6)",
}
```

```css
/* In CSS */
#terminal {
    backdrop-filter: blur(15px);
    border: 1px solid rgba(255, 255, 255, 0.2);
    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
}
```

### Minimal Transparency

```javascript
theme: {
    background: "rgba(0, 0, 0, 0.85)",
}
```

```css
#terminal {
    backdrop-filter: blur(5px);
}
```

### Maximum Transparency (Bold!)

```javascript
theme: {
    background: "rgba(0, 0, 0, 0.4)",
}
```

```css
#terminal {
    backdrop-filter: blur(20px) brightness(0.8);
}
```

### Frosted Glass Effect

```javascript
theme: {
    background: "rgba(255, 255, 255, 0.1)", // Light background
    foreground: "#000000", // Dark text
}
```

```css
#terminal {
    backdrop-filter: blur(30px) saturate(180%);
    border: 1px solid rgba(255, 255, 255, 0.3);
}
```

### Acrylic Effect (Windows 11 style)

```javascript
theme: {
    background: "rgba(32, 32, 32, 0.7)",
}
```

```css
#terminal {
    backdrop-filter: blur(40px) saturate(125%) brightness(0.9);
    border: 1px solid rgba(255, 255, 255, 0.15);
    box-shadow: 
        0 8px 32px rgba(0, 0, 0, 0.3),
        inset 0 1px 0 rgba(255, 255, 255, 0.1);
}
```

## Full Theme Customization

You can customize more than just the background:

```javascript
var term = new Terminal({
    allowTransparency: true,
    theme: {
        background: "rgba(0, 0, 0, 0.7)",
        foreground: "#d4d4d4",          // Text color
        cursor: "#ffffff",              // Cursor color
        cursorAccent: "#000000",        // Cursor text color
        selection: "rgba(255, 255, 255, 0.3)", // Selection highlight
        
        // ANSI Colors
        black: "#000000",
        red: "#e74856",
        green: "#16c60c",
        yellow: "#f9f1a5",
        blue: "#3b78ff",
        magenta: "#b4009e",
        cyan: "#61d6d6",
        white: "#cccccc",
        
        // Bright ANSI Colors
        brightBlack: "#767676",
        brightRed: "#e74856",
        brightGreen: "#16c60c",
        brightYellow: "#f9f1a5",
        brightBlue: "#3b78ff",
        brightMagenta: "#b4009e",
        brightCyan: "#61d6d6",
        brightWhite: "#f2f2f2",
    },
});
```

## Browser Compatibility

`backdrop-filter` is supported in:
- ✅ Chrome/Edge 76+
- ✅ Safari 9+
- ✅ Firefox 103+
- ✅ Opera 63+

For older browsers, the terminal will still work but without the blur effect.

## Performance Considerations

**Blur effects can impact performance**, especially on:
- Lower-end devices
- Large terminal windows
- Systems without GPU acceleration

If you experience lag:
1. Reduce blur amount: `blur(5px)` instead of `blur(20px)`
2. Remove blur entirely: `backdrop-filter: none;`
3. Increase opacity: Use `0.8` or `0.9` instead of `0.5`

## Tips for Best Results

1. **Match your background**: Use a background color that complements your page background
2. **Readability first**: Ensure text is still readable - don't go too transparent
3. **Test in different lighting**: What looks good in dark mode might not work in light mode
4. **Consider your content**: Busy backgrounds may need more opacity or blur

## Examples with Different Backgrounds

### Dark Background Image
```javascript
theme: { background: "rgba(0, 0, 0, 0.6)" } // More transparent OK
```

### Light Background Image
```javascript
theme: { background: "rgba(0, 0, 0, 0.8)" } // Need more opacity for contrast
```

### Busy/Complex Background
```javascript
theme: { background: "rgba(0, 0, 0, 0.75)" } // More opacity
// Plus heavy blur
backdrop-filter: blur(20px);
```

### Simple/Minimal Background
```javascript
theme: { background: "rgba(0, 0, 0, 0.5)" } // Can go more transparent
// Light or no blur
backdrop-filter: blur(5px);
```

## Troubleshooting

### Background not showing through
- Check `allowTransparency: true` is set
- Verify background has alpha channel: `rgba(r, g, b, alpha)` not `rgb(r, g, b)`
- Make sure container background is `transparent` not a solid color

### Text hard to read
- Increase opacity: Change `0.5` to `0.7` or `0.8`
- Add more blur: `blur(15px)` or `blur(20px)`
- Darken background: Use `rgba(0, 0, 0, 0.8)` instead of lighter values

### Blur not working
- Check browser compatibility
- Verify CSS syntax: `backdrop-filter: blur(10px);`
- Try without vendor prefixes first

### Performance issues
- Reduce blur amount
- Increase opacity
- Use simpler background image
- Disable backdrop-filter

## Quick Reference

```css
/* Transparency Level */
rgba(0, 0, 0, 0.5)  ← Change this number (0.0 to 1.0)

/* Blur Amount */
backdrop-filter: blur(10px);  ← Change this number

/* Remove blur entirely */
backdrop-filter: none;
```

---

**Enjoy your transparent terminal!** 🎨✨

Experiment with different values to find what looks best with your background image and personal style.