30 KiB
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,
256x256baseline JPEG, naminghamster_NNNN.p.jpg; 1811 are used (one stray neutral sheet inpacidle0is 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
.xmlfiles define the engine semantics reused below: animation triples (Start→Loop→Finish), one-shot clips, relative probability weights, and adisabled="true"package for the digging idle. frames/pacidle0/jpeg/hamster_0000.p.jpgis the neutral pose re-encoded (max diff 20 / mean 0.13 vshamster_0060) → dropped;idle_blinkis the 20 frames0060-0079.pacidle7(digging) andpacidle9(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):
{
"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 } }
}
}
rectis{x, y, width, height}in the 204x175 canvas space (the clip's own bounding box plus a 2 px margin).x/yis where that clip's image is blitted, so clips never drift relative to each other.anchor= bottom-centre of theidle_mainsilhouette = the point placed at the pet's screen position.fpsis 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-scaleandConfig::clip_fpscover 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 |
pacidlestart2 |
1190–1229 / 1230–1329 / 1330–1379 | 40/100/50 | `idle_activity_book_start |
pacidlestart3 |
0490–0559 / 0560–0599 / 0600–0679 | 70/40/80 | `idle_activity_sleep_start |
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
(
smoothstepon 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 anddropstays 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
inputgroup, 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_endplays 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_stopreturn 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_msmeasured 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.jsonnext toassets/, read from the working directory):backend,output, position, per-source sensors on/off (the screenshot signal isauto/key/files/off), the typing burst, idle timings, clip fps overrides,min_loopsper 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, theproblemparagraph template and one message per situation.{reason}and{folders}are filled at runtime, a message may drop itsfix, 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:
--traceprints the active chain while the window runs;--replay script.txtfeeds 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:
--replayscripts drive the real state machine and assert the chain sequence; asset test that walksassets/animations/and verifies every clip againstmanifest.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_frameswrites 30 clips / 1811 frames / 24.7 MB plus the manifest, verifies every clip by decoding it back, and reports unused source frames.tests/assets.rschecks 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 4prints 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,
--secondsfor automated runs,--traceto log the clip hand-offs of a live window. The window is drawn by two small backends behind oneBackendtrait (src/platform), not by winit, because of two defects the first version had:softbufferhands 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, awl_shmpool with an alpha channel on Wayland).- 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_v1top surface bound to the output that holds the saved position (config.outputcan 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) withdrag_start -> drag_loop -> drag_endand 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 rejectedCreateWindowis a void request the pet kept running with no window at all (the terminal still saidwindow: x11). Depth, visual and colormap are now chosen together, the creation ischecked 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_S0for 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/inputevent devices (needs theinputgroup;autoreports how many keyboards it opened,offdisables it — evdev works on Wayland and X11 alike, so no XRecord path is needed), screenshots are watched withnotifyin the configured folders, music comes from MPRIS over the session D-Bus, and the config gainedbackend,outputandsensorssections. 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 oftyping_start_keysinsidetyping_start_window_msis 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/inputprints the one-timeusermod -aG inputfix, instead of silently detecting nothing. A fake MPRIS player verified the music path:Playingswitches the pet to the music clip andPausedreturns it to idle. Screenshot detection was widened the same way: thePrintScreenkey is read by that same/dev/inputreader, 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-sensorsor--backendused 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/inputaccess, 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 aWS_EX_LAYERED | WS_EX_TOOLWINDOW | WS_EX_NOACTIVATE | WS_EX_TOPMOSTpopup drawn withUpdateLayeredWindow, 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 fromGetCursorPos(converted withScreenToClient), 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 areWH_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%\Picturesas 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 producesdrag_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 producesdrag_start -> drag_loop -> drag_endwhile 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.
CGEventTaptyping + 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
inputgroup (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_fpsand--fps-scalefor per-clip tuning once the pet is visible. - Baked shadow is a colour blob, not real alpha — decided: kept by default (
--shadow dropexists), because removing it erodes whiskers and dark props. - macOS media detection uses a private framework — accepted as optional.