From a0c15941ed077d56ccaaafb41249e1b2fc34df6c Mon Sep 17 00:00:00 2001
From: Ry2X <45420571+ry2x@users.noreply.github.com>
Date: Wed, 19 Aug 2026 01:01:55 +0900
Subject: [PATCH 1/2] refactor: add comments and clear purpose

---
 src/stores/application/appLauncher.ts         | 10 ++-
 src/stores/application/applicationCatalog.ts  | 24 ++++++-
 src/stores/application/applicationHistory.ts  | 23 ++++++
 src/widget/app-launcher/index.tsx             | 72 ++++++-------------
 src/widget/app-launcher/widget/AppItem.tsx    | 23 +++---
 src/widget/app-launcher/widget/AppList.tsx    | 26 ++++---
 .../widget/LauncherBackground.tsx             | 22 ++++++
 .../app-launcher/widget/SearchGoogleBtn.tsx   | 13 ++--
 .../app-launcher/widget/SearchInput.tsx       |  8 ++-
 9 files changed, 142 insertions(+), 79 deletions(-)
 create mode 100644 src/widget/app-launcher/widget/LauncherBackground.tsx

diff --git a/src/stores/application/appLauncher.ts b/src/stores/application/appLauncher.ts
index 170cfb9..a5ec3d9 100644
--- a/src/stores/application/appLauncher.ts
+++ b/src/stores/application/appLauncher.ts
@@ -4,15 +4,21 @@ import Apps from 'gi://AstalApps';
 
 import {searchApps} from '@/stores/application/applicationCatalog';
 
-export interface AppLauncherState {
+/** Reactive state used by the application launcher's search UI. */
+export interface AppSearchTextState {
+  /** Current search text. */
   text: Accessor<string>;
+  /** Updates the search text. */
   setText: Setter<string>;
+  /** Index of the currently selected result. */
   selectedIndex: Accessor<number>;
+  /** Updates the selected result index. */
   setSelectedIndex: Setter<number>;
+  /** Applications matching the current search text. */
   results: Accessor<Apps.Application[]>;
 }
 
-export function createAppLauncherState(): AppLauncherState {
+export function createAppSearchTextState(): AppSearchTextState {
   const [text, setText] = createState('');
   const [selectedIndex, setSelectedIndex] = createState(0);
   const results = createComputed(() => searchApps(text().trim().toLowerCase()));
diff --git a/src/stores/application/applicationCatalog.ts b/src/stores/application/applicationCatalog.ts
index f72008f..5b7de3b 100644
--- a/src/stores/application/applicationCatalog.ts
+++ b/src/stores/application/applicationCatalog.ts
@@ -10,6 +10,13 @@ function getResultKey(application: Apps.Application) {
   return application.name + (application.description || '') + (application.iconName || '');
 }
 
+/**
+ * Filters the provided list of applications to ensure that only unique applications are returned,
+ * based on their name, description, and icon name.
+ * The results are limited to a maximum number of entries defined by MAX_APP_RESULTS.
+ * @param applicationList The list of applications to filter for uniqueness.
+ * @returns A list of unique applications, limited to MAX_APP_RESULTS.
+ */
 function getUniqueResults(applicationList: Apps.Application[]) {
   const results: Apps.Application[] = [];
   const seen = new Set<string>();
@@ -26,7 +33,7 @@ function getUniqueResults(applicationList: Apps.Application[]) {
   return results;
 }
 
-function getApplicationList() {
+function getSortedAppList() {
   return applications.get_list().sort((applicationA, applicationB) => {
     const scoreA = history.getScore(applicationA);
     const scoreB = history.getScore(applicationB);
@@ -35,13 +42,26 @@ function getApplicationList() {
   });
 }
 
+/**
+ * Records the launch of an application, updating its score in the history.
+ * @param application The application that was launched.
+ * @returns void
+ */
 export function recordAppLaunch(application: Apps.Application) {
   history.recordLaunch(application);
 }
 
+/**
+ * Searches for applications based on the provided query string,
+ * returning a list of matching applications sorted by relevance and launch history.
+ * @param query The search query string.
+ * @returns A list of applications that match the search query.
+ */
 export function searchApps(query: string) {
-  const allApplications = getApplicationList();
+  const allApplications = getSortedAppList();
+
   if (query === '') return getUniqueResults(allApplications);
+
   const keywords = query.split(/\s+/);
 
   const results = allApplications
diff --git a/src/stores/application/applicationHistory.ts b/src/stores/application/applicationHistory.ts
index c819d1f..125f71d 100644
--- a/src/stores/application/applicationHistory.ts
+++ b/src/stores/application/applicationHistory.ts
@@ -18,6 +18,11 @@ function getApplicationKey(application: Apps.Application) {
   return application.entry || application.executable || application.name;
 }
 
+/**
+ * Manages the history of application launches,
+ * allowing for scoring and ranking of applications based on launch frequency.
+ * The history is persisted to a JSON file in the user's state directory.
+ */
 export class ApplicationHistory {
   private scores: Record<string, number> = {};
 
@@ -29,6 +34,11 @@ export class ApplicationHistory {
     return this.scores[getApplicationKey(application)] || 0;
   }
 
+  /**
+   * Records the launch of an application, updating its score in the history.
+   * @param application The application that was launched.
+   * @returns void
+   */
   recordLaunch(application: Apps.Application) {
     const key = getApplicationKey(application);
     if (!key) return;
@@ -41,6 +51,10 @@ export class ApplicationHistory {
     this.save();
   }
 
+  /**
+   * Trims the history to ensure that only the top MAX_HISTORY_ENTRIES are kept,
+   * based on their scores.
+   */
   private trim() {
     const entries = Object.entries(this.scores)
       .filter(([, score]) => Number.isFinite(score) && score > 0)
@@ -49,6 +63,12 @@ export class ApplicationHistory {
     this.scores = Object.fromEntries(entries);
   }
 
+  /**
+   * Migrates legacy scores from an older format to the current format,
+   * ensuring that only valid applications are retained.
+   * @param legacy A record of legacy application keys and their associated scores.
+   * @returns A new record of application keys and their migrated scores.
+   */
   private migrateLegacyScores(legacy: Record<string, number>) {
     const migrated: Record<string, number> = {};
     for (const [legacyKey, score] of Object.entries(legacy)) {
@@ -65,6 +85,9 @@ export class ApplicationHistory {
     return migrated;
   }
 
+  /**
+   * Loads the application launch history from the JSON file.
+   */
   private load() {
     try {
       const currentFile = Gio.File.new_for_path(HISTORY_FILE);
diff --git a/src/widget/app-launcher/index.tsx b/src/widget/app-launcher/index.tsx
index 4dc3a91..08c0a94 100644
--- a/src/widget/app-launcher/index.tsx
+++ b/src/widget/app-launcher/index.tsx
@@ -3,34 +3,14 @@ import {Astal, Gdk, Gtk} from 'ags/gtk4';
 import app from 'ags/gtk4/app';
 import {type Timer, idle} from 'ags/time';
 
-import {createAppLauncherState} from '@/stores/application/appLauncher';
-import {
-  ensureLauncherBackground,
-  registerLauncherBackground,
-} from '@/stores/application/launcherBackground';
-import {AppList} from '@/widget/app-launcher/widget/AppList';
-import {SearchInput} from '@/widget/app-launcher/widget/SearchInput';
-
-function createLauncherBackground() {
-  const picture = new Gtk.Picture({
-    contentFit: Gtk.ContentFit.COVER,
-    canTarget: false,
-    canShrink: true,
-    hexpand: true,
-    vexpand: true,
-    halign: Gtk.Align.FILL,
-    valign: Gtk.Align.FILL,
-    widthRequest: 1,
-    heightRequest: 1,
-  });
-
-  const unregister = registerLauncherBackground(picture);
-  picture.connect('destroy', unregister);
+import {createAppSearchTextState} from '@/stores/application/appLauncher';
+import {ensureLauncherBackground} from '@/stores/application/launcherBackground';
 
-  return picture;
-}
+import {AppList} from './widget/AppList';
+import {createLauncherBackground} from './widget/LauncherBackground';
+import {SearchInputBar} from './widget/SearchInput';
 
-function resetLauncherState(
+function resetAppSearchTextState(
   searchInput: Gtk.Entry,
   setText: (text: string) => void,
   setSelectedIndex: (index: number) => void
@@ -64,13 +44,15 @@ export interface AppLauncherProps {
 }
 
 export default function AppLauncher({monitor}: AppLauncherProps) {
-  const {text, setText, selectedIndex, setSelectedIndex, results} = createAppLauncherState();
   const monitorConnector = monitor.get_connector();
-  let focusTimer: Timer | null = null;
+
+  const {text, setText, selectedIndex, setSelectedIndex, results} = createAppSearchTextState();
 
   const launcherBackground = createLauncherBackground();
 
-  const searchInput = SearchInput({
+  let focusTimer: Timer | null = null;
+
+  const searchInputBar = SearchInputBar({
     text,
     setText,
     selectedIndex,
@@ -79,17 +61,8 @@ export default function AppLauncher({monitor}: AppLauncherProps) {
     monitorConnector,
   });
 
-  const launcherContent = (
-    <box orientation={Gtk.Orientation.VERTICAL} vexpand>
-      <box vexpand />
-      <box class="applauncher-search-container" hexpand>
-        {searchInput}
-      </box>
-    </box>
-  ) as Gtk.Box;
-
   const appList = AppList({
-    text,
+    searchText: text,
     selectedIndex,
     results,
     monitorConnector,
@@ -110,9 +83,9 @@ export default function AppLauncher({monitor}: AppLauncherProps) {
         focusTimer = null;
 
         if (!self.visible) {
-          resetLauncherState(searchInput, setText, setSelectedIndex);
+          resetAppSearchTextState(searchInputBar, setText, setSelectedIndex);
         } else {
-          focusTimer = focusLauncher(searchInput, appList);
+          focusTimer = focusLauncher(searchInputBar, appList);
         }
       }}
     >
@@ -125,14 +98,15 @@ export default function AppLauncher({monitor}: AppLauncherProps) {
             vexpand
             overflow={Gtk.Overflow.HIDDEN}
           >
-            <overlay
-              hexpand
-              vexpand
-              $={(self: Gtk.Overlay) => {
-                self.set_child(launcherBackground);
-                self.add_overlay(launcherContent);
-              }}
-            />
+            <overlay hexpand vexpand>
+              {launcherBackground}
+              <box $type="overlay" orientation={Gtk.Orientation.VERTICAL} vexpand>
+                <box vexpand />
+                <box class="applauncher-search-container" hexpand>
+                  {searchInputBar}
+                </box>
+              </box>
+            </overlay>
           </box>
 
           {/* Right Panel */}
diff --git a/src/widget/app-launcher/widget/AppItem.tsx b/src/widget/app-launcher/widget/AppItem.tsx
index a539105..2863b01 100644
--- a/src/widget/app-launcher/widget/AppItem.tsx
+++ b/src/widget/app-launcher/widget/AppItem.tsx
@@ -7,10 +7,17 @@ import {recordAppLaunch} from '@/stores/application/applicationCatalog';
 import {toggleAppLauncher} from '@/stores/shell/windowManager';
 
 export interface AppItemProps {
-  res: Apps.Application;
+  app: Apps.Application;
   monitorConnector: string | null;
 }
 
+/**
+ * Creates a set of properties for a Gtk.Image widget based on the provided icon string.
+ * If the icon string is a file path,
+ * it sets the 'file' property; otherwise, it sets the 'iconName' property.
+ * @param iconStr The icon string, either a file path or an icon name.
+ * @returns An object containing the appropriate Gtk.Image properties.
+ */
 function createImageProp(iconStr: string): Partial<Gtk.Image.ConstructorProps> {
   const iconProps: Partial<Gtk.Image.ConstructorProps> = {
     cssClasses: ['applauncher-item-icon'],
@@ -25,29 +32,29 @@ function createImageProp(iconStr: string): Partial<Gtk.Image.ConstructorProps> {
   return iconProps;
 }
 
-export function AppItem({res, monitorConnector}: AppItemProps): Gtk.Button {
+export function AppItem({app, monitorConnector}: AppItemProps): Gtk.Button {
   return (
     <button
       class="applauncher-item"
       canFocus={false}
       onClicked={() => {
         toggleAppLauncher(monitorConnector);
-        recordAppLaunch(res);
-        res.launch();
+        recordAppLaunch(app);
+        app.launch();
       }}
     >
       <box orientation={Gtk.Orientation.HORIZONTAL} spacing={12}>
-        <image {...createImageProp(res.iconName)} />
+        <image {...createImageProp(app.iconName)} />
         <box orientation={Gtk.Orientation.VERTICAL} valign={Gtk.Align.CENTER}>
           <label
-            label={res.name}
+            label={app.name}
             halign={Gtk.Align.START}
             class="applauncher-item-name"
             ellipsize={Pango.EllipsizeMode.END}
           />
-          {res.description && (
+          {app.description && (
             <label
-              label={res.description}
+              label={app.description}
               halign={Gtk.Align.START}
               class="applauncher-item-desc"
               ellipsize={Pango.EllipsizeMode.END}
diff --git a/src/widget/app-launcher/widget/AppList.tsx b/src/widget/app-launcher/widget/AppList.tsx
index 1898176..d92a1e4 100644
--- a/src/widget/app-launcher/widget/AppList.tsx
+++ b/src/widget/app-launcher/widget/AppList.tsx
@@ -4,16 +4,20 @@ import {type Timer, idle} from 'ags/time';
 
 import Apps from 'gi://AstalApps';
 
-import {AppItem} from '@/widget/app-launcher/widget/AppItem';
-import {SearchGoogleBtn} from '@/widget/app-launcher/widget/SearchGoogleBtn';
+import {AppItem} from './AppItem';
+import {SearchGoogleBtn} from './SearchGoogleBtn';
 
 export interface AppListProps {
-  text: Accessor<string>;
+  searchText: Accessor<string>;
   selectedIndex: Accessor<number>;
   results: Accessor<Apps.Application[]>;
   monitorConnector: string | null;
 }
 
+/**
+ * Adjust the scroll position of the provided scroll window to
+ * ensure that the target child widget is visible within the viewport.
+ */
 function scrollToSelection(scrollWindow: Gtk.ScrolledWindow, targetChild: Gtk.Widget) {
   const adjustment = scrollWindow.get_vadjustment();
   const viewport = scrollWindow.get_child();
@@ -34,6 +38,12 @@ function scrollToSelection(scrollWindow: Gtk.ScrolledWindow, targetChild: Gtk.Wi
   }
 }
 
+/**
+ * Updates the selection state of the application list and the "Search Google" button
+ * based on the current selected index and search query.
+ * It ensures that only one item is highlighted at a time and scrolls to
+ * the selected item if necessary.
+ */
 function updateSelection(
   appList: Gtk.Box,
   searchGoogleBtn: Gtk.Button,
@@ -68,13 +78,13 @@ function updateSelection(
 }
 
 export function AppList({
-  text,
+  searchText,
   selectedIndex,
   results,
   monitorConnector,
 }: AppListProps): Gtk.ScrolledWindow {
   const searchGoogleBtn = SearchGoogleBtn({
-    textState: text,
+    searchText,
     monitorConnector,
   });
 
@@ -97,7 +107,7 @@ export function AppList({
       <box orientation={Gtk.Orientation.VERTICAL} class="applauncher-list" spacing={10}>
         <box orientation={Gtk.Orientation.VERTICAL} spacing={10} $={self => (appList = self)}>
           <For each={results}>
-            {appInstance => <AppItem res={appInstance} monitorConnector={monitorConnector} />}
+            {appInstance => <AppItem app={appInstance} monitorConnector={monitorConnector} />}
           </For>
         </box>
         {searchGoogleBtn}
@@ -108,7 +118,7 @@ export function AppList({
   createEffect(() => {
     selectedIndex();
     results();
-    text();
+    searchText();
 
     selectionTimer?.cancel();
     selectionTimer = idle(() => {
@@ -119,7 +129,7 @@ export function AppList({
         scrollWindow,
         selectedIndex.peek(),
         results.peek(),
-        text.peek().trim()
+        searchText.peek().trim()
       );
     });
   });
diff --git a/src/widget/app-launcher/widget/LauncherBackground.tsx b/src/widget/app-launcher/widget/LauncherBackground.tsx
new file mode 100644
index 0000000..b59dc8a
--- /dev/null
+++ b/src/widget/app-launcher/widget/LauncherBackground.tsx
@@ -0,0 +1,22 @@
+import {Gtk} from 'ags/gtk4';
+
+import {registerLauncherBackground} from '@/stores/application/launcherBackground';
+
+export function createLauncherBackground() {
+  const picture = new Gtk.Picture({
+    contentFit: Gtk.ContentFit.COVER,
+    canTarget: false,
+    canShrink: true,
+    hexpand: true,
+    vexpand: true,
+    halign: Gtk.Align.FILL,
+    valign: Gtk.Align.FILL,
+    widthRequest: 1,
+    heightRequest: 1,
+  });
+
+  const unregister = registerLauncherBackground(picture);
+  picture.connect('destroy', unregister);
+
+  return picture;
+}
diff --git a/src/widget/app-launcher/widget/SearchGoogleBtn.tsx b/src/widget/app-launcher/widget/SearchGoogleBtn.tsx
index 285fe83..807013c 100644
--- a/src/widget/app-launcher/widget/SearchGoogleBtn.tsx
+++ b/src/widget/app-launcher/widget/SearchGoogleBtn.tsx
@@ -7,27 +7,26 @@ import {getDirectUrl, openQuery} from '@/stores/application/query';
 import {toggleAppLauncher} from '@/stores/shell/windowManager';
 
 export interface SearchGoogleBtnProps {
-  textState: Accessor<string>;
+  searchText: Accessor<string>;
   monitorConnector: string | null;
 }
 
-export function SearchGoogleBtn({textState, monitorConnector}: SearchGoogleBtnProps): Gtk.Button {
+export function SearchGoogleBtn({searchText, monitorConnector}: SearchGoogleBtnProps): Gtk.Button {
   return (
     <button
       class="applauncher-item"
       canFocus={false}
-      visible={textState.as((t: string) => (t || '').trim() !== '')}
+      visible={searchText.as((t: string) => (t || '').trim() !== '')}
       onClicked={() => {
-        const t = textState.peek() || '';
         toggleAppLauncher(monitorConnector);
-        openQuery(t);
+        openQuery(searchText.peek() || '');
       }}
     >
       <box orientation={Gtk.Orientation.HORIZONTAL} spacing={12}>
         <image iconName="web-browser" class="applauncher-item-icon" />
         <box orientation={Gtk.Orientation.VERTICAL} valign={Gtk.Align.CENTER}>
           <label
-            label={textState.as((t: string) =>
+            label={searchText.as((t: string) =>
               getDirectUrl(t || '') ? `Open "${t || ''}"` : `Search "${t || ''}"`
             )}
             halign={Gtk.Align.START}
@@ -35,7 +34,7 @@ export function SearchGoogleBtn({textState, monitorConnector}: SearchGoogleBtnPr
             ellipsize={Pango.EllipsizeMode.END}
           />
           <label
-            label={textState.as((t: string) =>
+            label={searchText.as((t: string) =>
               getDirectUrl(t || '') ? 'Open URL' : 'Search on Google'
             )}
             halign={Gtk.Align.START}
diff --git a/src/widget/app-launcher/widget/SearchInput.tsx b/src/widget/app-launcher/widget/SearchInput.tsx
index cea04a2..3c0dca3 100644
--- a/src/widget/app-launcher/widget/SearchInput.tsx
+++ b/src/widget/app-launcher/widget/SearchInput.tsx
@@ -7,7 +7,7 @@ import {recordAppLaunch} from '@/stores/application/applicationCatalog';
 import {openQuery} from '@/stores/application/query';
 import {toggleAppLauncher} from '@/stores/shell/windowManager';
 
-export interface SearchInputProps {
+export interface SearchInputBarProps {
   text: Accessor<string>;
   setText: Setter<string>;
   selectedIndex: Accessor<number>;
@@ -16,14 +16,14 @@ export interface SearchInputProps {
   monitorConnector: string | null;
 }
 
-export function SearchInput({
+export function SearchInputBar({
   text,
   setText,
   selectedIndex,
   setSelectedIndex,
   results,
   monitorConnector,
-}: SearchInputProps): Gtk.Entry {
+}: SearchInputBarProps): Gtk.Entry {
   const searchEntry = (
     <entry class="applauncher-input" placeholderText="Search apps..." hexpand />
   ) as Gtk.Entry;
@@ -33,6 +33,7 @@ export function SearchInput({
     setSelectedIndex(0);
   });
 
+  // Capture navigation keys before Gtk.Entry handles them so they control the selected result.
   const entryKeyCtrl = new Gtk.EventControllerKey();
   entryKeyCtrl.set_propagation_phase(Gtk.PropagationPhase.CAPTURE);
   entryKeyCtrl.connect('key-pressed', (_, keyval) => {
@@ -65,6 +66,7 @@ export function SearchInput({
     }
     return false;
   });
+
   searchEntry.add_controller(entryKeyCtrl);
 
   return searchEntry;

From 2863bc346e29643c8524ded01fc70593f04fe610 Mon Sep 17 00:00:00 2001
From: Ry2X <45420571+ry2x@users.noreply.github.com>
Date: Wed, 19 Aug 2026 01:18:54 +0900
Subject: [PATCH 2/2] refactor: remove magic number and fix words

---
 src/stores/wallpaper/wallpaper.ts             |  1 +
 src/stores/wallpaper/wallpaperSelector.ts     |  2 +
 src/stores/wallpaper/wallpaperThumbnail.ts    |  2 +
 .../wallpaper-selector/coverFlowGeometry.ts   | 11 +++-
 .../wallpaper-selector/widget/CoverFlow.tsx   | 61 +++++++++++--------
 .../widget/coverFlowAnimation.ts              |  8 ++-
 6 files changed, 55 insertions(+), 30 deletions(-)

diff --git a/src/stores/wallpaper/wallpaper.ts b/src/stores/wallpaper/wallpaper.ts
index 3cf59a3..5567996 100644
--- a/src/stores/wallpaper/wallpaper.ts
+++ b/src/stores/wallpaper/wallpaper.ts
@@ -32,6 +32,7 @@ export const wallpapersLoading = wallpapersLoadingState;
 export const wallpaperApplying = wallpaperApplyingState;
 export const wallpaperError = wallpaperErrorState;
 
+// A new refresh invalidates every older async enumeration.
 let refreshGeneration = 0;
 let refreshCancellable: Gio.Cancellable | null = null;
 
diff --git a/src/stores/wallpaper/wallpaperSelector.ts b/src/stores/wallpaper/wallpaperSelector.ts
index 07e8365..d715017 100644
--- a/src/stores/wallpaper/wallpaperSelector.ts
+++ b/src/stores/wallpaper/wallpaperSelector.ts
@@ -45,6 +45,7 @@ export function createWallpaperSelectorState({
 
   function animatePanelTo(height: number) {
     targetPanelHeight = height;
+    // Reuse the current timer when the target changes during an animation.
     if (animationTimer) return;
 
     animationTimer = interval(ANIMATION_INTERVAL_MS, () => {
@@ -69,6 +70,7 @@ export function createWallpaperSelectorState({
     deactivateSidePanel('wallpaper-selector', monitorConnector);
 
     cancelHideTimer();
+    // Keep scanning and the window alive until the closing animation has settled.
     hideTimer = timeout(HIDE_DELAY_MS, () => {
       hideTimer = null;
       setCoverFlowActive(false);
diff --git a/src/stores/wallpaper/wallpaperThumbnail.ts b/src/stores/wallpaper/wallpaperThumbnail.ts
index 85bd4d8..b97c94f 100644
--- a/src/stores/wallpaper/wallpaperThumbnail.ts
+++ b/src/stores/wallpaper/wallpaperThumbnail.ts
@@ -129,6 +129,7 @@ function pumpThumbnailQueue() {
 }
 
 export function ensureWallpaperThumbnails(items: Wallpaper[], priority = true) {
+  // Visible cards use priority jobs; the initial scan fills the cache afterward.
   const currentGeneration = generation;
   for (const wallpaper of items) {
     if (GLib.file_test(wallpaper.thumbnailPath, GLib.FileTest.IS_REGULAR)) continue;
@@ -162,6 +163,7 @@ export function subscribeThumbnailReady(subscriber: (path: string, thumbnailPath
 }
 
 export function cancelWallpaperThumbnailWork() {
+  // Invalidate queued and running jobs before killing their processes.
   generation++;
   thumbnailQueue = [];
   queuedThumbnails.clear();
diff --git a/src/widget/wallpaper-selector/coverFlowGeometry.ts b/src/widget/wallpaper-selector/coverFlowGeometry.ts
index f283172..ca92a46 100644
--- a/src/widget/wallpaper-selector/coverFlowGeometry.ts
+++ b/src/widget/wallpaper-selector/coverFlowGeometry.ts
@@ -3,6 +3,10 @@ import Gsk from 'gi://Gsk';
 
 const WALLPAPER_CARD_WIDTH = 384;
 const WALLPAPER_CARD_HEIGHT = 252;
+const CENTER_Y = 52;
+const ENTRANCE_OFFSET_Y = 70;
+const CLOSE_CARD_SPACING = 290;
+const FAR_CARD_SPACING = 190;
 
 function interpolateStops(distance: number, values: readonly number[]) {
   const clamped = Math.min(distance, values.length - 1);
@@ -22,12 +26,15 @@ export function getCoverFlowOpacity(offset: number) {
 export function createCoverFlowTransform(offset: number, containerWidth: number, entrance: number) {
   const distance = Math.abs(offset);
   const direction = Math.sign(offset);
-  const horizontal = distance <= 1 ? distance * 290 : 290 + (distance - 1) * 190;
+  const horizontal =
+    distance <= 1
+      ? distance * CLOSE_CARD_SPACING
+      : CLOSE_CARD_SPACING + (distance - 1) * FAR_CARD_SPACING;
   const scale = interpolateStops(distance, [1.06, 0.88, 0.76, 0.64, 0.56]);
   const skew = direction * interpolateStops(distance, [0, -9, -12, -14, -16]);
   const arcDrop = interpolateStops(distance, [-14, 24, 62, 108, 152]);
   const x = (containerWidth - WALLPAPER_CARD_WIDTH) / 2 + direction * horizontal;
-  const y = 52 + arcDrop + (1 - entrance) * 70;
+  const y = CENTER_Y + arcDrop + (1 - entrance) * ENTRANCE_OFFSET_Y;
 
   let transform: Gsk.Transform | null = Gsk.Transform.new();
   transform = transform.translate(new Graphene.Point({x, y}));
diff --git a/src/widget/wallpaper-selector/widget/CoverFlow.tsx b/src/widget/wallpaper-selector/widget/CoverFlow.tsx
index 84b0a3d..bb6a914 100644
--- a/src/widget/wallpaper-selector/widget/CoverFlow.tsx
+++ b/src/widget/wallpaper-selector/widget/CoverFlow.tsx
@@ -37,20 +37,22 @@ export interface CoverFlowOptions {
 export default class CoverFlowController {
   readonly widget: Gtk.Box;
 
-  private readonly fixed: Gtk.Fixed;
-  private readonly positionLabel: Gtk.Label;
+  private readonly cardContainer: Gtk.Fixed;
+  private readonly selectionLabel: Gtk.Label;
   private readonly statusLabel: Gtk.Label;
   private readonly cards = new Map<string, CoverFlowCardState>();
   private readonly disposers: (() => void)[];
   private readonly animation: CoverFlowAnimation;
   private active = false;
   private disposed = false;
-  private filtered: Wallpaper[] = [];
+  private availableWallpapers: Wallpaper[] = [];
   private selectedIndex = 0;
   private lastMoveAt = 0;
 
   constructor(private readonly options: CoverFlowOptions) {
-    this.fixed = new Gtk.Fixed({
+    // Cards are kept in Gtk.Fixed and moved with transforms so navigation
+    // updates existing widgets instead of rebuilding the whole cover flow.
+    this.cardContainer = new Gtk.Fixed({
       hexpand: false,
       vexpand: false,
       widthRequest: options.viewportWidth,
@@ -67,10 +69,10 @@ export default class CoverFlowController {
       heightRequest: VIEWPORT_HEIGHT,
       halign: Gtk.Align.FILL,
       valign: Gtk.Align.FILL,
-      child: this.fixed,
+      child: this.cardContainer,
     });
 
-    this.positionLabel = new Gtk.Label({
+    this.selectionLabel = new Gtk.Label({
       cssClasses: ['wallpaper-path'],
       canTarget: false,
       hexpand: true,
@@ -99,7 +101,7 @@ export default class CoverFlowController {
       }),
     });
     coverFlowLayer.add_overlay(viewport);
-    coverFlowLayer.add_overlay(this.positionLabel);
+    coverFlowLayer.add_overlay(this.selectionLabel);
 
     this.widget = (
       <box
@@ -115,7 +117,7 @@ export default class CoverFlowController {
     ) as Gtk.Box;
 
     this.animation = new CoverFlowAnimation({
-      fixed: this.fixed,
+      cardContainer: this.cardContainer,
       cards: this.cards,
       onVisualsUpdated: () => this.applyCardVisuals(),
       onFinished: () => this.finishAnimation(),
@@ -128,11 +130,11 @@ export default class CoverFlowController {
       if (dy !== 0) this.moveSelection(dy > 0 ? 1 : -1);
       return true;
     });
-    this.fixed.add_controller(scrollController);
+    this.cardContainer.add_controller(scrollController);
 
     this.disposers = [
       wallpapers.subscribe(() => {
-        if (this.active) this.filterWallpapers();
+        if (this.active) this.syncWallpapers();
       }),
       wallpaperError.subscribe(() => this.updateLabels()),
       wallpapersLoading.subscribe(() => this.updateLabels()),
@@ -146,9 +148,11 @@ export default class CoverFlowController {
     this.active = active;
 
     if (active) {
+      // Rebuild the small visible window around the current selection and
+      // animate it in when the selector is opened.
       this.lastMoveAt = 0;
       this.animation.resetEntrance();
-      this.filterWallpapers();
+      this.syncWallpapers();
       this.startAnimation();
       return;
     }
@@ -182,13 +186,13 @@ export default class CoverFlowController {
   }
 
   private selectedWallpaper() {
-    return this.filtered[this.selectedIndex] ?? null;
+    return this.availableWallpapers[this.selectedIndex] ?? null;
   }
 
   private handleCardClicked(card: WallpaperCardController) {
     const clicked = card.wallpaper;
     if (!clicked || wallpaperApplying()) return;
-    const index = this.filtered.findIndex(item => item.path === clicked.path);
+    const index = this.availableWallpapers.findIndex(item => item.path === clicked.path);
     if (index < 0) return;
     if (index === this.selectedIndex) this.activateSelection();
     else this.setSelection(index);
@@ -196,8 +200,8 @@ export default class CoverFlowController {
 
   private updateLabels() {
     const selected = this.selectedWallpaper();
-    this.positionLabel.set_label(
-      selected ? `${this.selectedIndex + 1} / ${this.filtered.length}` : '0 / 0'
+    this.selectionLabel.set_label(
+      selected ? `${this.selectedIndex + 1} / ${this.availableWallpapers.length}` : '0 / 0'
     );
     this.statusLabel.set_label(
       wallpaperError() || (wallpapersLoading() ? 'Loading wallpapers…' : '')
@@ -207,11 +211,13 @@ export default class CoverFlowController {
 
   private removeCard(path: string, state: CoverFlowCardState) {
     state.card.clear();
-    this.fixed.remove(state.card.widget);
+    this.cardContainer.remove(state.card.widget);
     this.cards.delete(path);
   }
 
   private applyCardVisuals() {
+    // Draw distant cards first and the selected card last so the center card
+    // remains visually above its neighbors.
     const ordered = [...this.cards.values()].sort(
       (a, b) => Math.abs(b.currentOffset) - Math.abs(a.currentOffset)
     );
@@ -219,7 +225,7 @@ export default class CoverFlowController {
     for (const state of ordered) {
       state.card.setSelected(Math.abs(state.currentOffset) < 0.5);
       state.card.widget.set_can_target(Math.abs(state.currentOffset) <= VISIBLE_RADIUS + 0.25);
-      this.fixed.set_child_transform(
+      this.cardContainer.set_child_transform(
         state.card.widget,
         createCoverFlowTransform(
           state.currentOffset,
@@ -227,7 +233,7 @@ export default class CoverFlowController {
           this.animation.getEntrance()
         )
       );
-      state.card.widget.insert_before(this.fixed, null);
+      state.card.widget.insert_before(this.cardContainer, null);
     }
   }
 
@@ -257,6 +263,8 @@ export default class CoverFlowController {
   }
 
   private reconcileCards(direction = 0) {
+    // Keep only the cards around the current selection so large wallpaper
+    // collections do not create a widget for every file.
     for (const [path, state] of [...this.cards]) {
       if (!state.retained) this.removeCard(path, state);
     }
@@ -270,8 +278,10 @@ export default class CoverFlowController {
     }
 
     const visibleItems: Wallpaper[] = [];
+    // Prefetch one extra card beyond the visible radius to make quick
+    // navigation show an already prepared thumbnail.
     for (let offset = -PREFETCH_RADIUS; offset <= PREFETCH_RADIUS; offset++) {
-      const wallpaper = this.filtered[this.selectedIndex + offset];
+      const wallpaper = this.availableWallpapers[this.selectedIndex + offset];
       if (!wallpaper) continue;
       visibleItems.push(wallpaper);
 
@@ -279,7 +289,7 @@ export default class CoverFlowController {
       if (!state) {
         const card = new WallpaperCardController(clicked => this.handleCardClicked(clicked));
         card.bind(wallpaper);
-        this.fixed.put(card.widget, 0, 0);
+        this.cardContainer.put(card.widget, 0, 0);
         const spawnOffset = offset + Math.sign(offset || direction || 1) * 0.35;
         state = {
           card,
@@ -305,23 +315,24 @@ export default class CoverFlowController {
   }
 
   private setSelection(index: number) {
-    if (this.filtered.length === 0) {
+    if (this.availableWallpapers.length === 0) {
       this.selectedIndex = 0;
       this.reconcileCards();
       return;
     }
-    const nextIndex = Math.max(0, Math.min(this.filtered.length - 1, index));
+    const nextIndex = Math.max(0, Math.min(this.availableWallpapers.length - 1, index));
     if (nextIndex === this.selectedIndex && this.cards.size > 0) return;
     const direction = Math.sign(nextIndex - this.selectedIndex);
     this.selectedIndex = nextIndex;
     this.reconcileCards(direction);
   }
 
-  private filterWallpapers() {
+  private syncWallpapers() {
+    // Keep the same wallpaper selected after a refresh when it still exists.
     const previousPath = this.selectedWallpaper()?.path;
-    this.filtered = wallpapers();
+    this.availableWallpapers = wallpapers();
     const preservedIndex = previousPath
-      ? this.filtered.findIndex(wallpaper => wallpaper.path === previousPath)
+      ? this.availableWallpapers.findIndex(wallpaper => wallpaper.path === previousPath)
       : -1;
     this.selectedIndex = preservedIndex >= 0 ? preservedIndex : 0;
     this.reconcileCards();
diff --git a/src/widget/wallpaper-selector/widget/coverFlowAnimation.ts b/src/widget/wallpaper-selector/widget/coverFlowAnimation.ts
index b4db255..ae97e3d 100644
--- a/src/widget/wallpaper-selector/widget/coverFlowAnimation.ts
+++ b/src/widget/wallpaper-selector/widget/coverFlowAnimation.ts
@@ -17,7 +17,7 @@ export interface CoverFlowCardState {
 }
 
 interface CoverFlowAnimationOptions {
-  fixed: Gtk.Fixed;
+  cardContainer: Gtk.Fixed;
   cards: Map<string, CoverFlowCardState>;
   onVisualsUpdated: () => void;
   onFinished: () => void;
@@ -47,7 +47,9 @@ export class CoverFlowAnimation {
     this.animationStartedAt = GLib.get_monotonic_time();
     if (this.tickId !== 0) return;
 
-    this.tickId = this.options.fixed.add_tick_callback((_widget, frameClock) => {
+    // A GTK frame callback keeps movement and opacity changes synchronized
+    // with rendering instead of relying on a fixed-rate timer.
+    this.tickId = this.options.cardContainer.add_tick_callback((_widget, frameClock) => {
       const now = frameClock.get_frame_time();
       const moveProgress = Math.min(1, (now - this.animationStartedAt) / MOVE_DURATION_US);
       const eased = easeOutCubic(moveProgress);
@@ -76,7 +78,7 @@ export class CoverFlowAnimation {
 
   stop() {
     if (this.tickId === 0) return;
-    this.options.fixed.remove_tick_callback(this.tickId);
+    this.options.cardContainer.remove_tick_callback(this.tickId);
     this.tickId = 0;
   }
 }