dsh-whale-bg

Readme

# dsh-whale-bg

English | [简体中文](README.zh.md)

An unofficial DeepSeek Harness Web UI background that rebuilds the DeepSeek
fish silhouette as a swarm of varied-size particle tiles.

<picture>
  <source
    type="image/webp"
    srcset="https://raw.githubusercontent.com/gooosie/dsh-whale-bg/main/docs/assets/dsh-whale-bg-preview.webp"
  >
  <img
    src="https://raw.githubusercontent.com/gooosie/dsh-whale-bg/main/docs/assets/dsh-whale-bg-preview.gif"
    alt="Animated preview of the dsh-whale-bg particle effect"
  >
</picture>

> This is a community project. It is not affiliated with, maintained by, or
> endorsed by DeepSeek. The fish geometry is reused from the MIT-licensed
> DeepSeek Harness repository; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

Features:

- **Entrance** — particles assemble from a scattered state into the whale
- **Idle swimming** — edges stay loose, the tail carries a travelling wave
- **Hover** — a radial mouse push with cubic falloff + per-tile angle noise
- **Flashlight lighting** — the light hugs the cursor: the whale is nearly
  invisible until the mouse comes near, then brightens inside a small radius
- **Themes** — light (multiply blend, deep blue) and dark (screen blend, glow)
- **30 FPS** rendering to keep the decorative layer inexpensive

## Compatibility

Developed and tested against `@deepseek-ai/dsh@0.1.0-rc.6` on its Web profile.
DeepSeek Harness is still in developer preview, so future releases may require
plugin changes.

## Install

Install the `dsh` CLI by following the
[DeepSeek Harness instructions](https://github.com/deepseek-ai/deepseek-harness#run).
Then install the published plugin into DSH's Web profile:

```sh
dsh plugin --profile web add dsh-whale-bg@0.1.0
dsh web
```

To install from a source checkout instead:

```sh
git clone https://github.com/gooosie/dsh-whale-bg.git
cd dsh-whale-bg
npm ci
npm run check
dsh plugin --profile web add .
dsh web
```

DSH's `web` command always boots the profile named `web`, so the plugin must be
installed into that profile. When installing from source, DSH links to the
checkout; do not move or delete that directory while the plugin is installed.

The `dsh.bundle` patch inserts the `whale-bg` row and the `dsh.client`
declaration mounts the browser half as `/plugins/dsh-whale-bg/client.js`.

Verify the composed configuration with `dsh web --dump-config`.

Remove:

```sh
dsh plugin --profile web remove dsh-whale-bg
```

## Development

```sh
npm ci
npm run build   # tsdown -> lib/index.js (ESM host) + wrapped lib/client.js
npm test        # validate manifests, entries, DSH handoff, injection, and theme API
npm run check   # strict types + clean build + package verification
npm run watch
```

## Structure

```
dsh-whale-bg/
├── package.json       # dsh.bundle (patch) + dsh.client (web module) manifests
├── cordis.patch.yml   # inserts the whale-bg composition row
├── tsdown.config.ts   # ESM host bundle + CJS client bundle
├── scripts/            # package-level regression verification
├── README.zh.md        # Simplified Chinese documentation
├── THIRD_PARTY_NOTICES.md
└── src/
    ├── index.ts       # no-op host entry (enables the Loader entry / scan)
    └── client.ts      # the whole whale background plugin
```

## Tuning

All knobs live in `src/client.ts`:

| Knob | Location | Default |
| --- | --- | --- |
| Particle density | `SAMPLE_SIZE`, `MODEL_STEP` | 60, 0.18 |
| Whale size / position | `computeLayout` | ≤720×540, center |
| Flashlight radius | `lightDistance / 7` | 7 model units |
| Idle visibility floor | `light = 0.05 + …` | 0.05 |
| Mouse push radius | `distance < 4.9` | 4.9 model units |
| Frame rate | `1000 / 30` | 30 FPS |

## Contributing and license

Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Project code
is available under the [MIT License](LICENSE). Third-party notices and the
non-affiliation statement are in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).