dsh-pajama-whale

He is a desk toy first and a status indicator second. Push him around the window, fling him at a wall — he squashes flat against it and stays pinned there until you drag him away. Nothing breaks: no gravity, no damage, no opinions about your code. Leave him alone and he dozes off.

Play with him while a long turn runs. He pulls out a laptop when tools start, pops a thought cloud when you are needed, and speaks up when the context is running out, when a turn failed, or when you have been at it for fifty minutes straight.

No configuration. No network calls of its own. The whole thing is one overlay slot.

Install

Web (verified on DSH 0.2.1-rc.2):

dsh plugin --profile web add dsh-pajama-whale

This installs the latest npm release; append @0.3.6 to pin it. Prefer the tagged GitHub source? Use dsh plugin --profile web add github:lubenkov/dsh-pajama-whale#v0.3.6 (requires git).

Desktop, from a terminal. The npm dsh CLI refuses the reserved desktop profile. Install the command from the app menu Manage dsh Command…, quit the app, then run:

dsh plugin --profile desktop add dsh-pajama-whale

Reopen the app afterwards.

Desktop, in the app. Open the Plugins page and install dsh-pajama-whale there. Keep the app running and follow its restart prompt.

To remove him:

dsh plugin --profile <profile> remove dsh-pajama-whale

No build step at install time: the artwork ships inlined in client.js, so dsh plugin add is all it takes — no postinstall hook, no runtime downloads. It is a pure UI bundle (no dependencies, no host services beyond the ones it reads through).

Declared for DSH >=0.2.1-rc.2 <0.3.0-0 in engines.dsh. DSH enforces it at installation and profile startup; outside the range it refuses the bundle until an exact-version exemption is granted. When listed, the market index carries its own copy of the range, so both must be kept in sync. See COMPATIBILITY.md for the API surface, the exemption command, and what degrades gracefully.

Play with him

You	He
Drag	Follows the pointer. Release slowly and he stays put; release fast (>120 px/s) and he flies. No gravity, no bouncing.
Drag into a wall	Sticks to it, flat: four directions × 8 frames, and the frame is picked by how far you overshoot (up to 110 px) or, after a throw, by impact speed.
Click	Shows the current context pressure (or the session title when it is unknown) in the cloud for 5 s.
Hover the cloud	Same context reading, while the cursor is there.
Click the cloud	Opens the session he is watching.

He follows the agent

What the session does	What he does
A tool has run in this turn	Switches to the working pose — laptop out, 12 frames
Turn running, no tool activity	thinking, 20 frames
Turn finishes	One joy burst
Waiting for your approval or an answer	Cloud shows ?
Last turn failed	Cloud shows ! error for 6 s
Context pressure reaches 80 %	One surprised; cloud shows context N% while it stays ≥80 %, and surprised re-arms below 75 %
50 min of continuous work	Cloud suggests take a break? for 9 s (repeats every 45 min; a pause under 3 min still counts as continuous)
A minute of quiet	Falls asleep on a looping 16-frame sleepy; a yawn (13 frames) when you wake him with the cursor — a new turn wakes him silently

While idle he only blinks (75 %) or wags his tail (25 %), every 1.9–4.5 s, plus a rare hmm… thought. That is 129 frames across 12 sprite sheets. While you drag him or while he is stuck to a wall, poses and one-shot emotions pause: the squash frame wins.

One cloud, strict priority

hover / click context → ? waiting → ! error → take a break? → context N% at ≥80 % → idle hmm… (3.6 s, every 70–160 s). Hovering or clicking always wins, so the pet never hides the context reading from you.

Cheap and quiet

• Nothing to build, nothing to fetch. All 12 sheets (2.3 MB of WebP, 129 frames) are inlined as data URIs into a single 3.1 MB client.js. The plugin makes no outbound requests of its own.
• Cheap when idle. The requestAnimationFrame loop stops as soon as the pet is idle and no pose is playing. Sprite frames advance at each animation's own rate — 8 fps for sleepy, 10 for yawn, 12 for thinking and working, 14 for tail, joy and surprised, 16 for blink. Breathing is a ~3.4 s CSS animation every 25–40 s. While the tab is hidden the browser suspends requestAnimationFrame and breathing is stopped explicitly; the status ticker and idle-thought timer are throttled by the browser but not cancelled. Breathing and random emotions are disabled under prefers-reduced-motion (pose animations still play).
• Never in your way. He mounts only into shell.overlay, and the overlay is pointer-events: none outside his body and cloud.
• Remembers his place. Position, wall and squash depth live in localStorage and are clamped when the window resizes.

Language and privacy

English and Chinese strings follow Settings → Language through ctx.locale (anything else falls back to English). The plugin reads only session status, context pressure, session title and recent tool activity to choose a pose. It sends nothing anywhere, has no telemetry, and stores only the pet's position, wall side, squash depth and stuck flag in localStorage on your machine.

If he does not show up

1. Confirm the profile you installed into is the one you boot.
2. Check the DSH version against the declared range. Outside it, installation or profile startup refuses the bundle; grant an exact-version exemption only after accepting the risk (see COMPATIBILITY.md).
3. Set localStorage['pajama-whale:debug'] = '1' and reload: the cloud then prints the live channels (session id, slot hooks, running state). Missing channels are listed in COMPATIBILITY.md — the pet still renders and drags without them.

Development

Node 20+; Python 3 with Pillow only for repacking artwork.

python tools/build-sheets.py   # PNG frames -> WebP strips (needs assets/sprites/)
node tools/build-client.mjs    # strips -> client.js data URIs
node tests/validate.mjs        # package, sheets, locales, size budget

CI runs the same validation on Node 20 and 24 and fails if the committed client.js drifts from its source.

Path	Role
src/client.src.js	readable client source, sheet placeholders
client.js	built artifact that ships (inlined data URIs)
assets/build/*.webp	packed sprite sheets + manifest.json
tools/build-sheets.py	packer (PNG frames → WebP strips)
tools/build-client.mjs	inliner (strips → client.js)
index.js	empty host half; the pet is browser-side only

assets/sprites/ (the ~64 MB source artwork pack) is not committed; the packed assets/build/*.webp strips are, so you never need it unless you redraw frames.

---

If this little whale makes your DSH window nicer, a ⭐ helps others find him: github.com/lubenkov/dsh-pajama-whale

License

MIT for the code and the artwork.