# Spritely

English | [Chinese](README.md)

> *Your spritely work companion* — a floating mascot for the dsh web UI that reacts to the agent's live work state.

Spritely (formerly the `ui-sprite` plugin) is a dsh client plugin that drops a small, animated character into the corner of the web interface. It watches the agent's activity — idle, thinking, writing, running tools, waiting on you, erroring, or finishing a run — and plays a matching pose, tracks your cursor with its eyes, and can be dragged anywhere.

<p align="center"><em>Four characters: Blob · Bot · Cat · Ghost</em></p>

![](images/dsh-plugin-spritely.webp)

## Features

- **Four switchable characters** — Blob (blue ball), Bot (mint robot), Cat (amber kitty), Ghost (violet specter), each with its own body and eye style.
- **Live work-state poses** — idle, thinking, writing, working, waiting, error, and a brief celebration when a run settles.
- **Cursor-tracking eyes** — pupils follow the mouse (rAF-throttled).
- **Draggable** — grab and move the mascot anywhere; reset returns it to the corner.
- **Customizable background** — solid colors, gradients, image URLs, and local image upload, with fit (contain / stretch) and a fade veil for legibility.
- **Sci-fi HUD styling** — the menu and panels use a fixed dark holographic palette with a cyan neon frame.
- **Selection toolbar** — select text in a conversation message and a floating bar appears: copy, read aloud (browser SpeechSynthesis), and ask (the selection lands in the composer as a Markdown quote block, caret ready on the next line).
- **Persisted** — your character, background, and position live in the DSH host's user-settings document (`~/.dsh/settings.yaml`), shared by every loopback browser on the machine; non-loopback browsers (LAN access) fall back to localStorage.

![](images/demo1.webp)

![](images/demo2.webp)

## Install

Spritely declares both `dsh.bundle` (shipping a `cordis.patch.yml` patch layer) and `dsh.client` (`platform: web`), so a single command installs and registers it:

```bash
# from npm
dsh plugin --profile <name> add @wangjunjian/dsh-spritely

# or from git
dsh plugin --profile <name> add github:wang-junjian/spritely

# or from a local checkout
dsh plugin --profile <name> add ./spritely
```

`add` applies the package's own patch layer, inserting a row `id: ui-sprite` / `name: '@wangjunjian/dsh-spritely'` into the config tree; the host Loader then picks up its `dsh.client` metadata, serves `/plugins/@wangjunjian/dsh-spritely/client.js`, and injects it into `window.__DSH_BOOT__` automatically.

Build artifacts (`lib/`) are not committed: installs from git or a local checkout build them via the `prepare` script, and the npm package ships them prebuilt.

> Its peer dependencies (`@deepseek-ai/dsh-client-runtime`, `dsh-client-ui-layout`, `dsh-client-locale`, …) are in-box dsh packages resolved from the dsh installation itself — they need not be installed separately.

> If you previously added the `ui-sprite` row to `~/.dsh/profiles/<name>/cordis.patch.yml` by hand (per the old instructions), remove that line after upgrading to avoid a duplicate registration.

## Usage

Click the mascot to open its menu:

- **New session** — start a new session (default workspace flow).
- **Reset position** — return the mascot to its default corner.
- **Set background** — open the background console (colors, gradients, image URL, local upload, scale, fade).
- **Switch sprite** — pick one of the four characters.

## Characters

| Character | Look | Palette |
|---|---|---|
| Blob | round ball + antenna star | blue |
| Bot | rounded head + LED eyes | mint green |
| Cat | triangular ears + vertical pupils + whiskers | amber |
| Ghost | wavy hem + big round eyes | violet |

## Development

```bash
npm install          # installs dsh peer dependencies + dev tooling
npm run build        # tsc (types) + tsdown (node-half lib + browser client bundle)
npm test             # vitest
npm run watch        # tsdown --watch
```

The build emits the node-half library (`lib/index.js`, `lib/invariant.js`) and the browser client bundle (`lib/client.js`) in dsh's `__ModuleLoader__` closure-factory format, with CSS Modules inlined by lightningcss.

## License

[MIT](./LICENSE)