392 lines
30 KiB
Markdown
392 lines
30 KiB
Markdown
# 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.
|