๐Ÿ‹ dsh-whale-buddy

A physics-driven, state-aware companion that brings the DeepSeek whale to life in DeepSeek Harness Web.

English ็ฎ€ไฝ“ไธญๆ–‡

licence: BSD-3-Clause DSH: 0.1.5-rc.2 tests: 138 passing runtime dependencies: 0

--- > [!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](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: ```jsonc // ~/.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 ```bash 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: ```bash # 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](https://github.com/dsh-plugins/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](https://github.com/aa2246740/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](https://github.com/deepseek-ai/deepseek-harness) (`FishLogo.tsx`) with zero coordinate alterations. --- ## ๐Ÿ“„ License [BSD-3-Clause](LICENSE) ยฉ 2026 dsh-whale-buddy contributors.