feat(config,client): OS reduced-motion detection with tri-state animations.enabled (UI/UX v3 P3c)

[mizu-jun]

UI/UX v3 P3c is the switch that turns the motion language off for people who asked their OS to stop moving things. P3a built the timing primitives (#77, #78), P3b1–P3b3 applied them to surfaces, hover and press (#79, #80, #82, #83); this makes all of it respect the OS accessibility preference.

Design: docs/superpowers/specs/2026-08-29-p3c-reduced-motion-design.md
Plan: docs/superpowers/plans/2026-08-29-p3c-reduced-motion.md

The shape, and why no animation code changed

animations.enabled becomes tri-state and AnimationsConfig carries the OS state itself:

pub enum AnimationsEnabled { Auto, Yes, No }   // serde: "auto" / true / false

pub struct AnimationsConfig {
    pub enabled: AnimationsEnabled,
    pub intensity: AnimationIntensity,
    #[serde(skip)]
    os_reduced_motion: bool,   // private; stamped by the platform layer
}

effective_multiplier() returns 0 for No, or for Auto when the OS flag is set. Every animation in this client — surface open/close, hover cross-fade, press pulse, tab accent — reaches its duration through scaled_duration_ms, so all ~70 call sites and every animation type are untouched. The switch lives in one place because that is where the multiplier already lived.

Three properties are structural rather than maintained by care:

• Detection can only ever disable. There is no path from os_reduced_motion to a larger multiplier.
• A detection failure changes nothing. None from the platform layer means "cannot tell" and is read as "not reduced".
• The OS value cannot reach config.toml. The field is private and #[serde(skip)]; the settings panel writes the file back through toml_edit, and a serializable OS value would persist a setting the user never chose. The privacy also makes AnimationsConfig { .. ..Default::default() } illegal outside the crate, which is how we know the seal holds.

enabled = true means "animate anyway" — an OS-wide preference is not always what someone wants inside a terminal. enabled = false still means never. Pre-P3c configs keep parsing; the default changes from true to auto, which is the point of the phase and only ever removes motion.

Detection

Platform	Source	New dependency
Windows	SystemParametersInfoW(SPI_GETCLIENTAREAANIMATION) — reports whether animations are enabled, so reduced motion is its negation	none (windows-sys already present, feature already enabled)
macOS	NSWorkspace.accessibilityDisplayShouldReduceMotion	objc2 core only — deliberately not the objc2-app-kit subtree for one BOOL
Linux	none	—

Sampled at startup and on WindowEvent::Focused(true). Focus-gain rather than a native change notification because it matches what the user does — open System Settings, change the preference, come back — and needs no observer machinery on either platform. ThemeChanged is the existing precedent for reacting to an OS preference here.

Correction to the v3 plan: it said macOS detection would "share the objc2 dependency decision with P2". That was stale — P2c added window-vibrancy, which does not expose this preference. P3c made its own call.

Two traps this phase had to be built around

A config hot-reload silently un-does it. Reloading builds a fresh Config whose OS flag starts unset, so saving config.toml would have restored animations the OS asked us to stop. The sampled value is now carried across explicitly (lifecycle.rs, before the new config replaces the old).

The settings row was correct on screen and wrong to a screen reader. The auto value shows how it resolves — "Auto (normal)" / "Auto (reduced)" — because a row reading just "auto" implies animations might be on when they are all off. But accessibility.rs and the keyboard-navigation path call the shared widget-description path directly, bypassing the render path where the real value was patched in, so AccessKit announced "Auto (normal)" under OS reduced motion. On a feature that exists for accessibility, being wrong for exactly that user is the defect that matters most. Fixed by giving SettingsPanel its own mirror of the sampled value, stamped at the same three sites, so every consumer reads one source.

Test coverage

• nexterm-config — the truth table (Auto + OS reduced → 0; Yes overrules the OS; No stays 0 whatever the OS says), backward-compatible parsing of the old booleans, the default, and that the OS flag never serializes.
• nexterm-client-gpu — the settings row cycles both directions, the auto label distinguishes its two resolutions, each state writes back its own TOML spelling, and the shared descriptor path (the one AccessKit reads) reports the right label.
• 1035 tests in nexterm-client-gpu; cargo test --workspace green; cargo clippy --workspace --all-targets --all-features -- -D warnings and cargo fmt --all -- --check clean.

platform::reduced_motion() itself has no unit test, deliberately: it is one FFI call per platform with no branching worth pinning, and CI cannot set an OS accessibility preference. Keeping it thin is what makes that acceptable — every decision lives above it, where the tests are.

Known limitations

• Linux has no detection. auto animates there; the manual setting stays the documented fallback. GNOME's enable-animations and the XDG settings portal are both plausible later.
• No native change notification. A preference changed while the window already has focus is not noticed until focus is lost and regained.
• The macOS arm is compiled but unverified outside CI. It rests on objc2's runtime class lookup finding NSWorkspace, which holds because winit and window-vibrancy link AppKit. If that turns out false, the fallback is objc2-app-kit — a dependency swap, not a redesign.
• Neither platform's detection is verified on a real machine. The config layer is unit-tested; that the OS reports what we think it reports is a two-minute manual check per platform, on the existing on-device verification backlog.

Test plan

• cargo test --workspace
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo fmt --all -- --check
• Windows: turn off "Show animations in Windows", focus the terminal, confirm every animation is instant and the settings row reads "Auto (reduced)"
• macOS: turn on "Reduce motion", same check
• Either platform: set enabled = true with the OS preference on, confirm animations still run
• Either platform: with the OS asking for reduced motion, save config.toml and confirm animations stay off (the hot-reload carry-over)

[github-actions]

Coverage report

Generated by cargo llvm-cov (workspace minus nexterm-client-gpu and nexterm-i18n).

[github-actions]

Coverage report

Generated by cargo llvm-cov (workspace minus nexterm-client-gpu and nexterm-i18n).