🐋 dsh-whale-buddy
A physics-driven, state-aware companion that brings the DeepSeek whale to life in DeepSeek Harness Web.
[!NOTE]
Independent Community Project: dsh-whale-buddy is an independent open-source plugin. It is not an official DeepSeek product and is not affiliated with, sponsored by, or endorsed by DeepSeek. The whale mark belongs to DeepSeek; see THIRD_PARTY_NOTICES.md.
🌟 Overview
dsh-whale-buddy enriches DeepSeek Harness Web (DSH) with a lively, responsive companion that visually mirrors the AI's real-time reasoning, tool calls, and execution states.
Built on a deterministic spring physics engine, the whale breaches through simulated water when a turn begins, swims calmly alongside the active status label, and wears dynamic contextual props representing current tasks—all while preserving the exact vector geometry of the official DeepSeek mark.
dsh-whale-buddy in action
✨ Key Features
-
🌊 Procedural Breach & Water Simulation
Breaches out of simulated water at the start of every turn, creating lively ripples, splash dynamics, and an engaging sense of presence.
-
🐋 Living Breathing Companion
Not just a static mark—the whale breathes steadily, blinks stochastically, and tilts its heading organically according to swimming velocity.
-
🎯 Full-Lifecycle Task & State Awareness
Instantly mirrors thinking, streaming responses, tool execution, file reading/editing, context compaction, and user interaction states with clear status labels and bespoke monochrome vector props.
-
🧷 Dual Seamless Surfaces
- Inline Status Whale: Nestled directly inside the conversation status row with zero layout shift or visual jitter.
- Whale Dock: A sleek, edge-anchored floating pill button on the right edge, draggable vertically, expanding smoothly into a comprehensive companion panel.
-
🎨 Native Visual Integration
Automatically samples typography gradient color stops from the DSH interface, adapting flawlessly to dark and light themes without modifying official logo paths.
-
♿ First-Class Accessibility
Fully respects prefers-reduced-motion: reduce. Immediately presents stable static poses, offers instant panel toggling, and eliminates background frame loop overhead.
🖥️ Product Surfaces
1. Inline Status Whale
When a conversation turn begins, the inline whale executes an authored breach out of a procedural sea, settling into an effortless swim beside the status label. It updates DSH's status text with clear, descriptive task names (深度求索中…, 正在作答…, 读取文件中…, 执行命令中…, etc.) and carries an appropriate task prop.
- Zero Layout Shift: Employs calculated negative bleeds (
fitToMark()) so the breach arc overflows cleanly without shifting surrounding chat layout.
- Native Ink Sampling: Dynamically extracts DSH's gradient stops on mount, harmonizing with both dark and light modes.
2. Whale Dock & Companion Panel
Attached to the right edge of the viewport, the Whale Dock provides a persistent, low-profile companion presence.
- Vertical Track Dragging: Drag the collapsed button vertically with a pointer, or focus it and use
Arrow Up / Arrow Down / Home / End. Position persists proportionally across window resizes.
- Continuous Surface Expansion: Opens inward into a compact companion panel featuring a live preview, state inspector, and quick toggles.
- Fluid Dismissal: Closes gracefully via the close button,
Escape, or outside clicks.
🎭 State & Gesture Matrix
| State | Status Label (zh) | Contextual Prop | Posture & Behavior |
|---|
idle | — | Tossable ball (after 9s dwell) | Relaxed swim, subtle drift, unhurried gestures |
thinking | 深度求索中… | Pulsing dots | Attentive posture, faster chase spring, slight nose dip |
responding | 正在作答… | Breathing speech bubble | Steady forward cruise |
working | 执行命令中… | Articulated wrench | Brisk, purposeful movement |
working · reading | 读取文件中… | Flowing file stream | Files stream horizontally beneath the hull |
working · editing | 编辑文件中… | Sketching pencil | Dynamic stroke cadence with steady drift |
working · searching | 搜索中… | Sweeping magnifier | Inquisitive scanning motions |
compacting | 压缩上下文中… | None (Body deformation) | Elastic vertical compression and rebound |
waiting | 等待你的确认… | Tilted question mark | Nose-up hover, near stillness |
error | 出错了 | Red alert exclamation | Urgent micro-shake with instant red accent |
[!TIP]
All props are plugin-authored vector elements drawn outside the logo silhouette, ensuring DeepSeek's official geometry remains 100% pristine.
📦 Installation
dsh-whale-buddy installs as a standard DeepSeek Harness Web plugin.
1. Register in Web Profile
Add the plugin to your DSH web profile configuration:
// ~/.dsh/profiles/web/package.json
{
"dependencies": {
"dsh-whale-buddy": "link:/path/to/dsh-whale-buddy"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-whale-buddy"
]
}
}
}
2. Build the Plugin
npm ci
npm run build
Environment Requirement: DeepSeek Harness 0.1.5-rc.2 or compatible (requires shell.overlay and conversation.input.overlay extension slots).
⚙️ Configuration
Configure preferences directly from the Whale Dock panel, or set them via localStorage:
localStorage Key | Accepted Values | Default | Description |
|---|
dsh-whale-buddy.enabled | 1 / 0 | 1 | Global master toggle |
dsh-whale-buddy.inlineEnabled | 1 / 0 | 1 | Enable/disable inline status whale |
dsh-whale-buddy.dockEnabled | 1 / 0 | 1 | Enable/disable Whale Dock |
dsh-whale-buddy.size | 18 – 36 | 26 | Inline whale display size (px) |
dsh-whale-buddy.motion | full / subtle / static | full | Motion profile intensity |
dsh-whale-buddy.dockTop | 0.0 – 1.0 | 0.5 | Normalized vertical track position |
🔬 Technical Implementation & Deep Dive
1. Physics-Driven Motion Core
- 120 Hz Fixed-Step Integration: Uses fixed-step substeps combined with critically damped harmonic springs to compute kinematic equations, ensuring identical motion cadence across varying display refresh rates.
- 33-Node Coupled Wave Simulation: Models the sea surface using 33 interconnected discrete harmonic springs, realistically simulating surface depression, fluid rebound, and bidirectional ripple propagation.
- Sub-Pixel Precision: All trajectory scales and travel amplitudes are computed in CSS pixel dimensions rather than relative vector coordinates, guaranteeing razor-sharp visuals at any display scaling factor.
2. Non-Destructive DOM Anchoring & Zero Reflow
- Reference Identity Tracking: Hooks into the DSH status element once via
role="status", then tracks the DOM node by reference identity to eliminate recursive re-matching loops during text changes.
- Negative-Bleed Headroom (
fitToMark()): Offsets visual headroom through negative margins, keeping the host layout box clamped at a stable 26 px without triggering document reflows.
- Clean Lifecycle Teardown: Automatically detaches all MutationObservers, animation frame loops, and restores DSH's original DOM state upon unmounting or session switching.
3. Reactive State Derivation & Debouncing
- Reactive Snapshot Observation: Evaluates DSH snapshot signals directly to identify streaming states, tool queues, and blocking user interaction events.
- 700 ms Minimum Dwell Window: Implements an intentional hold threshold to prevent microsecond tool calls from causing visual flickering.
- Pulsed Error Tracking: Identifies error occurrences by detecting state delta events rather than reading latched error strings, preventing stale warnings from lingering permanently.
4. Zero Dependencies & Absolute Vector Fidelity
- Zero external runtime dependencies; engine mathematics and rendering routines are fully decoupled from UI frameworks.
- DeepSeek's official vector paths are rendered as an unmodified rigid body inside an SVG luminance mask, with 0 coordinate deformation.
🏗️ Architecture & Project Layout
src/
├── index.ts # Plugin entry point
├── client/
│ ├── index.ts # DSH slot registrations
│ ├── config.ts # Schema-validated configuration
│ ├── locales.ts # Bilingual copy definitions
│ ├── integration/
│ │ ├── dsh.ts # React bridge for DSH slots
│ │ ├── thinking-state.ts # Semantic state evaluator
│ │ └── status-anchor.ts # Safe, non-destructive DOM status-line injector
│ ├── state/
│ │ └── whale-state.ts # Shared reactive state store
│ ├── whale/ # Standalone physics & motion core
│ │ ├── geometry.ts # Unmodified DeepSeek vector mark paths
│ │ ├── types.ts # Pose and kinematic interfaces
│ │ ├── spring.ts # Fixed-step spring integrator
│ │ ├── leap.ts # Analytical breach trajectory model
│ │ ├── water.ts # 33-node coupled harmonic spring wave model
│ │ ├── props.ts # Contextual prop definitions & scheduler
│ │ ├── renderer-svg.ts # Hardware-accelerated SVG renderer
│ │ └── view.ts # RAF lifecycle controller
│ └── surfaces/
│ ├── inline-status.ts # Inline status surface controller
│ ├── whale-dock.ts # Dock trigger surface
│ ├── dock-panel.ts # Companion panel surface
│ └── dock-drag.ts # Physics-based drag-and-drop controller
└── styles/
└── plugin-css.ts # Scoped component styles & CSS variables
🛠️ Development & Verification
The project includes an extensive automated test suite verifying physical convergence, DOM safety, and bundle integrity:
# Type check TypeScript sources
npm run typecheck
# Build production bundle
npm run build
# Run complete test suite (138 tests against production bundle)
npm run verify
# Launch visual interactive demo sandbox
npm run demo # Open http://localhost:4173/demo/index.html
# Capture visual artifacts and showcase recordings
npm run shots # Headless screenshot generation
npm run film # Record showcase animation video
🧩 Compatibility & Graceful Fallbacks
- Verified Host:
@deepseek-ai/dsh@0.1.5-rc.1 with client packages at 0.1.5-rc.2.
- Graceful Degradation: If future DSH updates change internal slot names or alter status row markup, the plugin fails silently without interrupting conversation flow.
- Dynamic Theme Adaptation: Adapts automatically to DSH
--dsw-alias-* CSS variables, backed by high-contrast standalone fallback themes.
🙏 Acknowledgements
- Implementation Heritage: dsh-thought-buddy (BSD-3-Clause) for the host/client bundle architecture, fixed-step spring timing model, and bundle verification strategy.
- Interaction Inspiration: dsh-notch (MIT) for the edge-anchored continuous surface concept.
- Trademark Notice: The whale mark is the intellectual property of DeepSeek, incorporated from deepseek-harness (
FishLogo.tsx) with zero coordinate alterations.
📄 License
BSD-3-Clause © 2026 dsh-whale-buddy contributors.
