# Stack Research

**Domain:** Cyberpunk GUI framework crate for Rust (webview-backed rendering, animations, audio)
**Researched:** 2026-02-25
**Confidence:** MEDIUM-HIGH

## Executive Decision

**Use Tauri v2 as an application framework (not a library crate)** with a Tauri plugin architecture to distribute HoloHue's Rust-side logic, and a companion npm package for the frontend layer. The consumer's workflow becomes: `cargo add tauri-plugin-holohue` + `npm install @holohue/ui`. This is the only viable path that balances "distribute via cargo" with "webview-rendered UI."

The pure `cargo add holohue` vision has an architectural tension: web-based rendering requires HTML/CSS/JS assets that cannot be meaningfully distributed through Cargo alone. The Tauri plugin model resolves this cleanly.

---

## Recommended Stack

### Core Framework Layer (Rust)

| Technology | Version | Purpose | Why Recommended |
|------------|---------|---------|-----------------|
| **Tauri** | 2.10.x | Application shell, window management, IPC bridge | Mature Rust+webview framework. v2 is stable (released Oct 2024, now at 2.10.2). Plugin architecture provides the cleanest distribution model. Transparent windows, custom chrome, frameless windows all supported. ~600KB minimum binary size. HIGH confidence. |
| **wry** | 0.54.x | WebView rendering (used transitively via Tauri) | Cross-platform webview abstraction. Uses Edge WebView2 (Windows), WebKitGTK (Linux), WebKit (macOS). Tauri wraps this, so direct usage is unnecessary unless you need lower-level control. HIGH confidence. |
| **tao** | latest | Window creation and event loop (used transitively via Tauri) | Fork of winit with menu bar and system tray support. Tauri uses this internally. HIGH confidence. |
| **window-vibrancy** | 0.7.x | Acrylic/Mica/blur window effects | Official Tauri crate. Supports Acrylic (Win10/11), Mica (Win11), Vibrancy (macOS). Essential for the translucent cyberpunk aesthetic. Does not support Linux (compositor-dependent). HIGH confidence. |
| **rust-embed** | 8.11.x | Compile-time embedding of web assets into binary | Embeds HTML/CSS/JS into the Rust binary at compile time. Enables the plugin crate to carry its own frontend assets. Use with Tauri's custom protocol to serve embedded assets to the webview. HIGH confidence. |
| **serde** / **serde_json** | 1.x | Rust<->JS serialization for IPC | Standard for Tauri command serialization. Required for theme configs, animation parameters, window state. HIGH confidence. |

### Frontend Rendering Layer (JavaScript/TypeScript)

| Technology | Version | Purpose | Why Recommended |
|------------|---------|---------|-----------------|
| **SolidJS** | 1.9.x | Reactive UI framework | Fine-grained reactivity without virtual DOM -- ideal for animation-heavy UIs where you need precise control over DOM updates. 3.9KB gzipped. Signals-based reactivity maps naturally to animation state. JSX syntax is familiar. Official Tauri template support exists. SolidJS 2.0 is in development but 1.9.x is stable and production-ready. HIGH confidence. |
| **Tailwind CSS** | 4.0.x | Utility-first CSS framework | v4.0 released Jan 2025 with 5x faster builds, CSS-first config (no JS config file), built-in container queries, 3D transform utilities, and `@property` support for registered custom properties. The `@property` support is critical for animating CSS custom properties (glow colors, intensities). Use as the base layer, with custom CSS for cyberpunk-specific effects. HIGH confidence. |
| **GSAP** | 3.12.x | Complex animation choreography | Now 100% free including all plugins (thanks to Webflow sponsorship). Timeline-based choreography is exactly what HoloHue needs for sequenced window spawn animations (expand -> light wave -> flicker). ScrollTrigger, MorphSVG, and SplitText all included. 20x faster than jQuery, runs on requestAnimationFrame. The only animation library with proper timeline composition for complex multi-step sequences. HIGH confidence. |
| **Howler.js** | 2.2.x | Audio playback (SFX + ambient) | 7KB gzipped, zero dependencies. Web Audio API with HTML5 Audio fallback. Audio sprite support for efficient SFX bundling (one file, many sounds). Stereo panning for spatial feedback. Automatic caching. Battle-tested (used in production games). Perfect for UI sound effects and ambient loops. HIGH confidence. |

### Development Tooling

| Tool | Version | Purpose | Notes |
|------|---------|---------|-------|
| **Vite** | 6.x | Frontend build tool and dev server | Official SolidJS integration via `vite-plugin-solid`. HMR for rapid UI iteration. Library mode for building the distributable frontend bundle. |
| **TypeScript** | 5.x | Type safety for frontend code | SolidJS has excellent TS support. Type the IPC boundary between Rust and JS. |
| **Tauri CLI** | 2.x | Build, dev, and bundle Tauri apps | `cargo install tauri-cli` or `cargo tauri` via cargo subcommand. |
| **@tauri-apps/api** | 2.x | Frontend API for Tauri commands | TypeScript bindings for invoking Rust commands, managing windows, events. |
| **PostCSS** | 8.x | CSS processing (transitively via Tailwind v4) | Tailwind v4 uses Lightning CSS internally but PostCSS plugins still work for custom transforms. |

---

## Distribution Architecture

This is the most critical architectural decision. Here is the recommended approach:

### The Problem

`cargo add holohue` implies a pure Rust crate. But HoloHue renders via webview, meaning it needs HTML, CSS, and JavaScript assets. Cargo cannot distribute npm packages or JS bundles natively.

### The Solution: Dual-Package Distribution

```
holohue/
  crates/
    tauri-plugin-holohue/     # Cargo crate (Rust logic + embedded web assets)
      src/
        lib.rs                # Plugin init, commands, window management
        theme.rs              # Theme system
        animation.rs          # Animation orchestration (Rust side)
        audio.rs              # Audio configuration
      assets/                 # Pre-built frontend bundle (committed or build-step)
      Cargo.toml              # Published to crates.io
    holohue/                  # Thin wrapper crate for ergonomics
      src/lib.rs              # Re-exports, builder pattern API
      Cargo.toml              # `cargo add holohue` -> depends on tauri-plugin-holohue
  packages/
    @holohue/ui/              # npm package (SolidJS components + CSS + audio assets)
      src/
        components/           # SolidJS component library
        themes/               # CSS theme definitions
        animations/           # GSAP animation presets
        audio/                # Howler.js sound manager + audio sprites
      package.json            # Published to npm
```

**Consumer workflow:**
```bash
# Rust side
cargo add holohue

# Frontend side
npm install @holohue/ui
```

**Alternative (simpler v1):** Embed all frontend assets into the Rust crate using `rust-embed` + Tauri custom protocol. The consumer only does `cargo add holohue` and the crate serves its own pre-built frontend. This sacrifices customizability but delivers the "zero-config" promise.

### Recommended for v1: Embedded Assets Approach

For v1 (demo-ready, not release-ready), embed everything:

1. Build the SolidJS frontend into a static bundle at crate build time
2. Use `rust-embed` to include the bundle in the crate binary
3. Serve via Tauri's custom protocol handler
4. Consumer gets everything from `cargo add holohue`

This matches the PROJECT.md goal: "v1 success = a working demo app."

---

## Alternatives Considered

| Category | Recommended | Alternative | Why Not Alternative |
|----------|-------------|-------------|---------------------|
| **App Framework** | Tauri v2 | Dioxus 0.7 | Dioxus is pure Rust (no JS needed), which is appealing, but its desktop webview rendering is less mature than Tauri's. Dioxus's Blitz native renderer is still experimental. The cyberpunk aesthetic demands CSS animation power that only a real browser engine delivers well. Tauri gives us the full CSS/JS animation stack. Dioxus is worth revisiting for v2 if Blitz matures. |
| **App Framework** | Tauri v2 | Raw wry 0.54 | wry is the bare webview layer that Tauri wraps. Using wry directly avoids Tauri's opinions but means reimplementing window management, IPC, security, bundling, and plugin architecture. Not worth it when Tauri provides all of this. |
| **App Framework** | Tauri v2 | Electron | 40x larger binary (244MB vs 6MB). Ships entire Chromium. Overkill for a Rust crate. Not Rust-native. |
| **Frontend Framework** | SolidJS | Svelte 5 | Svelte compiles away the framework (3KB) and has excellent DX. However, SolidJS's signal-based reactivity gives finer control over exactly when DOM updates happen -- critical for animation choreography where you need to coordinate multiple reactive values without triggering unnecessary re-renders. SolidJS also has first-class Tauri template support. |
| **Frontend Framework** | SolidJS | Vanilla JS/TS | No framework overhead, maximum control. But building a component library with reactive state, lifecycle hooks, and composition patterns from scratch is a massive time sink. SolidJS adds only 3.9KB but provides the entire reactive component model. |
| **Frontend Framework** | SolidJS | Leptos (Rust WASM) | Full-Rust stack is appealing for a Rust crate. But Leptos targets SSR web apps, not desktop component libraries. Its desktop story is immature. CSS animation integration is weaker. And the dev iteration speed for UI work is much slower than SolidJS + Vite HMR. |
| **CSS Framework** | Tailwind v4 | CYBERCORE CSS | CYBERCORE is a cyberpunk-specific CSS framework with glitch effects, neon borders, scanlines, etc. Tempting as a starting point, but it is a small community project (not battle-tested), its aesthetic may not match HoloHue's vision exactly, and building on top of it creates a dependency on an unmaintained project. Better to use Tailwind as the utility foundation and build HoloHue's own cyberpunk CSS layer. Borrow ideas from CYBERCORE but do not depend on it. |
| **CSS Framework** | Tailwind v4 | Plain CSS / CSS Modules | Tailwind's utility classes accelerate prototyping and the design token system (CSS custom properties in v4) maps perfectly to HoloHue's theme system. Plain CSS would work but is slower to develop with. |
| **Animation Library** | GSAP 3.12 | Motion (formerly Framer Motion) | Motion's mini bundle is only 2.3KB and it uses WAAPI for hardware acceleration. Excellent for simple transitions. But GSAP's Timeline API is purpose-built for choreographed multi-step animation sequences (window spawn: scale up -> border glow sweep -> content fade in -> flicker). Motion cannot match GSAP's choreography capabilities. |
| **Animation Library** | GSAP 3.12 | CSS-only animations | CSS @keyframes and transitions handle simple effects (glow pulse, opacity fade) but cannot orchestrate complex timelines with callbacks, staggered sequences, or dynamic parameters. Use CSS for ambient effects (breathing glow, scanline scroll) and GSAP for choreographed sequences. |
| **Audio Library** | Howler.js | Tone.js | Tone.js is a full audio synthesis framework (DAW-like). It can generate sounds programmatically, which is powerful but overkill for UI sound effects. HoloHue needs "play click.wav on button press," not "synthesize a 440Hz sine wave with ADSR envelope." Tone.js is 3x larger. Use Howler.js for sound playback; consider Tone.js only if generative/procedural audio becomes a v2 feature. |
| **Audio Library** | Howler.js | Raw Web Audio API | Possible but requires manual implementation of audio loading, caching, sprite management, format detection, and fallbacks. Howler.js does all of this in 7KB. |
| **Asset Embedding** | rust-embed | include_dir | include_dir is simpler but generates large amounts of code (every file becomes a Rust byte string), causing slow compile times and high RAM usage. rust-embed is more efficient and supports compression. |

---

## What NOT to Use

| Avoid | Why | Use Instead |
|-------|-----|-------------|
| **Electron** | 244MB binary, ships Chromium, not Rust-native | Tauri v2 (6MB binary, system webview) |
| **egui / iced** | Immediate-mode or Elm-architecture GUI. Cannot achieve the CSS animation richness needed for cyberpunk aesthetic. No CSS, no web audio, limited text rendering. | Tauri + webview rendering |
| **React** | 42KB+ runtime, virtual DOM overhead, re-renders entire subtrees. Poor fit for animation-heavy UI where you need surgical DOM control. | SolidJS (3.9KB, no VDOM, fine-grained updates) |
| **jQuery** | Legacy. Irrelevant in 2026. | SolidJS + GSAP |
| **Anime.js** | Smaller community, less capable timeline system than GSAP, no longer actively maintained at the same pace. | GSAP (now fully free, superior timeline API) |
| **Bootstrap / Material UI** | Design systems for conventional web apps. Antithetical to cyberpunk aesthetic. Would fight the design language at every turn. | Tailwind v4 (utility-first, no design opinions) + custom HoloHue CSS |
| **Dioxus (for v1)** | Webview desktop rendering less mature than Tauri. Blitz renderer experimental. Limited CSS animation support in native mode. Worth watching for v2+. | Tauri v2 |
| **CYBERCORE CSS (as dependency)** | Small community project, not battle-tested, aesthetic may diverge from HoloHue's vision. | Build custom cyberpunk CSS on Tailwind v4. Reference CYBERCORE for inspiration only. |

---

## Stack Patterns by Architecture Variant

### If building the v1 demo app (RECOMMENDED for v1):

Monorepo structure. Tauri app with embedded SolidJS frontend. Everything in one repo, one build.

```
holohue-gui/
  src-tauri/          # Rust: Tauri app + HoloHue core logic
  src/                # TypeScript/SolidJS: UI components, themes, animations, audio
  package.json        # Frontend dependencies
  Cargo.toml          # Workspace root
```

- Use `cargo tauri dev` for hot-reloading development
- Frontend served by Vite dev server in development
- Build produces a single executable with embedded frontend

### If distributing as a reusable crate (v2+ goal):

Dual-package model with Tauri plugin.

```
holohue/
  crates/tauri-plugin-holohue/   # Rust crate on crates.io
  packages/@holohue/ui/          # npm package on npmjs.com
```

- Rust crate provides: window management, theme engine, animation orchestration, IPC commands
- npm package provides: SolidJS components, CSS themes, GSAP presets, Howler.js sound manager
- Consumer adds both dependencies

### If maximum simplicity is needed:

Embed pre-built frontend assets in the Rust crate using `rust-embed`. Consumer only needs `cargo add holohue`. Limited customizability but zero-config experience.

---

## Version Compatibility Matrix

| Package | Compatible With | Notes |
|---------|----------------|-------|
| tauri 2.10.x | wry 0.54.x, tao (latest) | Tauri pins its own wry/tao versions. Do not override. |
| tauri 2.10.x | window-vibrancy 0.7.x | v0.4 is for Tauri v1. Must use 0.7+ for Tauri v2. |
| SolidJS 1.9.x | vite-plugin-solid 2.x | Official Vite plugin. Ensure versions match. |
| Tailwind CSS 4.0.x | Vite 6.x | v4 uses Lightning CSS internally. `@import "tailwindcss"` replaces old directives. |
| GSAP 3.12.x | Any framework | Framework-agnostic. Import and use directly. Now fully free. |
| Howler.js 2.2.x | Any environment | Zero dependencies. Works in any browser/webview context. |
| rust-embed 8.11.x | Any Rust project | Use `#[derive(RustEmbed)]` with `#[folder = "assets/dist"]` |

---

## Installation

### Rust Dependencies (Cargo.toml)

```toml
[dependencies]
tauri = { version = "2.10", features = ["custom-protocol"] }
tauri-build = { version = "2.0", features = [] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
window-vibrancy = "0.7"
rust-embed = { version = "8.11", features = ["compression"] }

[build-dependencies]
tauri-build = "2.0"
```

### Frontend Dependencies (package.json)

```bash
# Core
npm install solid-js @tauri-apps/api gsap howler

# Dev dependencies
npm install -D vite vite-plugin-solid typescript tailwindcss @tailwindcss/vite
npm install -D @types/howler
```

### Tauri Configuration (tauri.conf.json key settings)

```json
{
  "app": {
    "windows": [
      {
        "decorations": false,
        "transparent": true,
        "width": 1200,
        "height": 800
      }
    ]
  }
}
```

---

## Key Technical Decisions Rationale

### Why Tauri over pure Rust GUI?

HoloHue's core value proposition is "stunning, animated, cyberpunk-aesthetic GUI." CSS provides:
- `box-shadow` with multiple layers for glow effects
- `clip-path` for angled/notched corners (no canvas math needed)
- `backdrop-filter: blur()` for frosted glass effects
- `@keyframes` for ambient breathing animations at zero JS cost
- `mix-blend-mode` for light overlay effects
- Sub-pixel anti-aliased font rendering (the browser engine handles this)
- GPU-accelerated transforms and opacity animations via compositor

No Rust-native GUI framework can match this animation/visual fidelity without years of additional work.

### Why SolidJS over Svelte?

Both are excellent. SolidJS wins for HoloHue because:
1. **Signal granularity**: When a theme color changes, SolidJS updates only the DOM nodes that use that color. No virtual DOM diffing, no component re-renders. This matters when 50+ elements have independent glow animations.
2. **JSX composition**: Building a component library with TypeScript + JSX provides better tooling, type inference, and composition patterns than Svelte's template syntax.
3. **No compilation step for reactivity**: SolidJS reactivity works at runtime via signals. Svelte requires a compiler. For a library consumed by others, this is simpler.

### Why GSAP over CSS-only or Motion?

HoloHue's signature is choreographed animations. A window spawn involves:
1. Scale from 0 to 100% (200ms, ease-out)
2. Border glow sweeps clockwise (300ms, starts at step 1's 50%)
3. Content fades in (150ms, starts at step 2's end)
4. Subtle flicker effect (100ms, random timing)
5. Ambient glow pulse begins (loop)

This requires timeline composition with overlapping steps, callbacks, and dynamic parameters. GSAP's `gsap.timeline()` handles this natively. CSS cannot express inter-animation dependencies. Motion's API is too simple for this level of choreography.

### Why Howler.js over Tone.js?

HoloHue needs sound playback, not sound synthesis. The audio system plays pre-recorded files:
- Ambient background loops (crossfade between them)
- Click/hover/transition sound effects
- Error/success notification sounds

Howler.js does exactly this with audio sprites (one file, many sounds), caching, format detection, and spatial panning. Tone.js is for building synthesizers and DAWs -- massive overkill.

---

## Risk Assessment

| Risk | Severity | Mitigation |
|------|----------|------------|
| WebView rendering inconsistency across platforms (Edge vs WebKit) | Medium | Test on all 3 platforms. Use Tailwind's prefix/normalize. Avoid WebKit-only CSS features. Most cyberpunk effects (box-shadow, clip-path, backdrop-filter) work cross-browser. |
| window-vibrancy not supported on Linux | Low | Fall back to solid dark background on Linux. The cyberpunk aesthetic works fine without OS-level blur -- the CSS `backdrop-filter` within the webview provides internal blur effects. |
| GSAP bundle size (~50KB minified) | Low | Acceptable for a desktop app. Not a web performance concern. Tree-shake unused plugins. |
| SolidJS 2.0 migration | Low | v2.0 is in early development. v1.9.x will be supported for years. Migration path is being designed to be incremental. |
| Tauri v2 breaking changes | Low | v2 is stable (released Oct 2024). Minor version updates are non-breaking. |
| `rust-embed` compile time with large asset bundles | Medium | Use compression feature. Keep audio assets reasonable. Consider lazy-loading large audio files from disk instead of embedding. |
| Cross-platform audio autoplay restrictions | Medium | Webviews inherit browser autoplay policies. Ambient audio must be triggered by a user interaction (click/keypress) before it can start. Design the audio system to queue ambient playback until first interaction. |

---

## Sources

- [Tauri v2 Official Docs](https://v2.tauri.app/) -- Plugin development, window customization, configuration. HIGH confidence.
- [Tauri Releases on docs.rs](https://docs.rs/crate/tauri/latest) -- Version 2.10.2 confirmed. HIGH confidence.
- [Tauri v2 Stable Release Blog](https://v2.tauri.app/blog/tauri-20/) -- Release date Oct 2024 confirmed. HIGH confidence.
- [wry on docs.rs](https://docs.rs/wry/latest/wry/) -- Version 0.54.2 confirmed. HIGH confidence.
- [window-vibrancy GitHub](https://github.com/tauri-apps/window-vibrancy) -- Version 0.7.1, platform support confirmed. HIGH confidence.
- [SolidJS GitHub Releases](https://github.com/solidjs/solid/releases) -- Version 1.9.0 stable, 2.0 in development. HIGH confidence.
- [SolidJS Road to 2.0 Discussion](https://github.com/solidjs/solid/discussions/2425) -- v2 status. MEDIUM confidence.
- [Tailwind CSS v4.0 Blog](https://tailwindcss.com/blog/tailwindcss-v4) -- Released Jan 2025, features confirmed. HIGH confidence.
- [GSAP GitHub](https://github.com/greensock/GSAP) -- Now fully free, 3.12.x. HIGH confidence.
- [Howler.js GitHub](https://github.com/goldfire/howler.js) -- v2.2.3, 7KB, features confirmed. HIGH confidence.
- [rust-embed on docs.rs](https://docs.rs/crate/rust-embed/latest) -- Version 8.11.0 confirmed. HIGH confidence.
- [Tauri Build as Library Discussion](https://github.com/tauri-apps/tauri/discussions/8344) -- custom-protocol feature approach. MEDIUM confidence.
- [Tauri Plugin Development Docs](https://v2.tauri.app/develop/plugins/) -- Plugin structure and distribution. HIGH confidence.
- [CYBERCORE CSS](https://dev.to/sebyx07/introducing-cybercore-css-a-cyberpunk-design-framework-for-futuristic-uis-2e6c) -- Cyberpunk CSS framework reference. LOW confidence (small project).
- [Web Animation Performance Tier List](https://motion.dev/blog/web-animation-performance-tier-list) -- GPU-accelerated CSS properties. MEDIUM confidence.
- [2025 Survey of Rust GUI Libraries](https://www.boringcactus.com/2025/04/13/2025-survey-of-rust-gui-libraries.html) -- Ecosystem overview. MEDIUM confidence.
- [Tauri vs Electron Comparison (DoltHub)](https://www.dolthub.com/blog/2025-11-13-electron-vs-tauri/) -- Binary size, performance. MEDIUM confidence.
- [SolidJS + Tauri Starter Templates](https://github.com/riipandi/tauri-start-solid) -- Integration patterns. MEDIUM confidence.

---
*Stack research for: HoloHue cyberpunk GUI framework crate*
*Researched: 2026-02-25*