Tech HUD Eyecandy v1.2.0 - Design Upgrade Reference for Gemini
==================================================================

This reference document summarizes the architectural and feature upgrades implemented in Tech HUD Eyecandy v1.2.0.

1. Design Categories (Base Style Hierarchy)
-------------------------------------------
- Spaceship-Neon (Index 0): Cyberpunk neon glows, dark futuristic backgrounds, vibrant borders.
- Glass (Index 1): Multi-variant glass rendering with refraction and polished highlights.
- Marble (Index 2): Luxury stone textures mapping `marble-tile.jpg` with vein/trim coloring and procedural fallback.

2. Glass Variants
-----------------
- 0: Clear Glass (Subtle refraction and crystal sheen)
- 1: Frosted Glass (Soft diffused translucent look)
- 2: Blurry / Diffuse Glass (Radial depth gradient)
- 3: Ultra-Clear Polished Glass (High Brightness crystal clarity with zero noise)
- 4: Diamond Crystal Shimmer (Luxury high-gloss diagonal polish and specular reflection)

3. Marble Background & Asset Lookup
-----------------------------------
- Automatically searches for `marble-tile.jpg` in:
  1. Current working directory (`./marble-tile.jpg`)
  2. `/usr/local/share/tech-hud-eyecandy/marble-tile.jpg`
  3. `/usr/share/tech-hud-eyecandy/marble-tile.jpg`
- Falls back to procedural marble rendering with mineral vein curves if the image file is not found.

4. Dual Effect Opacity Controls
-------------------------------
- Every effect state class (Matrix Rain, Starfield, Defender, Bond Dancer, Synthwave Sun, Digital Clock, Analog Clock, Weather, Date Widget) includes:
  - `bg_opacity`: Effect background layer opacity.
  - `effect_opacity`: Overall effect drawing alpha scaling via Cairo offscreen groups (`cr.push_group()` / `cr.paint_with_alpha()`).

5. Text Character Color & Border Theme Binding
----------------------------------------------
- Text-based effects (Digital Clock, Weather, Date Widget, Analog Clock hands) feature:
  - `use_theme_color`: Checkbox to automatically inherit accent/border colors from the active theme.
  - Custom Character Color Button: Allows precise custom text coloring when theme binding is disabled.

6. Text 3D Styles (Shadow, Debossed/Carved, Embossed/Raised)
-----------------------------------------------------------
- Text 3D Style property (`text_3d_style`):
  - 0: Normal Text / Standard Shadow
  - 1: Debossed / Carved into Stone (Bright highlight top-left, deep shadow bottom-right; ideal for Marble design).
  - 2: Embossed / Raised 3D (Deep shadow top-left, bright highlight bottom-right; 3D pillowed appearance).