DesktopChomik/docs/PLAN.md
2026-10-28 09:56:33 +01:00

30 KiB
Raw Permalink Blame History

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):

{
  "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
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 (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 checked 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.