feat(skills): registry card polish and persisted pagination state (#2102)

* fix(skills): replace registry namespace with normalized repo label on cards and detail page

* feat(pagination): add last-page shortcut to shared pagination component

* feat(skills): pin registry pagination to viewport bottom and persist page size

* fix(skills): use host-agnostic icon for detail page repo badge

* fix(main): reuse DB page-size validator in uiPreferences IPC handler

* fix(skills): validate persisted registry limit and gate query on preference load

Author: samuv

main/src/ipc-handlers/ui-preferences.ts

@@ -1,8 +1,13 @@
 import { ipcMain } from 'electron'
 import {
+  getPageSizePreference,
   getViewModePreference,
+  isValidPageSize,
+  setPageSizePreference,
   setViewModePreference,
+  UI_PAGE_SIZE_PREFERENCE_KEYS,
   UI_PREFERENCE_KEYS,
+  type UiPageSizeKey,
   type UiPreferenceKey,
   type ViewMode,
 } from '../ui-preferences'
@@ -16,6 +21,13 @@ function isUiPreferenceKey(key: unknown): key is UiPreferenceKey {
   )
 }
 
+function isUiPageSizeKey(key: unknown): key is UiPageSizeKey {
+  return (
+    typeof key === 'string' &&
+    (UI_PAGE_SIZE_PREFERENCE_KEYS as readonly string[]).includes(key)
+  )
+}
+
 function isViewMode(value: unknown): value is ViewMode {
   return value === 'card' || value === 'table'
 }
@@ -34,4 +46,18 @@ export function register() {
       setViewModePreference(key, value)
     }
   )
+
+  ipcMain.handle(
+    'ui-preferences:get-page-size',
+    (_event, key: unknown): number | undefined =>
+      isUiPageSizeKey(key) ? getPageSizePreference(key) : undefined
+  )
+
+  ipcMain.handle(
+    'ui-preferences:set-page-size',
+    (_event, key: unknown, value: unknown): void => {
+      if (!isUiPageSizeKey(key) || !isValidPageSize(value)) return
+      setPageSizePreference(key, value)
+    }
+  )
 }

main/src/ui-preferences.ts

@@ -54,3 +54,56 @@ export function setViewModePreference(
     log.error(`[DB] Failed to write UI preference "${key}":`, err)
   }
 }
+
+export const UI_PAGE_SIZE_PREFERENCE_KEYS = [
+  'ui.pageSize.skillsRegistry',
+] as const
+
+export type UiPageSizeKey = (typeof UI_PAGE_SIZE_PREFERENCE_KEYS)[number]
+
+function isValidPageSizeKey(key: string): key is UiPageSizeKey {
+  return (UI_PAGE_SIZE_PREFERENCE_KEYS as readonly string[]).includes(key)
+}
+
+export function isValidPageSize(value: unknown): value is number {
+  return (
+    typeof value === 'number' &&
+    Number.isInteger(value) &&
+    value > 0 &&
+    value <= 1000
+  )
+}
+
+/**
+ * Reads a persisted page-size preference. Returns `undefined` when no
+ * preference has been stored yet or when the persisted value is malformed,
+ * so callers can fall back to a hardcoded default or URL param.
+ */
+export function getPageSizePreference(key: UiPageSizeKey): number | undefined {
+  try {
+    const raw = readSetting(key)
+    if (!raw) return undefined
+    const parsed = Number(raw)
+    if (!isValidPageSize(parsed)) return undefined
+    return parsed
+  } catch (err) {
+    log.error(`[DB] Failed to read page size preference "${key}":`, err)
+    return undefined
+  }
+}
+
+export function setPageSizePreference(key: UiPageSizeKey, value: number): void {
+  if (!isValidPageSizeKey(key)) {
+    log.warn(`[DB] Refusing to write unknown page size key: ${key}`)
+    return
+  }
+  if (!isValidPageSize(value)) {
+    log.warn(`[DB] Refusing to write invalid page size: ${value}`)
+    return
+  }
+  try {
+    writeSetting(key, String(value))
+  } catch (err) {
+    log.error(`[DB] Failed to write page size preference "${key}":`, err)
+  }
+}

preload/src/api/ui-preferences.ts

@@ -1,5 +1,6 @@
 import { ipcRenderer } from 'electron'
 import type {
+  UiPageSizeKey,
   UiPreferenceKey,
   ViewMode,
 } from '../../../main/src/ui-preferences'
@@ -10,12 +11,18 @@ export const uiPreferencesApi = {
       ipcRenderer.invoke('ui-preferences:get-view-mode', key),
     setViewMode: (key: UiPreferenceKey, value: ViewMode): Promise<void> =>
       ipcRenderer.invoke('ui-preferences:set-view-mode', key, value),
+    getPageSize: (key: UiPageSizeKey): Promise<number | undefined> =>
+      ipcRenderer.invoke('ui-preferences:get-page-size', key),
+    setPageSize: (key: UiPageSizeKey, value: number): Promise<void> =>
+      ipcRenderer.invoke('ui-preferences:set-page-size', key, value),
   },
 }
 
 export interface UiPreferencesAPI {
   uiPreferences: {
     getViewMode: (key: UiPreferenceKey) => Promise<ViewMode>
     setViewMode: (key: UiPreferenceKey, value: ViewMode) => Promise<void>
+    getPageSize: (key: UiPageSizeKey) => Promise<number | undefined>
+    setPageSize: (key: UiPageSizeKey, value: number) => Promise<void>
   }
 }

renderer/src/common/components/ui/__tests__/pagination.test.tsx

@@ -34,6 +34,9 @@ describe('Pagination', () => {
     expect(
       screen.getByRole('button', { name: /go to next page/i })
     ).toBeVisible()
+    expect(
+      screen.getByRole('button', { name: /go to last page/i })
+    ).toBeVisible()
   })
 
   it('uses a custom item label', () => {
@@ -53,14 +56,20 @@ describe('Pagination', () => {
     expect(
       screen.getByRole('button', { name: /go to next page/i })
     ).toBeEnabled()
+    expect(
+      screen.getByRole('button', { name: /go to last page/i })
+    ).toBeEnabled()
   })
 
-  it('disables next on the last page', () => {
+  it('disables next and last on the last page', () => {
     setup({ page: 9, pageSize: 12, total: 100 })
 
     expect(
       screen.getByRole('button', { name: /go to next page/i })
     ).toBeDisabled()
+    expect(
+      screen.getByRole('button', { name: /go to last page/i })
+    ).toBeDisabled()
     expect(
       screen.getByRole('button', { name: /go to previous page/i })
     ).toBeEnabled()
@@ -80,6 +89,9 @@ describe('Pagination', () => {
 
     await user.click(screen.getByRole('button', { name: /go to first page/i }))
     expect(onPageChange).toHaveBeenCalledWith(1)
+
+    await user.click(screen.getByRole('button', { name: /go to last page/i }))
+    expect(onPageChange).toHaveBeenCalledWith(9)
   })
 
   it('invokes onPageSizeChange when a new size is selected', async () => {

renderer/src/common/components/ui/pagination.tsx

@@ -1,5 +1,6 @@
 import {
   ChevronFirstIcon,
+  ChevronLastIcon,
   ChevronLeftIcon,
   ChevronRightIcon,
 } from 'lucide-react'
@@ -99,6 +100,15 @@ export function Pagination({
         >
           <ChevronRightIcon />
         </Button>
+        <Button
+          variant="ghost"
+          size="icon"
+          aria-label="Go to last page"
+          disabled={isLastPage}
+          onClick={() => onPageChange(totalPages)}
+        >
+          <ChevronLastIcon />
+        </Button>
       </div>
       <div className="flex items-center gap-2">
         <p className="text-secondary-foreground text-sm whitespace-nowrap">

renderer/src/common/hooks/__tests__/use-page-size-preference.test.tsx

@@ -0,0 +1,91 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import type { ReactNode } from 'react'
+import { usePageSizePreference } from '../use-page-size-preference'
+
+function makeWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false },
+    },
+  })
+  return ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  )
+}
+
+describe('usePageSizePreference', () => {
+  beforeEach(() => {
+    window.electronAPI.uiPreferences.getPageSize = vi
+      .fn()
+      .mockResolvedValue(undefined)
+    window.electronAPI.uiPreferences.setPageSize = vi
+      .fn()
+      .mockResolvedValue(undefined)
+  })
+
+  it('returns undefined while the initial read is in flight', () => {
+    const { result } = renderHook(
+      () => usePageSizePreference('ui.pageSize.skillsRegistry'),
+      { wrapper: makeWrapper() }
+    )
+
+    expect(result.current.pageSize).toBeUndefined()
+  })
+
+  it('reads the persisted page size from the main process', async () => {
+    window.electronAPI.uiPreferences.getPageSize = vi.fn().mockResolvedValue(50)
+
+    const { result } = renderHook(
+      () => usePageSizePreference('ui.pageSize.skillsRegistry'),
+      { wrapper: makeWrapper() }
+    )
+
+    await waitFor(() => {
+      expect(result.current.pageSize).toBe(50)
+    })
+    expect(window.electronAPI.uiPreferences.getPageSize).toHaveBeenCalledWith(
+      'ui.pageSize.skillsRegistry'
+    )
+  })
+
+  it('leaves pageSize undefined when nothing is persisted', async () => {
+    const { result } = renderHook(
+      () => usePageSizePreference('ui.pageSize.skillsRegistry'),
+      { wrapper: makeWrapper() }
+    )
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false)
+    })
+    expect(result.current.pageSize).toBeUndefined()
+  })
+
+  it('persists the new page size via IPC and updates state optimistically', async () => {
+    const { result } = renderHook(
+      () => usePageSizePreference('ui.pageSize.skillsRegistry'),
+      { wrapper: makeWrapper() }
+    )
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false)
+    })
+
+    act(() => {
+      result.current.setPageSize(24)
+    })
+
+    await waitFor(() => {
+      expect(result.current.pageSize).toBe(24)
+    })
+
+    await waitFor(() => {
+      expect(window.electronAPI.uiPreferences.setPageSize).toHaveBeenCalledWith(
+        'ui.pageSize.skillsRegistry',
+        24
+      )
+    })
+  })
+})

renderer/src/common/hooks/use-page-size-preference.ts

@@ -0,0 +1,74 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import log from 'electron-log/renderer'
+import { useCallback } from 'react'
+import type { UiPageSizeKey } from '../../../../main/src/ui-preferences'
+
+function pageSizePreferenceQueryKey(key: UiPageSizeKey) {
+  return ['ui-preference', 'page-size', key] as const
+}
+
+/**
+ * Reads and writes a persisted paginated-list page-size preference backed by
+ * the main-process SQLite `settings` table via IPC. Mirrors `useViewPreference`.
+ *
+ * Returns `undefined` until the initial read resolves so callers can fall
+ * back to a URL search param or a hardcoded default without flashing the
+ * wrong size.
+ */
+export function usePageSizePreference(key: UiPageSizeKey) {
+  const queryClient = useQueryClient()
+
+  const { data, isPending } = useQuery({
+    queryKey: pageSizePreferenceQueryKey(key),
+    queryFn: async (): Promise<number | null> => {
+      try {
+        const value = await window.electronAPI.uiPreferences.getPageSize(key)
+        return typeof value === 'number' ? value : null
+      } catch (error) {
+        log.error(`Failed to read page size preference "${key}":`, error)
+        return null
+      }
+    },
+    staleTime: Infinity,
+    refetchOnWindowFocus: false,
+  })
+
+  const { mutate } = useMutation({
+    mutationFn: async (value: number) => {
+      await window.electronAPI.uiPreferences.setPageSize(key, value)
+      return value
+    },
+    onMutate: async (value: number) => {
+      await queryClient.cancelQueries({
+        queryKey: pageSizePreferenceQueryKey(key),
+      })
+      const previous = queryClient.getQueryData<number | null>(
+        pageSizePreferenceQueryKey(key)
+      )
+      queryClient.setQueryData(pageSizePreferenceQueryKey(key), value)
+      return { previous }
+    },
+    onError: (error, _value, context) => {
+      log.error(`Failed to persist page size preference "${key}":`, error)
+      if (context?.previous !== undefined) {
+        queryClient.setQueryData(
+          pageSizePreferenceQueryKey(key),
+          context.previous
+        )
+      }
+    },
+  })
+
+  const setPageSize = useCallback(
+    (value: number) => {
+      mutate(value)
+    },
+    [mutate]
+  )
+
+  return {
+    pageSize: data ?? undefined,
+    isLoading: isPending,
+    setPageSize,
+  }
+}

renderer/src/common/mocks/electronAPI.ts

@@ -43,6 +43,8 @@ function createElectronStub(): Partial<ElectronAPI> {
     uiPreferences: {
       getViewMode: vi.fn().mockResolvedValue('card'),
       setViewMode: vi.fn().mockResolvedValue(undefined),
+      getPageSize: vi.fn().mockResolvedValue(undefined),
+      setPageSize: vi.fn().mockResolvedValue(undefined),
     } as ElectronAPI['uiPreferences'],
     chat: {
       stream: vi.fn(),