Play matching background intros at boot and on theme switches (#9639)

* Play matching theme background intros at boot

* Add Tokyo Night sunset lake boot intro

* Stage Tokyo Night boot intros on update

* Add user controls for background boot intros

* Optimize Tokyo Night boot intro videos

* Add Tokyo Night cityscape boot intro

* Add Ristretto boot intro videos

* Add Solitude boot intro videos

* Add White boot intro videos

* Add Vantablack boot intro videos

* Add Miasma nature boot intro

* Add Matte Black boot intro videos

* Add Lupine wave boot intro videos

* Add Last Horizon blink boot intro

* Add Everforest tree tops boot intro

* Add Ethereal cosmic boot intro

* Add four Retro 82 boot intros

* Add Tokyo Night Quattro boot intro

* Add Catppuccin Latte color fade boot intro

* Add five Gruvbox boot intros

* Expand Retro 82 boot intro coverage

* Complete Ethereal boot intros

* Complete Retro 82 boot intros

* Stage boot intros for the active theme

* Add Catppuccin boot intros

* Complete Tokyo Night boot intros

* Expand Lupine boot intros

* Add Osaka Jade mountain boot intro

* Prime boot intros before revealing wallpaper

* Complete Osaka Jade boot intros

* Keep kernel migration test valid after timestamp reuse

* Shorten packaged boot intros to six seconds

* Revert "Shorten packaged boot intros to six seconds"

This reverts commit 5530403aa9e789b977a1a1a77ea7acf37a9e3598.

* Document five to seven second intro target

* Ease Matte Black intros into six seconds

* Play boot intros through OWE instead of a shell player

The merged desktop video path removes BackgroundVideo.qml and makes
BackgroundMedia image-only. This keeps the intro feature by resolving the
matching intro as before and playing it with 'owe intro', which owns the
decode and the reveal. OWE 0.2.3 adds that command. The shell holds the
theme color while resolving and cancels with 'owe intro-stop'.

* Make boot intro startup atomic

* Retry boot intro through login window

* Document required OWE intro protocol

* Add Last Horizon video boot intros

* Play boot intros with released OWE

Use `owe intro` instead of the unreleased intro-prepare/intro-commit
protocol from omacom/owe#5. The boot is recorded before playback, and
OWE's intro_result status decides whether a failed intro never started
(release the boot for retry) or was interrupted (keep it consumed).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Replace Matte Black boot intros with shorter cuts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Hide the still behind black until the boot intro starts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Shorten the Everforest boot intro

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Document that boot intros should open dark

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Refine the Osaka Jade boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Skip compositor fades on the background layers

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Shorten the Catppuccin Latte boot intro

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Shorten the Catppuccin boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Shorten the White boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Shorten the Vantablack boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Shorten the Gruvbox boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Shorten the Retro 82 boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Shorten the Solitude boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Rework the Ristretto boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Shorten the Tokyo Night boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Complete the Lupine boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Complete the Last Horizon boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Complete the Miasma boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Add the Nord boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Add the Rose Pine boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Add the Flexoki Light boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Add the Hackerman boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Add the Kanagawa boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Add the Lumon boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Fade in the Last Horizon intros from black

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Animate the Catppuccin boot intros from their wallpapers

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KAPp37DLjmKQy8GZr3vFvF

* Animate the third White boot intro from its wallpaper

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KAPp37DLjmKQy8GZr3vFvF

* Animate the Flexoki Light, Lumon and Rose Pine plants intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KAPp37DLjmKQy8GZr3vFvF

* Shorten the Ethereal boot intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KAPp37DLjmKQy8GZr3vFvF

* Animate the remaining placeholder intros from their wallpapers

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KAPp37DLjmKQy8GZr3vFvF

* Replace Catppuccin intros with themotion scenes

Totoro moonrise, waves swelling from a line, and the blue eye tracing
itself open, rendered by https://github.com/yamz8/themotion
(scenes/catppuccin/*).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KAPp37DLjmKQy8GZr3vFvF

* Re-encode Catppuccin intros with exact final frames

Same motion; the settled frames are encoded at a fixed high quality so
the handoff lands on the wallpaper (themotion 0c5e86c).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Replace Lumon intros with themotion scenes

United in severance draws its lines and globe with a small pen-tip
light; Opinions equally wakes inside the picture's own screen and types
out the mark and tagline. Both keep the wallpaper's proportions, so the
handoff holds its shape. Made with https://github.com/yamz8/themotion
(scenes/lumon/*).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Land the Last Horizon intros exactly on their wallpapers

Same footage and timing; the last 0.4 s now blends into the wallpaper as
the shell draws it (libwebp decode, BT.709 limited range), with the
settled frames at high quality. Re-finished with themotion fit (09f156e).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Add Nord video boot intro for Night Hawks

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Replace Rose Pine intros with themotion scenes

Funky shapes pop in on a jelly spring and the doodles draw on (replacing
the reversed stock clip), the dot map spins in from a swelling dot, and
the plants spring up before the OMARCHY letters drop in. Made with
https://github.com/yamz8/themotion (scenes/rose-pine/*).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Replace Hackerman intros with themotion scenes

The synthwave terrain unfolds as the sun rises and the valley glow
flares into the floor; the geometric network bursts out from a triangle
at its core and locks into place. Made with
https://github.com/yamz8/themotion (scenes/hackerman/*).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Replace White 3-white with a themotion scene and land 1-2 exactly

3-white folds and slides its paper sheets into place along their
diagonal (themotion scenes/white/3-white). 1-white and 2-white keep
their footage and timing; their last 0.4 s now blend into the wallpaper
as the shell draws it (themotion fit).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Replace Ristretto 0-1 with themotion scenes and land 2-3 exactly

0-launch lifts its stripes off and bends them into their curves, and
1-color-curves fans its colour bands in along their curves (themotion
scenes/ristretto/*). 2-coffee-beans and 3-industrial-moon keep their
footage and timing; their last 0.4 s now blend into the wallpaper as
the shell draws it (themotion fit).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Replace Vantablack intros: new layer scenes, shared dot-hands cut

0-dot-hands uses the Matte Black cut, since both themes ship the same
wallpaper. 1-twisted-stairs keeps its footage and lands exactly on the
wallpaper (themotion fit). 2-layers-deep opens its depth front to back
and 3-layers-stacked lays its papercut stack down sheet by sheet
(themotion scenes/vantablack/*), replacing footage that opened on
unrelated shapes and a plain fade-in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Drop the shockwave ring from the Totoro intro

The moon now opens from its seed of light with only its halo; the thin
ring racing outward read as clutter (themotion 6970484).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Drop the shockwave ring from the blue-eye intro

The eye closes with its pulse and halo only (themotion, same change as
Totoro's).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Land the earlier footage intros exactly on their wallpapers

Everforest, Osaka Jade, Catppuccin Latte and two Matte Black intros
were finished before the exact-ending tooling and ended 0.9-4 levels
off their wallpapers (up to 134 on small spots). Their footage and
timing are unchanged; the last 0.4 s now blend into the wallpaper as the
shell draws it (themotion fit).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Fade two Matte Black intros up from black

ship-at-sea and dark-waters opened at brightness 17-20, so they popped
in after the black cover. They now fade up over 0.3 s; the cuts and
their exact endings are otherwise unchanged (themotion fit --fade-in).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Drop the Flexoki Light intro for now

Its orb scene isn't good enough yet, so Flexoki Light starts on its still
until a better intro is ready.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit bfe60d6c0a7a0983509a2dc2b295693bec2ceeb8)

* Skip boot intros while animations are off

A VM starts with animations off, and there Hyprland renders on the CPU, so a
video intro costs the most. The launcher now consumes the boot without playing
when Hyprland reports animations:enabled false, and the shell's cover check
treats that, like the intros toggle, as nothing to wait for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Add Miasma video boot intro for Crowned

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Keep boot intro startup outside the background service

OWE destroys and recreates the background plugin during playback. Keep the launcher and black cover in the persistent shell host, consume the boot before waiting briefly for OWE, and start on the video's first frame. The startup check runs with a video background too, so enabling the still background service later cannot play an intro over an established desktop.

Co-Authored-By: Codex Medium <codex@openai.com>

* Release the boot marker lock before waiting for OWE

The marker settles startup once it is written. Keeping the lock through readiness and playback makes a fresh shell wait for an older launcher before it can discover that the boot was consumed, leaving the still covered during that wait.

* Keep the boot intro cover above native and cloned backgrounds

Cloned backgrounds receive a scoped shell interface without the startup coordinator. Keep the input-transparent cover in the persistent host so every background stays hidden until OWE has a frame, without widening the plugin interface.

Co-Authored-By: Codex Medium <codex@openai.com>

* Map the startup cover only for an unsettled boot

The cover must know the boot was already consumed before its first frame, so restarting the shell during playback leaves OWE visible. Snapshot the marker without watching subsequent writes: the launcher consumes this boot before the intro starts, while the cover remains needed until the first decoded frame.

* Exercise automatic boot cover release in the clone test

The fixture hid the cover itself before the fake launcher exited, so a broken exit handler still passed. Let the launcher finish before checking the actual background pixels and leave cover release to the service.

Co-Authored-By: Greptile <165735046+greptile-apps[bot]@users.noreply.github.com>

* Finish the Miasma, Kanagawa, Ethereal and Nord intros

Start each intro on its scene instead of fading in from black, since
OWE now starts intros on their first frame.

- Miasma Crowned: ejuro's intro, shortened to 6.7 s and opening on the lit hand
- Nord Night Hawks: ejuro's intro
- Kanagawa: rendered in the wallpaper's own shape, so the handoff matches on
  16:10 and 3:2 screens too
- Ethereal, Nord and Miasma Crowned: 1080p endings that blend into the exact
  wallpaper, so the handoff no longer sharpens visibly

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Finish the Tokyo Night intros

Start each intro on its scene instead of fading in from black, since
OWE now starts intros on their first frame.

- Winding Road: a new starry night to sunset with no added clouds or sun,
  ending on the wallpaper
- Quattro: a new take where the car lands in the wallpaper's exact pose,
  colour-matched to the wallpaper
- Oma Cityscape: drop the second, larger moon that faded out at the end
- Quattro, Swirl Buck, Omakub and Oma Cityscape: 1080p endings that blend
  into the exact wallpaper, so the handoff no longer sharpens visibly

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Pair background intros by filename and play them on theme switches

Keep matching clips in backgrounds/intros so the selected image determines playback without registration, overrides, or checksum sidecars. Retain one global toggle and play automatically at boot and on a different theme selection.

Launch theme playback after releasing the selection lock. Check the staged theme directory identity so an older launcher cannot play a newer selection when filenames are reused. Skipped or failed playback immediately hands the selected still to the shell, including new pixels behind an unchanged path.

Synchronize the clone screenshot fixture with capture instead of a fixed launcher lifetime, while still requiring the real exit handler to release the cover.

Co-Authored-By: Codex Medium <codex@openai.com>

* Settle pending background colors when applying the current theme

An intro applies its theme immediately while a previous still-image reveal may still hold an older palette. Replace and consume that pending palette through the background's existing handoff methods so its reveal or fallback timer cannot restore old colors. Reusing those methods also works with existing background clones.

Publish the fake renderer's PID before announcing playback readiness, so the lock test cannot read an unwritten PID file. Regressions reproduce both failures on 7b238cf1 and pass with the fixes, including a deliberate scheduling delay at PID publication.

Co-Authored-By: Greptile <165735046+greptile-apps[bot]@users.noreply.github.com>

* Use the existing animations menu toggle for background intros

Keep the separate intro command available without another Style menu control. Disabled animations already suppress playback at boot and on theme changes.

Use remembered backgrounds with matching clips when testing suppressed theme intros, and require the normal still transition so the checks cannot pass merely because no clip was selected.

Co-Authored-By: Codex Medium <codex@openai.com>

* Finish the Lupine intros

Start each intro on its scene instead of fading in from black, since
OWE now starts intros on their first frame.

- Cherry Blossom White: a new take that pulls back from fresh leaves to the
  whole tree, easing to a stop on the wallpaper
- Pastel Clouds: drop the unrelated starry opening and its dip to black
- Elegant Blue Wave: drop the empty white opening
- Cherry Blossom Bokeh, Pastel Clouds, Elegant Blue Wave and Cherry Blossom
  White: 1080p endings that blend into the exact wallpaper

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JBE1V6gjrqn2aXCNNGhrUY

* Synchronize theme intro and bar crossfades

* Start theme intro fades from a cached first frame

* Open theme intros on moving scenes

* Start theme crossfades promptly

* Prepare theme intros before switching

* Finish the Catppuccin intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JBE1V6gjrqn2aXCNNGhrUY

* Keep theme intro handoffs covered

* Reload Hyprland after theme intro playback

* Finish the Rose Pine intros

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JBE1V6gjrqn2aXCNNGhrUY

* Restore the wallpaper early on each login

* Keep the startup wallpaper cover transparent

* Wait for readiness in the intro lifecycle test

* Consume login intros for updates outside Hyprland

* Fade login directly into the ready desktop intro

* Sharpen Quattro, Swirl Buck and Oma Cityscape

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Keep compositor backgrounds black during login

* Keep the shell visible through compositor shutdown

* Bound the login cover when startup media fails

* Encode the 1440p intros at H.264 level 5.1

At 2560x1440 the previous encodes used 16 reference frames, which puts
them at level 6.0. Intel hardware decoding plays those with stray grey
blocks. Four reference frames keep them at level 5.1, like the other
intros. Swirl Buck's stag now changes colour as one silhouette instead
of leaving a shrinking black disc on its head.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Hide the startup cursor until the desktop fades in

* Restore Swirl Buck's original stag

The stag now changes colour exactly as in the original clip again;
the previous edit made it jump from black to purple in one frame.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Initialize the startup cursor before the first compositor frame

* Render the Hackerman intros at 1440p

Both open on their first motion instead of fading in from black.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Render the Lumon intros at 1440p

Both open on their first motion instead of fading in from black.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Sharpen the Lupine intros

Upscaled from the original 720p clips and exported at 1440p with a
gentler encode, keeping the same frames, timing and endings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Resolve login intros before the wallpaper daemon starts

* Synchronize cold-start captures with the fixture phases

* Sharpen the rest of the Tokyo Night intros

Winding Road and Sunset Lake are regenerated natively at 1440p from
their wallpapers, since their original clips were 360p and 720p.
Omakub and Oma are redrawn from their wallpapers with the same motion.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Bjarne Oeverli <1419214+bjarneo@users.noreply.github.com>
Co-authored-by: Erik Johansson <172146456+ejuro@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Omarchy Bot <omarchybot@users.noreply.github.com>
Co-authored-by: Codex Medium <codex@openai.com>
Co-authored-by: Greptile <165735046+greptile-apps[bot]@users.noreply.github.com>
Co-authored-by: David Heinemeier Hansson <david@hey.com>

test/shell.d/background-instant-reload-test.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+
+set -euo pipefail
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+require_compositor "same-path background fallback"
+require_command quickshell
+require_command grim
+require_command magick
+
+stage=$(mktemp -d)
+qs_pid=""
+cleanup() {
+  [[ -z $qs_pid ]] || { kill "$qs_pid" 2>/dev/null || true; wait "$qs_pid" 2>/dev/null || true; }
+  rm -rf "$stage"
+}
+trap cleanup EXIT
+mkdir -p "$stage/home/.local/state/omarchy/current"
+ln -s "$ROOT/shell/plugins/background" "$stage/background"
+ln -s "$ROOT/shell/Commons" "$stage/Commons"
+ln -s "$ROOT/shell/Ui" "$stage/Ui"
+cp "$SHELL_TEST_DIR/fixtures/background-instant-reload/shell.qml" "$stage/shell.qml"
+magick -size 128x128 xc:magenta "$stage/still.png"
+ln -s "$stage/still.png" "$stage/home/.local/state/omarchy/current/background"
+: >"$stage/command"
+HOME="$stage/home" RELOAD_TEST_COMMAND="$stage/command" RELOAD_TEST_RESULT="$stage/result" \
+  quickshell -p "$stage" --no-color >"$stage/quickshell.log" 2>&1 &
+qs_pid=$!
+wait_phase() {
+  for attempt in {1..100}; do
+    [[ -f $stage/result && $(<"$stage/result") == "$1" ]] && return 0
+    sleep 0.03
+  done
+  fail "same-path background reaches $1" "$(cat "$stage/quickshell.log")"
+}
+pixel() {
+  local output
+  output=$(hyprctl -j monitors | jq -r '.[0].name')
+  timeout -k 1 3 grim -o "$output" "$stage/pixel.png"
+  magick "$stage/pixel.png" -format '%[hex:p{32,256}]' info:
+}
+wait_phase initial
+[[ $(pixel) == FF00FF ]] || fail "the initial background is visible"
+magick -size 128x128 xc:cyan "$stage/still.png"
+printf 'reload\n' >"$stage/command"
+wait_phase reloaded
+[[ $(pixel) == 00FFFF ]] || fail "the instant fallback reloads new pixels behind an unchanged path"
+printf 'done\n' >"$stage/command"
+wait "$qs_pid" || fail "the same-path reload fixture exits cleanly" "$(cat "$stage/quickshell.log")"
+qs_pid=""
+pass "the instant fallback reloads a replaced image at the same path"

test/shell.d/background-intro-clone-test.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+require_compositor "cloned background intro cover test"
+require_command quickshell
+require_command grim
+require_command magick
+
+stage=$(mktemp -d)
+qs_pid=""
+cleanup() {
+  [[ -z $qs_pid ]] || { kill "$qs_pid" 2>/dev/null || true; wait "$qs_pid" 2>/dev/null || true; }
+  rm -rf "$stage"
+}
+trap cleanup EXIT
+mkdir -p "$stage/bin" "$stage/home/.local/state/omarchy/current"
+cat >"$stage/bin/noop" <<'SH'
+#!/bin/bash
+exit 0
+SH
+chmod +x "$stage/bin/noop"
+for command in omarchy-shell omarchy-plugin-enable omarchy-notification-send; do
+  ln -s noop "$stage/bin/$command"
+done
+cat >"$stage/bin/omarchy-plugin-list" <<'SH'
+#!/bin/bash
+printf '[{"id":"intro-test.background"}]\n'
+SH
+cat >"$stage/bin/omarchy-theme-bg-boot-intro" <<'SH'
+#!/bin/bash
+for attempt in {1..200}; do
+  [[ ! -s $INTRO_TEST_RELEASE ]] || exit 0
+  sleep 0.05
+done
+exit 1
+SH
+chmod +x "$stage/bin/omarchy-plugin-list" "$stage/bin/omarchy-theme-bg-boot-intro"
+HOME="$stage/home" USER=intro-test OMARCHY_PATH="$ROOT" PATH="$stage/bin:$ROOT/bin:$PATH" \
+  "$ROOT/bin/omarchy-plugin-clone" omarchy.background >/dev/null
+ln -s "$stage/home/.config/omarchy/plugins/intro-test.background" "$stage/clone"
+ln -s "$ROOT/shell/Commons" "$stage/Commons"
+ln -s "$ROOT/shell/Ui" "$stage/Ui"
+ln -s "$ROOT/shell/services" "$stage/services"
+cp "$SHELL_TEST_DIR/fixtures/background-intro-clone/shell.qml" "$stage/shell.qml"
+magick -size 128x128 xc:magenta "$stage/still.png"
+ln -s "$stage/still.png" "$stage/home/.local/state/omarchy/current/background"
+
+wait_phase() {
+  for attempt in {1..100}; do
+    [[ -s $stage/result.json ]] && [[ $(jq -r .phase "$stage/result.json") == "$1" ]] && return 0
+    sleep 0.03
+  done
+  fail "cloned background reaches the $1 phase" "$(cat "$stage/quickshell.log")"
+}
+capture_pixel() {
+  hyprctl dispatch 'hl.dsp.dpms({ action = "enable" })' >/dev/null
+  local output
+  output=$(hyprctl -j monitors | jq -r '.[0].name')
+  timeout -k 1 3 grim -o "$output" "$stage/$1.png"
+  magick "$stage/$1.png" -format '%[hex:p{32,256}]' info:
+}
+for consumed in false true; do
+  if [[ $consumed == true ]]; then
+    printf '%s\n' "$HYPRLAND_INSTANCE_SIGNATURE" >"$stage/home/.local/state/omarchy/background-intro.session-id"
+  fi
+  rm -f "$stage/result.json"
+  : >"$stage/release"
+  HOME="$stage/home" OMARCHY_PATH="$ROOT" PATH="$stage/bin:$PATH" INTRO_TEST_RESULT="$stage/result.json" INTRO_TEST_RELEASE="$stage/release" \
+    quickshell -p "$stage" --no-color >"$stage/quickshell.log" 2>&1 &
+  qs_pid=$!
+  wait_phase cover
+  jq -e --argjson consumed "$consumed" '.scoped and .privateCoordinator and .selected and (.covered == ($consumed | not))' "$stage/result.json" >/dev/null || \
+    fail "the clone is scoped and a consumed login never maps the cover" "$(cat "$stage/result.json")"
+  if [[ $consumed == false ]]; then
+    pixel=$(capture_pixel cover)
+    [[ $pixel == "000000" ]] || fail "a fresh login keeps the cloned wallpaper hidden until startup is ready" "$pixel"
+    [[ $(magick "$stage/cover.png" -format '%[hex:p{32,10}]' info:) == "000000" ]] || fail "the startup cover hides the bar as well as the wallpaper"
+  else
+    [[ $(capture_pixel cover) == "FF00FF" ]] || fail "a consumed login does not flash a cover over the cloned background"
+  fi
+  printf 'captured\n' >"$stage/release"
+  wait_phase still
+  [[ $(capture_pixel still) == "FF00FF" ]] || fail "releasing the shared cover reveals the cloned background"
+  printf 'done\n' >"$stage/release"
+  wait "$qs_pid" || fail "the cloned background fixture exits cleanly" "$(cat "$stage/quickshell.log")"
+  qs_pid=""
+  if rg -q 'ReferenceError|TypeError|Unable to assign|Binding loop' "$stage/quickshell.log"; then
+    fail "the cloned background fixture has no QML errors" "$(cat "$stage/quickshell.log")"
+  fi
+done
+pass "a real clone is covered only for startup, with its scoped facade and consumed-login behavior intact"

test/shell.d/background-intro-lifecycle-test.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+require_compositor "background intro lifecycle test"
+require_command quickshell
+
+stage=$(mktemp -d)
+trap 'rm -rf "$stage"' EXIT
+mkdir -p "$stage/services" "$stage/bin" "$stage/home"
+printf 'P6\n1 1\n255\n\377\377\377' >"$stage/cover.ppm"
+cp "$ROOT/shell/services/BackgroundIntro.qml" "$stage/services/"
+ln -s "$ROOT/shell/Commons" "$stage/Commons"
+cp "$SHELL_TEST_DIR/fixtures/background-intro-lifecycle/shell.qml" "$stage/shell.qml"
+cat >"$stage/bin/omarchy-theme-bg-boot-intro" <<'SH'
+#!/bin/bash
+printf 'intro\n' >>"$INTRO_TEST_LOG"
+sleep 2
+SH
+chmod +x "$stage/bin/omarchy-theme-bg-boot-intro"
+cat >"$stage/bin/owe" <<'SH'
+#!/bin/bash
+if [[ -f $INTRO_TEST_FRAME_READY ]]; then
+  sleep 0.25
+  printf '{"kind":"video","ready":true,"has_transition":false,"time_pos":0.05}\n'
+else
+  printf '{"kind":"video","ready":true,"has_transition":true,"time_pos":0}\n'
+fi
+SH
+chmod +x "$stage/bin/owe"
+output=$(HOME="$stage/home" PATH="$stage/bin:$PATH" INTRO_TEST_LOG="$stage/starts" INTRO_TEST_COVER="$stage/cover.ppm" INTRO_TEST_FRAME_READY="$stage/video-ready" timeout 10 quickshell -p "$stage" --no-color 2>&1) || fail "background intro fixture exits cleanly" "$output"
+[[ $output == *"RESULT pass"* ]] || fail "background intro lifecycle assertions pass" "$output"
+if rg -q 'RESULT fail|ReferenceError|TypeError|Error:|Unable to assign|Binding loop' <<<"$output"; then
+  fail "background intro fixture has no QML errors" "$output"
+fi
+[[ $(wc -l <"$stage/starts") == 1 ]] || fail "recreating the background service does not run another launcher"
+pass "the cover stays while waiting and remains off when OWE recreates the background service"

test/shell.d/background-intro-test.sh

@@ -0,0 +1,303 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+test_tmp=$(mktemp -d)
+trap 'rm -rf "$test_tmp"' EXIT
+
+intro_home="$test_tmp/home"
+intro_runtime="$test_tmp/runtime"
+intro_state="$intro_home/.local/state/omarchy/current"
+theme_intro_dir="$intro_state/theme/backgrounds/intros"
+background="$intro_state/theme/backgrounds/road.webp"
+mkdir -p "$(dirname "$background")" "$theme_intro_dir" "$intro_runtime"
+printf 'matching still\n' >"$background"
+printf 'theme video\n' >"$theme_intro_dir/road.mp4"
+printf 'tokyo-night\n' >"$intro_state/theme.name"
+ln -s "$background" "$intro_state/background"
+
+resolved=$(HOME="$intro_home" "$ROOT/bin/omarchy-theme-bg-boot-intro" --resolve-only)
+[[ $resolved == "$theme_intro_dir/road.mp4" ]] || fail "a sibling intro matches the current image by filename" "$resolved"
+rm "$theme_intro_dir/road.mp4"
+resolved=$(HOME="$intro_home" "$ROOT/bin/omarchy-theme-bg-boot-intro" --resolve-only)
+[[ -z $resolved ]] || fail "a background without a matching video has no intro" "$resolved"
+printf 'theme video\n' >"$theme_intro_dir/road.mp4"
+
+custom_background="$intro_home/.config/omarchy/backgrounds/tokyo-night/road.webp"
+mkdir -p "${custom_background%/*}"
+printf 'different still with the same name\n' >"$custom_background"
+ln -nsf "$custom_background" "$intro_state/background"
+resolved=$(HOME="$intro_home" "$ROOT/bin/omarchy-theme-bg-boot-intro" --resolve-only)
+[[ -z $resolved ]] || fail "a different image directory does not inherit the theme intro" "$resolved"
+ln -nsf "$background" "$intro_state/background"
+
+toggle="$intro_home/.local/state/omarchy/toggles/background-intros-off"
+marker="$intro_home/.local/state/omarchy/background-intro.session-id"
+command_bin="$test_tmp/bin"
+command_log="$test_tmp/command-log"
+mkdir -p "$command_bin"
+cat >"$command_bin/owe" <<'SH'
+#!/bin/bash
+printf 'owe: %s\n' "$*" >>"$COMMAND_LOG"
+case ${1:-} in
+  intro)
+    [[ -z ${COVER_READY_FILE:-} || -f $COVER_READY_FILE ]] || exit 1
+    [[ ${OWE_FAIL:-} != "interrupted" && ${OWE_FAIL:-} != "unavailable" ]] || exit 1
+    [[ -z ${OWE_READY_FILE:-} || -f $OWE_READY_FILE ]] || exit 1
+    ;;
+  status)
+    [[ ${OWE_FAIL:-} != "unavailable" ]] || exit 1
+    [[ -z ${OWE_READY_FILE:-} || -f $OWE_READY_FILE ]] || exit 1
+    printf '{"status":"ok"}\n'
+    ;;
+esac
+SH
+chmod +x "$command_bin/owe"
+cat >"$command_bin/hyprctl" <<'SH'
+#!/bin/bash
+printf '{"option":"animations:enabled","int":%s,"bool":%s}\n' \
+  "$([[ ${ANIMATIONS:-on} == on ]] && echo 1 || echo 0)" "$([[ ${ANIMATIONS:-on} == on ]] && echo true || echo false)"
+SH
+chmod +x "$command_bin/hyprctl"
+cat >"$command_bin/omarchy-shell" <<'SH'
+#!/bin/bash
+if [[ $2 == "themeIntroCoverStatus" ]]; then
+  if [[ -n ${COVER_READY_FILE:-} && ! -f $COVER_READY_FILE ]]; then
+    echo "loading"
+  else
+    echo "${COVER_STATUS:-ready}"
+  fi
+fi
+SH
+chmod +x "$command_bin/omarchy-shell"
+
+mkdir -p "$(dirname "$toggle")"
+resolved=$(PATH="$command_bin:$PATH" HOME="$intro_home" "$ROOT/bin/omarchy-theme-bg-boot-intro" --resolve-startup)
+[[ $resolved == "$theme_intro_dir/road.mp4" ]] || fail "OWE can prepare the selected intro while the shell starts" "$resolved"
+[[ ! -e $marker && ! -s $command_log ]] || fail "startup preparation does not consume the login or start playback"
+resolved=$(PATH="$command_bin:$PATH" HOME="$intro_home" ANIMATIONS=off "$ROOT/bin/omarchy-theme-bg-boot-intro" --resolve-startup)
+[[ -z $resolved ]] || fail "disabled animations skip startup preparation"
+touch "$toggle"
+resolved=$(PATH="$command_bin:$PATH" HOME="$intro_home" "$ROOT/bin/omarchy-theme-bg-boot-intro" --resolve-startup)
+[[ -z $resolved ]] || fail "disabled intros skip startup preparation"
+pass "speculative login preparation respects settings and leaves playback to the shell"
+resolved=$(PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" OMARCHY_SESSION_ID=disabled-boot "$ROOT/bin/omarchy-theme-bg-boot-intro")
+[[ -z $resolved && $(<"$marker") == "disabled-boot" ]] || fail "the global toggle consumes the current login without playing"
+rm "$toggle"
+resolved=$(PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" OMARCHY_SESSION_ID=disabled-boot "$ROOT/bin/omarchy-theme-bg-boot-intro")
+[[ -z $resolved ]] || fail "enabling midway through a login does not start a delayed intro" "$resolved"
+
+: >"$command_log"
+PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" ANIMATIONS=off OMARCHY_SESSION_ID=still-boot "$ROOT/bin/omarchy-theme-bg-boot-intro"
+[[ $(<"$marker") == "still-boot" ]] || fail "with animations off the session is consumed"
+! grep -q '^owe: intro ' "$command_log" || fail "with animations off no intro plays"
+
+rm "$marker"
+: >"$command_log"
+started=$SECONDS
+if ! PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" OWE_FAIL=unavailable OMARCHY_SESSION_ID=unavailable-boot "$ROOT/bin/omarchy-theme-bg-boot-intro"; then
+  fail "an unavailable OWE settles startup rather than requesting another launcher"
+fi
+(( SECONDS - started >= 4 && SECONDS - started <= 7 )) || fail "startup waits only through the five-second window" "$((SECONDS - started))"
+[[ $(<"$marker") == "unavailable-boot" ]] || fail "an unavailable OWE still settles the session"
+! grep -q '^owe: intro ' "$command_log" || fail "an unavailable OWE never starts an intro"
+PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" OMARCHY_SESSION_ID=unavailable-boot "$ROOT/bin/omarchy-theme-bg-boot-intro"
+! grep -q '^owe: intro ' "$command_log" || fail "starting OWE after the deadline does not play a late intro"
+
+rm "$marker"
+: >"$command_log"
+ready="$test_tmp/owe-ready"
+(sleep 1; touch "$ready") &
+ready_pid=$!
+PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" OWE_READY_FILE="$ready" OMARCHY_SESSION_ID=delayed-boot "$ROOT/bin/omarchy-theme-bg-boot-intro"
+wait "$ready_pid"
+[[ $(<"$marker") == "delayed-boot" ]] || fail "waiting for OWE keeps the session consumed"
+grep -Fxq "owe: intro --start first-frame $theme_intro_dir/road.mp4" "$command_log" || fail "a ready OWE starts on the video's first frame without revealing the still"
+
+rm "$marker" "$ready"
+: >"$command_log"
+PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" OWE_READY_FILE="$ready" OMARCHY_SESSION_ID=restart-while-waiting "$ROOT/bin/omarchy-theme-bg-boot-intro" &
+waiting_pid=$!
+for attempt in {1..100}; do
+  [[ -f $marker && $(<"$marker") == "restart-while-waiting" ]] && break
+  sleep 0.01
+done
+if ! PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" OWE_READY_FILE="$ready" OMARCHY_SESSION_ID=restart-while-waiting timeout 1 "$ROOT/bin/omarchy-theme-bg-boot-intro"; then
+  kill "$waiting_pid" 2>/dev/null || true
+  wait "$waiting_pid" || true
+  fail "a restarted shell reads the consumed session without waiting for the old launcher"
+fi
+touch "$ready"
+wait "$waiting_pid"
+
+rm "$marker" "$ready"
+: >"$command_log"
+(sleep 0.5; touch "$toggle" "$ready") &
+ready_pid=$!
+PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" OWE_READY_FILE="$ready" OMARCHY_SESSION_ID=disabled-while-waiting "$ROOT/bin/omarchy-theme-bg-boot-intro"
+wait "$ready_pid"
+! grep -q '^owe: intro ' "$command_log" || fail "disabling intros while waiting cancels startup playback"
+rm "$toggle" "$ready" "$marker"
+: >"$command_log"
+(sleep 0.5; ln -nsf "$custom_background" "$intro_state/background"; touch "$ready") &
+ready_pid=$!
+PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" OWE_READY_FILE="$ready" OMARCHY_SESSION_ID=changed-while-waiting "$ROOT/bin/omarchy-theme-bg-boot-intro"
+wait "$ready_pid"
+! grep -q '^owe: intro ' "$command_log" || fail "changing the background while waiting cancels its old intro"
+ln -nsf "$background" "$intro_state/background"
+
+rm "$marker"
+if PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" OWE_FAIL=interrupted OMARCHY_SESSION_ID=interrupted-boot "$ROOT/bin/omarchy-theme-bg-boot-intro"; then
+  fail "an interrupted intro reports a failure"
+else
+  status=$?
+  (( status == 1 )) || fail "an interrupted intro does not request a retry" "$status"
+fi
+[[ $(<"$marker") == "interrupted-boot" ]] || fail "an intro interrupted after OWE accepted it still consumes the session"
+
+rm "$marker"
+: >"$command_log"
+for index in {1..32}; do
+  PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" OMARCHY_SESSION_ID=concurrent-boot "$ROOT/bin/omarchy-theme-bg-boot-intro" >"$test_tmp/output.$index" &
+  intro_pids[$index]=$!
+done
+for intro_pid in "${intro_pids[@]}"; do
+  wait "$intro_pid"
+done
+intro_count=$(grep -c '^owe: intro ' "$command_log")
+(( intro_count == 1 )) || fail "concurrent launchers start exactly one intro" "$intro_count"
+
+pass "login intros settle the session once, wait briefly for OWE, and start on the first frame"
+
+: >"$command_log"
+for session in first-login first-login second-login; do
+  PATH="$command_bin:$PATH" HOME="$intro_home" XDG_RUNTIME_DIR="$intro_runtime" COMMAND_LOG="$command_log" \
+    OMARCHY_SESSION_ID="" HYPRLAND_INSTANCE_SIGNATURE="$session" "$ROOT/bin/omarchy-theme-bg-boot-intro"
+done
+intro_count=$(grep -c '^owe: intro ' "$command_log")
+(( intro_count == 2 )) || fail "a new login replays the intro while a shell restart in the same session does not" "$intro_count"
+[[ $(<"$marker") == "second-login" ]] || fail "the marker identifies the latest compositor session"
+pass "logging out and back in replays the intro without requiring a reboot"
+
+ln -s "$ROOT/bin/omarchy-theme-bg-boot-intro" "$command_bin/omarchy-theme-bg-boot-intro"
+
+cat >"$command_bin/omarchy-notification-send" <<'SH'
+#!/bin/bash
+printf 'notification: %s\n' "$*" >>"$COMMAND_LOG"
+SH
+cat >"$command_bin/omarchy-theme-bg-current" <<'SH'
+#!/bin/bash
+printf 'Road\n'
+SH
+chmod +x "$command_bin"/omarchy-*
+
+PATH="$command_bin:$PATH" HOME="$intro_home" COMMAND_LOG="$command_log" "$ROOT/bin/omarchy-theme-bg-intro" disable
+if PATH="$command_bin:$PATH" HOME="$intro_home" "$ROOT/bin/omarchy-theme-bg-intro" status; then
+  fail "disabled background intros report a disabled status"
+fi
+PATH="$command_bin:$PATH" HOME="$intro_home" COMMAND_LOG="$command_log" "$ROOT/bin/omarchy-theme-bg-intro" enable
+PATH="$command_bin:$PATH" HOME="$intro_home" "$ROOT/bin/omarchy-theme-bg-intro" status || fail "enabled background intros report an enabled status"
+pass "background intros have one global on/off control"
+
+: >"$command_log"
+before_marker=$(<"$marker")
+PATH="$command_bin:$PATH" HOME="$intro_home" COMMAND_LOG="$command_log" "$ROOT/bin/omarchy-theme-bg-boot-intro" --theme-switch "$background" "$(stat -Lc '%d:%i' "$intro_state/theme")"
+grep -Fxq 'owe: refresh' "$command_log" || fail "unprepared theme switching synchronizes OWE with the selected image"
+grep -Fxq "owe: intro --start first-frame $theme_intro_dir/road.mp4" "$command_log" || fail "theme switching plays its matching intro even after boot was consumed"
+: >"$command_log"
+PATH="$command_bin:$PATH" HOME="$intro_home" COMMAND_LOG="$command_log" "$ROOT/bin/omarchy-theme-bg-boot-intro" --theme-switch "$background" "$(stat -Lc '%d:%i' "$intro_state/theme")" true
+grep -Fxq "owe: intro --start first-frame --refresh $theme_intro_dir/road.mp4" "$command_log" || fail "prepared theme switching synchronizes and starts in one call"
+! grep -Fxq 'owe: refresh' "$command_log" || fail "prepared playback avoids an extra refresh call"
+cover_ready="$test_tmp/cover-ready"
+(sleep 0.2; touch "$cover_ready") &
+cover_pid=$!
+PATH="$command_bin:$PATH" HOME="$intro_home" COMMAND_LOG="$command_log" COVER_READY_FILE="$cover_ready" "$ROOT/bin/omarchy-theme-bg-boot-intro" --theme-switch "$background" "$(stat -Lc '%d:%i' "$intro_state/theme")" true || fail "playback waits for the outgoing cover before starting"
+wait "$cover_pid"
+: >"$command_log"
+if PATH="$command_bin:$PATH" HOME="$intro_home" COMMAND_LOG="$command_log" COVER_STATUS=error "$ROOT/bin/omarchy-theme-bg-boot-intro" --theme-switch "$background" "$(stat -Lc '%d:%i' "$intro_state/theme")" true; then
+  fail "a failed cover requests the still fallback"
+fi
+! grep -q '^owe: intro ' "$command_log" || fail "a failed outgoing cover cannot expose an intro"
+[[ $(<"$marker") == "$before_marker" ]] || fail "theme switching does not reopen the session marker"
+: >"$command_log"
+PATH="$command_bin:$PATH" HOME="$intro_home" COMMAND_LOG="$command_log" "$ROOT/bin/omarchy-theme-bg-boot-intro" --theme-switch "$custom_background" "$(stat -Lc '%d:%i' "$intro_state/theme")"
+! grep -q '^owe: intro ' "$command_log" || fail "a superseded theme switch does not play an old intro"
+theme_id=$(stat -Lc '%d:%i' "$intro_state/theme")
+: >"$command_log"
+if PATH="$command_bin:$PATH" HOME="$intro_home" COMMAND_LOG="$command_log" ANIMATIONS=off "$ROOT/bin/omarchy-theme-bg-boot-intro" --theme-switch "$background" "$theme_id"; then
+  fail "a current theme launch requests its still fallback when animations were disabled"
+fi
+! grep -q '^owe: intro ' "$command_log" || fail "a canceled theme intro does not play"
+mv "$intro_state/theme" "$intro_state/previous-theme"
+cp -r "$intro_state/previous-theme" "$intro_state/theme"
+: >"$command_log"
+PATH="$command_bin:$PATH" HOME="$intro_home" COMMAND_LOG="$command_log" "$ROOT/bin/omarchy-theme-bg-boot-intro" --theme-switch "$background" "$theme_id"
+! grep -q '^owe: intro ' "$command_log" || fail "reused filenames do not let a superseded theme launch play"
+pass "theme switches can play their selected intro without resetting login startup"
+
+migration_home="$test_tmp/migration-home"
+migration_bin="$test_tmp/migration-bin"
+migration_calls="$test_tmp/migration-calls"
+mkdir -p "$migration_home/.local/state/omarchy/current" "$migration_bin"
+printf 'catppuccin\n' >"$migration_home/.local/state/omarchy/current/theme.name"
+cat >"$migration_bin/omarchy-theme-refresh" <<'SH'
+#!/bin/bash
+printf 'refresh\n' >>"$MIGRATION_CALLS"
+SH
+chmod +x "$migration_bin/omarchy-theme-refresh"
+
+HOME="$migration_home" PATH="$migration_bin:$PATH" MIGRATION_CALLS="$migration_calls" OMARCHY_PATH="$ROOT" OMARCHY_SESSION_ID=migration-boot bash -euo pipefail "$ROOT/migrations/1788281348.sh" >/dev/null
+[[ $(<"$migration_calls") == "refresh" ]] || fail "the migration refreshes an active theme with packaged intros"
+[[ $(<"$migration_home/.local/state/omarchy/background-intro.session-id") == "migration-boot" ]] || fail "the migration defers a newly installed intro until the next login"
+
+mkdir -p "$intro_runtime/hypr/older-session" "$intro_runtime/hypr/current-session"
+touch -d '2 minutes ago' "$intro_runtime/hypr/older-session"
+HOME="$migration_home" PATH="$migration_bin:$PATH" MIGRATION_CALLS="$migration_calls" OMARCHY_PATH="$ROOT" \
+  OMARCHY_SESSION_ID="" HYPRLAND_INSTANCE_SIGNATURE="" XDG_RUNTIME_DIR="$intro_runtime" \
+  bash -euo pipefail "$ROOT/migrations/1788281348.sh" >/dev/null
+[[ $(<"$migration_home/.local/state/omarchy/background-intro.session-id") == "current-session" ]] || fail "an update outside Hyprland consumes the session that shell restart will use"
+HOME="$migration_home" PATH="$migration_bin:$PATH" MIGRATION_CALLS="$migration_calls" OMARCHY_PATH="$ROOT" \
+  OMARCHY_SESSION_ID="" HYPRLAND_INSTANCE_SIGNATURE="" XDG_RUNTIME_DIR="$test_tmp/no-session" \
+  bash -euo pipefail "$ROOT/migrations/1788281348.sh" >/dev/null
+[[ $(<"$migration_home/.local/state/omarchy/background-intro.session-id") == "current-session" ]] || fail "a headless update leaves the previous session marker alone"
+
+pass "the migration does not start a login intro during an update"
+
+packaged_pairs=0
+for intro in "$ROOT"/themes/*/backgrounds/intros/*.mp4; do
+  [[ -f $intro ]] || continue
+  backgrounds=${intro%/intros/*}
+  stem=${intro##*/}
+  stem=${stem%.mp4}
+  matches=0
+  for extension in jpg jpeg png bmp webp; do
+    [[ ! -f $backgrounds/$stem.$extension ]] || ((++matches))
+  done
+  (( matches == 1 )) || fail "$intro has exactly one matching still image" "$matches"
+  ((++packaged_pairs))
+done
+(( packaged_pairs > 0 )) || fail "no packaged theme intros were found"
+pass "theme intro filenames match their sibling background images"
+
+# Picker preparation is speculative and must not consume login startup or play.
+prepare_root="$test_tmp/prepare-repo"
+prepare_backgrounds="$prepare_root/themes/demo/backgrounds"
+mkdir -p "$prepare_backgrounds/intros" "$intro_home/.local/state/omarchy/theme-backgrounds"
+printf 'first still\n' >"$prepare_backgrounds/1-first.webp"
+printf 'remembered still\n' >"$prepare_backgrounds/2-remembered.webp"
+printf 'remembered video\n' >"$prepare_backgrounds/intros/2-remembered.mp4"
+printf '%s\n' "$intro_state/theme/backgrounds/2-remembered.webp" >"$intro_home/.local/state/omarchy/theme-backgrounds/demo"
+rm -f "$toggle"
+: >"$command_log"
+marker_before=$(<"$marker")
+PATH="$command_bin:$PATH" HOME="$intro_home" OMARCHY_PATH="$prepare_root" COMMAND_LOG="$command_log" "$ROOT/bin/omarchy-theme-bg-boot-intro" --prepare-theme demo
+grep -Fxq "owe: intro-prepare $prepare_backgrounds/intros/2-remembered.mp4" "$command_log" || fail "picker preparation follows the theme's remembered background"
+! grep -q '^owe: intro ' "$command_log" || fail "preparation does not play an intro"
+[[ $(<"$marker") == "$marker_before" ]] || fail "preparation leaves login startup alone"
+touch "$toggle"
+: >"$command_log"
+PATH="$command_bin:$PATH" HOME="$intro_home" OMARCHY_PATH="$prepare_root" COMMAND_LOG="$command_log" "$ROOT/bin/omarchy-theme-bg-boot-intro" --prepare-theme demo
+[[ ! -s $command_log ]] || fail "disabled intros do not warm the renderer"
+pass "picker preparation respects the remembered background, login startup, and intro toggle"

test/shell.d/background-pending-theme-test.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+set -euo pipefail
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+require_compositor "pending background theme cancellation"
+require_command quickshell
+require_command python3
+require_command magick
+
+stage=$(mktemp -d)
+trap 'rm -rf "$stage"' EXIT
+mkdir -p "$stage/home/.local/state/omarchy/current"
+ln -s "$ROOT/shell/plugins/background" "$stage/background"
+ln -s "$ROOT/shell/Commons" "$stage/Commons"
+ln -s "$ROOT/shell/Ui" "$stage/Ui"
+magick -size 128x128 xc:magenta "$stage/still.png"
+ln -s "$stage/still.png" "$stage/home/.local/state/omarchy/current/background"
+python3 - "$ROOT/shell/shell.qml" "$SHELL_TEST_DIR/fixtures/background-pending-theme/shell.qml" "$stage/shell.qml" <<'PY'
+import re
+import sys
+from pathlib import Path
+source = Path(sys.argv[1]).read_text()
+method = re.search(r'^    function applyTheme\([^\n]+\n.*?^    }', source, re.M | re.S)
+assert method, 'real shell applyTheme method not found'
+fixture = Path(sys.argv[2]).read_text()
+Path(sys.argv[3]).write_text(fixture.replace('  // APPLY_THEME_FUNCTION', method.group()))
+PY
+output=$(HOME="$stage/home" timeout 10 quickshell -p "$stage" --no-color 2>&1) || fail "pending theme fixture exits cleanly" "$output"
+[[ $output == *"RESULT pass"* && $output != *"RESULT fail"* ]] || fail "the authoritative palette survives the previous background fallback timer" "$output"
+pass "a pending still transition cannot restore old colors after the current theme is applied"

test/shell.d/background-startup-failure-test.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(dirname "$0")/base-test.sh"
+require_compositor "failed background startup"
+require_command quickshell
+
+stage=$(mktemp -d)
+trap 'rm -rf "$stage"' EXIT
+mkdir -p "$stage/bin" "$stage/home/.local/state/omarchy/current"
+ln -s "$stage/deleted.png" "$stage/home/.local/state/omarchy/current/background"
+for component in Commons Ui services; do
+  ln -s "$ROOT/shell/$component" "$stage/$component"
+done
+ln -s "$ROOT/shell/plugins/background" "$stage/background"
+cp "$SHELL_TEST_DIR/fixtures/background-startup-failure/shell.qml" "$stage/shell.qml"
+cat >"$stage/bin/omarchy-theme-bg-boot-intro" <<'SH'
+#!/bin/bash
+exit 0
+SH
+chmod +x "$stage/bin/omarchy-theme-bg-boot-intro"
+
+output=$(HOME="$stage/home" PATH="$stage/bin:$PATH" timeout 13 quickshell -p "$stage" --no-color 2>&1) || fail "failed background startup exits cleanly" "$output"
+[[ $output == *"RESULT pass"* ]] || fail "a missing wallpaper reveals the desktop within the startup deadline" "$output"
+if rg -q 'RESULT fail|ReferenceError|TypeError|Unable to assign|Binding loop' <<<"$output"; then
+  fail "failed background startup has no QML errors" "$output"
+fi
+pass "a missing wallpaper reveals the desktop within the startup deadline"

test/shell.d/background-startup-test.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+require_compositor "background startup test"
+require_command quickshell
+
+stage=$(mktemp -d)
+trap 'rm -rf "$stage"' EXIT
+mkdir -p "$stage/services" "$stage/bin" "$stage/home/.local/state/omarchy/current"
+printf 'P6\n1 1\n255\n\377\000\377' >"$stage/still.ppm"
+ln -s "$stage/still.ppm" "$stage/home/.local/state/omarchy/current/background"
+ln -s "$ROOT/shell/Commons" "$stage/Commons"
+cp "$ROOT/shell/services/BackgroundIntro.qml" "$stage/services/"
+cp "$SHELL_TEST_DIR/fixtures/background-startup/shell.qml" "$stage/shell.qml"
+cat >"$stage/bin/omarchy-theme-bg-boot-intro" <<'SH'
+#!/bin/bash
+exit 0
+SH
+chmod +x "$stage/bin/omarchy-theme-bg-boot-intro"
+cat >"$stage/bin/hyprctl" <<'SH'
+#!/bin/bash
+if [[ $1 == "eval" ]]; then
+  printf '%s\n' "$*" >>"$STARTUP_CURSOR_LOG"
+else
+  /usr/bin/hyprctl "$@"
+fi
+SH
+chmod +x "$stage/bin/hyprctl"
+: >"$stage/cursor.log"
+output=$(HOME="$stage/home" PATH="$stage/bin:$PATH" STARTUP_CURSOR_LOG="$stage/cursor.log" timeout 6 quickshell -p "$stage" --no-color 2>&1) || fail "background startup fixture exits cleanly" "$output"
+[[ $output == *"RESULT pass"* ]] || fail "the wallpaper restores before background plugin loading" "$output"
+if rg -q 'RESULT fail|ReferenceError|TypeError|Error:|Unable to assign|Binding loop' <<<"$output"; then
+  fail "background startup fixture has no QML errors" "$output"
+fi
+pass "fresh startup hides the desktop until both the background and bar are ready"
+pass "the startup cursor stays hidden until the desktop begins fading in"

test/shell.d/fixtures/background-instant-reload/shell.qml

@@ -0,0 +1,28 @@
+import QtQuick
+import Quickshell
+import Quickshell.Io
+import "background" as BackgroundPlugin
+
+ShellRoot {
+  property bool reloaded: false
+  BackgroundPlugin.Background { id: background }
+  FileView { id: command; path: Quickshell.env("RELOAD_TEST_COMMAND"); watchChanges: true; onFileChanged: reload() }
+  FileView { id: result; path: Quickshell.env("RELOAD_TEST_RESULT"); atomicWrites: true }
+
+  Timer { interval: 600; running: true; onTriggered: result.setText("initial") }
+  Timer { id: settled; interval: 600; onTriggered: result.setText("reloaded") }
+  Timer {
+    interval: 100
+    running: true
+    repeat: true
+    onTriggered: {
+      if (command.text().trim() === "done") {
+        Qt.quit()
+      } else if (command.text().trim() === "reload" && !reloaded) {
+        reloaded = true
+        background.setBackground(background.currentBackground, true)
+        settled.start()
+      }
+    }
+  }
+}

test/shell.d/fixtures/background-intro-clone/shell.qml

@@ -0,0 +1,43 @@
+import QtQuick
+import Quickshell
+import Quickshell.Io
+import "services"
+import "clone" as Clone
+
+ShellRoot {
+  id: test
+  property var services: ({ "intro-test.background": background })
+  function firstPartyServiceFor(id) { return id === "omarchy.background" ? background : null }
+
+  PluginShellApi { id: facade; pluginId: "intro-test.background" }
+  Clone.Background { id: background; shell: facade }
+  BackgroundIntro { id: intro; host: test }
+  property bool stillReported: false
+  FileView { id: release; path: Quickshell.env("INTRO_TEST_RELEASE"); watchChanges: true; onFileChanged: reload() }
+  FileView { id: result; path: Quickshell.env("INTRO_TEST_RESULT"); atomicWrites: true }
+
+  Timer {
+    interval: 600
+    running: true
+    onTriggered: result.setText(JSON.stringify({
+      phase: "cover",
+      scoped: background.shell.pluginId === "intro-test.background",
+      privateCoordinator: background.shell.bootIntro === undefined,
+      selected: background.displayedBackground.endsWith("still.png"),
+      covered: intro.cover
+    }))
+  }
+  Timer {
+    interval: 100
+    running: true
+    repeat: true
+    onTriggered: {
+      if (release.text().trim() === "done") {
+        Qt.quit()
+      } else if (release.text().trim() === "captured" && !intro.cover && !intro.startupPending && !test.stillReported) {
+        test.stillReported = true
+        result.setText(JSON.stringify({ phase: "still", covered: intro.cover }))
+      }
+    }
+  }
+}

test/shell.d/fixtures/background-intro-lifecycle/shell.qml

@@ -0,0 +1,121 @@
+import QtQuick
+import Quickshell
+import Quickshell.Io
+import "services"
+import "Commons" as Commons
+
+ShellRoot {
+  id: test
+  property bool failed: false
+  property var services: ({})
+  function firstPartyServiceFor(id) { return services[id] || null }
+  function check(ok, message) {
+    if (!ok) {
+      failed = true
+      console.log("RESULT fail " + message)
+    }
+  }
+
+  QtObject { id: retainedBackground; property bool suspended: false }
+  BackgroundIntro { id: intro; host: test }
+
+  Process {
+    id: revealVideo
+    command: ["touch", Quickshell.env("INTRO_TEST_FRAME_READY")]
+  }
+
+  Timer {
+    interval: 300
+    running: true
+    onTriggered: {
+      test.check(intro.checked, "startup runs even when OWE left the background disabled for a video")
+      test.services = ({ "omarchy.background": retainedBackground })
+      intro.prepareTheme(Quickshell.env("INTRO_TEST_COVER"), "theme-one", Qt.btoa('background = "#123456"'), "")
+      test.check(intro.themeCoverStatus("theme-one") === "loading", "the cover waits for decoding and presentation")
+      test.check(intro.themeStatus("theme-one") === "pending", "app retints wait for the intro reveal")
+      test.check(!Qt.colorEqual(Commons.Color.background, "#123456"), "the palette waits for OWE's first frame")
+      intro.finishTheme("superseded-theme")
+      test.check(intro.themeToken === "theme-one", "an older intro cannot release the pending handoff")
+    }
+  }
+  Timer {
+    interval: 500
+    running: true
+    onTriggered: {
+      test.check(intro.cover, "the still stays covered while the launcher waits")
+      test.check(intro.themeCoverStatus("theme-one") === "ready", "the outgoing cover is presented before the shell is hidden")
+      retainedBackground.suspended = true
+    }
+  }
+  Timer {
+    interval: 600
+    running: true
+    onTriggered: {
+      test.check(intro.themeToken === "theme-one", "a leftover renderer still stays covered until video is revealed")
+      revealVideo.running = true
+      handoffDeadline = Date.now() + 3000
+      handoff.start()
+    }
+  }
+  property double handoffDeadline: 0
+  property bool openingFadeObserved: false
+  Connections {
+    target: intro
+    function onThemeTokenChanged() {
+      if (handoff.running && intro.themeToken === "") {
+        Qt.callLater(function() {
+          test.check(intro.themeStatus("theme-one") === "pending", "app retints also wait through the opening crossfade")
+          test.openingFadeObserved = true
+        })
+      }
+    }
+  }
+  Timer {
+    id: handoff
+    interval: 16
+    repeat: true
+    onTriggered: {
+      if (intro.themeToken || !test.openingFadeObserved) {
+        if (Date.now() >= test.handoffDeadline) {
+          test.check(false, "the ready video releases its cover before the deadline")
+          Qt.quit()
+        }
+        return
+      }
+      stop()
+      test.check(!intro.cover && intro.checked, "OWE taking the background releases the cover")
+      test.check(intro.themeToken === "" && Qt.colorEqual(Commons.Color.background, "#123456"), "first-frame handoff starts the palette and wallpaper fade together")
+      retainedBackground.suspended = false
+      Qt.callLater(function() { test.check(!intro.cover, "resuming the retained background cannot cover or retry playback") })
+      completionDeadline = Date.now() + 3000
+      completion.start()
+    }
+  }
+  property double completionDeadline: 0
+  Timer {
+    id: completion
+    interval: 16
+    repeat: true
+    onTriggered: {
+      if (intro.themeStatus("theme-one") !== "ready" || !intro.startupSettled) {
+        if (Date.now() >= test.completionDeadline) {
+          test.check(false, "the fade and launcher complete before the deadline")
+          Qt.quit()
+        }
+        return
+      }
+      stop()
+      test.check(intro.themeStatus("theme-one") === "ready", "the completed crossfade releases app retints")
+      intro.prepareTheme("", "failed-theme", Qt.btoa('background = "#654321"'), "")
+      intro.finishTheme("failed-theme")
+      test.check(Qt.colorEqual(Commons.Color.background, "#654321"), "failed playback still releases its pending palette")
+      intro.prepareTheme("", "cancelled-theme", Qt.btoa('background = "#abcdef"'), "")
+      intro.cancelTheme()
+      intro.finishTheme("cancelled-theme")
+      test.check(Qt.colorEqual(Commons.Color.background, "#654321") && !intro.themeToken, "a superseding theme cannot be overwritten by an older completion")
+      test.check(!intro.cover, "launcher completion leaves the still uncovered")
+      if (!test.failed) console.log("RESULT pass")
+      Qt.quit()
+    }
+  }
+}

test/shell.d/fixtures/background-pending-theme/shell.qml

@@ -0,0 +1,35 @@
+import QtQuick
+import Quickshell
+import qs.Commons
+import "background" as BackgroundPlugin
+
+ShellRoot {
+  id: shell
+  function firstPartyServiceFor(id) { return id === "omarchy.background" ? background : null }
+  BackgroundPlugin.Background { id: background }
+
+  // APPLY_THEME_FUNCTION
+
+  Timer {
+    interval: 600
+    running: true
+    onTriggered: {
+      var oldColors = Qt.btoa('accent = "#ff0000"\nbackground = "#000000"\nforeground = "#ffffff"\n')
+      var newColors = Qt.btoa('accent = "#123456"\nbackground = "#000000"\nforeground = "#ffffff"\n')
+      background.transitionBackgroundWithTheme("", "/missing-still.png", "/missing-still.png", oldColors, "")
+      shell.applyTheme(newColors, "")
+    }
+  }
+  Timer {
+    interval: 1300
+    running: true
+    onTriggered: {
+      if (Qt.colorEqual(Color.accent, "#123456")) {
+        console.log("RESULT pass")
+      } else {
+        console.log("RESULT fail previous colors returned: " + Color.accent)
+      }
+      Qt.quit()
+    }
+  }
+}

test/shell.d/fixtures/background-startup-failure/shell.qml

@@ -0,0 +1,40 @@
+import QtQuick
+import Quickshell
+import "services"
+import "background" as BackgroundPlugin
+
+ShellRoot {
+  id: test
+  property var services: ({ "omarchy.background": background })
+  property var bar: ({})
+  property bool failed: false
+  function firstPartyServiceFor(id) { return services[id] || null }
+  function check(ok, message) {
+    if (!ok) {
+      failed = true
+      console.log("RESULT fail " + message)
+    }
+  }
+
+  BackgroundPlugin.Background { id: background }
+  BackgroundIntro { id: intro; host: test }
+
+  Timer {
+    interval: 600
+    running: true
+    onTriggered: {
+      test.check(background.displayedBackground.endsWith("deleted.png"), "the missing wallpaper is selected")
+      test.check(!background.ready && intro.startupPending && intro.cover, "the failed image cannot release startup through readiness")
+    }
+  }
+  Timer {
+    interval: 11000
+    running: true
+    onTriggered: {
+      test.check(!background.ready, "the missing wallpaper never becomes ready")
+      test.check(!intro.startupPending && !intro.cover && intro.startupOpacity === 0, "the deadline fades the cover away despite the failed wallpaper")
+      if (!test.failed) console.log("RESULT pass")
+      Qt.quit()
+    }
+  }
+}

test/shell.d/fixtures/background-startup/shell.qml

@@ -0,0 +1,86 @@
+import QtQuick
+import Quickshell
+import Quickshell.Io
+import "services"
+
+ShellRoot {
+  id: test
+  property var services: ({})
+  property var pluginRegistry: null
+  property var bar: null
+  property bool failed: false
+  function firstPartyServiceFor(id) { return services[id] || null }
+  function check(ok, message) {
+    if (!ok) {
+      failed = true
+      console.log("RESULT fail " + message)
+    }
+  }
+
+  QtObject {
+    id: registry
+    property var installedPlugins: ({ "omarchy.background": {} })
+    signal pluginsChanged()
+    function resolveEnabledId(id) { return id }
+    function isEnabled(id) { return false }
+  }
+  QtObject {
+    id: background
+    property bool suspended: false
+    property bool ready: false
+  }
+  BackgroundIntro { id: intro; host: test }
+  FileView { id: cursorLog; path: Quickshell.env("STARTUP_CURSOR_LOG"); printErrors: false }
+
+  Timer {
+    interval: 400
+    running: true
+    onTriggered: {
+      test.check(!intro.backgroundActive, "the plugin has not loaded yet")
+      test.check(intro.cover && !intro.themeBackground, "fresh startup does not prepare an outgoing still image")
+      test.check(intro.startupSettled, "the launcher has finished without an intro")
+      test.check(intro.startupPending && intro.startupOpacity === 1, "a fresh login hides the desktop until its media and bar are ready")
+      cursorLog.reload()
+      cursorLog.waitForJob()
+      test.check(!cursorLog.text().trim(), "startup does not restore the cursor while media is loading")
+      test.services = ({ "omarchy.background": background })
+    }
+  }
+  Timer {
+    interval: 600
+    running: true
+    onTriggered: {
+      test.check(intro.cover, "a loading plugin does not release the startup wallpaper")
+      background.ready = true
+    }
+  }
+  Timer {
+    interval: 800
+    running: true
+    onTriggered: {
+      test.check(!intro.cover && !intro.themeBackground, "a ready plugin releases the startup cover and its image")
+      test.check(intro.startupPending && intro.startupOpacity === 1, "a ready background alone cannot reveal an unready bar")
+      cursorLog.reload()
+      cursorLog.waitForJob()
+      test.check(!cursorLog.text().trim(), "startup does not restore the cursor before the bar is ready")
+      test.bar = ({})
+    }
+  }
+  Timer {
+    interval: 1400
+    running: true
+    onTriggered: {
+      test.check(!intro.startupPending && intro.startupOpacity === 0, "the desktop fades in after both the media and bar are ready")
+      cursorLog.reload()
+      cursorLog.waitForJob()
+      test.check(cursorLog.text().includes("omarchy_startup_cursor_restore()"), "the opening fade restores the cursor")
+      test.services = ({})
+      intro.cover = true
+      test.pluginRegistry = registry
+      registry.pluginsChanged()
+      test.check(!intro.cover, "a disabled background plugin does not leave a startup cover on screen")
+      if (!test.failed) console.log("RESULT pass")
+      Qt.quit()
+    }
+  }
+}

test/shell.d/fixtures/startup-cursor/hyprland.lua

@@ -0,0 +1,25 @@
+package.path = os.getenv("OMARCHY_PATH") .. "/?.lua;" .. package.path
+o = {
+  shell_quote = function(value) return "'" .. value:gsub("'", "'\\''") .. "'" end,
+  launch = function(value) return value end,
+}
+local exec = hl.exec_cmd
+hl.exec_cmd = function(command)
+  if command == "omarchy-launch-shell" then
+    local file = assert(io.open(os.getenv("CURSOR_TEST_STAGE") .. "/session", "w"))
+    file:write(os.getenv("WAYLAND_DISPLAY") .. "\n" .. os.getenv("HYPRLAND_INSTANCE_SIGNATURE"))
+    file:close()
+    exec("quickshell -p " .. o.shell_quote(os.getenv("CURSOR_TEST_STAGE")))
+  elseif command:match("^hyprctl ") then
+    exec(command)
+  end
+end
+require("default.hypr.autostart")
+hl.config({
+  misc = { disable_hyprland_logo = true, disable_splash_rendering = true, background_color = "rgb(000000)", disable_watchdog_warning = true },
+  xwayland = { enabled = false },
+  cursor = { enable_hyprcursor = false },
+})
+hl.monitor({ output = "", mode = "640x480@60", position = "auto", scale = 1 })
+hl.layer_rule({ match = { namespace = "omarchy-background" }, no_anim = true })
+hl.bind("SUPER + Q", hl.dsp.exec_cmd("true"))

test/shell.d/fixtures/startup-cursor/shell.qml

@@ -0,0 +1,38 @@
+import QtQuick
+import Quickshell
+import Quickshell.Io
+import Quickshell.Wayland
+import "services"
+
+ShellRoot {
+  id: test
+  property var bar: ({})
+  property var services: ({ "omarchy.background": background })
+  function firstPartyServiceFor(id) { return background }
+  QtObject { id: background; property bool suspended: false; property bool ready: false }
+  BackgroundIntro {
+    id: intro
+    host: test
+    onStartupPendingChanged: if (!startupPending) phase.setText("revealed")
+  }
+  FileView {
+    id: release
+    path: Quickshell.env("CURSOR_TEST_STAGE") + "/release"
+    watchChanges: true
+    onLoaded: background.ready = text().trim() === "reveal"
+    onFileChanged: reload()
+  }
+  FileView {
+    id: phase
+    path: Quickshell.env("CURSOR_TEST_STAGE") + "/phase"
+    atomicWrites: true
+  }
+  PanelWindow {
+    anchors { top: true; bottom: true; left: true; right: true }
+    exclusionMode: ExclusionMode.Ignore
+    WlrLayershell.layer: WlrLayer.Bottom
+    mask: Region {}
+    color: "magenta"
+  }
+  Component.onCompleted: phase.setText("holding")
+}

test/shell.d/hyprland-shutdown-test.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+
+source "$(dirname "$0")/base-test.sh"
+
+if ! systemctl --user show-environment >/dev/null 2>&1; then
+  skip "no user manager; skipping compositor shutdown"
+  exit 0
+fi
+
+require_command python3
+require_command systemd-run
+
+test_tmp=$(mktemp -d)
+unit="omarchy-test-hyprland-shutdown-$$.service"
+trap 'systemctl --user stop "$unit" >/dev/null 2>&1; rm -rf "$test_tmp"' EXIT
+
+cat >"$test_tmp/compositor.py" <<'PY'
+import os
+import pathlib
+import signal
+import sys
+import time
+
+state = pathlib.Path(sys.argv[1])
+child = os.fork()
+if child == 0:
+    def stop_shell(signum, frame):
+        (state / "shell-stopped").touch()
+        sys.exit(0)
+
+    signal.signal(signal.SIGTERM, stop_shell)
+    (state / "shell-ready").touch()
+    while True:
+        signal.pause()
+
+def stop_compositor(signum, frame):
+    # Give an early shell SIGTERM time to remove the wallpaper.
+    time.sleep(0.2)
+    if not (state / "shell-stopped").exists():
+        (state / "wallpaper-retained").touch()
+    sys.exit(0)
+
+signal.signal(signal.SIGTERM, stop_compositor)
+while not (state / "shell-ready").exists():
+    time.sleep(0.01)
+(state / "ready").touch()
+while True:
+    signal.pause()
+PY
+
+dropin="$ROOT/etc/systemd/user/wayland-wm@hyprland.desktop.service.d/10-keep-shell.conf"
+kill_mode=$(sed -n 's/^KillMode=//p' "$dropin")
+systemd-run --user --collect --quiet --unit="$unit" \
+  --property="KillMode=$kill_mode" --property=TimeoutStopSec=2s \
+  python3 "$test_tmp/compositor.py" "$test_tmp" || fail "isolated compositor starts"
+
+for (( attempt = 0; attempt < 100; attempt++ )); do
+  [[ -f $test_tmp/ready ]] && break
+  sleep 0.02
+done
+[[ -f $test_tmp/ready ]] || fail "isolated compositor and shell are ready"
+
+systemctl --user stop "$unit" || fail "isolated compositor stops"
+[[ -f $test_tmp/wallpaper-retained ]] || fail "wallpaper survives compositor teardown"
+pass "wallpaper survives compositor teardown"
+
+if systemctl --user is-active --quiet "$unit"; then
+  fail "compositor shutdown leaves no running service"
+fi
+pass "compositor shutdown leaves no running service"

test/shell.d/hyprland-startup-cursor-cold-test.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+
+set -euo pipefail
+source "$(dirname "$0")/base-test.sh"
+require_compositor "cold compositor cursor startup"
+require_command Hyprland
+require_command quickshell
+require_command grim
+require_command magick
+require_command python3
+
+python3 <<'PY'
+import os
+import pathlib
+import signal
+import subprocess
+import tempfile
+import time
+
+root = pathlib.Path(os.environ["ROOT"])
+with tempfile.TemporaryDirectory() as directory:
+  stage = pathlib.Path(directory)
+  home = stage / "home"
+  home.mkdir()
+  (stage / "release").write_text("")
+  (stage / "bin").mkdir()
+  launcher = stage / "bin/omarchy-theme-bg-boot-intro"
+  launcher.write_text("#!/bin/bash\nexit 0\n")
+  launcher.chmod(0o755)
+  for name in ("Commons", "services"):
+    (stage / name).symlink_to(root / "shell" / name)
+  fixture = root / "test/shell.d/fixtures/startup-cursor"
+  (stage / "shell.qml").write_text((fixture / "shell.qml").read_text())
+  env = os.environ.copy()
+  env.update(HOME=str(home), OMARCHY_PATH=str(root), CURSOR_TEST_STAGE=str(stage),
+         PATH=str(stage / "bin") + ":" + env["PATH"], AQ_BACKEND="wayland",
+         HYPRLAND_NO_SD_VARS="1", HYPRLAND_NO_SD_NOTIFY="1", GSETTINGS_BACKEND="memory",
+         XCURSOR_THEME="Adwaita", XCURSOR_PATH="/usr/share/icons:/usr/share/pixmaps", XCURSOR_SIZE="24", HYPRCURSOR_SIZE="24")
+  env.pop("HYPRLAND_INSTANCE_SIGNATURE", None)
+  env.pop("HYPRCURSOR_THEME", None)
+  log = open(stage / "compositor.log", "w")
+  compositor = subprocess.Popen(["Hyprland", "--config", str(fixture / "hyprland.lua")],
+                  env=env, stdout=log, stderr=log, start_new_session=True)
+  try:
+    deadline = time.monotonic() + 5
+    while not (stage / "session").exists():
+      assert compositor.poll() is None, "cold compositor exited before startup"
+      assert time.monotonic() < deadline, "cold compositor never started"
+      time.sleep(0.005)
+    display, signature = (stage / "session").read_text().splitlines()
+    env.update(WAYLAND_DISPLAY=display, HYPRLAND_INSTANCE_SIGNATURE=signature)
+    # Capture immediately, including before Quickshell loads its cover. The
+    # fixture cannot reveal while grim or magick is busy taking these frames.
+    deadline = time.monotonic() + 5
+    for sample in range(3):
+      assert time.monotonic() < deadline, "initial compositor captures timed out"
+      screenshot = stage / "frame.png"
+      subprocess.run(["grim", "-c", str(screenshot)], env=env, check=True,
+               stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=5)
+      maximum = subprocess.check_output(["magick", str(screenshot), "-format", "%[fx:maxima]", "info:"], text=True, timeout=5)
+      assert maximum == "0", "the cursor appeared in the first compositor frames"
+
+    def wait_phase(expected):
+      deadline = time.monotonic() + 5
+      while not (stage / "phase").exists() or (stage / "phase").read_text() != expected:
+        assert compositor.poll() is None and time.monotonic() < deadline, "startup never reached " + expected
+        time.sleep(0.01)
+
+    wait_phase("holding")
+    (stage / "release").write_text("reveal")
+    wait_phase("revealed")
+    # Cursor visibility is polled by the compositor independently of the fade.
+    deadline = time.monotonic() + 5
+    while True:
+      subprocess.run(["grim", "-c", str(screenshot)], env=env, check=True,
+               stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=5)
+      green = subprocess.check_output(["magick", str(screenshot), "-channel", "G", "-separate", "-threshold", "0", "-format", "%[fx:mean*w*h]", "info:"], text=True, timeout=5)
+      if float(green) > 20:
+        break
+      assert time.monotonic() < deadline, "the normal cursor did not return with the desktop"
+  finally:
+    os.killpg(compositor.pid, signal.SIGTERM)
+    compositor.wait(timeout=10)
+    log.close()
+PY
+pass "a fresh compositor never exposes its cursor before the desktop reveal"

test/shell.d/hyprland-startup-cursor-test.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+
+set -euo pipefail
+source "$(dirname "$0")/base-test.sh"
+require_command lua
+
+lua <<'LUA'
+package.path = os.getenv("ROOT") .. "/?.lua;" .. package.path
+local events, recovery, command = {}, nil, nil
+local config = { invisible = false, enable_hyprcursor = true, sync_gsettings_theme = true }
+local env = { XCURSOR_THEME = "my-xcursor", HYPRCURSOR_THEME = "my-hyprcursor", XCURSOR_PATH = "/my/icons" }
+local getenv = os.getenv
+os.getenv = function(name) return env[name] or getenv(name) end
+local monitors = {}
+hl = {
+  on = function(event, callback) events[event] = callback end,
+  get_monitors = function() return monitors end,
+  get_config = function(key) return config[key:match("%.(.+)")] end,
+  env = function(name, value) env[name] = value end,
+  config = function(values)
+    for name, value in pairs(values.cursor) do config[name] = value end
+  end,
+  timer = function(callback, options)
+    assert(options.timeout == 15000 and options.type == "oneshot")
+    recovery = callback
+  end,
+  exec_cmd = function(value)
+    if value == "omarchy-launch-shell" then
+      assert(config.invisible and env.XCURSOR_THEME == "my-xcursor", "hide the compositor cursor while restoring application settings before launch")
+    end
+    command = value
+  end,
+}
+o = { shell_quote = function(value) return "'" .. value .. "'" end, launch = function(value) return value end }
+
+require("default.hypr.autostart")
+assert(not config.invisible, "loading the module must wait for user configuration")
+events["config.reloaded"]()
+assert(config.invisible and not config.enable_hyprcursor and not config.sync_gsettings_theme)
+assert(env.XCURSOR_THEME == "omarchy-startup" and env.XCURSOR_PATH:match("/default/hypr/cursors:/my/icons$"))
+assert(omarchy_startup_cursor_pending, "the first compositor frame must use the blank cursor")
+events["hyprland.start"]()
+assert(env.XCURSOR_THEME == "my-xcursor" and env.XCURSOR_PATH == "/my/icons", "applications must inherit the user's cursor")
+assert(config.invisible, "starting applications must not reveal the cursor")
+
+local previous_recovery = recovery
+events["config.reloaded"]()
+assert(recovery ~= previous_recovery and config.invisible, "a config reload must retain startup hiding and rearm recovery")
+recovery()
+assert(command:match("setcursor 'my%-xcursor'"), "restore the Xcursor fallback before revealing the pointer")
+assert(config.invisible, "wait for the normal theme before restoring visibility")
+omarchy_startup_cursor_restore(true)
+assert(not config.invisible and config.enable_hyprcursor and config.sync_gsettings_theme)
+assert(command:match("setcursor 'my%-hyprcursor'"), "restore the user's Hyprcursor theme")
+local previous_command = command
+previous_recovery()
+assert(command == previous_command, "recovery must not change a revealed cursor")
+events["config.reloaded"]()
+assert(not config.invisible and env.XCURSOR_THEME == "my-xcursor", "ordinary config reloads must not hide the cursor")
+
+omarchy_startup_cursor_pending = nil
+monitors = { {} }
+events["config.reloaded"]()
+assert(not omarchy_startup_cursor_pending and not config.invisible, "installing the fix in a running compositor must leave its cursor alone")
+LUA
+pass "the first compositor frame starts blank and the reveal restores user cursor settings"

test/shell.d/launch-shell-test.sh

@@ -20,7 +20,11 @@ trap cleanup EXIT
 
 fake_bin="$test_tmp/bin"
 shell_root="$test_tmp/root"
-mkdir -p "$fake_bin" "$shell_root/shell"
+launch_home="$test_tmp/home"
+startup_wallpaper="$test_tmp/Selected wallpaper.webp"
+mkdir -p "$fake_bin" "$shell_root/shell" "$launch_home/.local/state/omarchy/current"
+touch "$startup_wallpaper"
+ln -s "$startup_wallpaper" "$launch_home/.local/state/omarchy/current/background"
 
 # Each launch consumes the next status from OMARCHY_TEST_QS_STATUSES; "run"
 # stands in for a healthy shell that keeps going until stopped.
@@ -28,8 +32,8 @@ cat >"$fake_bin/quickshell" <<'SH'
 #!/bin/bash
 
 printf '%s\n' "$*" >>"$OMARCHY_TEST_QS_LOG"
-printf 'watcher=%s popup=%s\n' \
-  "${QS_DISABLE_FILE_WATCHER:-unset}" "${QS_NO_RELOAD_POPUP:-unset}" >>"$OMARCHY_TEST_QS_ENV_LOG"
+printf 'watcher=%s popup=%s background=%s\n' \
+  "${QS_DISABLE_FILE_WATCHER:-unset}" "${QS_NO_RELOAD_POPUP:-unset}" "${OMARCHY_STARTUP_BACKGROUND:-unset}" >>"$OMARCHY_TEST_QS_ENV_LOG"
 
 launches=$(wc -l <"$OMARCHY_TEST_QS_LOG")
 status=$(awk -v n="$launches" 'NR == n { print; found = 1 } END { if (!found) print "0" }' <<<"$OMARCHY_TEST_QS_STATUSES")
@@ -90,6 +94,7 @@ launch_shell() {
   : >"$logger_log"
 
   PATH="$fake_bin:$PATH" \
+  HOME="$launch_home" \
   OMARCHY_PATH="$shell_root" \
   OMARCHY_TEST_QS_LOG="$qs_log" \
   OMARCHY_TEST_QS_ENV_LOG="$qs_env_log" \
@@ -113,9 +118,11 @@ pass "a shell that exits cleanly is left alone"
 
 # A misspelled variable would leave Quickshell hot-reloading the tree pacman
 # rewrites underneath it, which is what crashes the restart that follows.
-[[ $(<"$qs_env_log") == "watcher=1 popup=1" ]] ||
+[[ $(<"$qs_env_log") == "watcher=1 popup=1 "* ]] ||
   fail "the shell launches with Quickshell's own reloading off" "$(<"$qs_env_log")"
 pass "the shell launches with Quickshell's config watcher and reload popup off"
+[[ $(<"$qs_env_log") == *"background=$startup_wallpaper" ]] || fail "the shell receives the resolved wallpaper path before startup" "$(<"$qs_env_log")"
+pass "the selected wallpaper can decode as soon as Quickshell starts"
 
 # Qt leaves through _exit(), so Quickshell's crash handler never relaunches it.
 launch_shell $'255\n0' || fail "a shell that died on a Wayland error is relaunched"

test/shell.d/menu-test.sh

@@ -359,6 +359,11 @@ assertEqual(
   'omarchy-bar transparent toggle',
   'menu exposes Menu Bar transparency as a toggle'
 )
+assert(
+  !defaultItems.some(item => item.id.startsWith('style.background-intro'))
+    && defaultById['trigger.toggle.animations'].action === 'omarchy-toggle-animations',
+  'menu uses the existing animations toggle without separate background intro controls'
+)
 assertDeepEqual(
   defaultItems.filter(item => item.parent === 'setup.plugin').map(item => item.label),
   ['Enable Plugin', 'Disable Plugin', 'Add Plugin', 'Clone Plugin', 'Remove Plugin'],

test/shell.d/theme-intro-switch-test.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+test_tmp=$(mktemp -d)
+trap 'rm -rf "$test_tmp"' EXIT
+home="$test_tmp/home"
+state="$home/.local/state/omarchy/current"
+themes="$home/.config/omarchy/themes"
+commands="$test_tmp/bin"
+log="$test_tmp/commands"
+mkdir -p "$state" "$commands" "$home/.local/state/omarchy/theme-backgrounds"
+for theme in alpha beta; do
+  mkdir -p "$themes/$theme/backgrounds/intros"
+  cp "$ROOT/themes/tokyo-night/colors.toml" "$themes/$theme/colors.toml"
+  printf 'still\n' >"$themes/$theme/backgrounds/1-sky.webp"
+  printf 'still\n' >"$themes/$theme/backgrounds/2-road.webp"
+  printf 'intro\n' >"$themes/$theme/backgrounds/intros/2-road.mp4"
+done
+cp -r "$themes/alpha" "$state/theme"
+printf 'alpha\n' >"$state/theme.name"
+ln -s "$state/theme/backgrounds/1-sky.webp" "$state/background"
+printf '%s\n' "$state/theme/backgrounds/2-road.webp" >"$home/.local/state/omarchy/theme-backgrounds/beta"
+printf 'already-consumed\n' >"$home/.local/state/omarchy/background-intro.session-id"
+
+cat >"$commands/noop" <<'STUB'
+#!/bin/bash
+exit 0
+STUB
+chmod +x "$commands/noop"
+# Post-theme retints run through bash -lc; this fixture only exercises selection and presentation.
+for command in omarchy-theme-set-templates omarchy-hook omarchy-theme-set-herdr-machines omarchy-theme-bg-cache; do
+  ln -s noop "$commands/$command"
+done
+cat >"$commands/bash" <<'STUB'
+#!/bin/bash
+if [[ $1 == "-lc" && $2 == "omarchy-restart-hyprctl" ]]; then
+  omarchy-restart-hyprctl
+fi
+STUB
+cat >"$commands/omarchy-restart-hyprctl" <<'STUB'
+#!/bin/bash
+echo "hypr-reload" >>"$TEST_LOG"
+STUB
+cat >"$commands/hyprctl" <<'STUB'
+#!/bin/bash
+printf '{"bool":%s}\n' "${TEST_ANIMATIONS:-true}"
+STUB
+cat >"$commands/omarchy-shell" <<'STUB'
+#!/bin/bash
+printf 'shell: %s\n' "$*" >>"$TEST_LOG"
+if [[ -n ${TEST_GATE_DIR:-} ]]; then
+  if [[ $2 == "themeIntroStatus" && ! -f $TEST_GATE_DIR/fade-ready ]]; then
+    if [[ ! -f $TEST_GATE_DIR/fade-waited ]]; then
+      touch "$TEST_GATE_DIR/fade-waited"
+      echo "pending"
+    else
+      touch "$TEST_GATE_DIR/fade-ready"
+      echo "ready"
+    fi
+  elif [[ $2 == "themeIntroCoverStatus" && ! -f $TEST_GATE_DIR/cover-ready ]]; then
+    if [[ ! -f $TEST_GATE_DIR/fade-ready || $(<"$TEST_STATE/theme.name") != "$TEST_OLD_THEME" ]]; then
+      touch "$TEST_GATE_DIR/premature-swap"
+    fi
+    if [[ ! -f $TEST_GATE_DIR/cover-waited ]]; then
+      touch "$TEST_GATE_DIR/cover-waited"
+      echo "loading"
+    else
+      touch "$TEST_GATE_DIR/cover-ready"
+      echo "ready"
+    fi
+  else
+    echo "ready"
+  fi
+fi
+STUB
+cat >"$commands/owe" <<'STUB'
+#!/bin/bash
+if [[ $1 == intro && -n ${TEST_RELEASE:-} ]]; then
+  printf '%s\n' "$$" >"$TEST_INTRO_PID"
+fi
+printf 'owe: %s\n' "$*" >>"$TEST_LOG"
+[[ ${TEST_OWE_FAIL:-false} != true ]] || exit 1
+if [[ $1 == "render" ]]; then
+  [[ ${TEST_LIVE_FRAME:-false} == "true" ]] || exit 1
+  snapshot=$(jq -r '.path' <<<"$2")
+  printf 'live video frame\n' >"$snapshot"
+elif [[ $1 == "intro-prepare" && ${TEST_OWE_NO_PREPARE:-false} == "true" ]]; then
+  exit 1
+fi
+if [[ $1 == intro && -n ${TEST_RELEASE:-} ]]; then
+  for attempt in {1..100}; do
+    [[ ! -f $TEST_RELEASE ]] || exit 0
+    sleep 0.05
+  done
+  exit 1
+fi
+STUB
+chmod +x "$commands/bash" "$commands/omarchy-restart-hyprctl" "$commands/hyprctl" "$commands/omarchy-shell" "$commands/owe"
+
+set_theme() {
+  : >"$log"
+  HOME="$home" OMARCHY_PATH="$ROOT" PATH="$commands:$ROOT/bin:$PATH" XDG_RUNTIME_DIR="$test_tmp" TEST_LOG="$log" \
+    /bin/bash "$ROOT/bin/omarchy-theme-set" "$1" >"$test_tmp/stdout" 2>"$test_tmp/stderr" || fail "theme selection completes" "$(cat "$test_tmp/stderr")"
+}
+wait_command() {
+  for attempt in {1..100}; do
+    grep -q "$1" "$log" && return 0
+    sleep 0.02
+  done
+  fail "theme selection reaches $1" "$(cat "$log")"
+}
+
+set_theme beta
+wait_command '^owe: intro '
+grep -Fxq "owe: intro --start first-frame --refresh $state/theme/backgrounds/intros/2-road.mp4" "$log" || fail "a theme switch plays the remembered background's matching prepared intro"
+[[ $(readlink "$state/background") == "$state/theme/backgrounds/2-road.webp" ]] || fail "the remembered background is selected"
+! grep -qE '^shell: background (prepare|themeTransition)' "$log" || fail "an intro replaces the normal still transition"
+[[ $(<"$home/.local/state/omarchy/background-intro.session-id") == already-consumed ]] || fail "a theme switch leaves login consumption unchanged"
+pass "switching themes plays the matching intro for the remembered background"
+
+set_theme beta
+[[ $(readlink "$state/background") == "$state/theme/backgrounds/1-sky.webp" ]] || fail "reselecting the current theme cycles its background"
+grep -q '^shell: background themeTransition ' "$log" || fail "same-theme cycling uses the normal still transition"
+! grep -q '^owe: intro ' "$log" || fail "same-theme cycling does not play an intro"
+OMARCHY_THEME_SKIP_BACKGROUND=1 set_theme alpha
+! grep -q '^owe: intro ' "$log" || fail "theme refresh does not play an intro"
+pass "same-theme cycling and refresh keep the normal background behavior"
+
+printf '%s\n' "$state/theme/backgrounds/2-road.webp" >"$home/.local/state/omarchy/theme-backgrounds/beta"
+mkdir -p "$home/.local/state/omarchy/toggles"
+touch "$home/.local/state/omarchy/toggles/background-intros-off"
+set_theme beta
+grep -q '^shell: background themeTransition ' "$log" || fail "disabled intros use the normal still transition"
+! grep -q '^owe: intro ' "$log" || fail "disabled intros do not play on theme selection"
+rm "$home/.local/state/omarchy/toggles/background-intros-off"
+printf '%s\n' "$state/theme/backgrounds/2-road.webp" >"$home/.local/state/omarchy/theme-backgrounds/alpha"
+TEST_ANIMATIONS=false set_theme alpha
+grep -q '^shell: background themeTransition ' "$log" || fail "disabled animations use the normal still transition"
+! grep -q '^owe: intro ' "$log" || fail "disabled animations do not play an intro"
+OMARCHY_THEME_HEADLESS=1 set_theme beta
+! grep -q '^owe: intro ' "$log" || fail "headless theme setup does not play an intro"
+pass "theme intros respect the global toggle, disabled animations, and headless setup"
+
+# Alpha's remembered image must have a clip for these presentation checks.
+printf '%s\n' "$state/theme/backgrounds/2-road.webp" >"$home/.local/state/omarchy/theme-backgrounds/alpha"
+TEST_OWE_FAIL=true set_theme alpha
+wait_command '^shell: background setInstant '
+wait_command '^hypr-reload$'
+! grep -q '^owe: intro ' "$log" || fail "an unavailable renderer falls back to the still"
+pass "unavailable OWE falls back to the selected still image"
+
+printf '%s\n' "$state/theme/backgrounds/2-road.webp" >"$home/.local/state/omarchy/theme-backgrounds/beta"
+release="$test_tmp/release"
+TEST_LIVE_FRAME=true TEST_INTRO_PID="$test_tmp/intro.pid" TEST_RELEASE="$release" set_theme beta
+wait_command '^owe: intro '
+cover=$(awk '/^shell: shell prepareThemeIntro / { print $4; exit }' "$log")
+[[ -f $cover && $(<"$cover") == "live video frame" ]] || fail "an interrupted video supplies the outgoing cover instead of its final still"
+kill -0 "$(<"$test_tmp/intro.pid")" || fail "the fake renderer is still playing during the lock check"
+timeout 1 flock "$test_tmp/omarchy-theme-set.lock" true || fail "theme playback does not retain the theme selection lock"
+touch "$release"
+pass "interrupted playback uses its current frame and releases the theme selection lock"
+
+TEST_OWE_NO_PREPARE=true set_theme alpha
+wait_command '^owe: intro '
+grep -Fxq "owe: intro --start first-frame $state/theme/backgrounds/intros/2-road.mp4" "$log" || fail "older OWE uses the ordinary intro path"
+pass "older OWE keeps the ordinary intro startup path"
+
+gates="$test_tmp/gates"
+mkdir "$gates"
+TEST_GATE_DIR="$gates" TEST_STATE="$state" TEST_OLD_THEME=alpha set_theme beta
+wait_command '^owe: intro '
+[[ -f $gates/fade-waited && -f $gates/cover-waited && -f $gates/cover-ready ]] || fail "a rapid selection waits for the opening fade and replacement cover"
+[[ ! -f $gates/premature-swap ]] || fail "the outgoing fade and cover settle before replacing the active theme"
+pass "rapid switches present the outgoing video cover before replacing its still"
+
+wait_command '^hypr-reload$'
+release="$test_tmp/reload-release"
+TEST_INTRO_PID="$test_tmp/intro.pid" TEST_RELEASE="$release" set_theme alpha
+wait_command '^owe: intro '
+! grep -q '^hypr-reload$' "$log" || fail "the compositor is not reloaded during intro playback"
+touch "$release"
+wait_command '^hypr-reload$'
+(( $(grep -c '^hypr-reload$' "$log") == 1 )) || fail "the compositor reloads once after playback"
+pass "theme intros defer the compositor reload until playback finishes"
+
+release="$test_tmp/superseded-release"
+TEST_INTRO_PID="$test_tmp/intro.pid" TEST_RELEASE="$release" set_theme beta
+wait_command '^owe: intro '
+cover=$(awk '/^shell: shell prepareThemeIntro / { print $4; exit }' "$log")
+! grep -q '^hypr-reload$' "$log" || fail "the held intro has not reloaded the compositor"
+OMARCHY_THEME_SKIP_BACKGROUND=1 set_theme alpha
+grep -q '^hypr-reload$' "$log" || fail "a theme refresh reloads the compositor immediately"
+touch "$release"
+for attempt in {1..100}; do
+  [[ -f $cover ]] || break
+  sleep 0.02
+done
+[[ ! -f $cover ]] || fail "the superseded intro finishes cleanup"
+(( $(grep -c '^hypr-reload$' "$log") == 1 )) || fail "the superseded intro cannot reload during a newer theme"
+pass "superseded intros do not reload the compositor"

test/shell.d/video-background-test.sh

@@ -330,6 +330,7 @@ video_snapshot=$(snapshot_background_path "$CURRENT_THEME_PATH/backgrounds/old.m
 
 CHOSEN_THEME_BACKGROUND="$transition_home/disappeared.mp4"
 BACKGROUND_TRANSITION_SNAPSHOTS=false
+THEME_BACKGROUND_INTRO=""
 OLD_BACKGROUND_SNAPSHOT=""
 PREPARED_BACKGROUND=""
 PREPARED_BACKGROUND_SNAPSHOT=""