feat: replace useSettings with useUserPreferences

- extract sidebar collapsed state into separate `usePackageSidebarPreferences` composable
- add `preferences-sync.client.ts` plugin for early color mode + server sync init
- wrap theme select in `<ClientOnly>` to prevent SSR hydration mismatch
- show sync status indicator on settings page for authenticated users
- add `useColorModePreference` composable to sync color mode with `@nuxtjs/color-mode`

Author: gusa4grr

app/components/CollapsibleSection.vue

@@ -16,16 +16,16 @@ const props = withDefaults(defineProps<Props>(), {
   headingLevel: 'h2',
 })
 
-const appSettings = useSettings()
+const { sidebarPreferences } = usePackageSidebarPreferences()
 
 const buttonId = `${props.id}-collapsible-button`
 const contentId = `${props.id}-collapsible-content`
 
 const isOpen = shallowRef(true)
 
 onPrehydrate(() => {
-  const settings = JSON.parse(localStorage.getItem('npmx-settings') || '{}')
-  const collapsed: string[] = settings?.sidebar?.collapsed || []
+  const sidebar = JSON.parse(localStorage.getItem('npmx-sidebar-preferences') || '{}')
+  const collapsed: string[] = sidebar?.collapsed || []
   for (const id of collapsed) {
     if (!document.documentElement.dataset.collapsed?.split(' ').includes(id)) {
       document.documentElement.dataset.collapsed = (
@@ -48,17 +48,16 @@ onMounted(() => {
 function toggle() {
   isOpen.value = !isOpen.value
 
-  const removed = appSettings.settings.value.sidebar.collapsed.filter(c => c !== props.id)
+  const removed = sidebarPreferences.value.collapsed.filter(c => c !== props.id)
 
   if (isOpen.value) {
-    appSettings.settings.value.sidebar.collapsed = removed
+    sidebarPreferences.value.collapsed = removed
   } else {
     removed.push(props.id)
-    appSettings.settings.value.sidebar.collapsed = removed
+    sidebarPreferences.value.collapsed = removed
   }
 
-  document.documentElement.dataset.collapsed =
-    appSettings.settings.value.sidebar.collapsed.join(' ')
+  document.documentElement.dataset.collapsed = sidebarPreferences.value.collapsed.join(' ')
 }
 
 const ariaLabel = computed(() => {

app/components/Settings/AccentColorPicker.vue

@@ -1,12 +1,12 @@
 <script setup lang="ts">
-import { useAccentColor } from '~/composables/useSettings'
+import { useAccentColor } from '~/composables/useUserPreferences'
 
 const { accentColors, selectedAccentColor, setAccentColor } = useAccentColor()
 
 onPrehydrate(el => {
-  const settings = JSON.parse(localStorage.getItem('npmx-settings') || '{}')
+  const preferences = JSON.parse(localStorage.getItem('npmx-user-preferences') || '{}')
   const defaultId = 'sky'
-  const id = settings.accentColorId
+  const id = preferences.accentColorId
   if (id) {
     const input = el.querySelector<HTMLInputElement>(`input[value="${id}"]`)
     if (input) {

app/components/Settings/BgThemePicker.vue

@@ -2,9 +2,9 @@
 const { backgroundThemes, selectedBackgroundTheme, setBackgroundTheme } = useBackgroundTheme()
 
 onPrehydrate(el => {
-  const settings = JSON.parse(localStorage.getItem('npmx-settings') || '{}')
+  const preferences = JSON.parse(localStorage.getItem('npmx-user-preferences') || '{}')
   const defaultId = 'neutral'
-  const id = settings.preferredBackgroundTheme
+  const id = preferences.preferredBackgroundTheme
   if (id) {
     const input = el.querySelector<HTMLInputElement>(`input[value="${id}"]`)
     if (input) {

app/composables/useInstallCommand.ts

@@ -12,11 +12,11 @@ export function useInstallCommand(
   installVersionOverride?: MaybeRefOrGetter<string | null>,
 ) {
   const selectedPM = useSelectedPackageManager()
-  const { settings } = useSettings()
+  const { preferences } = useUserPreferences()
 
   // Check if we should show @types in install command
   const showTypesInInstall = computed(() => {
-    return settings.value.includeTypesInInstall && !!toValue(typesPackageName)
+    return preferences.value.includeTypesInInstall && !!toValue(typesPackageName)
   })
 
   const installCommandParts = computed(() => {

app/composables/usePackageSidebarPreferences.ts

@@ -0,0 +1,24 @@
+interface SidebarPreferences {
+  collapsed: string[]
+}
+
+const STORAGE_KEY = 'npmx-sidebar-preferences'
+const DEFAULT_SIDEBAR_PREFERENCES: SidebarPreferences = { collapsed: [] }
+
+let sidebarRef: Ref<SidebarPreferences> | null = null
+
+/**
+ * Composable for managing sidebar section collapsed state.
+ * This is local-only and uses its own LS key.
+ */
+export function usePackageSidebarPreferences() {
+  if (!sidebarRef) {
+    sidebarRef = useLocalStorage<SidebarPreferences>(STORAGE_KEY, DEFAULT_SIDEBAR_PREFERENCES, {
+      mergeDefaults: true,
+    })
+  }
+
+  return {
+    sidebarPreferences: sidebarRef,
+  }
+}

app/composables/useUserPreferences.ts

@@ -0,0 +1,132 @@
+import { ACCENT_COLORS, BACKGROUND_THEMES } from '#shared/utils/constants'
+import {
+  DEFAULT_USER_PREFERENCES,
+  type AccentColorId,
+  type BackgroundThemeId,
+  type ColorModePreference,
+} from '#shared/schemas/userPreferences'
+
+/**
+ * Main composable for user preferences.
+ * Uses `npmx-user-preferences` localStorage key and syncs to the server
+ * for authenticated users via `useUserPreferencesProvider`.
+ */
+export function useUserPreferences() {
+  const provider = useUserPreferencesProvider(DEFAULT_USER_PREFERENCES)
+
+  return {
+    preferences: provider.data,
+    isAuthenticated: provider.isAuthenticated,
+    isSyncing: provider.isSyncing,
+    isSynced: provider.isSynced,
+    hasError: provider.hasError,
+    syncError: provider.syncError,
+    lastSyncedAt: provider.lastSyncedAt,
+    initSync: provider.initSync,
+  }
+}
+
+export function useRelativeDates() {
+  const { preferences } = useUserPreferences()
+  return computed(() => preferences.value.relativeDates)
+}
+
+export function useAccentColor() {
+  const { preferences } = useUserPreferences()
+  const colorMode = useColorMode()
+
+  const accentColors = computed(() => {
+    const isDark = colorMode.value === 'dark'
+    const colors = isDark ? ACCENT_COLORS.dark : ACCENT_COLORS.light
+
+    return Object.entries(colors).map(([id, value]) => ({
+      id: id as AccentColorId,
+      name: id,
+      value,
+    }))
+  })
+
+  function setAccentColor(id: AccentColorId | null) {
+    if (id) {
+      document.documentElement.style.setProperty('--accent-color', `var(--swatch-${id})`)
+    } else {
+      document.documentElement.style.removeProperty('--accent-color')
+    }
+    preferences.value.accentColorId = id
+  }
+
+  return {
+    accentColors,
+    selectedAccentColor: computed(() => preferences.value.accentColorId),
+    setAccentColor,
+  }
+}
+
+export function useBackgroundTheme() {
+  const backgroundThemes = Object.entries(BACKGROUND_THEMES).map(([id, value]) => ({
+    id: id as BackgroundThemeId,
+    name: id,
+    value,
+  }))
+
+  const { preferences } = useUserPreferences()
+
+  function setBackgroundTheme(id: BackgroundThemeId | null) {
+    if (id) {
+      document.documentElement.dataset.bgTheme = id
+    } else {
+      document.documentElement.removeAttribute('data-bg-theme')
+    }
+    preferences.value.preferredBackgroundTheme = id
+  }
+
+  return {
+    backgroundThemes,
+    selectedBackgroundTheme: computed(() => preferences.value.preferredBackgroundTheme),
+    setBackgroundTheme,
+  }
+}
+
+/**
+ * Composable for syncing color mode preference.
+ * Keeps the user preference in sync with @nuxtjs/color-mode's own LS key (`npmx-color-mode`)
+ * so that the color-mode module picks up the correct value on page load.
+ */
+export function useColorModePreference() {
+  const { preferences } = useUserPreferences()
+  const colorMode = useColorMode()
+
+  /**
+   * Set color mode preference and sync to both user preferences and the
+   * `npmx-color-mode` LS key used by @nuxtjs/color-mode.
+   */
+  function setColorMode(mode: ColorModePreference) {
+    preferences.value.colorModePreference = mode
+    colorMode.preference = mode
+  }
+
+  /**
+   * On init, if the user has a stored preference, apply it to @nuxtjs/color-mode.
+   * This handles the case where preferences were synced from the server.
+   */
+  function applyStoredColorMode() {
+    const stored = preferences.value.colorModePreference
+    if (stored) {
+      colorMode.preference = stored
+    } else {
+      // No user preference stored yet — seed it from the current color-mode LS value
+      const currentPreference = colorMode.preference as ColorModePreference
+      if (currentPreference && currentPreference !== 'system') {
+        preferences.value.colorModePreference = currentPreference
+      }
+    }
+  }
+
+  return {
+    colorModePreference: computed(
+      () => preferences.value.colorModePreference ?? colorMode.preference,
+    ),
+    setColorMode,
+    applyStoredColorMode,
+  }
+}

app/composables/useUserPreferencesProvider.ts

@@ -0,0 +1,100 @@
+/**
+ * Abstraction for user preferences storage
+ * Supports both localStorage (for anonymous users) and API-based storage (for authenticated users)
+ *
+ * Design:
+ * - Anonymous users: localStorage only
+ * - Authenticated users: localStorage as cache, API as source of truth
+ * - Changes sync to server with debounce (2s) and on route change/page unload
+ *
+ * Module-level singletons are safe here: on the server, useLocalStorage returns
+ * a ref with defaults (no real localStorage); on the client, there's only one app instance.
+ */
+
+import type { RemovableRef } from '@vueuse/core'
+import { useLocalStorage } from '@vueuse/core'
+import type { UserPreferences } from '#shared/schemas/userPreferences'
+
+const STORAGE_KEY = 'npmx-user-preferences'
+
+export type HydratedUserPreferences = Required<Omit<UserPreferences, 'updatedAt'>> &
+  Pick<UserPreferences, 'updatedAt'>
+
+let dataRef: RemovableRef<HydratedUserPreferences> | null = null
+let syncInitialized = false
+
+/**
+ * User preferences provider with server sync support.
+ */
+export function useUserPreferencesProvider(defaultValue: HydratedUserPreferences) {
+  if (!dataRef) {
+    dataRef = useLocalStorage<HydratedUserPreferences>(STORAGE_KEY, defaultValue, {
+      mergeDefaults: true,
+    })
+  }
+
+  // After the guard above, dataRef is guaranteed to be initialized.
+  const preferences: RemovableRef<HydratedUserPreferences> = dataRef
+
+  const { user } = useAtproto()
+
+  const isAuthenticated = computed(() => !!user.value?.did)
+  const {
+    status,
+    lastSyncedAt,
+    error,
+    loadFromServer,
+    scheduleSync,
+    setupRouteGuard,
+    setupBeforeUnload,
+  } = useUserPreferencesSync()
+
+  const isSyncing = computed(() => status.value === 'syncing')
+  const isSynced = computed(() => status.value === 'synced')
+  const hasError = computed(() => status.value === 'error')
+
+  async function initSync(): Promise<void> {
+    if (syncInitialized || import.meta.server) return
+    syncInitialized = true
+
+    setupRouteGuard(() => preferences.value)
+    setupBeforeUnload(() => preferences.value)
+
+    if (isAuthenticated.value) {
+      const serverPrefs = await loadFromServer()
+      if (serverPrefs) {
+        preferences.value = { ...preferences.value, ...serverPrefs }
+      }
+    }
+
+    watch(
+      preferences,
+      newPrefs => {
+        if (isAuthenticated.value) {
+          scheduleSync(newPrefs)
+        }
+      },
+      { deep: true },
+    )
+
+    watch(isAuthenticated, async newIsAuth => {
+      if (newIsAuth) {
+        const serverPrefs = await loadFromServer()
+        if (serverPrefs) {
+          preferences.value = { ...defaultValue, ...preferences.value, ...serverPrefs }
+        }
+      }
+    })
+  }
+
+  return {
+    data: preferences,
+    isAuthenticated,
+    isSyncing,
+    isSynced,
+    hasError,
+    syncError: error,
+    lastSyncedAt,
+    initSync,
+  }
+}

app/pages/search.vue

@@ -65,7 +65,7 @@ onMounted(() => {
 const rawVisibleResults = computed(() => results.value)
 
 // Settings for platform package filtering
-const { settings } = useSettings()
+const { preferences } = useUserPreferences()
 
 /**
  * Reorder results to put exact package name match at the top,
@@ -78,7 +78,7 @@ const visibleResults = computed(() => {
   let objects = raw.objects
 
   // Filter out platform-specific packages if setting is enabled
-  if (settings.value.hidePlatformPackages) {
+  if (preferences.value.hidePlatformPackages) {
     objects = objects.filter(r => !isPlatformSpecificPackage(r.package.name))
   }