Add a Gaming page, and let the desktop react to games

Live first, because unlike every other page here this one has a live
dimension: card temperature, power draw, whether Game Mode actually
engaged. It polls only while it is open, since a settings page nobody is
looking at has no business waking the CPU.

The part that makes it Panama's page rather than a gamemode config
editor is the hook. gamemode runs a script when a game asks for it and
another when the game exits, so the power profile switches to
performance and notifications go quiet for exactly the duration of a
game -- and afterwards both go back to what they WERE, not to a default.
A Do Not Disturb someone set by hand survives a game; a power profile
someone chose is restored rather than replaced. Verified against real
gamemode activation, not merely by calling the hook.

Two things the page reports rather than hides. Game Mode's headline
trick is switching the CPU governor to performance, and this machine
already runs performance, so it says so instead of implying it helps.
And Proton builds are listed but never chosen: Steam picks the runtime
per game, and a control here would claim an authority this page does not
have.

The hook first called a notifications function that did not exist, and
the one that did was a TOGGLE -- the wrong primitive entirely, since
toggling at game start would unsilence notifications that were already
silent. The shell gained an explicit setter and reader.

search-routing-contract kept its own hand-written list of every page,
which made adding one fail as "not a known page" -- a sixth place to
register a page and a sixth chance to forget. It now derives the mapping
from the shell, which already knows it.

Claude-Session: https://claude.ai/code/session_01BRvzt4H8XXLPVH5MyYdk9L

tests/quickshell/gaming-contract.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+
+# What Panama does while a game runs must be undone afterwards -- to what was
+# there before, not to a default.
+#
+# That distinction is the whole feature. If ending a game forced Do Not Disturb
+# off, it would silently undo a Do Not Disturb someone set by hand; if it forced
+# the power profile to "balanced", it would undo a deliberate choice. Both are
+# worse than doing nothing at all, because both look like the desktop
+# misbehaving rather than a setting being wrong.
+#
+# Read-only: it reads gaming state and never engages Game Mode.
+
+set -uo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+helper="$repo_dir/config/dot/quickshell/scripts/panama-gaming"
+service="$repo_dir/config/dot/quickshell/services/Gaming.qml"
+page="$repo_dir/config/dot/quickshell/modules/settings/GamingPage.qml"
+shell_file="$repo_dir/config/dot/quickshell/shell.qml"
+
+fail() {
+    printf 'gaming contract: %s\n' "$1" >&2
+    exit 1
+}
+
+for path in "$helper" "$service" "$page" "$shell_file"; do
+    [[ -r "$path" ]] || fail "missing $path"
+done
+[[ -x "$helper" ]] || fail 'panama-gaming is not executable'
+
+# ── The hook restores, it does not impose ───────────────────────────────────
+hook_body="$(sed -n '/^def hook/,/^def /p' "$helper")"
+[[ -n "$hook_body" ]] || fail 'the hook is missing'
+grep -q 'state_path' <<<"$hook_body" \
+    || fail 'the hook records nothing about the state before a game, so it cannot restore it'
+grep -qE 'before\.get\("profile"\)' <<<"$hook_body" \
+    || fail 'the power profile is not restored to what it was'
+grep -q 'before.get("silenced") is False' <<<"$hook_body" \
+    || fail 'Do Not Disturb is cleared unconditionally, which would undo one the user set themselves'
+grep -qE 'set.*"balanced"' <<<"$hook_body" \
+    && fail 'the hook restores a hardcoded profile rather than the previous one'
+
+# ── The shell can be told, not only toggled ─────────────────────────────────
+# A toggle is the wrong primitive here: if notifications were already silenced,
+# toggling at game start would unsilence them.
+grep -q 'function setDnd(enabled: bool)' "$shell_file" \
+    || fail 'there is no explicit way to set Do Not Disturb, only a toggle'
+grep -q 'function dndState()' "$shell_file" \
+    || fail 'there is no way to read Do Not Disturb, so the hook cannot know what to restore'
+grep -qE '"notifications",\s*$' <<<"$(grep -A1 'qs", "ipc", "call"' "$helper")" >/dev/null 2>&1 || true
+grep -q '"setDnd"' "$helper" \
+    || fail 'the hook does not use the explicit setter'
+
+# ── The hook does not depend on the shell being up ──────────────────────────
+# A game can start after a shell restart; a hook that asked the shell for its
+# settings would silently do nothing.
+grep -q 'settings.json' <<<"$hook_body" \
+    || fail 'the hook reads its settings from somewhere other than the settings file'
+
+# ── Honest reporting ────────────────────────────────────────────────────────
+grep -q 'governorAlreadyThere' "$service" \
+    || fail 'the service cannot tell when Game Mode would change nothing'
+page_code="$(grep -vE '^\s*//' "$page")"
+grep -q 'already runs that governor' <<<"$page_code" \
+    || fail 'the page does not say when Game Mode has no effect on this machine'
+# Proton is listed, never chosen: Steam owns that per game.
+grep -qiE 'setProton|selectProton|chooseProton' <<<"$page_code" \
+    && fail 'the page claims to choose the Proton build, which Steam owns per game'
+
+# ── Polling stops when nobody is looking ────────────────────────────────────
+grep -q 'running: root.watching' "$service" \
+    || fail 'the poll timer runs regardless of whether the page is open'
+grep -q 'Gaming.watching = false' "$page" \
+    || fail 'the page never stops the poll timer, so it would poll forever after being closed'
+
+command -v jq >/dev/null 2>&1 || { printf 'gaming contract: SKIP (no jq)\n'; exit 0; }
+
+state="$("$helper" snapshot 2>/dev/null)" || fail 'snapshot failed'
+jq -e '(.gpus | type == "array") and (.gameMode | type == "object") and (.library | type == "object")' \
+    <<<"$state" >/dev/null || fail 'the snapshot is incomplete'
+jq -e '.gameMode | has("active") and has("daemonRunning") and has("hooksInstalled")' <<<"$state" >/dev/null \
+    || fail 'Game Mode state is incomplete'
+# An integrated GPU reporting no video memory must not be described as discrete.
+jq -e '[.gpus[] | select(.discrete) | .vramTotalBytes > 0] | all' <<<"$state" >/dev/null \
+    || fail 'a card with no video memory is reported as the discrete one'
+
+[[ -n "$("$helper" set-overlay-preset nonsense 2>/dev/null | jq -r '.error // ""')" ]] \
+    || fail 'an unknown overlay preset was accepted'
+[[ -n "$("$helper" hook nonsense 2>/dev/null | jq -r '.error // ""')" ]] \
+    || fail 'an unknown hook phase was accepted'
+
+printf 'gaming contract: PASS (%s GPU(s), %s games, hooks %s)\n' \
+    "$(jq '.gpus | length' <<<"$state")" \
+    "$(jq -r '.library.games' <<<"$state")" \
+    "$(jq -r 'if .gameMode.hooksInstalled then "installed" else "not installed" end' <<<"$state")"

tests/quickshell/search-routing-contract.sh

@@ -25,6 +25,7 @@ repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 schema="$repo_dir/config/dot/quickshell/config/PreferenceSchema.qml"
 search="$repo_dir/config/dot/quickshell/services/SettingsSearch.qml"
 pages_dir="$repo_dir/config/dot/quickshell/modules/settings"
+shell_file="$pages_dir/SettingsShell.qml"
 
 fail() {
     printf 'search routing contract: %s\n' "$1" >&2
@@ -36,29 +37,23 @@ routes="$(grep -oE '"[a-zA-Z]+": "[a-z-]+"' "$search" | tr -d '"' | tr ':' ' ')"
 
 # page id -> Page component file, as SettingsShell maps them.
 page_file() {
-    case "$1" in
-        home) printf 'HomePage.qml' ;;
-        appearance) printf 'AppearancePage.qml' ;;
-        displays) printf 'DisplaysPage.qml' ;;
-        connectivity) printf 'ConnectivityPage.qml' ;;
-        home-phone) printf 'HomePhonePage.qml' ;;
-        desktop) printf 'DesktopPage.qml' ;;
-        sound) printf 'SoundPage.qml' ;;
-        notifications) printf 'NotificationsPage.qml' ;;
-        screen-intelligence) printf 'ScreenIntelligencePage.qml' ;;
-        shortcuts) printf 'ShortcutsPage.qml' ;;
-        mouse) printf 'MousePage.qml' ;;
-        privacy) printf 'PrivacyPage.qml' ;;
-        region) printf 'RegionPage.qml' ;;
-        accounts) printf 'OnlineAccountsPage.qml' ;;
-        accessibility) printf 'AccessibilityPage.qml' ;;
-        power) printf 'PowerPage.qml' ;;
-        datetime) printf 'DateTimePage.qml' ;;
-        applications) printf 'ApplicationsPage.qml' ;;
-        services) printf 'HealthPage.qml' ;;
-        about) printf 'AboutPage.qml' ;;
-        *) printf '' ;;
-    esac
+    # Derived from SettingsShell rather than restated here. This was a
+    # hand-written list of every page, which meant adding one made this contract
+    # fail with "not a known page" -- a sixth place to register a page, and the
+    # sixth chance to forget. The shell already maps page -> component id and
+    # component id -> type, and the type names its file.
+    local page="$1" component type
+    component="$(grep -oE "case \"$page\": return [a-zA-Z]+;" "$shell_file" \
+        | sed -E 's/.*return ([a-zA-Z]+);/\1/' | head -1)"
+    if [[ -z "$component" ]]; then
+        # Home is the switch's default arm rather than a case.
+        [[ "$page" == "home" ]] || { printf ''; return; }
+        component="homePage"
+    fi
+    type="$(grep -oE "Component \{ id: $component; [A-Za-z]+ \{\} \}" "$shell_file" \
+        | sed -E 's/.*; ([A-Za-z]+) \{\} \}/\1/' | head -1)"
+    [[ -n "$type" ]] || { printf ''; return; }
+    printf '%s.qml' "$type"
 }
 
 violations=0