This commit is contained in:
olcxja 2026-10-28 09:56:33 +01:00
commit 75df901d2d
1852 changed files with 11873 additions and 0 deletions

392
docs/PLAN.md Normal file
View file

@ -0,0 +1,392 @@
# Implementation plan — Hamster Desktop Pet
A desktop pet: a transparent, always-on-top hamster window that reacts to user activity
(typing, screenshots, music, dragging) using the 18 animation folders in `frames/` (30 clips).
Target platforms: **Linux (X11 first, Wayland as far as the platform allows)** and **Windows**.
**macOS** is best-effort (same code, lower priority for the platform-specific sensors).
---
## 1. Language choice: Rust (decided)
The hard part is not the GUI — it is cross-platform system hooks (global keyboard, screenshot
detection, media playback) plus a transparent overlay window. All four candidates could do it;
the table is kept as the record of that trade-off.
| Option | Pros | Cons |
| --- | --- | --- |
| **Rust** (`x11rb`, `wayland-client`, `tray-icon`, `zbus`, `windows`, `objc2`) | Single self-contained binary (~5 MB), no runtime; safest against crash/UB bugs; cargo test/CI trivial; first-class crates for every needed hook; cross-compile to Windows already works on this machine (`x86_64-pc-windows-gnu` target installed); WebP decode via `image` | No batteries-included GUI: window/tray plumbing is manual; X11/Wayland transparency needs care and testing; WinRT media API is verbose; longer compile times |
| **C++20 + Qt 6** | Qt gives transparent frameless always-on-top windows, tray menu, HiDPI, multi-monitor (`QScreen`), WebP plugin, timers and JSON for free; mature and well documented; one codebase for all three OSes | Heaviest toolchain (Qt SDK per platform, ~1 GB); manual memory management; still requires hand-written platform code for hooks; ships 20–40 MB of Qt libs |
| **Python 3 + PySide6** | Fastest to write and iterate; Pillow for the asset pipeline; pytest for tests; same Qt window features | Needs a bundled runtime (~40–90 MB via PyInstaller) and 60–120 MB RAM for a desktop pet; GC pauses can jitter animation; global hooks are the weak point (`pynput` is X11-only, Windows/macOS need separate bindings) |
| **Electron / Tauri** | Best animation rendering with the least effort (Chromium WebP/CSS/canvas); transparent frameless always-on-top is a solved path; tray built in; great debugging | Electron ships Chromium (~150 MB install, 100–200 MB RAM) — heavy for a pet; Tauri is light but WebKitGTK transparency is flaky and it still needs Rust; global keyboard hooks rely on native modules with maintenance risk |
**Chosen: Rust** — small, no runtime, every required system hook exists as a maintained crate
(`x11rb`, `wayland-client`, `tray-icon`, `zbus`, `windows`, `objc2`, `image`), and Windows builds already
cross-compile from this machine.
---
## 2. Source assets (measured)
- 18 animation folders, **1812 frames**, `256x256` baseline JPEG, naming `hamster_NNNN.p.jpg`; 1811
are used (one stray neutral sheet in `pacidle0` is skipped).
- Background is **exactly black** (corner pixels are `(0,0,0)`; the JPEGs are clean, no noise floor).
- The character occupies only the bottom-right area, so every clip is cropped to the union of the
frames it uses; the shared canvas is **204x175**.
- Original `.xml` files define the engine semantics reused below: animation triples
(`Start` → `Loop` → `Finish`), one-shot clips, relative probability weights, and a
`disabled="true"` package for the digging idle.
- `frames/pacidle0/jpeg/hamster_0000.p.jpg` is the neutral pose re-encoded (max diff 20 / mean 0.13
vs `hamster_0060`) → dropped; `idle_blink` is the 20 frames `0060-0079`.
- `pacidle7` (digging) and `pacidle9` (paper plane) touch or pass the source frame edges
(`x 255`, `y 255`); they still fit inside the shared 204x175 canvas.
## 3. Target asset format
Simple and obvious: **one folder per clip, 0-based 3-digit frame numbers, lossless RGBA WebP**.
```
assets/animations/
manifest.json
idle_main/frame_000.webp
typing/frame_000.webp … typing/frame_059.webp
idle_activity_sleep_finish/frame_000.webp …
```
`manifest.json` carries only asset facts (no behaviour):
```json
{
"version": 1,
"canvas": { "width": 204, "height": 175 },
"anchor": { "x": 144, "y": 158 },
"clips": {
"typing": { "frames": 60, "fps": 30, "loop": true,
"rect": { "x": 82, "y": 49, "width": 104, "height": 111 } },
"idle_main": { "frames": 1, "fps": 30, "loop": true,
"rect": { "x": 103, "y": 55, "width": 83, "height": 103 } }
}
}
```
- `rect` is `{x, y, width, height}` in the 204x175 canvas space (the clip's own bounding box plus
a 2 px margin). `x/y` is where that clip's image is blitted, so clips never drift relative to
each other.
- `anchor` = bottom-centre of the `idle_main` silhouette = the point placed at the pet's screen position.
- `fps` is **30** for every clip. The original engine's rate is unknown, so 30 fps is the project
default and is tunable per clip in the converter table (`--fps-scale` and `Config::clip_fps` cover
tuning at runtime). Playback is wall-clock based, so the visible speed never depends on the monitor.
- Measured output: 30 clips, 1811 frames, canvas 204x175, anchor (144, 158), **24.7 MB**
(13.6 KB per frame).
### Clip names (source → output)
| Source | Frames | Count | New clip(s) |
| --- | --- | --- | --- |
| `pacmainidle` | 0060 | 1 | `idle_main` |
| `pacidle0` | 0060–0079 | 20 | `idle_blink` |
| `pacidle1` | 1560–1639 | 80 | `idle_look_around` |
| `pacidle2` | 0000–0059 | 60 | `idle_nose_rub` |
| `pacidle3` | 0220–0279 | 60 | `idle_yawn` |
| `pacidle4` | 0120–0149 | 30 | `idle_rock` |
| `pacidle5` | 0080–0119 | 40 | `idle_peek` |
| `pacidle6` | 0150–0219 | 70 | `idle_yawn_second` |
| `pacidle7` | 1640–1779 | 140 | `idle_dig` (off by default, source XML disables it) |
| `pacidle8` | 0420–0489 | 70 | `idle_squint` |
| `pacidle9` | 1780–1999 | 220 | `idle_paper_plane` |
| `pacidlestart1` | 1380–1419 / 1420–1519 / 1520–1559 | 40/100/40 | `idle_activity_newspaper_start|loop|finish` |
| `pacidlestart2` | 1190–1229 / 1230–1329 / 1330–1379 | 40/100/50 | `idle_activity_book_start|loop|finish` |
| `pacidlestart3` | 0490–0559 / 0560–0599 / 0600–0679 | 70/40/80 | `idle_activity_sleep_start|loop|finish` |
| `pactyping` | 0680–0719 / 0720–0779 / 0780–0819 | 40/60/40 | `typing_start`, `typing`, `typing_stop` |
| `pacscreenshot` | 0280–0419 | 140 | `screenshot` |
| `pacmusic` | 0990–1043 / 1044–1057 / 1058–1119 | 54/14/62 | `music_start`, `music` (loop), `music_stop` — one source take, split by hand: 1044–1057 is a single bob whose wrap is seamless (measured), so listening loops instead of replaying the whole take |
| `paccharacter` | 1120–1124 / 1145–1174 / 1175–1189 | 5/30/15 | `drag_start`, `drag_loop`, `drag_end` |
### Matting (JPG black → WebP alpha)
Tested both ways on real frames:
- **Rejected:** alpha = pixel luminance. Correct over a black desktop, but the hamster goes
translucent and washed out over a light background — its dark eyes/outline become transparent.
- **Chosen:** mask matting. Flood-fill the background from the image border over pixels below a
low threshold (22/255 by default), so only the *outer* background is removed while enclosed dark details
(eyes, outline) stay fully opaque; give the mask boundary a one-pixel alpha ramp
(`smoothstep` on luminance) and un-multiply colour only on that ramp to avoid a dark fringe.
The baked soft shadow stays as a slightly dark blob: the shadow is dimmer than the character
outline (measured 15..60 vs 90+), so removing it needs a threshold of ~45 which eats whiskers and
dark props. `--shadow keep` (threshold 22) is therefore the default and `drop` stays available;
the decision came from an A/B preview sheet over light, dark and photo backgrounds.
Converter tool → `tools/convert_frames`: reads `frames/`, writes `assets/animations/`, validates
expected frame counts, writes the manifest, and prints the total size. Deterministic output,
one command, no manual steps.
---
## 4. Behaviour spec
Reused concept (one implementation, three callers): **clip chain** = optional `start` (plays once) →
`loop` (repeats while the condition holds) → `finish` (plays once) → back to idle.
| Trigger | Chain | Notes |
| --- | --- | --- |
| Typing starts | `typing_start` → `typing` → `typing_stop` | Start only on the idle→typing transition, never on key repeat; stop after ~700 ms without a key |
| Typing stops | `typing_stop` | Interruptible: a new key during `typing_stop` returns to `typing` |
| Screenshot taken | `screenshot` (one-shot) | Fires on the `PrintScreen` key and on an image appearing in a watched folder; one shot never reacts twice (the key claims a file saved within 8 s, and filesystem events for one file are deduped for 1 s) |
| Music playing | `music_start` → `music` → `music_stop` | Takes the headphones on, listens in a loop while any player reports `playing`, takes them off when all pause/stop |
| Mouse drag | `drag_start` → `drag_loop` → `drag_end` | `drag_loop` uses "ping-pong" playback so the short 30-frame loop reads as continuous walking |
| Idle | `idle_main` | 1 frame; no work while nothing changes |
| Idle activities | `idle_blink`, `idle_nose_rub`, … (one-shots) | Randomly scheduled from the main idle using the original probability weights (blink 500, rock 150, nose rub 50, squint 40, yawn 20, peek 20, dig 10, look around 5, yawn-2 5, paper plane 5), then back to `idle_main` |
| Long idle activities | `idle_activity_{newspaper,book,sleep}_*` chains | Rare (weight 5), `loop` repeats for a few seconds, then `finish` |
Rules, implemented in `src/core/engine.rs` and covered by its unit tests:
- One chain wins by priority `drag > screenshot > typing > music > idle activity > main idle`.
- **An override plays the running chain's finish clip first** (`typing_start` -> `typing` ->
`typing_stop`), and only then starts the new chain; a finish clip that is already playing is never
restarted. Chains without a finish clip (the screenshot reaction, one-shot idle gags) are cut,
exactly like the source engine.
- Sensors only report facts, and a fix never requires more access than read-only: the keyboard reader
needs the `input` group, music needs the user's own session bus, screenshots need a folder to watch.
- **A start clip is never cut** (`ChainPolicy::WaitForStart`, used by typing and music): a hand-over
asked for while it runs waits until it has played out, so the finish clip starts from the pose the
start clip was building instead of snapping there. The looping middle hands over at once, so stopping
typing or music reacts within a fraction of a second.
- Dragging is the exception: it takes over instantly, and its own `drag_end` plays on release.
- When a condition ends while a finish clip plays, the target is re-read once that clip ends, so keys
pressed during `typing_stop` return to typing instead of dropping to idle.
- A condition that is still valid keeps its chain: a screenshot arriving mid-drag waits in line instead
of ending the drag. A queued reaction is dropped if it cannot start within `screenshot_request_ttl_ms`,
but once it starts it always plays out in full.
- An idle activity only starts from the resting animation and is dropped, not resumed, when interrupted.
- A full activity runs its start clip, then loops its middle for `activity_loop_ms` measured from the
loop clip itself, then plays its finish clip. `min_loops` (per clip) raises that budget so the loop
always completes at least that many cycles; only the idle activity loops are timed, so only they
can be stretched, and any other key is reported and ignored at startup.
- Timing is real milliseconds against a monotonic clock, with at most 100 ms of animation advanced per
tick, so a slow render neither slows clips down nor fast-forwards them.
---
## 5. Architecture
```
src/core/ platform-free, fully unit-testable
manifest schema, validation, frame path and file name helpers
frames on demand decode + LRU cache
clip_player one clip at a fixed fps: loop, ping-pong, one-shot, 100 ms step cap
chains chain and idle activity tables: clip names, probabilities, cooldowns
engine events -> priorities -> start/loop/finish phases, idle scheduler
config JSON load/save, validation, clamping, defaults
texts dialog wording: defaults, placeholders, load from texts.json
clock, rng, replay fake clock for tests, deterministic rng, scripted runs
src/platform/ window, frame loop and display backends
mod the frame loop, the Backend trait, input events
compositor canvas -> premultiplied ARGB + clickable rectangles
x11, wayland, windows one backend per display server
dialog startup dialog via the desktop's own tool or a message box
src/sensors/ evdev or Windows hook (typing + PrintScreen), MPRIS/SMTC music, folder watch
```
Rust layout: a small workspace with the app crate (`src/`, modules above) and a `convert_frames`
binary crate under `tools/`; platform modules are gated per target and picked in one
`platform::run` entry point, so the core never imports a platform crate directly.
- Render loop: polls at the clip's own frame rate (4–16 ms) and only drives the clock; clips advance
by elapsed time at their own fps
and the window is redrawn only when the visible frame changes (idle = no work). The replay mode steps
the same way at 20 ms so scripted runs behave like a live loop.
- Frame cache: clips are decoded on demand into an LRU cache (240 frames, roughly the length of the
longest chains); the first frame of a clip costs the decode, every later one is a cache hit.
Nothing is decoded at startup except `idle_main`.
- Input: the window is click-through where the sprite is transparent. The mask follows the drawn
frame: a backend gets new rectangles whenever the frame changes, and while a drag is running the
whole window stays clickable so the pointer cannot slip out of it (Windows does not need the
rectangles: a layered window hit tests its own alpha, and the capture keeps the drag alive).
- Dragging: not clamped at all, so the pet can be pushed over a screen edge or onto another monitor.
Only a start position that is off every monitor is pulled back on screen, whole.
- Config (JSON in the project, `config.json` next to `assets/`, read from the working directory):
`backend`, `output`, position, per-source sensors on/off (the
screenshot signal is `auto`/`key`/`files`/`off`), the typing burst, idle timings, clip fps overrides,
`min_loops` per looping activity clip, disabled activities. The file ships with every default in it, so the knobs are easy to find and are
edited before a build; the only thing written back to it is the window position. Nothing is kept in
the user's home directory, and without a config file the pet runs on its defaults without writing
anything. Bad values are clamped, never fatal.
- The wording of the startup dialog is `texts.json`, read from the same directory: `title`, `intro`,
`outro`, the `problem` paragraph template and one message per situation. `{reason}` and `{folders}`
are filled at runtime, a message may drop its `fix`, anything left out keeps its built-in wording and
a broken file warns and falls back, so a half finished file never leaves the dialog empty.
- Debug: `--trace` prints the active chain while the window runs; `--replay script.txt` feeds a scripted
event sequence through the real state machine.
## 6. Platform support matrix
Target matrix; the macOS column is the plan (M5), not an existing build.
| Capability | Linux X11 | Linux Wayland | Windows | macOS |
| --- | --- | --- | --- | --- |
| Transparent overlay + always-on-top | depth-32 dock window, needs a compositing WM (shape mask fallback) | `wlr-layer-shell` top surface (KWin, sway, Hyprland); xdg toplevel fallback elsewhere | `WS_EX_LAYERED` popup, frames through `UpdateLayeredWindow` | yes |
| Click-through on transparent pixels | shape extension | input region, refreshed with each frame | the layered window's own alpha hit test | yes |
| Dragging the pet | pointer grab, 1:1 with the cursor | layer margins rewritten per motion | mouse capture, position from the live cursor | yes |
| Typing detection | `/dev/input` event devices (`input` group) | same — evdev does not care about the session type | `WH_KEYBOARD_LL` | `CGEventTap` (Accessibility permission) |
| Screenshot taken | `PrintScreen` via `/dev/input` + watch XDG screenshot folders (`sensors.screenshot`: `auto`/`key`/`files`/`off`) | same (evdev does not care about the session type) | watch `Pictures\Screenshots` + PrtSc key (`WH_KEYBOARD_LL`) | watch `com.apple.screencapture` location (Desktop by default) |
| Media playing | MPRIS over D-Bus | MPRIS over D-Bus | SMTC (WinRT) | MediaRemote (private API) — may stay unimplemented |
| Tray icon | planned (M6) | planned (M6) | planned (M6) | planned (M6) |
Windows builds come from the same source; macOS only needs its own `platform/` module (M5).
## 7. Edge cases to handle explicitly
- Asset problems: missing/corrupt frame, manifest frame count mismatch, unknown clip name → clear error
at startup (dev) or skip the clip and keep running (release); never a crash or a blank window.
- Events: key auto-repeat, a burst of keys mid-`typing_stop`, screenshot events that arrive twice for one
shot, several media players (pick a playing one deterministically), player switching mid-loop.
- Timing: clock jumps, sleeping laptop waking up, a very slow render frame (accumulate dt, clamp the
0.1 s max step so clips don't skip), first frame not yet decoded (show the previous frame, never a gap).
- Window: multi-monitor and negative coordinates, monitor unplugged while running, scale changes,
a saved position off every monitor (pulled back on screen), always-on-top refused by the WM (log,
keep running), a
compositor without layer-shell (xdg fallback that cannot be dragged), a Wayland output whose origin
is not (0,0) (layer margins are relative to it) and a press that lands while the animation swaps the
input region under the cursor (the full window stays clickable during a drag).
- Resources: decoding errors are retried once then the clip is marked broken; cache never unbounded;
the position is written after every drag, so even a killed pet restarts where it was left.
- Platform degradation: missing D-Bus session (containers), no media player installed, no screenshot
folder existing, permission denied for global hooks → disable that sensor only, with one log line.
## 8. Testing
- Unit (fast, no OS): state machine transitions for every event combination and priority clash;
chain player timing on a fake clock; idle scheduler weight distribution; config parse/clamp on
malformed files; LRU eviction; matting golden test (fixed sample frames → expected pixel hash);
manifest validation against the real generated assets.
- Integration: `--replay` scripts drive the real state machine and assert the chain sequence;
asset test that walks `assets/animations/` and verifies every clip against `manifest.json`.
- Manual checklist per OS: overlay transparency, click-through, drag, tray, each sensor, multi-monitor,
idle CPU/RAM measured with the pet on screen for a minute.
## 9. Milestones
- **M0 — assets — DONE.** `tools/convert_frames` writes 30 clips / 1811 frames / 24.7 MB plus the
manifest, verifies every clip by decoding it back, and reports unused source frames. `tests/assets.rs`
checks the generated set against the manifest (frame lists, sizes, golden pixels, anchor placement).
- **M1 — core — DONE.** Manifest validation, LRU frame cache, fixed-fps clip player, chain player,
state machine with priorities and finish-first overrides, idle scheduler, config loading, replay mode.
111 unit tests pass; `cargo run --release -- --replay scripts/demo.txt --seed 4` prints the verified
sequence (typing -> typing_stop -> queued screenshot -> drag -> music -> idle activities).
- **M2 — window — DONE on Linux/X11 and Wayland** (tray deferred to M6). Transparent always-on-top
window, pixel-shaped input region (click-through), drag with the left button, right click quits,
position saved to the config and clamped to a monitor, `--seconds` for automated runs, `--trace` to
log the clip hand-offs of a live window.
The window is drawn by two small backends behind one `Backend` trait (`src/platform`), not by winit,
because of two defects the first version had:
1. `softbuffer` hands the compositor an XRGB buffer, so the Wayland window came out **black**. Frames
are now premultiplied ARGB written into the surface's own buffer (a depth-32 window on X11, a
`wl_shm` pool with an alpha channel on Wayland).
2. Dragging froze the animation: every pointer motion asked the server where the window was and which
monitors existed, which on Wayland means a round trip per motion, so the loop never reached its
next frame while the mouse moved. The loop now keeps wall-clock time of its own and only drains
events: X11 moves the window itself during a pointer grab, Wayland rewrites the layer margins.
Wayland specifics: the surface is a `zwlr_layer_shell_v1` top surface bound to the output that holds
the saved position (`config.output` can name one), and because layer margins are measured from that
output's corner, global positions are converted on the way in and out. Without layer-shell (GNOME)
it degrades to an xdg toplevel, which the compositor places, so drags cannot move it there.
Verified on a live KWin session: the pet renders exactly at the configured global position, the
pixels the hamster does not cover show the desktop instead of black, hovering and pressing reach the
app, a drag follows the cursor across monitors (margins go negative and KWin honours them), the
animation keeps playing while the pointer moves (62 drag frames counted during one drag) and the
saved position matches where the hamster really is on screen, read back from a screenshot match.
X11 was re-verified the same way: a 252x223 depth-32 window, clicks on transparent pixels reach the
window below while the body receives them, a drag follows the cursor 1:1 (72,18 in, 72,18 out) with
the animation running (frames differ by ~6k pixels between captures during the drag), and the saved
position is the one the pet was moved to.
Re-run after the asset tolerance change: on this
session's Xwayland display a saved position of (1600,300) puts the depth-32 window exactly at
(1431,118), the window margin is byte-identical to the same desktop pixels captured before the pet
started (no black box), a drag moves it by exactly (+120,+80) with `drag_start -> drag_loop ->
drag_end` and 3.2% of the pixels changing between two captures taken during the drag, a click on a
transparent margin pixel starts no drag at all, and a right click quits with the new anchor (1720,380)
written to the config.
That pass found and fixed a real bug: without a compositor the window was created with the depth of
the root visual but the 32-bit visual, a combination the server rejects, and since a rejected
`CreateWindow` is a void request the pet kept running with no window at all (the terminal still said
`window: x11`). Depth, visual and colormap are now chosen together, the creation is `check`ed so a
rejection becomes an error instead of an invisible pet, and the shape-masked fallback divides the
alpha back out of the premultiplied pixels so soft edges do not turn dark. Both modes were checked on
the Xwayland display by owning `_NET_WM_CM_S0` for the composited run: a 252x223 window at the saved
position, depth 24 + shape mask in the fallback (click on a transparent corner starts no drag) and
depth 32 + real alpha in the composited run (244 pixels keep partial alpha), 5.4k painted pixels, a
drag following the pointer (532,318 -> 602,368), frames still changing during the drag (6.4k pixels)
and the position written back to the config.
- **M3 — Linux sensors — DONE.** Typing is read from `/dev/input` event devices (needs the `input`
group; `auto` reports how many keyboards it opened, `off` disables it — evdev works on Wayland and
X11 alike, so no XRecord path is needed), screenshots are watched with `notify` in the configured
folders, music comes from MPRIS over the session D-Bus, and the config gained `backend`, `output`
and `sensors` sections. Verified on the live session: keyboards opened, the MPRIS watcher attached,
and an image copied into the watched folder played the screenshot clip.
Two follow-ups from real use: a lone key press no longer starts typing (a burst of
`typing_start_keys` inside `typing_start_window_ms` is required, then single keys keep it going),
and the sensors explain themselves when something is missing — a missing session bus names the
usual cause (running as root) and a denied `/dev/input` prints the one-time `usermod -aG input`
fix, instead of silently detecting nothing. A fake MPRIS player verified the music path: `Playing`
switches the pet to the music clip and `Paused` returns it to idle.
Screenshot detection was widened the same way: the `PrintScreen` key is read by that same
`/dev/input` reader, so a shot that is never saved (clipboard only) still counts, while a file
saved within 8 s of the press is treated as that same shot rather than a second reaction — verified
live with a virtual keyboard and the watched folder. The same pass fixed a real bug: running with
`--no-sensors` or `--backend` used to write those overrides into the config file for good, because
the whole in-memory config was saved; now only the config as it was loaded is written back, with
the new window position.
Sensors report two kinds of startup line: plain notes and *problems* — the ones the user can fix.
Every problem (no `/dev/input` access, no session bus, no screenshot folder, a watcher that will not
start) is shown in a startup dialog next to its fix, drawn by whatever the desktop already ships
(`kdialog`, `zenity`, `yad` — the pet has no toolkit of its own). Nothing waits for the dialog and
the pet runs behind it; an undismissed dialog is taken down when the pet exits. Windows shows the
same text in its own message box (M4); macOS gets its native dialog with its milestone, and until
then the startup notes are the fallback.
- **M4 — Windows — DONE**, cross-compiled with `cargo build --release --target x86_64-pc-windows-gnu`
(no Windows machine was needed for the build, and the .exe was exercised under Wine). The window is
a `WS_EX_LAYERED | WS_EX_TOOLWINDOW | WS_EX_NOACTIVATE | WS_EX_TOPMOST` popup drawn with
`UpdateLayeredWindow`, which also gives click-through for free because a layered window hit tests
its own alpha; a drag takes the mouse capture and each position comes from `GetCursorPos` (converted
with `ScreenToClient`), so a motion message that arrives after the window has already moved still
reports where the pointer is now. Per monitor DPI awareness is requested at startup and the canvas
is rendered at the resulting integer scale. Sensors are `WH_KEYBOARD_LL` (typing plus PrintScreen,
with auto repeat filtered out), the Windows media session manager (SMTC) polled once a second, and
the same folder watch as Linux with `%USERPROFILE%\Pictures` as the default folder. The startup
dialog uses the native message box, shown on its own thread so nothing waits for it.
Verified under Wine on a live KWin session: the window lands exactly where the Windows virtual
desktop says it should (Wine's origin is the primary monitor's corner, like real Windows), the
pixels the hamster does not cover are byte-identical to the desktop captured before the pet existed,
the pet paints and animates (5719 pixels differ between two captures), a press on a painted pixel
produces `drag_start -> drag_loop -> drag_end`, a right click quits, and a build run leaves the
config file untouched apart from the window position. Two things could not be exercised without
Windows itself: SMTC (Wine has no WinRT — the pet reports the problem and runs on) and layered-window
compositing against a real desktop. A later pass re-ran the .exe under Wine: the window appears at
the Windows coordinate the config asks for (Wine's virtual desktop origin is 1366 px away from the
Xwayland one), it paints with alpha (a transparent corner, 5.4k painted pixels), a press on the body
produces `drag_start -> drag_loop -> drag_end` while 4.5k pixels keep changing between captures, the
window follows the pointer exactly over a 180x96 px drag in twelve steps, and the new position is
written back to the config. The drag reads the live cursor (`GetCursorPos`), so it does not depend on
Wine's motion messages, which arrive late and repeat the old position.
- **M5 — macOS best-effort.** `CGEventTap` typing + screenshot folder watch; media may stay out of scope.
- **M6 — polish.** Tray toggles, packaging (AppImage/tar.gz, .zip), docs.
## 10. Risks / open questions
- **Typing detection needs the `input` group** (evdev), because a sandboxed or unprivileged build
cannot read keyboards. Without it the sensor logs one line and the rest of the pet keeps working; a
Flatpak build would need its own permission for `/dev/input`.
- **X11 transparency + always-on-top** depends on a compositing WM. The window requests a depth-32
visual and premultiplied ARGB, which works on a compositing session. Without one it falls back to the
root visual plus a bounding shape: the pet is hard edged rather than transparent, but visible,
animated and click-through outside its silhouette. On Wayland the alpha channel is part of the
buffer, so it is transparent by construction.
- **Compositors without layer-shell** (GNOME/Mutter) get an ordinary toplevel: it still animates and
reacts, but the compositor owns its position, so the saved position and dragging do not apply.
- **Original frame rate is unknown** — decided: 30 fps everywhere, with `Config::clip_fps` and
`--fps-scale` for per-clip tuning once the pet is visible.
- **Baked shadow** is a colour blob, not real alpha — decided: kept by default (`--shadow drop` exists),
because removing it erodes whiskers and dark props.
- **macOS media detection** uses a private framework — accepted as optional.