🐋 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.

---

✨ 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.