Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(web): 拖住企鹅就能挪动桌宠,点一下它会跳、眼睛还跟着指针

lmlihenge3f22fbf712c
diff --git a/changelog/unreleased/2026-10-21-desktop-pet-motion.md b/changelog/unreleased/2026-10-21-desktop-pet-motion.md
new file mode 100644
index 00000000..91e2a51e
--- /dev/null
+++ b/changelog/unreleased/2026-10-21-desktop-pet-motion.md
@@ -0,0 +1,49 @@
+# The pet is moved by dragging the penguin itself, hops when it is clicked, and its eyes follow the pointer
+
+- **Date:** 2026-10-21
+- **Type:** fix
+- **Scope:** `web`
+- **Breaking:** no
+
+[中文版](2026-10-21-desktop-pet-motion.zh.md)
+
+The desktop pet could not be moved. It was draggable before this, but by the wrong thing: the window carried an
+OS drag region over everything *except* the penguin, which was opted out of it so that a click could reach the
+page — and the penguin is the one part of a transparent window a hand reliably finds. The visible pet was
+therefore exactly the part that would not move, and on a desktop where the transparent area of a frameless
+window receives no pointer input at all, nothing on the pet could move it.
+
+The penguin itself is now the handle: pressing it and moving drags the window, and a press that stays put is a
+click — it opens the panel and makes the pet hop, so a press answers before anything else happens. The pet also
+stopped being a still picture: it blinks on its own, and its pupils follow the pointer.
+
+## Details
+
+- The page moves its own window (`window.moveBy`, one step per pointer sample) instead of asking the window
+ system to. The gesture is measured in screen coordinates — a step taken in the page's own coordinates would
+ fold the window's own movement back into the drag — and it is the app's one drag state machine
+ (`usePointerDrag`, the same one a resize handle and the dock's tabs use), which tracks the gesture on the
+ window and says whether a press was a drag.
+- A press that travels more than 4 CSS px on either axis is a drag and never opens the panel. A press that
+ stays put is a click, wherever the pointer landed on the penguin. The rest of the window keeps its OS drag
+ region for the platforms whose window system delivers input to it, so nothing that could be dragged before
+ stopped being draggable.
+- The hop is 520ms: off the ground with a stretch, down with a squash and a small second bounce. It plays on a
+ click and when a notice arrives — a schedule firing, a tool call waiting for a person, a budget warning — so
+ the pet is seen to notice rather than only read.
+- The eyes: the pair blinks on a 6.4s cycle, and the pupils slide toward the pointer, up to 2.2 of the penguin's
+ own SVG units sideways and 1.6 of them vertically, which is as far as they can go without touching the white
+ ring they sit in. The offset is written straight onto the element as two custom properties, so a pointer
+ moving at 60Hz does not re-render the page.
+- `prefers-reduced-motion` switches the blink, the bob and the hop off with every other animation in the app.
+ The pupils still follow the pointer: that is a position, not a tween, and it is what the pet has left to say
+ in a window where nothing may move.
+- `/pet` is still an ordinary route. In a browser tab the penguin draws, blinks, follows the pointer and hops
+ when clicked; dragging it does nothing, because a browser ignores `moveBy` on a window a script did not open
+ and there is no window there for the page to move.
+
+## Compatibility
+
+- No API, preference, wire-format or dependency change: the pet window, the `/pet` route, the `showPet`
+ preference and the shell's own smoke run are all as they were, and the drag no longer depends on
+ `-webkit-app-region` for the pet to be movable.
diff --git a/changelog/unreleased/2026-10-21-desktop-pet-motion.zh.md b/changelog/unreleased/2026-10-21-desktop-pet-motion.zh.md
new file mode 100644
index 00000000..761f3585
--- /dev/null
+++ b/changelog/unreleased/2026-10-21-desktop-pet-motion.zh.md
@@ -0,0 +1,36 @@
+# 拖住企鹅本身就能挪动桌宠,点它有回弹,眼睛还会跟着指针看
+
+- **Date:** 2026-10-21
+- **Type:** fix
+- **Scope:** `web`
+- **Breaking:** no
+
+[English](2026-10-21-desktop-pet-motion.md)
+
+桌宠拖不动。它此前是能拖的,只是拖错了东西:窗口上盖着一整片系统拖动区,偏偏把企鹅挖了出去 —— 为了让点击
+能落在页面上,企鹅被标成不可拖 —— 而企鹅是透明窗口上人唯一能可靠摸到的那一块。于是看得见的桌宠正好就是
+拖不动的那部分;而在「无边框透明窗口的空透明像素收不到鼠标」的桌面上,整只桌宠没有任何地方能拖动它。
+
+现在企鹅自己就是把手:按住它移动就拖动窗口,而按住不动就是一次点击 —— 开合面板,并让企鹅跳一下,按下去
+立刻有回应。桌宠也不再是一张静止的画:它会自己眨眼,瞳孔跟着指针转。
+
+## 细节
+
+- 由页面自己移动窗口(`window.moveBy`,每个指针采样走一步),而不是请窗口系统代劳。手势按**屏幕坐标**度量
+ —— 用页面自己的坐标量,窗口自身的位移会被折回手势里 —— 走的是全应用共用的那台拖动状态机
+ (`usePointerDrag`,缩放条与停靠栏标签页用的是同一个),它在窗口上跟踪手势,并判断某一次按压算不算拖动。
+- 任一轴位移超过 4 CSS px 就是拖动,绝不开面板;按住不动就是点击,落在企鹅的任何位置都算。窗口其余部分保留
+ 原来的系统拖动区,供那些会把输入投递到透明区域的窗口系统使用 —— 此前拖得动的地方现在照旧拖得动。
+- 跳跃 520ms:带着拉伸离地、带挤压落地、再弹一下。它在点击时播放,也在收到通知时播放(定时任务触发、有工具
+ 调用在等批准、预算告警)—— 于是桌宠的「注意到了」是看得见的,而不只是读得到。
+- 眼睛:一对眼睛按 6.4 秒一轮眨眼,瞳孔随指针滑动,横向最多 2.2 个企鹅自己的 SVG 单位、纵向 1.6 个 —— 这是
+ 不碰到所在白眼圈所能到的极限。偏移直接写成元素上的两个自定义属性,所以 60Hz 的指针移动不会触发页面重渲染。
+- 系统要求减少动效时,眨眼、摇晃与跳跃随应用里其它动画一起关闭。瞳孔仍然跟随指针:那是一个位置而不是一段
+ 补间,也是在一个不许动的窗口里桌宠剩下的表达。
+- `/pet` 仍是普通路由。浏览器标签里打开,企鹅照样画出来、眨眼、跟随指针、点了会跳;拖动则没有反应 —— 浏览器
+ 会忽略脚本没打开过的窗口上的 `moveBy`,而且那里本来也没有窗口可给页面移动。
+
+## 兼容性
+
+- 没有接口、偏好、传输格式或依赖变化:桌宠窗口、`/pet` 路由、`showPet` 偏好与壳自己的冒烟运行都照旧,而桌宠
+ 能不能被拖动不再依赖 `-webkit-app-region`。
diff --git a/packages/web/e2e/pet.spec.mjs b/packages/web/e2e/pet.spec.mjs
index 8c5df4a4..584fe560 100644
--- a/packages/web/e2e/pet.spec.mjs
+++ b/packages/web/e2e/pet.spec.mjs
@@ -7,7 +7,9 @@
* point of the design: everything the pet shows it reads over HTTP, so a browser tab can be held
* to the same behavior. The two readings that belong to the shell — the model balance's route and
* the update snapshot — therefore assert their desktop-only wording here; the desktop half is
- * verified by the shell's own smoke run.
+ * verified by the shell's own smoke run. The one gesture that belongs to the shell is moving the
+ * window: what a press does to this page is pinned here, and the shell's own probe drives the same
+ * gesture to watch the window move.
*
* The notice is the real thing, not a stub: a Session under `always-ask` is sent a Prompt that
* makes the mock model call a tool, the runtime escalates that call, and the user-channel event
@@ -56,6 +58,50 @@ test("the pet shows its readings, and speaks up when a call needs the user", asy
// (sidebar, chat) must not be in it.
await expect(page.getByPlaceholder(/输入消息/)).toHaveCount(0);
+ // --- the penguin is the handle: it drags, and a press that stays put is a click ---
+ //
+ // A browser cannot move its own window — `moveBy` is ignored outside a window a script opened —
+ // so the move itself is the shell's to prove (its smoke run drives the same gesture over CDP).
+ // What is pinned here is the page's half of the gesture, which is where the two mistakes live: a
+ // press that travels must not open the panel, and a press that stays put must do something a
+ // person can see.
+ const box = await penguin.boundingBox();
+ const centre = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+ // A nudge that starts and ends inside the penguin: the browser fires its own click for that press
+ // (both ends are on the same element), and that click is exactly what must not open the panel.
+ await page.mouse.move(centre.x, centre.y);
+ await page.mouse.down();
+ await page.mouse.move(centre.x + 14, centre.y + 10, { steps: 4 });
+ await page.mouse.up();
+ await expect(page.getByText("模型余额", { exact: true })).toHaveCount(0);
+ await expect(penguin).not.toHaveClass(/pet-hop/);
+
+ // And a drag that leaves the penguin entirely, which is what moving the pet looks like.
+ await page.mouse.move(centre.x, centre.y);
+ await page.mouse.down();
+ await page.mouse.move(centre.x + 60, centre.y + 30, { steps: 8 });
+ await page.mouse.up();
+ await expect(page.getByText("模型余额", { exact: true })).toHaveCount(0);
+ await expect(penguin).not.toHaveClass(/pet-hop/);
+
+ // The eyes follow the pointer, and the offset is a fraction of the penguin's own box rather than
+ // a pixel count: from the top-left corner of the window the pupils sit up and to the left.
+ await page.mouse.move(2, 2);
+ const pupils = await page.locator(".pet-pupils").evaluate((el) => {
+ const matrix = new DOMMatrixReadOnly(getComputedStyle(el).transform);
+ return [matrix.e, matrix.f];
+ });
+ expect(pupils[0], "pupils look left").toBeLessThan(0);
+ expect(pupils[1], "pupils look up").toBeLessThan(0);
+
+ // A click: the panel opens, and the pet hops on the way (the class is the hop — the animation
+ // itself is off under reduced motion, which is what this spec runs in).
+ await penguin.click();
+ await expect(page.getByText("模型余额", { exact: true })).toBeVisible();
+ await expect(penguin).toHaveClass(/pet-hop/);
+ await penguin.click();
+ await expect(page.getByText("模型余额", { exact: true })).toHaveCount(0);
+
// --- the panel behind a click ---
await penguin.click();
await expect(page.getByText("模型余额", { exact: true })).toBeVisible();
diff --git a/packages/web/src/features/pet/penguin.tsx b/packages/web/src/features/pet/penguin.tsx
index ad4bdc62..ce14484a 100644
--- a/packages/web/src/features/pet/penguin.tsx
+++ b/packages/web/src/features/pet/penguin.tsx
@@ -8,6 +8,12 @@
*
* The bob is a CSS animation (styles.css, `.pet-bob`), so the global reduced-motion rule turns it
* off with every other animation in the app and leaves a still penguin standing.
+ *
+ * The eyes are the only part of the drawing that is not fixed: two groups carry a class each and
+ * nothing else, so the stylesheet owns how they move — the pair blinks on its own slow cycle
+ * (`.pet-eyes`), and the pupils slide toward the pointer (`.pet-pupils`, whose offset the page
+ * writes onto the button as two custom properties). Neither adds a path: the shapes are the same
+ * five, and the icon-registry guard counts them by file.
*/
export function Penguin({ className }: { className?: string }) {
return (
@@ -29,10 +35,14 @@ export function Penguin({ className }: { className?: string }) {
fill="#f8fafc"
/>
{/* The white eye-ring is the Adelie's own marking: the one detail that says which penguin. */}
- <circle cx="40" cy="24" r="5.5" fill="#f8fafc" />
- <circle cx="60" cy="24" r="5.5" fill="#f8fafc" />
- <circle cx="40" cy="24" r="2.6" fill="#0f172a" />
- <circle cx="60" cy="24" r="2.6" fill="#0f172a" />
+ <g className="pet-eyes">
+ <circle cx="40" cy="24" r="5.5" fill="#f8fafc" />
+ <circle cx="60" cy="24" r="5.5" fill="#f8fafc" />
+ <g className="pet-pupils">
+ <circle cx="40" cy="24" r="2.6" fill="#0f172a" />
+ <circle cx="60" cy="24" r="2.6" fill="#0f172a" />
+ </g>
+ </g>
{/* Beak and feet. */}
<path d="M50 30l7 5-7 5-7-5 7-5Z" fill="#f59e0b" />
<path d="M33 99h16l-3 7H34l-1-7Z" fill="#f59e0b" />
diff --git a/packages/web/src/features/pet/pet-motion.ts b/packages/web/src/features/pet/pet-motion.ts
new file mode 100644
index 00000000..89a2621f
--- /dev/null
+++ b/packages/web/src/features/pet/pet-motion.ts
@@ -0,0 +1,61 @@
+/**
+ * The arithmetic behind the pet's two pointer-driven motions: moving its window, and the eyes
+ * following the pointer.
+ *
+ * Both are pure functions of pointer positions, kept out of pet-page.tsx because that file is React
+ * state and HTTP reads, while this is the part worth a unit test:
+ *
+ * - the slop that tells a drag from a click. Getting it wrong is what makes a companion annoying in
+ * both directions: a couple of pixels of shake while pressing would move the window instead of
+ * opening the panel, and a drag would end by opening the panel on top of wherever the pet was
+ * put.
+ * - the clamp that keeps the pupils inside the white ring they sit in, whatever the pointer does.
+ *
+ * The frame is the screen, not the page: the window moves, and a drag measured in client
+ * coordinates would feed its own movement back into the gesture (the page slides under a pointer
+ * that has not moved). `screenX`/`screenY` are unaffected by the window's own position, so the
+ * numbers here stay the pointer's own.
+ */
+
+/** A pointer sample in screen coordinates. */
+export interface PetPoint {
+ x: number;
+ y: number;
+}
+
+/**
+ * How far a press may travel before it is a drag, in CSS px on either axis. Four is small enough
+ * that the smallest deliberate drag is read as one, and wide enough that a hand pressing a 72px
+ * penguin can shake without meaning to move it — the same order Chromium's own drag slop uses.
+ */
+export const DRAG_SLOP_PX = 4;
+
+/**
+ * How far the pupils slide off centre, in the penguin's own SVG units (its viewBox is 100 units
+ * wide). The pupil's radius is 2.6 and the white ring's is 5.5, so this is close to as far as they
+ * can go without touching the ring — and as far as they should: the penguin is drawn 72px wide, so
+ * a unit here is most of a pixel, and a glance that could not be seen would not be a glance.
+ */
+export const PUPIL_MAX = { x: 2.2, y: 1.6 } as const;
+
+/** The movement between two samples: exactly what the window is moved by. */
+export function petStep(from: PetPoint, to: PetPoint): PetPoint {
+ return { x: to.x - from.x, y: to.y - from.y };
+}
+
+/** Whether a press that began at `start` and has reached `at` is a drag rather than a click. */
+export function petDrag(start: PetPoint, at: PetPoint): boolean {
+ const step = petStep(start, at);
+ return Math.max(Math.abs(step.x), Math.abs(step.y)) > DRAG_SLOP_PX;
+}
+
+/**
+ * Where the pupils sit for a pointer that is off the pet's centre by `dx` and `dy`, each given as a
+ * fraction of the pet's own half-width and half-height — so 1 is beside it, 2 is a screen away, and
+ * the sign is the direction. Both axes clamp on their own, which is what keeps the offset inside
+ * the ring on a wide window as well as a tall one.
+ */
+export function pupilShift(dx: number, dy: number): PetPoint {
+ const slide = (value: number, max: number) => Math.max(-max, Math.min(max, value * max));
+ return { x: slide(dx, PUPIL_MAX.x), y: slide(dy, PUPIL_MAX.y) };
+}
diff --git a/packages/web/src/features/pet/pet-page.tsx b/packages/web/src/features/pet/pet-page.tsx
index 39ff8913..95ace402 100644
--- a/packages/web/src/features/pet/pet-page.tsx
+++ b/packages/web/src/features/pet/pet-page.tsx
@@ -13,18 +13,27 @@
* the pet speaks, it does not stack up a notification center.
* - The panel behind a click: the pinned balance, the client-update state with the one action that
* state offers, the last notice, and the way to hide the pet again.
- * - The window itself, which drags: the page paints the penguin and marks the rest of the window
- * draggable (`.pet-drag` / `.pet-no-drag` in styles.css — `-webkit-app-region` is Electron's and
- * has no React type of its own).
+ * - The penguin, which carries the hand: it is what a person reaches for, so it is also what moves
+ * the window. The page moves its own window (`window.moveBy`, one step per pointer sample) rather
+ * than leaving the one visible thing inside a `no-drag` hole in a drag region it cannot use — the
+ * rest of the window keeps that OS drag region for the platforms whose window system delivers
+ * input to it. A press that stays put is a click and nothing else: it opens the panel and makes
+ * the pet hop, so a drag never also opens the panel on top of wherever the pet was put.
+ *
+ * The pet moves on its own too: it bobs, it blinks, its pupils follow the pointer (all three in
+ * styles.css and penguin.tsx) and it hops when it has something to say.
*
* In a plain browser tab (anyone can open /pet) the penguin still draws and the notices still
* arrive, and the two desktop-only readings say so instead of failing: everything about the shell
- * is gated on being the shell's own window, exactly as the update modal and the tray switch are.
+ * is gated on being the shell's own window, exactly as the update modal and the tray switch are. A
+ * tab cannot move itself either — a browser ignores `moveBy` on a window a script did not open — so
+ * dragging there does nothing at all, which is the honest answer for a window nobody can move.
*/
import { useCallback, useEffect, useRef, useState } from "react";
import type { ReactNode } from "react";
import type { DesktopUpdateStatus } from "@adelie/server/api";
import { providerInfo } from "@adelie/core/model-catalog";
+import { usePointerDrag } from "@adelie/ui";
import * as api from "../../api/endpoints";
import { openUserEvents } from "../../api/sse";
import { S } from "../../lib/strings";
@@ -42,6 +51,8 @@ import {
updateText,
} from "./pet-notice";
import type { PetNotice } from "./pet-notice";
+import { DRAG_SLOP_PX, petStep, pupilShift } from "./pet-motion";
+import type { PetPoint } from "./pet-motion";
import { Penguin } from "./penguin";
/** How long a bubble stays up before the pet stops talking. */
@@ -54,6 +65,11 @@ const NOTICE_KEEP = 5;
* what turns that into a bubble. Once a minute, on a route that answers from memory.
*/
const UPDATE_POLL_MS = 60_000;
+/**
+ * How long a hop's class stays on. A little longer than the hop itself (520ms, styles.css): the
+ * class is what starts it, and taking it off mid-flight would stop the pet in the air.
+ */
+const HOP_MS = 620;
/**
* One line of the panel: a muted label with its optional action on the first line, and the value
@@ -134,6 +150,94 @@ export function PetPage() {
const [update, setUpdate] = useState<DesktopUpdateStatus | null>(null);
const balance = usePetBalance(inShell);
+ // --- the penguin's own pointer work -------------------------------------
+ //
+ // Three things ride on the penguin, and none of them is state the app reads, so none of them
+ // re-renders anything while a hand is on it: the window moves, the eyes follow, and a press that
+ // stayed put opens the panel and hops. The drag itself is `usePointerDrag` — the app's one drag
+ // state machine, which tracks the gesture on the window rather than on the element and says which
+ // presses were drags — fed a threshold and a step from pet-motion.ts.
+ const petRef = useRef<HTMLButtonElement | null>(null);
+ /** The pointer's last screen position: the pet's moves are the steps between samples. */
+ const pressAt = useRef<PetPoint | null>(null);
+ /**
+ * Whether the press just released was a drag. A drag ends with a `click` like any other press —
+ * the browser fires one when the press and the release land on the same element, which capture
+ * makes sure of — and that click must not open the panel.
+ */
+ const suppressClick = useRef(false);
+ const [hopping, setHopping] = useState(false);
+
+ /** Hops once, from the top: a click while a hop is running restarts it instead of being lost. */
+ const hop = useCallback(() => {
+ setHopping(false);
+ window.requestAnimationFrame(() => setHopping(true));
+ }, []);
+ useEffect(() => {
+ if (!hopping) return;
+ const timer = window.setTimeout(() => setHopping(false), HOP_MS);
+ return () => window.clearTimeout(timer);
+ }, [hopping]);
+
+ const petDragProps = usePointerDrag<object>({
+ threshold: DRAG_SLOP_PX,
+ begin: (event) => {
+ // Screen coordinates, not the page's: the window moves under the pointer, so a step measured
+ // in `clientX`/`clientY` would fold the pet's own movement back into the gesture.
+ suppressClick.current = false;
+ pressAt.current = { x: event.screenX, y: event.screenY };
+ return {};
+ },
+ onMove: (event) => {
+ const last = pressAt.current;
+ if (last === null) return;
+ const at = { x: event.screenX, y: event.screenY };
+ pressAt.current = at;
+ const step = petStep(last, at);
+ // `moveBy` clamps the window to the screen; sitting at an edge is the pointer being there
+ // too, so the samples stay in step and the pet simply stays put until the hand comes back.
+ if (step.x !== 0 || step.y !== 0) window.moveBy(step.x, step.y);
+ },
+ onEnd: (_payload, dragged) => {
+ suppressClick.current = dragged;
+ pressAt.current = null;
+ },
+ onCancel: () => {
+ pressAt.current = null;
+ },
+ });
+
+ // The pupils follow the pointer. Written straight onto the element as two custom properties
+ // (styles.css reads them on `.pet-pupils`): a pointer moving at 60Hz would otherwise re-render
+ // this page — its panel, its balance row and its notice list — sixty times a second.
+ useEffect(() => {
+ const pet = petRef.current;
+ if (pet === null) return;
+ const onLook = (event: PointerEvent) => {
+ const box = pet.getBoundingClientRect();
+ if (box.width === 0 || box.height === 0) return;
+ // Off the pet's centre, in units of its own half-width and half-height: 1 is beside it.
+ const shift = pupilShift(
+ (event.clientX - (box.left + box.width / 2)) / (box.width / 2),
+ (event.clientY - (box.top + box.height / 2)) / (box.height / 2),
+ );
+ pet.style.setProperty("--pet-look-x", `${shift.x}px`);
+ pet.style.setProperty("--pet-look-y", `${shift.y}px`);
+ };
+ window.addEventListener("pointermove", onLook);
+ return () => window.removeEventListener("pointermove", onLook);
+ }, []);
+
+ /** The click the penguin answers: keyboard activation reaches it too, and that is a click. */
+ const onPetClick = () => {
+ if (suppressClick.current) {
+ suppressClick.current = false;
+ return;
+ }
+ setPanelOpen((open) => !open);
+ hop();
+ };
+
// The window is transparent where the page paints nothing (styles.css): the app's own windows
// get a canvas background from the shared theme, and this is the one window that must not.
useEffect(() => {
@@ -141,11 +245,19 @@ export function PetPage() {
return () => document.body.classList.remove("pet-body");
}, []);
- /** Says one thing: it goes to the top of the panel's list and up into the bubble. */
- const speak = useCallback((notice: PetNotice) => {
- setNotices((prev) => [notice, ...prev].slice(0, NOTICE_KEEP));
- setBubble(notice);
- }, []);
+ /**
+ * Says one thing: it goes to the top of the panel's list, up into the bubble, and the pet hops —
+ * a notice arriving is the pet noticing, and seen out of the corner of an eye that is the whole
+ * difference between a companion and a log line.
+ */
+ const speak = useCallback(
+ (notice: PetNotice) => {
+ setNotices((prev) => [notice, ...prev].slice(0, NOTICE_KEEP));
+ setBubble(notice);
+ hop();
+ },
+ [hop],
+ );
// What happened while nobody was looking: the user-level stream, which is this app's
// cross-Session channel (schedules, approvals waiting, budget warnings).
@@ -267,12 +379,20 @@ export function PetPage() {
{noticeText(bubble, S.pet)}
</div>
)}
+ {/* The penguin is the window's handle: it drags (usePointerDrag above), and a press that
+ stayed put is a click. `.pet-hop` replaces `.pet-bob` for as long as the hop lasts — one
+ element, one animation, so the landing never fights the idle bob. `touch-none` keeps a
+ finger's own scrolling and long-press gestures out of the drag. */}
<button
+ ref={petRef}
type="button"
aria-label={S.pet.open}
data-tooltip={S.pet.open}
- onClick={() => setPanelOpen((open) => !open)}
- className="pet-no-drag pet-bob block h-[72px] w-[72px] shrink-0 outline-none"
+ onClick={onPetClick}
+ {...petDragProps}
+ className={`pet-no-drag block h-[72px] w-[72px] shrink-0 cursor-grab touch-none outline-none active:cursor-grabbing ${
+ hopping ? "pet-hop" : "pet-bob"
+ }`}
>
<Penguin className="h-full w-full" />
</button>
diff --git a/packages/web/src/styles.css b/packages/web/src/styles.css
index b9c44a01..9633a317 100644
--- a/packages/web/src/styles.css
+++ b/packages/web/src/styles.css
@@ -461,13 +461,22 @@
/* ---------- The desktop pet window ---------- */
/* The pet is a frameless, transparent Electron window showing the app's /pet route
- (features/pet/pet-page.tsx; the shell's main.ts creates it). Three things are the app's own
- here, in plain CSS rather than utilities: the drag regions, because `-webkit-app-region` has no
- place in csstype's React style types, and the window's transparency, which has to override the
- shared theme's canvas background on <body>. All of it is inert in a browser tab. */
+ (features/pet/pet-page.tsx; the shell's main.ts creates it). What the app owns here, in plain
+ CSS rather than utilities: the window's drag region, because `-webkit-app-region` has no place in
+ csstype's React style types; the window's transparency, which has to override the shared theme's
+ canvas background on <body>; and the pet's own three motions — the idle bob, the hop, and the
+ eyes — which are keyframes rather than utilities because Tailwind has no keyframes for a
+ penguin, and because everything here has to be switched off together by the reduced-motion block
+ above. All of it is inert in a browser tab. */
/* The whole window drags the pet around; the penguin and the panel opt out so they stay
- clickable. Everything else — the margins around the penguin, the bubble — is the grab handle. */
+ clickable. This is the OS drag region, and it covers what is left of the window — the margins
+ around the penguin, the bubble. The penguin is NOT one of these handles: it drags the window
+ itself, from the page (`window.moveBy`, pet-page.tsx), because a visible thing marked `no-drag`
+ is a thing a hand cannot move, and the penguin is the one part of a transparent window a person
+ reliably reaches. So the two mechanisms divide the same work on purpose: the page takes the part
+ a hand aims at, and this region keeps the rest movable where the window system delivers input to
+ a transparent area at all. */
.pet-drag {
-webkit-app-region: drag;
}
@@ -497,3 +506,57 @@ body.pet-body #root {
.pet-bob {
animation: pet-bob 3.6s ease-in-out infinite;
}
+
+/* The hop: the pet's answer to a click and to a notice arriving, so a press says something even
+ before the panel appears. The page swaps this in for `.pet-bob` for as long as it lasts
+ (HOP_MS, pet-page.tsx) — one element, one animation, so the landing never fights the idle bob.
+ A hop is a jump with the weight in it: off the ground with a stretch, down with a squash, and a
+ small second bounce. */
+@keyframes pet-hop {
+ 0% {
+ transform: translateY(0) scale(1, 1);
+ }
+ 25% {
+ transform: translateY(-13px) scale(0.95, 1.06);
+ }
+ 55% {
+ transform: translateY(0) scale(1.07, 0.93);
+ }
+ 80% {
+ transform: translateY(-3px) scale(0.99, 1.01);
+ }
+ 100% {
+ transform: translateY(0) scale(1, 1);
+ }
+}
+.pet-hop {
+ animation: pet-hop 520ms cubic-bezier(0.2, 0.8, 0.3, 1);
+}
+
+/* The eyes, the one part of the drawing that is not still: the pair blinks on its own slow cycle,
+ and the pupils slide toward the pointer. `transform-box: fill-box` is what makes `center` the
+ eyes' own centre instead of the SVG's origin (which is what an SVG element measures from by
+ default), so the blink closes in place rather than collapsing toward the top of the head.
+ The pupils' offset is written on the penguin as `--pet-look-*` (pet-page.tsx), in the SVG's own
+ units; the fallback is what the eyes look with before a pointer has ever moved. Reduced motion
+ stops the blink with every other animation; the pupils still follow, which is a position rather
+ than a tween. */
+@keyframes pet-blink {
+ 0%,
+ 90%,
+ 100% {
+ transform: scaleY(1);
+ }
+ 92%,
+ 94% {
+ transform: scaleY(0.1);
+ }
+}
+.pet-eyes {
+ transform-box: fill-box;
+ transform-origin: center;
+ animation: pet-blink 6.4s ease-in-out infinite;
+}
+.pet-pupils {
+ transform: translate(var(--pet-look-x, 0px), var(--pet-look-y, 0px));
+}
diff --git a/packages/web/test/pet-motion.test.ts b/packages/web/test/pet-motion.test.ts
new file mode 100644
index 00000000..e5beffac
--- /dev/null
+++ b/packages/web/test/pet-motion.test.ts
@@ -0,0 +1,62 @@
+/**
+ * The pet's pointer arithmetic: what a drag is, and where its pupils look.
+ *
+ * The two behaviours this decides are the ones a person notices immediately and cannot be argued
+ * with: whether pressing on the penguin moves it or opens its panel, and whether its eyes follow
+ * the pointer. Both are thresholds, so both are pinned here at the boundary rather than only in
+ * the middle — a slop that drifts by a pixel is a click that moves the window.
+ */
+import { describe, expect, it } from "vitest";
+import {
+ DRAG_SLOP_PX,
+ PUPIL_MAX,
+ petDrag,
+ petStep,
+ pupilShift,
+} from "../src/features/pet/pet-motion.js";
+
+describe("petStep", () => {
+ it("is the movement between the two samples, in the direction it happened", () => {
+ expect(petStep({ x: 100, y: 200 }, { x: 130, y: 190 })).toEqual({ x: 30, y: -10 });
+ expect(petStep({ x: 100, y: 200 }, { x: 100, y: 200 })).toEqual({ x: 0, y: 0 });
+ expect(petStep({ x: 100, y: 200 }, { x: 100, y: 207 })).toEqual({ x: 0, y: 7 });
+ });
+});
+
+describe("petDrag", () => {
+ it("is not a drag while the press stays put", () => {
+ expect(petDrag({ x: 10, y: 10 }, { x: 10, y: 10 })).toBe(false);
+ });
+
+ it("is not a drag within the slop, on either axis or both", () => {
+ expect(petDrag({ x: 10, y: 10 }, { x: 10 + DRAG_SLOP_PX, y: 10 })).toBe(false);
+ expect(petDrag({ x: 10, y: 10 }, { x: 10, y: 10 - DRAG_SLOP_PX })).toBe(false);
+ expect(petDrag({ x: 10, y: 10 }, { x: 10 + DRAG_SLOP_PX, y: 10 + DRAG_SLOP_PX })).toBe(false);
+ });
+
+ it("is a drag one pixel past the slop, on either axis, in either direction", () => {
+ expect(petDrag({ x: 10, y: 10 }, { x: 10 + DRAG_SLOP_PX + 1, y: 10 })).toBe(true);
+ expect(petDrag({ x: 10, y: 10 }, { x: 10, y: 10 + DRAG_SLOP_PX + 1 })).toBe(true);
+ expect(petDrag({ x: 10, y: 10 }, { x: 10 - DRAG_SLOP_PX - 1, y: 10 })).toBe(true);
+ expect(petDrag({ x: 10, y: 10 }, { x: 10, y: 10 - DRAG_SLOP_PX - 1 })).toBe(true);
+ });
+});
+
+describe("pupilShift", () => {
+ it("looks straight ahead for a pointer on the pet", () => {
+ expect(pupilShift(0, 0)).toEqual({ x: 0, y: 0 });
+ });
+
+ it("slides proportionally while the pointer is inside the pet's own box", () => {
+ expect(pupilShift(0.5, -0.5)).toEqual({ x: PUPIL_MAX.x / 2, y: -PUPIL_MAX.y / 2 });
+ });
+
+ it("stops at the edge of the ring however far the pointer goes", () => {
+ expect(pupilShift(1, 1)).toEqual({ x: PUPIL_MAX.x, y: PUPIL_MAX.y });
+ expect(pupilShift(40, -40)).toEqual({ x: PUPIL_MAX.x, y: -PUPIL_MAX.y });
+ });
+
+ it("clamps the two axes on their own, so a wide window is not a tall one", () => {
+ expect(pupilShift(40, 0.5)).toEqual({ x: PUPIL_MAX.x, y: PUPIL_MAX.y / 2 });
+ });
+});