MeteorNOX/DeepSeek-Balance-Whale-Widget

## Core Features
- The plugin adds a persistent whale widget to the lower-right corner of the DSH Web interface and starts automatically when the interface opens.
- It shows DeepSeek API balance with automatic refresh every 60 seconds, manual refresh by clicking the whale, and a rolling number animation when the balance changes.
- It displays today's usage through either local balance-difference bookkeeping without a platform token or a platform-token mode that calculates usage from the platform usage API.
- The widget supports dragging with edge snapping, horizontal mirroring when snapped to the left side, window-based scaling, and press animation with optional sound effects.
- A hover menu provides scale adjustment from 0.6 to 2.5 times, sound toggles, volume control, sound-set selection, and usage-mode selection while remembering size settings.

## Use Cases
- Users can keep DeepSeek balance and daily usage visible while working in the DSH Web interface.
- Users can track daily consumption without a platform session token by relying on balance-difference observations stored in a local usage file.
- Users can calculate today's usage with peak and off-peak pricing by supplying a platform session token for the platform usage endpoint.
- Users can reposition, resize, and mute the widget through dragging, snapping, and the hover menu according to browser layout preferences.

## Technical Details
- The package is a DSH bundle plugin installed and removed through dsh plugin commands, with local development using a link: source path or npm publication.
- Balance data requires DEEPSEEK_API_KEY and calls api.deepseek.com/user/balance, while optional real-time usage requires DEEPSEEK_PLATFORM_TOKEN and calls platform.deepseek.com/api/v0/usage/by_api_key/amount.
- The plugin exposes local endpoints such as /dsh-whale/image.png, /dsh-whale/balance.json, and /dsh-whale/size.json for image delivery, balance data, and persisted widget settings.
- Assets include a transparent PNG for the whale and optional MP3 sound files, while speech bubbles are drawn by code and usage records are stored in .dshw-usage.json.

## Notes
- If DEEPSEEK_API_KEY is not configured, balance display reports the missing credential, and token-based usage requires a separately configured platform session token.
- Local link: installations store an absolute source path, so moving the source directory requires removing and adding the plugin again.
- Sound files are optional and absent files cause silent fallback, while local code changes with link: require restarting dsh web because of ESM caching.