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>
2026-10-07 22:00:52 +02:00
1 parent a137760c89
commit 902fd8aebd
@@ -15,7 +15,9 @@
 # against a half-written tree, and that failed reload leaves a second engine
 # generation behind that turns the next restart's IPC kill into a crash.
 run_shell() {
-  QS_DISABLE_FILE_WATCHER=1 QS_NO_RELOAD_POPUP=1 \
+  local startup_background
+  startup_background=$(readlink -f "$HOME/.local/state/omarchy/current/background" 2>/dev/null)
+  OMARCHY_STARTUP_BACKGROUND="$startup_background" QS_DISABLE_FILE_WATCHER=1 QS_NO_RELOAD_POPUP=1 \
    systemd-cat -t omarchy-shell -- quickshell -n -p "$OMARCHY_PATH/shell" &
  shell_pid=$!

@@ -0,0 +1,201 @@
+#!/bin/bash
+
+# omarchy:summary=Play the current background's matching theme intro
+# omarchy:hidden=true
+
+set -euo pipefail
+
+state_home="$HOME/.local/state"
+current_dir="$state_home/omarchy/current"
+current_background_link="$current_dir/background"
+marker="$state_home/omarchy/background-intro.session-id"
+toggle="$state_home/omarchy/toggles/background-intros-off"
+video_extensions=(mp4 m4v mov webm mkv avi)
+
+resolve_intro() {
+  local background
+  local stem
+  local extension
+  local intro
+
+  background=$(readlink -f "${1:-$current_background_link}" 2>/dev/null) || return 1
+  [[ -f $background ]] || return 1
+  case ${background,,} in
+  *.jpg | *.jpeg | *.png | *.bmp | *.webp) ;;
+  *) return 1 ;;
+  esac
+
+  stem=${background##*/}
+  stem=${stem%.*}
+  for extension in "${video_extensions[@]}"; do
+    intro="${background%/*}/intros/$stem.$extension"
+    if [[ -f $intro ]]; then
+      printf '%s\n' "$intro"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Preparation is speculative: the selected staged clip is compared again by OWE.
+prepare_theme_intro() {
+  local theme="$1" background remembered name source intro
+  local -a names=()
+  [[ -n $theme && $theme != .* && $theme != */* ]] || return 0
+  [[ ! -f $toggle ]] && ! animations_off || return 0
+  owe warm >/dev/null 2>&1 || return 0
+  [[ $(cat "$current_dir/theme.name" 2>/dev/null) != "$theme" ]] || return 0
+  remembered=$(cat "$state_home/omarchy/theme-backgrounds/$theme" 2>/dev/null || true)
+  if [[ ${remembered%/*} == "$current_dir/theme/backgrounds" ]]; then
+    name=${remembered##*/}
+  elif [[ -f $remembered ]]; then
+    background="$remembered"
+  else
+    mapfile -d '' -t names < <(
+      find -L "$HOME/.config/omarchy/backgrounds/$theme" -maxdepth 1 -type f -print0 2>/dev/null | sort -z
+    )
+    if (( ${#names[@]} > 0 )); then
+      background=${names[0]}
+    else
+      mapfile -d '' -t names < <(
+        find -L "$OMARCHY_PATH/themes/$theme/backgrounds" "$HOME/.config/omarchy/themes/$theme/backgrounds" -maxdepth 1 -type f \
+          \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.bmp' -o -iname '*.webp' \) -printf '%f\0' 2>/dev/null | sort -zu
+      )
+      (( ${#names[@]} > 0 )) || return 0
+      name=${names[0]}
+    fi
+  fi
+  if [[ -n ${name:-} ]]; then
+    for source in "$HOME/.config/omarchy/themes/$theme" "$OMARCHY_PATH/themes/$theme"; do
+      if [[ -f $source/backgrounds/$name ]]; then
+        background="$source/backgrounds/$name"
+        break
+      fi
+    done
+  fi
+  [[ -n ${background:-} ]] || return 0
+  intro=$(resolve_intro "$background" || true)
+  [[ -z $intro ]] || owe intro-prepare "$intro" >/dev/null 2>&1 || true
+}
+
+animations_off() {
+  [[ $(hyprctl -j getoption animations:enabled 2>/dev/null | jq -r '.bool' 2>/dev/null) == "false" ]]
+}
+
+theme_switch=false
+intro_prepared=false
+expected_background=""
+expected_theme=""
+case ${1:-} in
+  "") ;;
+  --prepare-theme)
+    prepare_theme_intro "${2:-}"
+    exit 0
+    ;;
+  --resolve-only)
+    resolve_intro "${2:-}" || true
+    exit 0
+    ;;
+  --resolve-startup)
+    if [[ ! -f $toggle ]] && ! animations_off; then
+      resolve_intro || true
+    fi
+    exit 0
+    ;;
+  --theme-switch)
+    theme_switch=true
+    expected_background=$(readlink -f "${2:-}" 2>/dev/null) || exit 1
+    expected_theme=${3:-}
+    intro_prepared=${4:-false}
+    [[ -n $expected_theme ]] || exit 1
+    ;;
+  *)
+    echo "Usage: omarchy-theme-bg-boot-intro [--resolve-only [background]|--resolve-startup|--prepare-theme theme|--theme-switch background theme-id [prepared]]" >&2
+    exit 1
+    ;;
+esac
+
+if [[ $theme_switch == false ]]; then
+  mkdir -p "$(dirname "$marker")"
+  exec 9>"$state_home/omarchy/background-intro.lock"
+  flock 9
+
+  session_id=${OMARCHY_SESSION_ID:-${HYPRLAND_INSTANCE_SIGNATURE:-}}
+  [[ -n $session_id ]] || exit 0
+  if [[ -f $marker && $(<"$marker") == "$session_id" ]]; then
+    exit 0
+  fi
+
+  marker_staged=$(mktemp "$state_home/omarchy/.background-intro.session-id.XXXXXX")
+  trap 'rm -f "$marker_staged"' EXIT
+  printf '%s\n' "$session_id" >"$marker_staged"
+  mv -f "$marker_staged" "$marker"
+  trap - EXIT
+  exec 9>&-
+fi
+
+selection_current() {
+  [[ $(readlink -f "$current_background_link") == "$expected_background" &&
+    $(stat -Lc '%d:%i' "$current_dir/theme" 2>/dev/null) == "$expected_theme" ]]
+}
+
+if [[ $theme_switch == true ]] && ! selection_current; then
+  exit 0
+fi
+
+if [[ -f $toggle ]] || animations_off; then
+  [[ $theme_switch == false ]] || exit 1
+  exit 0
+fi
+
+intro=$(resolve_intro || true)
+if [[ -z $intro ]]; then
+  [[ $theme_switch == false ]] || exit 1
+  exit 0
+fi
+
+if [[ $theme_switch == true && $intro_prepared != "true" ]]; then
+  owe refresh >/dev/null || exit 1
+elif [[ $theme_switch == false ]]; then
+  deadline=$((SECONDS + 5))
+  while ! timeout 1 owe status >/dev/null 2>&1; do
+    if (( SECONDS >= deadline )); then
+      exit 0
+    fi
+    sleep 0.2
+  done
+  (( SECONDS < deadline )) || exit 0
+fi
+
+# The asynchronous outgoing cover must reach the compositor before playback
+# can hide the shell background. Older shells have no readiness method.
+if [[ $theme_switch == true ]]; then
+  deadline=$((SECONDS + 3))
+  while true; do
+    cover_status=$(omarchy-shell shell themeIntroCoverStatus "$expected_theme" 2>/dev/null || true)
+    case $cover_status in
+      loading)
+        (( SECONDS < deadline )) || exit 1
+        sleep 0.01
+        ;;
+      error) exit 1 ;;
+      superseded) exit 0 ;;
+      *) break ;;
+    esac
+  done
+fi
+
+if [[ $theme_switch == true ]] && ! selection_current; then
+  exit 0
+fi
+
+# A selection or setting changed while OWE was starting no longer permits this intro.
+if [[ ! -f $toggle && $intro == "$(resolve_intro || true)" ]] && ! animations_off; then
+  if [[ $theme_switch == true && $intro_prepared == "true" ]]; then
+    owe intro --start first-frame --refresh "$intro"
+  else
+    owe intro --start first-frame "$intro"
+  fi
+elif [[ $theme_switch == true ]]; then
+  exit 1
+fi
@@ -0,0 +1,34 @@
+#!/bin/bash
+
+# omarchy:summary=Enable or disable background intros
+# omarchy:args=<enable|disable|toggle|status>
+# omarchy:examples=omarchy theme bg intro toggle | omarchy theme bg intro disable
+
+set -euo pipefail
+
+toggle="$HOME/.local/state/omarchy/toggles/background-intros-off"
+case ${1:-} in
+  enable)
+    rm -f "$toggle"
+    omarchy-notification-send "Background Intros" "Enabled"
+    ;;
+  disable)
+    mkdir -p "$(dirname "$toggle")"
+    touch "$toggle"
+    omarchy-notification-send "Background Intros" "Disabled"
+    ;;
+  toggle)
+    if [[ -f $toggle ]]; then
+      omarchy-theme-bg-intro enable
+    else
+      omarchy-theme-bg-intro disable
+    fi
+    ;;
+  status)
+    [[ ! -f $toggle ]]
+    ;;
+  *)
+    echo "Usage: omarchy-theme-bg-intro <enable|disable|toggle|status>" >&2
+    exit 1
+    ;;
+esac
@@ -50,6 +50,13 @@ shell_ipc() {
  timeout 2 omarchy-shell "$@" >/dev/null 2>&1
 }

+wait_for_theme_intro() {
+  local method="$1" token="$2" pending="$3" deadline=$((SECONDS + 3))
+  while (( SECONDS < deadline )) && [[ $(omarchy-shell shell "$method" "$token" 2>/dev/null) == "$pending" ]]; do
+    sleep 0.02
+  done
+}
+
 is_video_path() {
  [[ ${1,,} =~ \.(mp4|m4v|mov|webm|mkv|avi)$ ]]
 }
@@ -70,10 +77,18 @@ snapshot_background_path() {
 }

 snapshot_current_background() {
-  local current_background
+  local current_background snapshot

-  current_background=$(readlink -f "$CURRENT_BACKGROUND_LINK" 2>/dev/null || true)
-  snapshot_background_path "$current_background" "previous"
+  # An interrupted intro is still moving; its final still would flash as a
+  # cover. Capture the frame already playing instead, when OWE supports it.
+  mkdir -p "$BACKGROUND_TRANSITION_CACHE"
+  snapshot="$BACKGROUND_TRANSITION_CACHE/previous-$$.ppm"
+  if owe render "$(jq -nc --arg path "$snapshot" '{cmd: "snapshot", path: $path}')" >/dev/null 2>&1; then
+    echo "$snapshot"
+  else
+    current_background=$(readlink -f "$CURRENT_BACKGROUND_LINK" 2>/dev/null || true)
+    snapshot_background_path "$current_background" "previous"
+  fi
 }

 theme_background_state_file() {
@@ -171,7 +186,7 @@ set_theme_background_link() {
 }

 set_theme_background() {
-  local new_background new_background_snapshot
+  local new_background new_background_snapshot theme_id intro_prepared=false

  if [[ -z $CHOSEN_THEME_BACKGROUND || ! -f $CHOSEN_THEME_BACKGROUND ]]; then
    if ! choose_theme_background; then
@@ -182,6 +197,37 @@ set_theme_background() {
  fi

  new_background="$CHOSEN_THEME_BACKGROUND"
+  if [[ -n $THEME_BACKGROUND_INTRO ]]; then
+    if [[ -n $INTRO_PREPARE_PID ]] && wait "$INTRO_PREPARE_PID"; then
+      intro_prepared=true
+    fi
+    theme_id=$(stat -Lc '%d:%i' "$CURRENT_THEME_PATH")
+    THEME_INTRO_TOKEN="$theme_id"
+    shell_ipc shell prepareThemeIntro "$OLD_BACKGROUND_SNAPSHOT" "$theme_id" "$colors_payload" "$shell_payload" || \
+      shell_ipc shell applyTheme "$colors_payload" "$shell_payload" || true
+    ln -nsf "$new_background" "$CURRENT_BACKGROUND_LINK"
+    (
+      if ! omarchy-theme-bg-boot-intro --theme-switch "$new_background" "$theme_id" "$intro_prepared"; then
+        if [[ $(readlink -f "$CURRENT_BACKGROUND_LINK") == "$(readlink -f "$new_background")" &&
+          $(stat -Lc '%d:%i' "$CURRENT_THEME_PATH" 2>/dev/null) == "$theme_id" ]]; then
+          shell_ipc background setInstant "$new_background" || true
+        fi
+      fi
+      shell_ipc shell finishThemeIntro "$theme_id" || true
+      wait_for_theme_intro themeIntroStatus "$theme_id" "pending"
+      # Reloading Hyprland interrupts video presentation. Wait for playback,
+      # then serialize with theme selection so an old intro cannot reload
+      # the compositor during the next theme's video.
+      (
+        flock 9
+        if [[ $(stat -Lc '%d:%i' "$CURRENT_THEME_PATH" 2>/dev/null) == "$theme_id" ]]; then
+          omarchy-restart-hyprctl
+        fi
+      ) 9>"$THEME_SET_LOCK"
+      [[ -z $OLD_BACKGROUND_SNAPSHOT ]] || rm -f "$OLD_BACKGROUND_SNAPSHOT"
+    ) 9>&- &
+    return
+  fi
  new_background_snapshot=""
  if [[ -n $PREPARED_BACKGROUND_SNAPSHOT && $PREPARED_BACKGROUND == "$new_background" ]]; then
    new_background_snapshot="$PREPARED_BACKGROUND_SNAPSHOT"
@@ -337,6 +383,12 @@ fi
 exec 9>"$THEME_SET_LOCK"
 flock 9

+# A current video frame only represents the screen after its opening fade.
+# Finish that short reveal before capturing the next outgoing cover.
+if [[ $THEME_HEADLESS != "1" && $OMARCHY_THEME_SKIP_BACKGROUND != "1" ]]; then
+  wait_for_theme_intro themeIntroStatus "$(stat -Lc '%d:%i' "$CURRENT_THEME_PATH" 2>/dev/null)" "pending"
+fi
+
 PREVIOUS_THEME_NAME=$(cat "$CURRENT_THEME_NAME_PATH" 2>/dev/null || true)
 remember_current_theme_background

@@ -365,11 +417,24 @@ OLD_BACKGROUND_SNAPSHOT=""
 PREPARED_BACKGROUND=""
 PREPARED_BACKGROUND_SNAPSHOT=""
 BACKGROUND_TRANSITION_SNAPSHOTS=true
+THEME_BACKGROUND_INTRO=""
+INTRO_PREPARE_PID=""
+THEME_INTRO_TOKEN=""
 if [[ $THEME_HEADLESS != "1" && $OMARCHY_THEME_SKIP_BACKGROUND != "1" ]]; then
  # Resolve the staged choice while the old theme still exists. Video changes
  # switch directly to the durable path in QML, so neither side needs a copy.
  if choose_staged_theme_background; then
-    if background_transition_uses_snapshots "$CHOSEN_THEME_BACKGROUND"; then
+    if [[ $PREVIOUS_THEME_NAME != "$THEME_NAME" && ! -f $HOME/.local/state/omarchy/toggles/background-intros-off ]] &&
+      [[ $(hyprctl -j getoption animations:enabled 2>/dev/null | jq -r '.bool') == "true" ]]; then
+      THEME_BACKGROUND_INTRO=$(omarchy-theme-bg-boot-intro --resolve-only "$STAGED_THEME_BACKGROUND")
+    fi
+    if [[ -n $THEME_BACKGROUND_INTRO ]]; then
+      OLD_BACKGROUND_SNAPSHOT=$(snapshot_current_background)
+      # OWE retains the opened clip across the staged directory's rename.
+      owe intro-prepare "$THEME_BACKGROUND_INTRO" >/dev/null 2>&1 9>&- &
+      INTRO_PREPARE_PID=$!
+      shell_ipc shell prepareThemeIntro "$OLD_BACKGROUND_SNAPSHOT" "$(stat -Lc '%d:%i' "$NEXT_THEME_PATH")" "" "" || true
+    elif background_transition_uses_snapshots "$CHOSEN_THEME_BACKGROUND"; then
      OLD_BACKGROUND_SNAPSHOT=$(snapshot_current_background)

      # Hand the shell the next background now, so it decodes while the
@@ -389,6 +454,12 @@ fi
 # Generate dynamic configs
 omarchy-theme-set-templates

+# Replacing the theme's still can cancel an active OWE intro even before the
+# background link changes. Present its cover before replacing either path.
+if [[ -n $THEME_BACKGROUND_INTRO ]]; then
+  wait_for_theme_intro themeIntroCoverStatus "$(stat -Lc '%d:%i' "$NEXT_THEME_PATH")" "loading"
+fi
+
 # Swap next theme in as current
 rm -rf "$CURRENT_THEME_PATH"
 mv "$NEXT_THEME_PATH" "$CURRENT_THEME_PATH"
@@ -418,7 +489,6 @@ flock -u 9

 post_theme_commands=(
  omarchy-restart-terminal
-  omarchy-restart-hyprctl
  omarchy-restart-btop
  omarchy-restart-opencode
  omarchy-restart-helix
@@ -437,6 +507,14 @@ post_theme_commands=(
 )

 if [[ $THEME_HEADLESS != "1" ]]; then
+  # Let the wallpaper and bar finish their reveal before app retints compete
+  # with decoding and the shell's frame rendering. An intro reloads Hyprland
+  # after playback; ordinary theme changes reload it with the app retints.
+  if [[ -n $THEME_INTRO_TOKEN ]]; then
+    wait_for_theme_intro themeIntroStatus "$THEME_INTRO_TOKEN" "pending"
+  else
+    post_theme_commands+=(omarchy-restart-hyprctl)
+  fi
  run_parallel "${post_theme_commands[@]}"

  # Call hook on theme set
@@ -11,6 +11,11 @@ hl.layer_rule({ match = { namespace = "omarchy-bar" }, no_anim = true, animation
 -- for normal open/close, and skip it for panel handoff.
 hl.layer_rule({ match = { namespace = "^(omarchy-menu|omarchy-image-selector|omarchy-emojis|omarchy-clipboard|omarchy-keyboard-panel|omarchy-osd|omarchy-reminders|omarchy-network-qr)$" }, no_anim = true, animation = "none" })

+-- A boot intro hands the desktop between OWE's video layer and the shell's
+-- background layer. The media fades itself, so a compositor fade on either
+-- layer only dips the screen toward the empty desktop during the handoff.
+hl.layer_rule({ match = { namespace = "^(omarchy-background|owe-background)$" }, no_anim = true, animation = "none" })
+
 -- Dev gallery is the main shell workbench; open it maximized like
 -- SUPER+ALT+F so component previews have the whole workspace.
 o.window({ class = "^org.quickshell$", title = "^Omarchy shell – dev gallery$" }, { maximize = true })
@@ -1,4 +1,12 @@
+require("default.hypr.startup-cursor")
+
 hl.on("hyprland.start", function()
+  -- Applications inherit the user's cursor; only the compositor starts blank.
+  if omarchy_startup_cursor_pending then
+    hl.env("XCURSOR_PATH", omarchy_startup_cursor.path)
+    hl.env("XCURSOR_THEME", omarchy_startup_cursor.xcursor)
+  end
+
  -- Slow app launch fix -- set systemd vars before starting session services.
  hl.exec_cmd("systemctl --user import-environment $(env | cut -d'=' -f 1)")
  hl.exec_cmd("dbus-update-activation-environment --systemd --all")
@@ -104,6 +104,7 @@ hl.config({
  misc = {
    disable_hyprland_logo = true,
    disable_splash_rendering = true,
+    background_color = "rgb(000000)",
    disable_scale_notification = true,
    focus_on_activate = true,
    anr_missed_pings = 3,
@@ -0,0 +1,46 @@
+-- Hyprland polls cursor.invisible, so its first frames need a blank cursor too.
+function omarchy_startup_cursor_restore(loaded)
+  if not omarchy_startup_cursor_pending then return end
+  local cursor = omarchy_startup_cursor
+  if loaded then
+    omarchy_startup_cursor_pending = false
+    hl.config({ cursor = cursor.config })
+    if cursor.config.enable_hyprcursor and cursor.hyprcursor then
+      hl.exec_cmd("hyprctl setcursor " .. o.shell_quote(cursor.hyprcursor) .. " " .. cursor.size)
+    end
+  elseif not cursor.restoring then
+    -- Reload the normal Xcursor fallback before enabling Hyprcursor or GSettings.
+    cursor.restoring = true
+    hl.exec_cmd("hyprctl setcursor " .. o.shell_quote(cursor.xcursor) .. " " .. cursor.size
+      .. " && hyprctl eval 'omarchy_startup_cursor_restore(true)'")
+  end
+end
+
+hl.on("config.reloaded", function()
+  if omarchy_startup_cursor_pending == nil then
+    -- Config updates in an existing compositor must not hide its pointer.
+    omarchy_startup_cursor_pending = #hl.get_monitors() == 0
+    if omarchy_startup_cursor_pending then
+      local hyprcursor = hl.get_config("cursor.enable_hyprcursor")
+      omarchy_startup_cursor = {
+        config = {
+          invisible = hl.get_config("cursor.invisible"),
+          enable_hyprcursor = hyprcursor,
+          sync_gsettings_theme = hl.get_config("cursor.sync_gsettings_theme"),
+        },
+        hyprcursor = os.getenv("HYPRCURSOR_THEME"),
+        size = tonumber((hyprcursor and os.getenv("HYPRCURSOR_SIZE")) or os.getenv("XCURSOR_SIZE")) or 24,
+        path = os.getenv("XCURSOR_PATH") or "~/.local/share/icons:~/.icons:/usr/share/icons:/usr/share/pixmaps",
+        xcursor = os.getenv("XCURSOR_THEME") or "default",
+      }
+      if omarchy_startup_cursor.size <= 0 then omarchy_startup_cursor.size = 24 end
+      hl.env("XCURSOR_PATH", os.getenv("OMARCHY_PATH") .. "/default/hypr/cursors:" .. omarchy_startup_cursor.path)
+      hl.env("XCURSOR_THEME", "omarchy-startup")
+    end
+  end
+  if omarchy_startup_cursor_pending then
+    -- Keep the temporary cursor private to the compositor, including GSettings.
+    hl.config({ cursor = { invisible = true, enable_hyprcursor = false, sync_gsettings_theme = false } })
+    hl.timer(function() omarchy_startup_cursor_restore() end, { timeout = 15000, type = "oneshot" })
+  end
+end)
@@ -53,6 +53,7 @@ hl.config({
  misc = {
    disable_hyprland_logo = true,
    disable_splash_rendering = true,
+    background_color = "rgb(000000)",
    force_default_wallpaper = 0,
  },

@@ -6,12 +6,11 @@ Omarchy themes live under `themes/<name>/` in the source tree (installed at
 `colors.toml`; Omarchy generates the active theme files from
 `default/themed/*.tpl` when `omarchy-theme-set <name>` runs.

-Beyond `colors.toml` and hand-written config overrides, a first-party theme can
-ship `backgrounds/` (users overlay their own via
-`~/.config/omarchy/backgrounds/<name>/`; the active image is the
-`~/.local/state/omarchy/current/background` symlink), `preview.png` and
-`preview-unlock.png` for the theme switcher, `icons.theme`, `keyboard.rgb`,
-`unlock.png`, and a `light.mode` marker file.
+Beyond `colors.toml` and hand-written config overrides, a first-party theme can ship `backgrounds/` (users overlay their own via `~/.config/omarchy/backgrounds/<name>/`; the active image is the `~/.local/state/omarchy/current/background` symlink), `preview.png` and `preview-unlock.png` for the theme switcher, `icons.theme`, `keyboard.rgb`, `unlock.png`, and a `light.mode` marker file.
+
+A theme can pair a still background with a silent intro video using matching filenames: `backgrounds/0-winding-road.webp` and `backgrounds/intros/0-winding-road.mp4`. The video plays automatically at login and when switching to that theme with this background selected. No registration, checksum file or manual setting is needed. Supported video extensions are `mp4`, `m4v`, `mov`, `webm`, `mkv` and `avi`. Intro videos stay inside the nested `intros/` directory so the background picker does not list them as looping wallpapers. An image selected from another directory looks for its intro in that directory's own `intros/`, so a same-named custom image cannot inherit a theme's video.
+
+Aim for a video between five and seven seconds long that opens on its scene setup and ends on the matching still. The shell provides the opening crossfade, so an added fade from black is unnecessary. OWE owns decoding, mute and the handoff back to that image. The theme picker prepares the highlighted theme's remembered intro offscreen, paused at its opening frame. OWE keeps one prepared clip and an idle renderer for up to one minute, then releases them. A theme switch also starts preparation while its templates render; OWE compares the selected video with the prepared clip before resuming it. Older OWE versions use the ordinary startup path. Hyprland and the SDDM greeter use a black compositor background. On a fresh login, the persistent shell host keeps an opaque black cover above the bar and wallpaper until the bar has loaded and OWE has a moving video frame, then fades both in together over 420 ms. Hyprland initializes with a transparent cursor so its visibility polling cannot expose a pointer in the first frames. The temporary Xcursor theme stays private to the compositor; applications inherit the normal cursor environment. The opening fade restores the selected cursor and settings. Shell restarts and a fifteen-second compositor timeout recover a cursor left hidden by an interrupted startup. With intros disabled or unavailable, it waits for the still to be ready instead. A ten-second deadline releases the cover if a missing wallpaper or failed plugin never becomes ready. Ordinary shell restarts preload the selected still alongside the bar without mapping that login cover. Login intros use the Hyprland instance signature, so logging out and back in plays the intro again. The launcher consumes the current session before waiting up to five seconds for OWE. Shell restarts and a daemon starting after that window cannot play a delayed intro. Theme switches synchronize OWE with the selected image and use its first-frame start mode. An interrupted video supplies its currently playing frame as the outgoing snapshot. Rapid selections wait for the previous opening fade to finish before capturing it. Theme replacement and playback wait for the outgoing cover to decode and reach the compositor on every screen. A persistent layer holds that outgoing wallpaper until OWE hides the shell background and reports a ready video with an advancing playback position and no outgoing still transition, then crossfades it over 420 ms while applying the new bar palette. The shell retains its background service and decoded wallpaper while it is hidden, so handing the still back does not recreate them. App retints wait until the opening crossfade completes, with a three-second bound, so they do not compete with its first frames. The compositor reload waits until playback finishes because reloading Hyprland pauses video presentation. A superseded intro skips that reload. Failed playback releases the pending palette, and a newer theme invalidates the older handoff. Refreshing a theme, headless setup, and cycling backgrounds within the same theme do not trigger intros. Toggle > Animations suppresses playback along with the other animations. The `omarchy theme bg intro toggle` command can toggle intros separately.

 A theme installed from a git repo is held to a much shorter list; see [What an installed theme may not ship](#what-an-installed-theme-may-not-ship).

@@ -0,0 +1,4 @@
+[Service]
+# Let start-hyprland stop the compositor before killing its shell clients.
+# Sending SIGTERM to the whole group removes the wallpaper during teardown.
+KillMode=mixed
@@ -6,6 +6,10 @@ You can do this most easily by going to _Install > Style > Background_ in the Om

 Backgrounds can be videos as well as stills. Drop an `mp4`, `m4v`, `mov`, `webm`, `mkv`, or `avi` file in the same folder and it appears alongside the images. Videos are played by the OWE wallpaper engine. It decodes the video once for all monitors and plays its sound through the default audio output, and it stops playback whenever nothing can see it. The lock screen draws the same decode, muted, through OWE. A video wallpaper still costs far more power than a still one.

+Themes can include a short intro for a still background. For `backgrounds/road.webp`, the matching video lives at `backgrounds/intros/road.mp4`. It plays automatically at boot and when switching to a theme with that background selected, then returns to the still. Intro videos stay out of the background picker and never loop.
+
+Turning off _Toggle > Animations_ also turns off background intros. Omarchy does this by default in a virtual machine. The `omarchy theme bg intro toggle` command can toggle intros separately. Refreshing a theme or choosing another background within the same theme does not play an intro.
+
 You can find a huge collection of cool curated backgrounds on https://github.com/dharmx/walls.

 Video backgrounds keep a cached still on the lock screen while playback is paused or unavailable. Animated GIFs play on the desktop and show a still frame on the lock screen.
@@ -0,0 +1,26 @@
+echo "Re-stage the active theme with packaged intro videos"
+
+theme_name_path="$HOME/.local/state/omarchy/current/theme.name"
+
+[[ -s $theme_name_path ]] || exit 0
+
+theme_name=$(<"$theme_name_path")
+[[ $theme_name =~ ^[[:alnum:]_][[:alnum:].+_-]*$ ]] || exit 0
+[[ -d $OMARCHY_PATH/themes/$theme_name/backgrounds/intros ]] || exit 0
+
+omarchy-theme-refresh
+
+state_dir="$HOME/.local/state/omarchy"
+marker="$state_dir/background-intro.session-id"
+session_id=${OMARCHY_SESSION_ID:-${HYPRLAND_INSTANCE_SIGNATURE:-}}
+if [[ -z $session_id ]]; then
+  hypr_dir=$(find "${XDG_RUNTIME_DIR:-/run/user/$UID}/hypr" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\n' 2>/dev/null | sort -n | tail -n 1 | cut -d' ' -f2- || true)
+  session_id=${hypr_dir##*/}
+fi
+[[ -n $session_id ]] || exit 0
+mkdir -p "$state_dir"
+marker_staged=$(mktemp "$state_dir/.background-intro.session-id.XXXXXX")
+trap 'rm -f "$marker_staged"' EXIT
+printf '%s\n' "$session_id" >"$marker_staged"
+mv -f "$marker_staged" "$marker"
+trap - EXIT
@@ -11,6 +11,7 @@ Item {
  id: root

  property var shell: null
+  property bool suspended: false
  readonly property string home: Quickshell.env("HOME")
  readonly property string stateHome: home + "/.local/state"
  readonly property string currentBackgroundLink: stateHome + "/omarchy/current/background"
@@ -37,11 +38,20 @@ Item {
  property var sizeQueue: []
  property bool finishingTransition: false
  property int backgroundVersion: 0
+  property int reloadVersion: 0
  property int revealStartedVersion: -1
  property int pendingThemeVersion: -1
  property string pendingColorsRaw: ""
  property string pendingShellRaw: ""
  property real revealProgress: 1
+  readonly property bool ready: {
+    if (isVideo(displayedBackground)) return true
+    if (backgrounds.instances.length === 0) return false
+    for (var panel of backgrounds.instances) {
+      if (!panel.backgroundReady) return false
+    }
+    return true
+  }

  function isVideo(path) {
    return Util.isVideoPath(path)
@@ -56,7 +66,8 @@ Item {
  }

  function setBackground(path, instant) {
-    transitionBackground("", path, path, instant, false)
+    if (instant) reloadVersion += 1
+    transitionBackground("", path, path, instant, instant)
  }

  function transitionBackground(fromPath, path, finalPath, instant, force) {
@@ -223,6 +234,10 @@ Item {
      root.setBackground(path, true)
    }

+    function setSuspended(value: string): void {
+      root.suspended = value === "true"
+    }
+
    function transition(fromPath: string, path: string): void {
      root.transitionBackground(fromPath, path, path, false, false)
    }
@@ -259,7 +274,7 @@ Item {
    from: 0
    to: 1
    duration: Style.duration(420)
-    easing.type: Easing.InOutCubic
+    easing.type: Easing.OutCubic
    onFinished: {
      if (root.incomingBackground) {
        root.displayedBackground = root.currentBackground || root.incomingBackground
@@ -272,6 +287,7 @@ Item {
  Component.onCompleted: refreshBackground()

  Variants {
+    id: backgrounds
    model: Quickshell.screens

    PanelWindow {
@@ -279,7 +295,7 @@ Item {
      required property var modelData

      screen: modelData
-      visible: !remapGuard.remapping
+      visible: !remapGuard.remapping && !root.suspended
      anchors { top: true; bottom: true; left: true; right: true }

      ScreenMoveRemap {
@@ -294,6 +310,13 @@ Item {
      updatesEnabled: true

      property bool maskReady: false
+      property int readyFrames: 0
+      readonly property bool backgroundReady: base.ready && readyFrames >= 2
+
+      FrameAnimation {
+        running: base.ready && panel.readyFrames < 2
+        onTriggered: panel.readyFrames += 1
+      }

      // Decode the wallpaper at the size this screen can show, not the size
      // it was shipped at. With PreserveAspectCrop Qt takes sourceSize as the
@@ -337,9 +360,12 @@ Item {
        id: base
        anchors.fill: parent
        path: root.displayedBackground
+        version: root.reloadVersion
+        cached: true
        constrainDecode: true
        decodeSize: panel.decodeSize(root.displayedBackground)
        onReadyChanged: {
+          panel.readyFrames = 0
          if (ready && root.finishingTransition) {
            root.incomingBackground = ""
            root.oldBackground = ""
@@ -80,9 +80,9 @@ Item {
  property color background: Color.bar.background
  property color urgent: Color.bar.active

-  Behavior on barForeground { enabled: root.foregroundAnimationEnabled; ColorAnimation { duration: Style.duration(420); easing.type: Easing.InOutCubic } }
-  Behavior on background { ColorAnimation { duration: Style.duration(420); easing.type: Easing.InOutCubic } }
-  Behavior on urgent { ColorAnimation { duration: Style.duration(420); easing.type: Easing.InOutCubic } }
+  Behavior on barForeground { enabled: root.foregroundAnimationEnabled; ColorAnimation { duration: Style.duration(420); easing.type: Easing.OutCubic } }
+  Behavior on background { ColorAnimation { duration: Style.duration(420); easing.type: Easing.OutCubic } }
+  Behavior on urgent { ColorAnimation { duration: Style.duration(420); easing.type: Easing.OutCubic } }
  property var tooltipTarget: null
  property var pendingTooltipTarget: null
  property string tooltipText: ""
@@ -274,7 +274,29 @@ Item {
  property var imageArray: []
  readonly property var matchingImageIndices: ImagePickerModel.matchingIndices(imageArray, filterText)
  onMatchingImageIndicesChanged: updateVisibleItems()
-  onSelectedIndexChanged: updateVisibleItems()
+  onSelectedIndexChanged: {
+    updateVisibleItems()
+    introPrepareTimer.restart()
+  }
+  onThemeModeChanged: if (themeMode) introPrepareTimer.restart()
+
+  Timer {
+    id: introPrepareTimer
+    interval: 75
+    onTriggered: {
+      if (root.opened && root.themeMode && !introPrepare.running) {
+        introPrepare.theme = root.nameForPath(root.currentPath())
+        introPrepare.command = ["omarchy-theme-bg-boot-intro", "--prepare-theme", root.nameForPath(root.currentPath())]
+        introPrepare.running = true
+      }
+    }
+  }
+
+  Process {
+    id: introPrepare
+    property string theme: ""
+    onExited: if (root.opened && root.themeMode && theme !== root.nameForPath(root.currentPath())) introPrepareTimer.restart()
+  }

  function updateVisibleItems() {
    ImagePickerModel.syncWindow(visibleImages, ImagePickerModel.visibleWindow(matchingImageIndices, selectedIndex, previewRadius))
@@ -0,0 +1,329 @@
+import QtQuick
+import Quickshell
+import Quickshell.Wayland
+import Quickshell.Io
+import qs.Commons
+
+// Keep startup and theme covers alive across background service handoffs.
+Item {
+  id: root
+
+  property var host: null
+  property bool cover: true
+  readonly property bool sessionConsumed: String(sessionMarker.text() || "").trim() === (Quickshell.env("OMARCHY_SESSION_ID") || Quickshell.env("HYPRLAND_INSTANCE_SIGNATURE"))
+  property bool startupSettled: sessionConsumed
+  property bool startupPending: !sessionConsumed
+  property bool startupMediaReady: false
+  property real startupOpacity: startupPending ? 1 : 0
+  readonly property bool desktopReady: !host || (!host.pluginReloading && (!host.pluginRegistry || !host.pluginRegistry.scanning) && (!("bar" in host) || !!host.bar))
+  property bool checked: false
+  property string themeToken: ""
+  property string transitionToken: ""
+  readonly property string startupBackgroundPath: Quickshell.env("OMARCHY_STARTUP_BACKGROUND")
+  property string themeBackground: sessionConsumed && !Util.isVideoPath(startupBackgroundPath) ? startupBackgroundPath : ""
+  property var themeNativeSize: null
+  property string themeColors: ""
+  property string themeShell: ""
+  property real themeOpacity: 1
+  readonly property var backgroundService: host && host.services ? host.firstPartyServiceFor("omarchy.background") : null
+  readonly property bool backgroundActive: !!backgroundService && !backgroundService.suspended
+  readonly property bool backgroundReady: backgroundActive && backgroundService.ready !== false
+
+  function restoreStartupCursor() {
+    Quickshell.execDetached(["hyprctl", "eval", "if omarchy_startup_cursor_restore then omarchy_startup_cursor_restore() end"])
+  }
+
+  function finishStartup() {
+    if (!cover || !startupSettled) return
+    var registry = host ? host.pluginRegistry : null
+    var backgroundId = registry ? registry.resolveEnabledId("omarchy.background") : ""
+    var disabled = registry && registry.installedPlugins[backgroundId] && !registry.isEnabled(backgroundId)
+    if (!backgroundReady && !disabled) return
+    cover = false
+    if (!themeToken) themeBackground = ""
+    startupMediaReady = true
+    revealStartup()
+  }
+
+  function revealStartup() {
+    if (!startupPending || startupFade.running || !startupMediaReady || !desktopReady) return
+    if (!startupCovers.instances.length) return
+    for (var panel of startupCovers.instances)
+      if (panel.readyFrames < 2) return
+    startupFade.start()
+  }
+
+  onDesktopReadyChanged: revealStartup()
+  onBackgroundReadyChanged: finishStartup()
+  Connections {
+    target: root.host && root.host.pluginRegistry ? root.host.pluginRegistry : null
+    function onPluginsChanged() { root.finishStartup() }
+  }
+
+  function prepareTheme(fromPath, token, colors, shell) {
+    framePoll.stop()
+    themeFade.stop()
+    themeToken = token
+    transitionToken = token
+    if (themeBackground !== fromPath) {
+      themeNativeSize = backgroundService && backgroundService.nativeSizes ? backgroundService.nativeSizes[backgroundService.displayedBackground] : null
+    }
+    themeBackground = fromPath
+    themeColors = colors
+    themeShell = shell
+    themeOpacity = 1
+    themeFallback.restart()
+  }
+
+  function revealTheme() {
+    if (!themeToken && !cover) return
+    framePoll.stop()
+    themeFallback.stop()
+    if (themeToken) {
+      Color.loadColors(Util.decodeBase64(themeColors))
+      Color.loadShell(Util.decodeBase64(themeShell))
+      Style.scheduleRefresh()
+    }
+    cover = false
+    themeToken = ""
+    themeColors = ""
+    themeShell = ""
+    if (startupPending) {
+      // The login reveal starts on moving video, without showing its final still.
+      themeBackground = ""
+      startupMediaReady = true
+      revealStartup()
+    } else {
+      themeFade.restart()
+    }
+  }
+
+  function finishTheme(token) {
+    if (token === themeToken) revealTheme()
+  }
+
+  function themeStatus(token) {
+    return token === transitionToken && (themeToken || themeFade.running || startupFade.running) ? "pending" : "ready"
+  }
+
+  function themeCoverStatus(token) {
+    if (token !== themeToken) return "superseded"
+    if (!themeBackground) return "ready"
+    for (var panel of covers.instances) {
+      if (panel.coverFailed) return "error"
+      if (!panel.coverReady) return "loading"
+    }
+    return covers.instances.length > 0 ? "ready" : "loading"
+  }
+
+  function cancelTheme() {
+    framePoll.stop()
+    themeFallback.stop()
+    themeFade.stop()
+    themeToken = ""
+    transitionToken = ""
+    themeBackground = ""
+    themeColors = ""
+    themeShell = ""
+  }
+
+  NumberAnimation {
+    id: startupFade
+    target: root
+    property: "startupOpacity"
+    to: 0
+    duration: Style.duration(420)
+    easing.type: Easing.OutCubic
+    onStarted: root.restoreStartupCursor()
+    onFinished: root.startupPending = false
+  }
+
+  // A missing wallpaper or failed plugin must not leave applications hidden.
+  Timer {
+    interval: 10000
+    running: root.startupPending
+    onTriggered: {
+      root.cover = false
+      if (!root.themeToken) root.themeBackground = ""
+      root.startupMediaReady = true
+      startupFade.start()
+    }
+  }
+
+  NumberAnimation {
+    id: themeFade
+    target: root
+    property: "themeOpacity"
+    to: 0
+    duration: Style.duration(420)
+    easing.type: Easing.OutCubic
+    onFinished: root.themeBackground = ""
+  }
+
+  Timer {
+    id: themeFallback
+    interval: 10000
+    onTriggered: root.revealTheme()
+  }
+
+  // A renderer left over from another intro can first fade from its still.
+  // Keep that preparation hidden until the actual video is fully revealed.
+  Timer {
+    id: framePoll
+    interval: 16
+    repeat: true
+    onTriggered: if (!frameStatus.running) frameStatus.running = true
+  }
+
+  Process {
+    id: frameStatus
+    command: ["owe", "render-status"]
+    property string token: ""
+    onStarted: token = root.themeToken
+    stdout: StdioCollector { id: frameStatusOut }
+    onExited: function(exitCode) {
+      if (exitCode !== 0 || token !== root.themeToken || (!token && !root.cover)) return
+      try {
+        var status = JSON.parse(frameStatusOut.text)
+        if (status.kind === "video" && status.ready && !status.has_transition && status.time_pos > 0)
+          root.revealTheme()
+      } catch (e) {}
+    }
+  }
+
+  // A shell restart shares this compositor session; a new login does not.
+  FileView {
+    id: sessionMarker
+    path: Quickshell.env("HOME") + "/.local/state/omarchy/background-intro.session-id"
+    blockLoading: true
+    watchChanges: false
+    printErrors: false
+  }
+
+  Process {
+    id: startupBackground
+    command: ["readlink", "-f", Quickshell.env("HOME") + "/.local/state/omarchy/current/background"]
+    stdout: StdioCollector { id: startupBackgroundOut }
+    onExited: function(exitCode) {
+      var path = String(startupBackgroundOut.text || "").trim()
+      if (exitCode === 0 && root.cover && !root.startupPending && !root.themeToken && !Util.isVideoPath(path))
+        root.themeBackground = path
+    }
+  }
+
+  Component.onCompleted: {
+    checked = true
+    if (sessionConsumed) restoreStartupCursor()
+    if (!startupBackgroundPath && !startupPending) startupBackground.running = true
+    introProc.running = true
+  }
+
+  Component.onDestruction: if (startupPending) restoreStartupCursor()
+
+  onBackgroundActiveChanged: {
+    if (!backgroundActive && checked) {
+      if (cover || themeToken) {
+        framePoll.start()
+        if (!frameStatus.running) frameStatus.running = true
+      }
+    }
+  }
+
+  // Cover the bar as well as the wallpaper on a new login. Shell restarts
+  // retain the current desktop and never map this startup cover.
+  Variants {
+    id: startupCovers
+    model: Quickshell.screens
+
+    PanelWindow {
+      required property var modelData
+      property int readyFrames: 0
+      screen: modelData
+      visible: root.startupPending
+      color: "transparent"
+      mask: Region {}
+      anchors { top: true; bottom: true; left: true; right: true }
+      exclusionMode: ExclusionMode.Ignore
+      WlrLayershell.layer: WlrLayer.Overlay
+      WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
+      WlrLayershell.namespace: "omarchy-background"
+
+      Rectangle {
+        anchors.fill: parent
+        color: "black"
+        opacity: root.startupOpacity
+      }
+
+      FrameAnimation {
+        running: root.startupPending && root.desktopReady && readyFrames < 2
+        onTriggered: {
+          readyFrames += 1
+          if (readyFrames === 2) root.revealStartup()
+        }
+      }
+    }
+  }
+
+  Variants {
+    id: covers
+    model: Quickshell.screens
+
+    PanelWindow {
+      id: panel
+      required property var modelData
+      property int coverFrames: 0
+      readonly property bool coverReady: outgoingFrame.status === Image.Ready && coverFrames >= 2
+      readonly property bool coverFailed: outgoingFrame.status === Image.Error
+      screen: modelData
+      visible: (!root.startupPending && root.cover) || root.themeBackground !== ""
+      // Keep the window transparent throughout the fade. Paint the startup
+      // color inside it so changing the window format cannot flash black.
+      color: "transparent"
+      mask: Region {}
+      anchors { top: true; bottom: true; left: true; right: true }
+      exclusionMode: ExclusionMode.Ignore
+      WlrLayershell.layer: WlrLayer.Bottom
+      WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
+      WlrLayershell.namespace: "omarchy-background"
+
+      Rectangle {
+        anchors.fill: parent
+        visible: root.cover
+        color: Color.background
+      }
+
+      Image {
+        id: outgoingFrame
+        anchors.fill: parent
+        source: root.themeBackground ? Util.fileUrl(root.themeBackground) : ""
+        sourceSize: {
+          var w = Math.ceil((parent.width || modelData.width) * modelData.devicePixelRatio)
+          var h = Math.ceil((parent.height || modelData.height) * modelData.devicePixelRatio)
+          var native = root.themeNativeSize
+          return native && (native.width < w || native.height < h) ? Qt.size(native.width, native.height) : Qt.size(w, h)
+        }
+        fillMode: Image.PreserveAspectCrop
+        opacity: root.themeOpacity
+        // Start decoding while the remaining theme configs render.
+        asynchronous: true
+        onStatusChanged: panel.coverFrames = 0
+      }
+
+      // Give the ready image a frame to reach the compositor before OWE
+      // releases the shell's wallpaper underneath this cover.
+      FrameAnimation {
+        running: outgoingFrame.status === Image.Ready && panel.coverFrames < 2
+        onTriggered: panel.coverFrames += 1
+      }
+    }
+  }
+
+  Process {
+    id: introProc
+    command: ["omarchy-theme-bg-boot-intro"]
+    onExited: {
+      root.startupSettled = true
+      root.finishStartup()
+    }
+  }
+}
@@ -21,6 +21,7 @@ ShellRoot {
  property BarWidgetRegistry barWidgetRegistry: BarWidgetRegistry { }
  property AppLibrary appLibrary: AppLibrary { }
  property BrightnessKeys brightnessKeys: BrightnessKeys { host: shell }
+  property BackgroundIntro bootIntro: BackgroundIntro { host: shell }

  property string home: Quickshell.env("HOME")

@@ -1704,6 +1705,7 @@ ShellRoot {
    function ping(): string {
      return "ok"
    }
+
  }

  // ---------------------------------------------------------- shell IPC
@@ -1711,11 +1713,34 @@ ShellRoot {
  ShellIpc {
    target: "shell"

+    function prepareThemeIntro(fromPath: string, token: string, colorsB64: string, shellB64: string): void {
+      shell.bootIntro.prepareTheme(fromPath, token, colorsB64, shellB64)
+    }
+
+    function finishThemeIntro(token: string): void {
+      shell.bootIntro.finishTheme(token)
+    }
+
+    function themeIntroStatus(token: string): string {
+      return shell.bootIntro.themeStatus(token)
+    }
+
+    function themeIntroCoverStatus(token: string): string {
+      return shell.bootIntro.themeCoverStatus(token)
+    }
+
    function ping(): string {
      return "ok"
    }

    function applyTheme(colorsB64: string, shellB64: string): string {
+      if (shell.bootIntro) shell.bootIntro.cancelTheme()
+      var background = shell.firstPartyServiceFor("omarchy.background")
+      if (background && typeof background.setPendingTheme === "function" && typeof background.applyPendingTheme === "function") {
+        background.setPendingTheme(colorsB64, shellB64)
+        background.applyPendingTheme()
+        return "ok"
+      }
      var colorsRaw = ""
      var shellRaw = ""
      try { colorsRaw = Qt.atob(String(colorsB64 || "")) } catch (e) { colorsRaw = "" }
@@ -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"
@@ -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"
@@ -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"
@@ -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"
@@ -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"
@@ -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"
@@ -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"
@@ -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()
+      }
+    }
+  }
+}
@@ -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 }))
+      }
+    }
+  }
+}
@@ -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()
+    }
+  }
+}
@@ -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()
+    }
+  }
+}
@@ -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()
+    }
+  }
+}
@@ -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()
+    }
+  }
+}
@@ -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"))
@@ -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")
+}
@@ -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"
@@ -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"
@@ -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"
@@ -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"
@@ -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'],
@@ -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"
@@ -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=""