dsh-particle-whale 🐳

> English | 简体中文

A native Three.js 3D particle whale background plugin for DeepSeek Harness (DSH) and DSH Desktop.

Recreated with authentic WebGL shaders, full-screen forward fluid locomotion, volumetric 3D particle distribution, and real-time reactive state hooks.

---

Features

• Volumetric 3D Particle Mesh: Uses distance-transform mapping to turn DeepSeek's 2D vector silhouette into a full 3D spindle body with curved dorsal/belly thickness, surface normals, specular highlights, and Fresnel rim glow.
• Head-First Forward Swimming: True aquatic locomotion where the head guides the heading and traveling waves propagate down the spine to the flukes. Banks smoothly into turns across the full window.
• Reactive Agent State:

- Idle: Calm, full-screen widescreen cruise (1.05x scale, 1.1x speed) with subtle tail undulation. - Active (Thinking / Streaming / Tool execution): Smoothly swims to the top-right corner, scales down into a mini companion indicator (0.45x scale), and orbits with high-energy bioluminescent pulse waves.

• New Session Scatter Effect: Triggers a clean nebula explosion and reassembly animation only when creating a new session (Cmd+N / Ctrl+N or clicking the "New Chat" button). Casual clicks are ignored to keep reading undisturbed.
• Frosted Glass Composer: Adds an 88% translucent frosted glass finish (backdrop-filter: blur(20px)) to the chat input card so the whale swims visibly underneath without affecting text contrast.
• Dark / Light Theme Adaptive: Silver-cyan glowing particles with additive blending in dark mode; high-contrast deep sapphire particles in light mode.
• Settings Panel Integration: Plugs directly into DSH Desktop's General Settings page with a native toggle switch and local state persistence.
• High Performance (60–120 FPS): pointer-events: none overlay, precomputed jitter buffers, instanced mesh rendering, and decoupled async state polling.

---

Directory Structure

dsh-particle-whale/
├── package.json          # Cordis client injection manifest
├── cordis.patch.yml      # Cordis kernel plugin patch
├── build.mjs             # esbuild bundler (inlines Three.js runtime)
├── src/
│   └── client.ts         # WebGL rendering pipeline, physics & UI store
├── lib/
│   ├── index.js          # Host entry (empty for client-only plugins)
│   └── client.js         # Production bundle (zero runtime dependencies)
├── README.md
└── LICENSE

---

Quick Start

Option 1: Symlink (Recommended for local dev & testing)

1. Open the DSH Desktop web profile node_modules directory: ``bash cd ~/Library/Application\ Support/dsh-desktop/harness/profiles/web/node_modules ``

2. Symlink this project: ``bash ln -s /path/to/dsh-particle-whale dsh-particle-whale ``

3. Register the plugin in ~/Library/Application Support/dsh-desktop/harness/profiles/web/package.json: ``json { "dependencies": { "dsh-particle-whale": "*" }, "dsh": { "profile": { "bundles": [ "dsh-particle-whale" ] } } } ``

4. Launch or reload DSH Desktop (Cmd+R).

---

Option 2: Install via npm

cd ~/Library/Application\ Support/dsh-desktop/harness/profiles/web
npm install dsh-particle-whale

---

Development & Building

To modify the shaders, kinematics, or UI components:

# Install build dependencies
npm install

# Compile src/client.ts -> lib/client.js
npm run build

---

License

[MIT](./LICENSE) © 2026