diff --git a/.changeset/web-storage-appearance-notification.md b/.changeset/web-storage-appearance-notification.md
new file mode 100644
index 0000000000..82313689e3
--- /dev/null
+++ b/.changeset/web-storage-appearance-notification.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Consolidate web client localStorage access and decouple appearance/notification state into dedicated modules.
diff --git a/apps/kimi-web/src/App.vue b/apps/kimi-web/src/App.vue
index 367cfec89e..0b5ea163e2 100644
--- a/apps/kimi-web/src/App.vue
+++ b/apps/kimi-web/src/App.vue
@@ -31,6 +31,7 @@ import { useKimiWebClient } from './composables/useKimiWebClient';
 import { useIsMobile } from './composables/useIsMobile';
 import type { AppConfig, ThinkingLevel } from './api/types';
 import type { FilePreviewRequest, ToolMedia } from './types';
+import { safeGetString, safeSetString, STORAGE_KEYS } from './lib/storage';
 
 const client = useKimiWebClient();
 provide('resolveImage', client.resolveImageUrl);
@@ -204,8 +205,8 @@ function onGlobalKeydown(e: KeyboardEvent): void {
 // Layout: resizable session column. ResizeHandle owns the column width (with
 // localStorage persistence); we mirror it here to drive the App grid.
 // ---------------------------------------------------------------------------
-const SIDEBAR_WIDTH_KEY = 'kimi-web.sidebar-width';
-const SIDEBAR_COLLAPSED_KEY = 'kimi-web.sidebar-collapsed';
+const SIDEBAR_WIDTH_KEY = STORAGE_KEYS.sidebarWidth;
+const SIDEBAR_COLLAPSED_KEY = STORAGE_KEYS.sidebarCollapsed;
 const SIDEBAR_DEFAULT = 270;
 const SIDEBAR_MIN = 170;
 const SIDEBAR_MAX = 420;
@@ -219,7 +220,7 @@ const sideWidth = computed(() =>
 
 function loadSidebarCollapsed(): void {
   try {
-    sidebarCollapsed.value = localStorage.getItem(SIDEBAR_COLLAPSED_KEY) === 'true';
+    sidebarCollapsed.value = safeGetString(SIDEBAR_COLLAPSED_KEY) === 'true';
   } catch {
     sidebarCollapsed.value = false;
   }
@@ -227,7 +228,7 @@ function loadSidebarCollapsed(): void {
 
 function saveSidebarCollapsed(): void {
   try {
-    localStorage.setItem(SIDEBAR_COLLAPSED_KEY, String(sidebarCollapsed.value));
+    safeSetString(SIDEBAR_COLLAPSED_KEY, String(sidebarCollapsed.value));
   } catch {
     // ignore
   }
diff --git a/apps/kimi-web/src/api/config.ts b/apps/kimi-web/src/api/config.ts
index 1051613b15..620e9eca8e 100644
--- a/apps/kimi-web/src/api/config.ts
+++ b/apps/kimi-web/src/api/config.ts
@@ -1,7 +1,9 @@
 // apps/kimi-web/src/api/config.ts
 // Reads Vite env, builds REST/WS URLs, manages stable clientId.
 
-const CLIENT_ID_KEY = 'kimi-web.client-id';
+import { safeGetString, safeSetString, STORAGE_KEYS } from '../lib/storage';
+
+const CLIENT_ID_KEY = STORAGE_KEYS.clientId;
 const WEB_CLIENT_NAME = 'kimi-code-web';
 const WEB_CLIENT_UI_MODE = 'web';
 
@@ -86,10 +88,10 @@ export function buildWsUrl(origin: string, clientId: string): string {
 }
 
 function getClientId(): string {
-  const stored = globalThis.localStorage?.getItem(CLIENT_ID_KEY);
+  const stored = safeGetString(CLIENT_ID_KEY);
   if (stored) return stored;
   const generated = `web_${globalThis.crypto?.randomUUID?.() || Math.random().toString(36).slice(2)}`;
-  globalThis.localStorage?.setItem(CLIENT_ID_KEY, generated);
+  safeSetString(CLIENT_ID_KEY, generated);
   return generated;
 }
 
diff --git a/apps/kimi-web/src/components/Composer.vue b/apps/kimi-web/src/components/Composer.vue
index dabe088a65..075c206cf2 100644
--- a/apps/kimi-web/src/components/Composer.vue
+++ b/apps/kimi-web/src/components/Composer.vue
@@ -10,6 +10,7 @@ import type { FileItem } from './MentionMenu.vue';
 import type { ActivationBadges, ConversationStatus, PermissionMode, QueuedPromptView } from '../types';
 import type { AppModel, AppSkill, ThinkingLevel } from '../api/types';
 import { modelThinkingAvailability } from '../lib/modelThinking';
+import { draftStorageKey, safeGetString, safeRemove, safeSetString } from '../lib/storage';
 
 // ---------------------------------------------------------------------------
 // Attachment state
@@ -104,25 +105,13 @@ const { t } = useI18n();
 // Unsent-draft persistence: the composer text is kept in localStorage PER
 // SESSION, so switching away and back (or a page refresh) restores whatever the
 // user was typing for that session. Cleared when the draft is sent/steered.
-const DRAFT_PREFIX = 'kimi-web.draft.';
-function draftKey(sid: string | undefined): string {
-  return DRAFT_PREFIX + (sid && sid.length > 0 ? sid : '__new__');
-}
 function loadDraft(sid: string | undefined): string {
-  try {
-    return localStorage.getItem(draftKey(sid)) ?? '';
-  } catch {
-    return '';
-  }
+  return safeGetString(draftStorageKey(sid)) ?? '';
 }
 function saveDraft(sid: string | undefined, value: string): void {
-  try {
-    const key = draftKey(sid);
-    if (value) localStorage.setItem(key, value);
-    else localStorage.removeItem(key);
-  } catch {
-    // localStorage unavailable (private mode / quota) — drafts just don't persist.
-  }
+  const key = draftStorageKey(sid);
+  if (value) safeSetString(key, value);
+  else safeRemove(key);
 }
 
 const text = ref(loadDraft(props.sessionId));
diff --git a/apps/kimi-web/src/components/ConversationPane.vue b/apps/kimi-web/src/components/ConversationPane.vue
index 31920499ee..e303baba35 100644
--- a/apps/kimi-web/src/components/ConversationPane.vue
+++ b/apps/kimi-web/src/components/ConversationPane.vue
@@ -12,6 +12,7 @@ import Composer from './Composer.vue';
 import SwarmCard from './SwarmCard.vue';
 import ChatDock from './ChatDock.vue';
 import { getVisibleWorkspaces } from '../lib/workspacePicker';
+import { safeRemove, STORAGE_KEYS } from '../lib/storage';
 
 const props = defineProps<{
   turns: ChatTurn[];
@@ -172,11 +173,7 @@ const { t } = useI18n();
 // The align toggle was removed with its UI (6e50cb7) — reading layout is
 // always centered now. Drop the old persisted preference so users who once
 // picked 'left' aren't frozen on it with no way back.
-try {
-  localStorage.removeItem('kimi-web.content-align');
-} catch {
-  // localStorage unavailable
-}
+safeRemove(STORAGE_KEYS.contentAlign);
 
 const chatPaneRef = ref<InstanceType<typeof ChatPane> | null>(null);
 const emptyComposerRef = ref<{ loadForEdit: (v: string) => void } | null>(null);
diff --git a/apps/kimi-web/src/components/OpenInMenu.vue b/apps/kimi-web/src/components/OpenInMenu.vue
index 35cfd38b96..27e89f135f 100644
--- a/apps/kimi-web/src/components/OpenInMenu.vue
+++ b/apps/kimi-web/src/components/OpenInMenu.vue
@@ -5,6 +5,7 @@
 <script setup lang="ts">
 import { computed, nextTick, onUnmounted, ref } from 'vue';
 import { useI18n } from 'vue-i18n';
+import { safeGetString, safeSetString, STORAGE_KEYS } from '../lib/storage';
 
 const { t } = useI18n();
 
@@ -64,12 +65,12 @@ const visibleTargets = computed(() => {
   return platformTargets.filter((t) => available.has(t.id));
 });
 
-const LAST_TARGET_KEY = 'kimi-web.open-in.last-target';
+const LAST_TARGET_KEY = STORAGE_KEYS.openInLastTarget;
 const lastTargetId = ref<TargetId | null>(null);
 
 function loadLastTarget(): void {
   try {
-    const raw = localStorage.getItem(LAST_TARGET_KEY);
+    const raw = safeGetString(LAST_TARGET_KEY);
     if (raw && visibleTargets.value.some((t) => t.id === raw)) {
       lastTargetId.value = raw as TargetId;
     } else {
@@ -83,7 +84,7 @@ loadLastTarget();
 
 function saveLastTarget(id: TargetId): void {
   try {
-    localStorage.setItem(LAST_TARGET_KEY, id);
+    safeSetString(LAST_TARGET_KEY, id);
   } catch { /* ignore */ }
   lastTargetId.value = id;
 }
diff --git a/apps/kimi-web/src/composables/client/useAppearance.ts b/apps/kimi-web/src/composables/client/useAppearance.ts
new file mode 100644
index 0000000000..1575d838cd
--- /dev/null
+++ b/apps/kimi-web/src/composables/client/useAppearance.ts
@@ -0,0 +1,190 @@
+// apps/kimi-web/src/composables/client/useAppearance.ts
+// Appearance preferences (theme / color scheme / accent / UI font size) and
+// the streaming "fast moon" spinner state. Pure local UI state: only touches
+// storage + the DOM, never rawState or the API. The values are module-level
+// singletons so the whole app shares one instance.
+
+import { ref, watch } from 'vue';
+import { safeGetString, safeSetString, STORAGE_KEYS } from '../../lib/storage';
+
+/** UI theme: 'terminal' = dense line look, 'modern' = bubbles everywhere,
+    'kimi' = the official Kimi design language. */
+export type Theme = 'terminal' | 'modern' | 'kimi';
+
+/** Color scheme: 'light', 'dark', or follow the OS preference ('system'). */
+export type ColorScheme = 'light' | 'dark' | 'system';
+
+/** Accent: 'blue' (Kimi blue, default) or 'mono' (black/white). */
+export type Accent = 'blue' | 'mono';
+
+const ACCENT_VALUES: readonly string[] = ['blue', 'mono'];
+const COLOR_SCHEME_VALUES: readonly string[] = ['light', 'dark', 'system'];
+const UI_FONT_SIZE_DEFAULT = 15;
+const UI_FONT_SIZE_MIN = 12;
+const UI_FONT_SIZE_MAX = 20;
+
+function loadAccent(): Accent {
+  const v = safeGetString(STORAGE_KEYS.accent);
+  if (v && ACCENT_VALUES.includes(v)) return v as Accent;
+  return 'blue';
+}
+
+function applyAccent(a: Accent): void {
+  if (typeof document === 'undefined' || !document.documentElement) return;
+  document.documentElement.dataset.accent = a;
+}
+
+function loadColorScheme(): ColorScheme {
+  const v = safeGetString(STORAGE_KEYS.colorScheme);
+  if (v && COLOR_SCHEME_VALUES.includes(v)) return v as ColorScheme;
+  return 'system';
+}
+
+function applyColorScheme(c: ColorScheme): void {
+  if (typeof document === 'undefined' || !document.documentElement) return;
+  document.documentElement.dataset.colorScheme = c;
+
+  // Mobile browser chrome (status/address bar) follows <meta name=theme-color>.
+  const metas = document.querySelectorAll<HTMLMetaElement>('meta[name="theme-color"]');
+  if (metas.length === 0) return;
+  const pinned = c === 'dark' ? '#0d1117' : c === 'light' ? '#ffffff' : null;
+  metas.forEach((meta) => {
+    const media = meta.getAttribute('media') ?? '';
+    const systemValue = media.includes('dark') ? '#0d1117' : '#ffffff';
+    meta.setAttribute('content', pinned ?? systemValue);
+  });
+}
+
+function loadTheme(): Theme {
+  const v = safeGetString(STORAGE_KEYS.theme);
+  if (v === 'terminal' || v === 'modern' || v === 'kimi') return v;
+  return 'modern';
+}
+
+function applyTheme(t: Theme): void {
+  if (typeof document === 'undefined' || !document.documentElement) return;
+  document.documentElement.dataset.theme = t;
+}
+
+function clampUiFontSize(value: number): number {
+  if (!Number.isFinite(value)) return UI_FONT_SIZE_DEFAULT;
+  return Math.min(UI_FONT_SIZE_MAX, Math.max(UI_FONT_SIZE_MIN, Math.round(value)));
+}
+
+function loadUiFontSize(): number {
+  const v = safeGetString(STORAGE_KEYS.uiFontSize);
+  return v === null ? UI_FONT_SIZE_DEFAULT : clampUiFontSize(Number(v));
+}
+
+function applyUiFontSize(value: number): void {
+  if (typeof document === 'undefined' || !document.documentElement) return;
+  document.documentElement.style.setProperty('--ui-font-size', `${clampUiFontSize(value)}px`);
+}
+
+const theme = ref<Theme>(loadTheme());
+const colorScheme = ref<ColorScheme>(loadColorScheme());
+const accent = ref<Accent>(loadAccent());
+const uiFontSize = ref<number>(loadUiFontSize());
+
+watch(theme, applyTheme, { immediate: true });
+watch(colorScheme, applyColorScheme, { immediate: true });
+watch(accent, applyAccent, { immediate: true });
+watch(uiFontSize, applyUiFontSize, { immediate: true });
+
+function setTheme(t: Theme): void {
+  if (t !== 'terminal' && t !== 'modern' && t !== 'kimi') return;
+  theme.value = t;
+  safeSetString(STORAGE_KEYS.theme, t);
+}
+
+function toggleTheme(): void {
+  setTheme(theme.value === 'modern' ? 'terminal' : 'modern');
+}
+
+function setColorScheme(c: ColorScheme): void {
+  if (!COLOR_SCHEME_VALUES.includes(c)) return;
+  colorScheme.value = c;
+  safeSetString(STORAGE_KEYS.colorScheme, c);
+}
+
+function setAccent(a: Accent): void {
+  if (!ACCENT_VALUES.includes(a)) return;
+  accent.value = a;
+  safeSetString(STORAGE_KEYS.accent, a);
+}
+
+function setUiFontSize(value: number): void {
+  const next = clampUiFontSize(value);
+  uiFontSize.value = next;
+  safeSetString(STORAGE_KEYS.uiFontSize, String(next));
+}
+
+// CSS handles the moon frames; this only flips the spinner between normal and
+// fast classes when the active session is visibly producing content quickly.
+const MOON_FAST_WINDOW_MS = 600;
+const MOON_FAST_MIN_ELAPSED_MS = 250;
+const MOON_FAST_CHECK_INTERVAL_MS = 250;
+const MOON_FAST_HOLD_MS = 1000;
+const MOON_FAST_CHARS_PER_SECOND = 160;
+
+type MoonSpeedSample = { time: number; chars: number };
+
+const fastMoon = ref(false);
+let moonSpeedSamples: MoonSpeedSample[] = [];
+let moonFastResetTimer: ReturnType<typeof setTimeout> | null = null;
+let lastMoonFastCheckAt = -MOON_FAST_CHECK_INTERVAL_MS;
+
+function resetFastMoon(): void {
+  moonSpeedSamples = [];
+  lastMoonFastCheckAt = -MOON_FAST_CHECK_INTERVAL_MS;
+  fastMoon.value = false;
+  if (moonFastResetTimer !== null) {
+    clearTimeout(moonFastResetTimer);
+    moonFastResetTimer = null;
+  }
+}
+
+function holdFastMoon(): void {
+  fastMoon.value = true;
+  if (moonFastResetTimer !== null) clearTimeout(moonFastResetTimer);
+  moonFastResetTimer = setTimeout(() => {
+    moonFastResetTimer = null;
+    moonSpeedSamples = [];
+    lastMoonFastCheckAt = -MOON_FAST_CHECK_INTERVAL_MS;
+    fastMoon.value = false;
+  }, MOON_FAST_HOLD_MS);
+}
+
+function recordMoonDelta(chars: number): void {
+  if (chars <= 0) return;
+  const now = Date.now();
+  moonSpeedSamples.push({ time: now, chars });
+  const cutoff = now - MOON_FAST_WINDOW_MS;
+  moonSpeedSamples = moonSpeedSamples.filter((s) => s.time >= cutoff);
+
+  if (now - lastMoonFastCheckAt < MOON_FAST_CHECK_INTERVAL_MS) return;
+  lastMoonFastCheckAt = now;
+
+  const oldest = moonSpeedSamples[0]?.time ?? now;
+  const elapsed = Math.max(now - oldest, MOON_FAST_MIN_ELAPSED_MS);
+  const totalChars = moonSpeedSamples.reduce((sum, s) => sum + s.chars, 0);
+  const charsPerSecond = (totalChars / elapsed) * 1000;
+  if (charsPerSecond >= MOON_FAST_CHARS_PER_SECOND) holdFastMoon();
+}
+
+export function useAppearance() {
+  return {
+    theme,
+    colorScheme,
+    accent,
+    uiFontSize,
+    fastMoon,
+    setTheme,
+    toggleTheme,
+    setColorScheme,
+    setAccent,
+    setUiFontSize,
+    resetFastMoon,
+    recordMoonDelta,
+  };
+}
diff --git a/apps/kimi-web/src/composables/client/useNotification.ts b/apps/kimi-web/src/composables/client/useNotification.ts
new file mode 100644
index 0000000000..a25cad7448
--- /dev/null
+++ b/apps/kimi-web/src/composables/client/useNotification.ts
@@ -0,0 +1,102 @@
+// apps/kimi-web/src/composables/client/useNotification.ts
+// Browser "turn completed" notification: the on/off preference (persisted) and
+// the OS permission + Notification API. Pure UI action module — it never reads
+// rawState or calls the API. The rawState-dependent bits (is the session active
+// & visible, its title, the click-to-select action) are passed in by the caller
+// via NotifyCompletionCtx.
+
+import { ref } from 'vue';
+import { i18n } from '../../i18n';
+import { safeGetString, safeSetString, STORAGE_KEYS } from '../../lib/storage';
+
+function loadNotify(): boolean {
+  const v = safeGetString(STORAGE_KEYS.notifyOnComplete);
+  return v === null ? true : v === '1';
+}
+
+const notifyOnComplete = ref(loadNotify());
+const notifyPermission = ref<string>(
+  typeof Notification !== 'undefined' ? Notification.permission : 'denied',
+);
+
+/** Enable/disable completion notifications. Enabling requests OS permission;
+    if the user blocks it the preference stays off. */
+async function setNotifyOnComplete(on: boolean): Promise<void> {
+  if (!on) {
+    notifyOnComplete.value = false;
+    safeSetString(STORAGE_KEYS.notifyOnComplete, '0');
+    return;
+  }
+  if (typeof Notification === 'undefined') return;
+  let perm = Notification.permission;
+  if (perm === 'default') {
+    try {
+      perm = await Notification.requestPermission();
+    } catch {
+      // ignore
+    }
+  }
+  notifyPermission.value = perm;
+  if (perm !== 'granted') return; // blocked — leave the toggle off
+  notifyOnComplete.value = true;
+  safeSetString(STORAGE_KEYS.notifyOnComplete, '1');
+}
+
+export interface NotifyCompletionCtx {
+  /** True when the target session is the active one and the page is visible —
+      in which case we suppress the notification. */
+  isActiveAndVisible: boolean;
+  /** Session title used as the notification title. */
+  sessionTitle: string;
+  /** Called when the user clicks the notification (e.g. select the session). */
+  onClick: () => void;
+}
+
+/** Fire a completion notification for a finished session, but only when the
+    caller says the user isn't already looking at it. */
+function maybeNotifyCompletion(sid: string, ctx: NotifyCompletionCtx): void {
+  if (!notifyOnComplete.value) return;
+  if (typeof Notification === 'undefined') return;
+  const perm = Notification.permission;
+  if (perm === 'denied') return;
+  if (perm === 'default') {
+    // Request permission asynchronously; if granted, fire the notification.
+    void Notification.requestPermission().then((p) => {
+      notifyPermission.value = p;
+      if (p === 'granted') fire(sid, ctx);
+    });
+    return;
+  }
+  fire(sid, ctx);
+}
+
+function fire(sid: string, ctx: NotifyCompletionCtx): void {
+  if (ctx.isActiveAndVisible) return;
+  const title = ctx.sessionTitle.trim() || 'Kimi Code';
+  try {
+    const n = new Notification(title, {
+      body: i18n.global.t('settings.notifyBody'),
+      tag: `kimi-complete-${sid}`,
+    });
+    n.onclick = () => {
+      try {
+        window.focus();
+      } catch {
+        // ignore
+      }
+      ctx.onClick();
+      n.close();
+    };
+  } catch {
+    // Notification construction can throw on some platforms — ignore.
+  }
+}
+
+export function useNotification() {
+  return {
+    notifyOnComplete,
+    notifyPermission,
+    setNotifyOnComplete,
+    maybeNotifyCompletion,
+  };
+}
diff --git a/apps/kimi-web/src/composables/useKimiWebClient.ts b/apps/kimi-web/src/composables/useKimiWebClient.ts
index b9b0bbd585..17611fee20 100644
--- a/apps/kimi-web/src/composables/useKimiWebClient.ts
+++ b/apps/kimi-web/src/composables/useKimiWebClient.ts
@@ -6,6 +6,12 @@ import { computed, reactive, ref, watch } from 'vue';
 import { i18n } from '../i18n';
 import { getKimiWebApi } from '../api';
 import { isDaemonApiError, isDaemonNetworkError } from '../api/errors';
+import { safeGetString, safeRemove, safeSetString, STORAGE_KEYS } from '../lib/storage';
+import { useAppearance } from './client/useAppearance';
+import { useNotification } from './client/useNotification';
+
+const appearance = useAppearance();
+const notification = useNotification();
 import type {
   AppApprovalRequest,
   AppConfig,
@@ -65,103 +71,31 @@ import type {
 // Internal reactive state (plain object wrapped in reactive())
 // ---------------------------------------------------------------------------
 
-const PERMISSION_STORAGE_KEY = 'kimi-web.permission';
-const ACTIVE_WORKSPACE_KEY = 'kimi-active-workspace';
-const THINKING_STORAGE_KEY = 'kimi-web.thinking';
-const PLAN_MODE_STORAGE_KEY = 'kimi-web.plan-mode';
-const SWARM_MODE_STORAGE_KEY = 'kimi-web.swarm-mode';
-const GOAL_MODE_STORAGE_KEY = 'kimi-web.goal-mode';
-const THEME_STORAGE_KEY = 'kimi-web.theme';
-const UI_FONT_SIZE_STORAGE_KEY = 'kimi-web.ui-font-size';
-const STARRED_MODELS_STORAGE_KEY = 'kimi-web.starred-models';
-const UNREAD_STORAGE_KEY = 'kimi-web.unread';
-const UI_FONT_SIZE_DEFAULT = 15;
-const UI_FONT_SIZE_MIN = 12;
-const UI_FONT_SIZE_MAX = 20;
+const PERMISSION_STORAGE_KEY = STORAGE_KEYS.permission;
+const ACTIVE_WORKSPACE_KEY = STORAGE_KEYS.activeWorkspace;
+const THINKING_STORAGE_KEY = STORAGE_KEYS.thinking;
+const PLAN_MODE_STORAGE_KEY = STORAGE_KEYS.planMode;
+const SWARM_MODE_STORAGE_KEY = STORAGE_KEYS.swarmMode;
+const GOAL_MODE_STORAGE_KEY = STORAGE_KEYS.goalMode;
+const STARRED_MODELS_STORAGE_KEY = STORAGE_KEYS.starredModels;
+const UNREAD_STORAGE_KEY = STORAGE_KEYS.unread;
 const SESSION_NOT_FOUND_CODE = 40401;
 const PROMPT_NOT_FOUND_CODE = 40402;
-const ONBOARDED_STORAGE_KEY = 'kimi-web.onboarded';
+const ONBOARDED_STORAGE_KEY = STORAGE_KEYS.onboarded;
 const THINKING_LEVELS: readonly ThinkingLevel[] = ['off', 'low', 'medium', 'high', 'xhigh', 'max'];
 
-/** UI theme: 'terminal' = dense line look, 'modern' = bubbles everywhere,
-    'kimi' = the official Kimi design language (Quiet Utility: flat surfaces,
-    kimiDark interaction accent, PingFang/Geist type). */
-export type Theme = 'terminal' | 'modern' | 'kimi';
-
-/** Color scheme: 'light', 'dark', or follow the OS preference ('system'). */
-export type ColorScheme = 'light' | 'dark' | 'system';
+// Appearance types + logic live in ./client/useAppearance; re-exported here so
+// existing `import type { Theme, ColorScheme, Accent } from './useKimiWebClient'`
+// callers keep working.
+export type { Accent, ColorScheme, Theme } from './client/useAppearance';
 
 // The code-font setting was removed with its UI (b8a9e83). Clear the old
 // persisted key so users who once picked a font aren't frozen on it forever.
-try {
-  localStorage.removeItem('kimi-web.code-font');
-} catch {
-  // ignore
-}
-
-// Accent / colour scheme: 'blue' (Kimi blue, default) or 'mono' (black/white,
-// Vercel-style). Reflected onto <html data-accent>; style.css remaps the blue
-// tokens to grayscale for 'mono'. Orthogonal to the terminal/modern theme.
-export type Accent = 'blue' | 'mono';
-const ACCENT_STORAGE_KEY = 'kimi-web.accent';
-const ACCENT_VALUES: readonly string[] = ['blue', 'mono'];
-function loadAccentFromStorage(): Accent {
-  try {
-    const v = localStorage.getItem(ACCENT_STORAGE_KEY);
-    if (v && ACCENT_VALUES.includes(v)) return v as Accent;
-  } catch {
-    // ignore
-  }
-  return 'blue';
-}
-function applyAccentToDocument(a: Accent): void {
-  if (typeof document === 'undefined' || !document.documentElement) return;
-  document.documentElement.dataset.accent = a;
-}
-
-const COLOR_SCHEME_STORAGE_KEY = 'kimi-web.color-scheme';
-const COLOR_SCHEME_VALUES: readonly string[] = ['light', 'dark', 'system'];
-
-function loadColorSchemeFromStorage(): ColorScheme {
-  try {
-    const v = localStorage.getItem(COLOR_SCHEME_STORAGE_KEY);
-    if (v && COLOR_SCHEME_VALUES.includes(v)) return v as ColorScheme;
-  } catch {
-    // ignore
-  }
-  return 'system';
-}
-
-function saveColorSchemeToStorage(v: ColorScheme): void {
-  try {
-    localStorage.setItem(COLOR_SCHEME_STORAGE_KEY, v);
-  } catch {
-    // ignore
-  }
-}
-
-/** Reflect the chosen color scheme onto <html data-color-scheme>. jsdom-safe. */
-function applyColorSchemeToDocument(c: ColorScheme): void {
-  if (typeof document === 'undefined' || !document.documentElement) return;
-  document.documentElement.dataset.colorScheme = c;
-
-  // Mobile browser chrome (status/address bar) follows <meta name=theme-color>.
-  // The static tags in index.html only track the OS preference — when the user
-  // explicitly picks light/dark, pin both media variants to the app's colour
-  // so the chrome doesn't sit in the opposite scheme.
-  const metas = document.querySelectorAll<HTMLMetaElement>('meta[name="theme-color"]');
-  if (metas.length === 0) return;
-  const pinned = c === 'dark' ? '#0d1117' : c === 'light' ? '#ffffff' : null;
-  metas.forEach((meta) => {
-    const media = meta.getAttribute('media') ?? '';
-    const systemValue = media.includes('dark') ? '#0d1117' : '#ffffff';
-    meta.setAttribute('content', pinned ?? systemValue);
-  });
-}
+safeRemove(STORAGE_KEYS.codeFont);
 
 function loadPermissionFromStorage(): PermissionMode {
   try {
-    const v = localStorage.getItem(PERMISSION_STORAGE_KEY);
+    const v = safeGetString(PERMISSION_STORAGE_KEY);
     if (v === 'auto' || v === 'yolo' || v === 'manual') return v;
   } catch {
     // localStorage not available (e.g. jsdom without config)
@@ -171,7 +105,7 @@ function loadPermissionFromStorage(): PermissionMode {
 
 function savePermissionToStorage(mode: PermissionMode): void {
   try {
-    localStorage.setItem(PERMISSION_STORAGE_KEY, mode);
+    safeSetString(PERMISSION_STORAGE_KEY, mode);
   } catch {
     // ignore
   }
@@ -179,7 +113,7 @@ function savePermissionToStorage(mode: PermissionMode): void {
 
 function loadThinkingFromStorage(): ThinkingLevel {
   try {
-    const v = localStorage.getItem(THINKING_STORAGE_KEY);
+    const v = safeGetString(THINKING_STORAGE_KEY);
     if (v && (THINKING_LEVELS as readonly string[]).includes(v)) return v as ThinkingLevel;
   } catch {
     // ignore
@@ -189,7 +123,7 @@ function loadThinkingFromStorage(): ThinkingLevel {
 
 function saveThinkingToStorage(v: ThinkingLevel): void {
   try {
-    localStorage.setItem(THINKING_STORAGE_KEY, v);
+    safeSetString(THINKING_STORAGE_KEY, v);
   } catch {
     // ignore
   }
@@ -197,7 +131,7 @@ function saveThinkingToStorage(v: ThinkingLevel): void {
 
 function loadPlanModeFromStorage(): boolean {
   try {
-    return localStorage.getItem(PLAN_MODE_STORAGE_KEY) === 'true';
+    return safeGetString(PLAN_MODE_STORAGE_KEY) === 'true';
   } catch {
     return false;
   }
@@ -205,7 +139,7 @@ function loadPlanModeFromStorage(): boolean {
 
 function savePlanModeToStorage(v: boolean): void {
   try {
-    localStorage.setItem(PLAN_MODE_STORAGE_KEY, v ? 'true' : 'false');
+    safeSetString(PLAN_MODE_STORAGE_KEY, v ? 'true' : 'false');
   } catch {
     // ignore
   }
@@ -213,7 +147,7 @@ function savePlanModeToStorage(v: boolean): void {
 
 function loadSwarmModeFromStorage(): boolean {
   try {
-    return localStorage.getItem(SWARM_MODE_STORAGE_KEY) === 'true';
+    return safeGetString(SWARM_MODE_STORAGE_KEY) === 'true';
   } catch {
     return false;
   }
@@ -221,7 +155,7 @@ function loadSwarmModeFromStorage(): boolean {
 
 function saveSwarmModeToStorage(v: boolean): void {
   try {
-    localStorage.setItem(SWARM_MODE_STORAGE_KEY, v ? 'true' : 'false');
+    safeSetString(SWARM_MODE_STORAGE_KEY, v ? 'true' : 'false');
   } catch {
     // ignore
   }
@@ -229,7 +163,7 @@ function saveSwarmModeToStorage(v: boolean): void {
 
 function loadGoalModeFromStorage(): boolean {
   try {
-    return localStorage.getItem(GOAL_MODE_STORAGE_KEY) === 'true';
+    return safeGetString(GOAL_MODE_STORAGE_KEY) === 'true';
   } catch {
     return false;
   }
@@ -237,7 +171,7 @@ function loadGoalModeFromStorage(): boolean {
 
 function saveGoalModeToStorage(v: boolean): void {
   try {
-    localStorage.setItem(GOAL_MODE_STORAGE_KEY, v ? 'true' : 'false');
+    safeSetString(GOAL_MODE_STORAGE_KEY, v ? 'true' : 'false');
   } catch {
     // ignore
   }
@@ -249,7 +183,7 @@ function saveGoalModeToStorage(v: boolean): void {
 // the in-memory map starts empty and there is no server-side read cursor.
 function loadUnreadFromStorage(): Record<string, boolean> {
   try {
-    const raw = localStorage.getItem(UNREAD_STORAGE_KEY);
+    const raw = safeGetString(UNREAD_STORAGE_KEY);
     if (!raw) return {};
     const parsed = JSON.parse(raw) as unknown;
     if (!parsed || typeof parsed !== 'object') return {};
@@ -271,7 +205,7 @@ function saveUnreadToStorage(map: Record<string, boolean>): void {
     for (const [id, value] of Object.entries(map)) {
       if (value) out[id] = true;
     }
-    localStorage.setItem(UNREAD_STORAGE_KEY, JSON.stringify(out));
+    safeSetString(UNREAD_STORAGE_KEY, JSON.stringify(out));
   } catch {
     // ignore
   }
@@ -279,7 +213,7 @@ function saveUnreadToStorage(map: Record<string, boolean>): void {
 
 function loadStarredModelsFromStorage(): string[] {
   try {
-    const raw = localStorage.getItem(STARRED_MODELS_STORAGE_KEY);
+    const raw = safeGetString(STARRED_MODELS_STORAGE_KEY);
     if (!raw) return [];
     const parsed = JSON.parse(raw);
     if (Array.isArray(parsed) && parsed.every((item) => typeof item === 'string')) {
@@ -293,62 +227,15 @@ function loadStarredModelsFromStorage(): string[] {
 
 function saveStarredModelsToStorage(v: string[]): void {
   try {
-    localStorage.setItem(STARRED_MODELS_STORAGE_KEY, JSON.stringify(v));
-  } catch {
-    // ignore
-  }
-}
-
-function loadThemeFromStorage(): Theme {
-  try {
-    const v = localStorage.getItem(THEME_STORAGE_KEY);
-    if (v === 'terminal' || v === 'modern' || v === 'kimi') return v;
-  } catch {
-    // ignore
-  }
-  // Modern is the default for new users (no stored choice); the onboarding screen
-  // confirms/changes it. Existing users keep whatever they persisted.
-  return 'modern';
-}
-
-function saveThemeToStorage(v: Theme): void {
-  try {
-    localStorage.setItem(THEME_STORAGE_KEY, v);
+    safeSetString(STARRED_MODELS_STORAGE_KEY, JSON.stringify(v));
   } catch {
     // ignore
   }
 }
 
-function clampUiFontSize(value: number): number {
-  if (!Number.isFinite(value)) return UI_FONT_SIZE_DEFAULT;
-  return Math.min(UI_FONT_SIZE_MAX, Math.max(UI_FONT_SIZE_MIN, Math.round(value)));
-}
-
-function loadUiFontSizeFromStorage(): number {
-  try {
-    const v = localStorage.getItem(UI_FONT_SIZE_STORAGE_KEY);
-    return v === null ? UI_FONT_SIZE_DEFAULT : clampUiFontSize(Number(v));
-  } catch {
-    return UI_FONT_SIZE_DEFAULT;
-  }
-}
-
-function saveUiFontSizeToStorage(value: number): void {
-  try {
-    localStorage.setItem(UI_FONT_SIZE_STORAGE_KEY, String(clampUiFontSize(value)));
-  } catch {
-    // ignore
-  }
-}
-
-function applyUiFontSizeToDocument(value: number): void {
-  if (typeof document === 'undefined' || !document.documentElement) return;
-  document.documentElement.style.setProperty('--ui-font-size', `${clampUiFontSize(value)}px`);
-}
-
 function loadActiveWorkspaceFromStorage(): string | null {
   try {
-    return localStorage.getItem(ACTIVE_WORKSPACE_KEY);
+    return safeGetString(ACTIVE_WORKSPACE_KEY);
   } catch {
     return null;
   }
@@ -359,11 +246,11 @@ function loadActiveWorkspaceFromStorage(): string | null {
 // and mergedWorkspaces would otherwise re-derive it from those sessions' cwds).
 // History is untouched — only the sidebar entry is hidden — so this is persisted
 // per browser, keyed by root path.
-const HIDDEN_WORKSPACES_KEY = 'kimi-web.hidden-workspaces';
+const HIDDEN_WORKSPACES_KEY = STORAGE_KEYS.hiddenWorkspaces;
 
 function loadHiddenWorkspacesFromStorage(): string[] {
   try {
-    const v = localStorage.getItem(HIDDEN_WORKSPACES_KEY);
+    const v = safeGetString(HIDDEN_WORKSPACES_KEY);
     if (!v) return [];
     const parsed = JSON.parse(v);
     return Array.isArray(parsed) ? parsed.filter((x): x is string => typeof x === 'string') : [];
@@ -374,7 +261,7 @@ function loadHiddenWorkspacesFromStorage(): string[] {
 
 function saveHiddenWorkspacesToStorage(roots: string[]): void {
   try {
-    localStorage.setItem(HIDDEN_WORKSPACES_KEY, JSON.stringify(roots));
+    safeSetString(HIDDEN_WORKSPACES_KEY, JSON.stringify(roots));
   } catch {
     // ignore
   }
@@ -382,7 +269,7 @@ function saveHiddenWorkspacesToStorage(roots: string[]): void {
 
 function saveActiveWorkspaceToStorage(id: string): void {
   try {
-    localStorage.setItem(ACTIVE_WORKSPACE_KEY, id);
+    safeSetString(ACTIVE_WORKSPACE_KEY, id);
   } catch {
     // ignore
   }
@@ -525,20 +412,6 @@ const starredModelIds = ref<string[]>(loadStarredModelsFromStorage());
 const skillsBySession = ref<Record<string, AppSkill[]>>({});
 const providers = ref<AppProvider[]>([]);
 
-// CSS handles the moon frames; this only flips the spinner between normal and
-// fast classes when the active session is visibly producing content quickly.
-const MOON_FAST_WINDOW_MS = 600;
-const MOON_FAST_MIN_ELAPSED_MS = 250;
-const MOON_FAST_CHECK_INTERVAL_MS = 250;
-const MOON_FAST_HOLD_MS = 1000;
-const MOON_FAST_CHARS_PER_SECOND = 160;
-
-type MoonSpeedSample = { time: number; chars: number };
-const fastMoon = ref(false);
-let moonSpeedSamples: MoonSpeedSample[] = [];
-let moonFastResetTimer: ReturnType<typeof setTimeout> | null = null;
-let lastMoonFastCheckAt = -MOON_FAST_CHECK_INTERVAL_MS;
-
 // Background task output polling — mirrors TUI's 1-second refresh.
 const TASK_OUTPUT_POLL_INTERVAL_MS = 1000;
 const TASK_OUTPUT_POLL_BYTES = 4096;
@@ -547,44 +420,6 @@ let taskOutputPollTimer: ReturnType<typeof setInterval> | null = null;
 let lastPolledSessionId: string | undefined;
 let fetchedTerminalTaskOutputIds = new Set<string>();
 
-function resetFastMoon(): void {
-  moonSpeedSamples = [];
-  lastMoonFastCheckAt = -MOON_FAST_CHECK_INTERVAL_MS;
-  fastMoon.value = false;
-  if (moonFastResetTimer !== null) {
-    clearTimeout(moonFastResetTimer);
-    moonFastResetTimer = null;
-  }
-}
-
-function holdFastMoon(): void {
-  fastMoon.value = true;
-  if (moonFastResetTimer !== null) clearTimeout(moonFastResetTimer);
-  moonFastResetTimer = setTimeout(() => {
-    moonFastResetTimer = null;
-    moonSpeedSamples = [];
-    lastMoonFastCheckAt = -MOON_FAST_CHECK_INTERVAL_MS;
-    fastMoon.value = false;
-  }, MOON_FAST_HOLD_MS);
-}
-
-function recordMoonDelta(chars: number): void {
-  if (chars <= 0) return;
-  const now = Date.now();
-  moonSpeedSamples.push({ time: now, chars });
-  const cutoff = now - MOON_FAST_WINDOW_MS;
-  moonSpeedSamples = moonSpeedSamples.filter((s) => s.time >= cutoff);
-
-  if (now - lastMoonFastCheckAt < MOON_FAST_CHECK_INTERVAL_MS) return;
-  lastMoonFastCheckAt = now;
-
-  const oldest = moonSpeedSamples[0]?.time ?? now;
-  const elapsed = Math.max(now - oldest, MOON_FAST_MIN_ELAPSED_MS);
-  const totalChars = moonSpeedSamples.reduce((sum, s) => sum + s.chars, 0);
-  const charsPerSecond = (totalChars / elapsed) * 1000;
-  if (charsPerSecond >= MOON_FAST_CHARS_PER_SECOND) holdFastMoon();
-}
-
 // Model picked while in the "new session draft" state (onboarding composer —
 // no backend session exists yet, so POST /profile has nothing to target).
 // Applied and cleared when the first prompt creates the session.
@@ -666,57 +501,21 @@ function persistSessionProfile(patch: {
     });
 }
 
-// ---------------------------------------------------------------------------
-// Theme (Terminal default vs Modern bubbles). Persisted to localStorage and
-// mirrored onto <html data-theme> so fixed/teleported dialogs + sheets inherit.
-// ---------------------------------------------------------------------------
-const theme = ref<Theme>(loadThemeFromStorage());
-
-/** Reflect the active theme onto <html data-theme>. jsdom-safe. */
-function applyThemeToDocument(t: Theme): void {
-  if (typeof document === 'undefined' || !document.documentElement) return;
-  document.documentElement.dataset.theme = t;
-}
-
-// Sync on every change AND immediately (so the very first paint is themed).
-watch(theme, applyThemeToDocument, { immediate: true });
-
-/** Set the active theme and persist it. */
-function setTheme(t: Theme): void {
-  if (t !== 'terminal' && t !== 'modern' && t !== 'kimi') return;
-  theme.value = t;
-  saveThemeToStorage(t);
-}
-
-/** Flip Terminal ↔ Modern. */
-function toggleTheme(): void {
-  setTheme(theme.value === 'modern' ? 'terminal' : 'modern');
-}
-
-const uiFontSize = ref<number>(loadUiFontSizeFromStorage());
-watch(uiFontSize, applyUiFontSizeToDocument, { immediate: true });
-
-function setUiFontSize(value: number): void {
-  const next = clampUiFontSize(value);
-  uiFontSize.value = next;
-  saveUiFontSizeToStorage(next);
-}
-
 // ---------------------------------------------------------------------------
 // Beta: proportional conversation TOC with viewport indicator and hover tooltip.
 // Default off; persisted per browser.
 // ---------------------------------------------------------------------------
-const BETA_TOC_STORAGE_KEY = 'kimi-web.beta-toc';
+const BETA_TOC_STORAGE_KEY = STORAGE_KEYS.betaToc;
 function loadBetaTocFromStorage(): boolean {
   try {
-    return localStorage.getItem(BETA_TOC_STORAGE_KEY) === 'true';
+    return safeGetString(BETA_TOC_STORAGE_KEY) === 'true';
   } catch {
     return false;
   }
 }
 function saveBetaTocToStorage(v: boolean): void {
   try {
-    localStorage.setItem(BETA_TOC_STORAGE_KEY, v ? 'true' : 'false');
+    safeSetString(BETA_TOC_STORAGE_KEY, v ? 'true' : 'false');
   } catch {
     // ignore
   }
@@ -727,110 +526,6 @@ function setBetaToc(v: boolean): void {
   saveBetaTocToStorage(v);
 }
 
-// ---------------------------------------------------------------------------
-// Color scheme (light / dark / system). Persisted and mirrored onto
-// <html data-color-scheme> so CSS can switch variables.
-// ---------------------------------------------------------------------------
-const colorScheme = ref<ColorScheme>(loadColorSchemeFromStorage());
-
-watch(colorScheme, applyColorSchemeToDocument, { immediate: true });
-
-function setColorScheme(c: ColorScheme): void {
-  if (!COLOR_SCHEME_VALUES.includes(c)) return;
-  colorScheme.value = c;
-  saveColorSchemeToStorage(c);
-}
-
-const accent = ref<Accent>(loadAccentFromStorage());
-watch(accent, applyAccentToDocument, { immediate: true });
-function setAccent(a: Accent): void {
-  if (!ACCENT_VALUES.includes(a)) return;
-  accent.value = a;
-  try {
-    localStorage.setItem(ACCENT_STORAGE_KEY, a);
-  } catch {
-    // ignore
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Browser system notification on turn completion. Default on; the preference
-// is persisted per browser, and allowing notifications requires OS permission.
-// ---------------------------------------------------------------------------
-const NOTIFY_STORAGE_KEY = 'kimi-web.notify-on-complete';
-function loadNotifyFromStorage(): boolean {
-  try {
-    const v = localStorage.getItem(NOTIFY_STORAGE_KEY);
-    return v === null ? true : v === '1';
-  } catch {
-    return true;
-  }
-}
-const notifyOnComplete = ref(loadNotifyFromStorage());
-const notifyPermission = ref<string>(
-  typeof Notification !== 'undefined' ? Notification.permission : 'denied',
-);
-
-/** Enable/disable completion notifications. Enabling requests OS permission;
-    if the user blocks it the preference stays off. */
-async function setNotifyOnComplete(on: boolean): Promise<void> {
-  if (!on) {
-    notifyOnComplete.value = false;
-    try { localStorage.setItem(NOTIFY_STORAGE_KEY, '0'); } catch { /* ignore */ }
-    return;
-  }
-  if (typeof Notification === 'undefined') return;
-  let perm = Notification.permission;
-  if (perm === 'default') {
-    try { perm = await Notification.requestPermission(); } catch { /* ignore */ }
-  }
-  notifyPermission.value = perm;
-  if (perm !== 'granted') return; // blocked — leave the toggle off
-  notifyOnComplete.value = true;
-  try { localStorage.setItem(NOTIFY_STORAGE_KEY, '1'); } catch { /* ignore */ }
-}
-
-/** Fire a completion notification for a finished session, but only when the
-    user isn't already looking at it (page hidden, or a different session). */
-function maybeNotifyCompletion(sid: string): void {
-  if (!notifyOnComplete.value) return;
-  if (typeof Notification === 'undefined') return;
-  const perm = Notification.permission;
-  if (perm === 'denied') return;
-  if (perm === 'default') {
-    // Request permission asynchronously; if granted, fire the notification.
-    void Notification.requestPermission().then((p) => {
-      notifyPermission.value = p;
-      if (p === 'granted') fireCompletionNotification(sid);
-    });
-    return;
-  }
-  fireCompletionNotification(sid);
-}
-
-function fireCompletionNotification(sid: string): void {
-  const isActiveAndVisible =
-    sid === rawState.activeSessionId &&
-    typeof document !== 'undefined' &&
-    document.visibilityState === 'visible';
-  if (isActiveAndVisible) return;
-  const session = rawState.sessions.find((s) => s.id === sid);
-  const title = session?.title?.trim() || 'Kimi Code';
-  try {
-    const n = new Notification(title, {
-      body: i18n.global.t('settings.notifyBody'),
-      tag: `kimi-complete-${sid}`,
-    });
-    n.onclick = () => {
-      try { window.focus(); } catch { /* ignore */ }
-      void selectSession(sid);
-      n.close();
-    };
-  } catch {
-    // Notification construction can throw on some platforms — ignore.
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Onboarding: a "has the user been onboarded" flag that gates the first-run
 // onboarding screen (preferences: language + theme). Persisted; can be reset to
@@ -838,7 +533,7 @@ function fireCompletionNotification(sid: string): void {
 // ---------------------------------------------------------------------------
 function loadStringFromStorage(key: string): string {
   try {
-    return localStorage.getItem(key) ?? '';
+    return safeGetString(key) ?? '';
   } catch {
     return '';
   }
@@ -847,7 +542,7 @@ const onboarded = ref<boolean>(loadStringFromStorage(ONBOARDED_STORAGE_KEY) ===
 function setOnboarded(done: boolean): void {
   onboarded.value = done;
   try {
-    localStorage.setItem(ONBOARDED_STORAGE_KEY, done ? '1' : '0');
+    safeSetString(ONBOARDED_STORAGE_KEY, done ? '1' : '0');
   } catch {
     /* ignore */
   }
@@ -985,7 +680,7 @@ function connectEventsIfNeeded(): void {
       }
 
       if (appEvent.type === 'assistantDelta' && meta.sessionId === rawState.activeSessionId) {
-        recordMoonDelta((appEvent.delta.text?.length ?? 0) + (appEvent.delta.thinking?.length ?? 0));
+        appearance.recordMoonDelta((appEvent.delta.text?.length ?? 0) + (appEvent.delta.thinking?.length ?? 0));
       }
 
       // Turn-end cleanup for the session the event belongs to — including
@@ -2622,7 +2317,7 @@ function onSessionIdle(sid: string): void {
   // For the session on screen, refresh git status (edits the agent just made)
   // and runtime status (model/context usage may have changed this turn).
   if (sid === rawState.activeSessionId) {
-    resetFastMoon();
+    appearance.resetFastMoon();
     void loadGitStatus(sid);
     void refreshSessionStatus(sid);
   } else {
@@ -2633,7 +2328,16 @@ function onSessionIdle(sid: string): void {
   }
 
   // Browser notification when the user isn't watching this session.
-  maybeNotifyCompletion(sid);
+  notification.maybeNotifyCompletion(sid, {
+    isActiveAndVisible:
+      sid === rawState.activeSessionId &&
+      typeof document !== 'undefined' &&
+      document.visibilityState === 'visible',
+    sessionTitle: rawState.sessions.find((s) => s.id === sid)?.title ?? '',
+    onClick: () => {
+      void selectSession(sid);
+    },
+  });
 
   const queue = rawState.queuedBySession[sid] ?? [];
   if (queue.length === 0) return;
@@ -2930,7 +2634,7 @@ function applyWorkspaceEvent(event: WorkspaceLifecycleEvent): void {
     if (nextWorkspace) saveActiveWorkspaceToStorage(nextWorkspace);
     else {
       try {
-        localStorage.removeItem(ACTIVE_WORKSPACE_KEY);
+        safeRemove(ACTIVE_WORKSPACE_KEY);
       } catch {
         // ignore
       }
@@ -3194,7 +2898,7 @@ async function selectSession(
     writeSessionUrl(sessionId, opts?.urlMode ?? 'push');
     rawState.sessionLoading = !messagesLoaded && !knownEmpty;
     rawState.activeSessionId = sessionId;
-    resetFastMoon();
+    appearance.resetFastMoon();
     // Opening a session clears its unread dot.
     if (rawState.unreadBySession[sessionId]) {
       rawState.unreadBySession = { ...rawState.unreadBySession, [sessionId]: false };
@@ -3813,7 +3517,7 @@ async function deleteWorkspace(id: string): Promise<void> {
     rawState.activeWorkspaceId = nextWorkspace;
     if (nextWorkspace) saveActiveWorkspaceToStorage(nextWorkspace);
     else {
-      try { localStorage.removeItem(ACTIVE_WORKSPACE_KEY); } catch { /* ignore */ }
+      try { safeRemove(ACTIVE_WORKSPACE_KEY); } catch { /* ignore */ }
     }
   }
   if (removingActiveWorkspace || activeSessionInRemovedWorkspace) {
@@ -4393,7 +4097,7 @@ export function useKimiWebClient() {
     questions,
     activity,
     isSending,
-    fastMoon,
+    fastMoon: appearance.fastMoon,
 
     // Model + Provider reactive state
     models,
@@ -4401,25 +4105,25 @@ export function useKimiWebClient() {
     providers,
 
     // Theme
-    theme,
-    setTheme,
-    toggleTheme,
-    uiFontSize,
-    setUiFontSize,
+    theme: appearance.theme,
+    setTheme: appearance.setTheme,
+    toggleTheme: appearance.toggleTheme,
+    uiFontSize: appearance.uiFontSize,
+    setUiFontSize: appearance.setUiFontSize,
 
     // Beta features
     betaToc,
     setBetaToc,
 
     // Color scheme
-    colorScheme,
-    setColorScheme,
-
-    accent,
-    setAccent,
-    notifyOnComplete,
-    notifyPermission,
-    setNotifyOnComplete,
+    colorScheme: appearance.colorScheme,
+    setColorScheme: appearance.setColorScheme,
+
+    accent: appearance.accent,
+    setAccent: appearance.setAccent,
+    notifyOnComplete: notification.notifyOnComplete,
+    notifyPermission: notification.notifyPermission,
+    setNotifyOnComplete: notification.setNotifyOnComplete,
     onboarded,
     setOnboarded,
 
diff --git a/apps/kimi-web/src/composables/useResizable.ts b/apps/kimi-web/src/composables/useResizable.ts
index ed6b4dbbb5..41c9d8d60d 100644
--- a/apps/kimi-web/src/composables/useResizable.ts
+++ b/apps/kimi-web/src/composables/useResizable.ts
@@ -5,6 +5,7 @@
 // dragging). Used by the sidebar session column drag handle.
 
 import { onBeforeUnmount, ref, type Ref } from 'vue';
+import { safeGetString, safeSetString } from '../lib/storage';
 
 export interface UseResizableOptions {
   /** localStorage key the chosen width is persisted under. */
@@ -34,7 +35,7 @@ export interface UseResizable {
 
 function readStored(key: string): number | null {
   try {
-    const raw = localStorage.getItem(key);
+    const raw = safeGetString(key);
     if (raw === null) return null;
     const n = Number(raw);
     return Number.isFinite(n) ? n : null;
@@ -45,7 +46,7 @@ function readStored(key: string): number | null {
 
 function writeStored(key: string, value: number): void {
   try {
-    localStorage.setItem(key, String(value));
+    safeSetString(key, String(value));
   } catch {
     // localStorage unavailable (e.g. private mode) — width still works in-memory
   }
diff --git a/apps/kimi-web/src/debug/trace.ts b/apps/kimi-web/src/debug/trace.ts
index 3e43f68297..925dc70fd4 100644
--- a/apps/kimi-web/src/debug/trace.ts
+++ b/apps/kimi-web/src/debug/trace.ts
@@ -8,6 +8,7 @@
 // request/WS behavior: callers pass data in, errors here must not propagate.
 
 import { ref, shallowRef } from 'vue';
+import { safeGetString, STORAGE_KEYS } from '../lib/storage';
 
 export type TraceSource = 'rest' | 'ws' | 'client';
 
@@ -72,11 +73,7 @@ export function isTraceEnabled(): boolean {
     // location unavailable
   }
   if (!enabled) {
-    try {
-      enabled = localStorage.getItem('kimi-web.debug') === '1';
-    } catch {
-      // localStorage unavailable
-    }
+    enabled = safeGetString(STORAGE_KEYS.debug) === '1';
   }
   enabledCache = enabled;
   return enabled;
diff --git a/apps/kimi-web/src/i18n/index.ts b/apps/kimi-web/src/i18n/index.ts
index a678761f8e..da6a33585b 100644
--- a/apps/kimi-web/src/i18n/index.ts
+++ b/apps/kimi-web/src/i18n/index.ts
@@ -1,7 +1,6 @@
 import { createI18n } from 'vue-i18n';
 import { messages } from './locales';
-
-const STORAGE_KEY = 'kimi-locale';
+import { safeGetString, safeSetString, STORAGE_KEYS } from '../lib/storage';
 
 export const availableLocales = [
   { code: 'en', label: 'English' },
@@ -11,7 +10,7 @@ export const availableLocales = [
 export type LocaleCode = (typeof availableLocales)[number]['code'];
 
 function detect(): LocaleCode {
-  const stored = globalThis.localStorage?.getItem(STORAGE_KEY);
+  const stored = safeGetString(STORAGE_KEYS.locale);
   if (stored === 'en' || stored === 'zh') return stored;
   return globalThis.navigator?.language?.toLowerCase().startsWith('zh') ? 'zh' : 'en';
 }
@@ -25,7 +24,7 @@ export const i18n = createI18n({
 
 export function setLocale(l: LocaleCode): void {
   i18n.global.locale.value = l;
-  globalThis.localStorage?.setItem(STORAGE_KEY, l);
+  safeSetString(STORAGE_KEYS.locale, l);
 }
 
 export default i18n;
diff --git a/apps/kimi-web/src/lib/storage.ts b/apps/kimi-web/src/lib/storage.ts
new file mode 100644
index 0000000000..c45bfab02f
--- /dev/null
+++ b/apps/kimi-web/src/lib/storage.ts
@@ -0,0 +1,84 @@
+// apps/kimi-web/src/lib/storage.ts
+// Thin, safe wrapper over localStorage: raw read/write/remove plus JSON
+// helpers, each guarded with try/catch. No validation, clamping, or enum
+// checks here — those stay at call sites. Read helpers return null when the
+// key is missing or storage is unavailable, so callers decide their own
+// fallback. Centralizes the persisted key strings so each key has a single
+// source of truth.
+
+export const STORAGE_KEYS = {
+  // useKimiWebClient
+  permission: 'kimi-web.permission',
+  activeWorkspace: 'kimi-active-workspace',
+  thinking: 'kimi-web.thinking',
+  planMode: 'kimi-web.plan-mode',
+  swarmMode: 'kimi-web.swarm-mode',
+  goalMode: 'kimi-web.goal-mode',
+  theme: 'kimi-web.theme',
+  uiFontSize: 'kimi-web.ui-font-size',
+  starredModels: 'kimi-web.starred-models',
+  unread: 'kimi-web.unread',
+  onboarded: 'kimi-web.onboarded',
+  accent: 'kimi-web.accent',
+  colorScheme: 'kimi-web.color-scheme',
+  hiddenWorkspaces: 'kimi-web.hidden-workspaces',
+  betaToc: 'kimi-web.beta-toc',
+  notifyOnComplete: 'kimi-web.notify-on-complete',
+  // cross-file
+  locale: 'kimi-locale',
+  clientId: 'kimi-web.client-id',
+  debug: 'kimi-web.debug',
+  openInLastTarget: 'kimi-web.open-in.last-target',
+  sidebarCollapsed: 'kimi-web.sidebar-collapsed',
+  sidebarWidth: 'kimi-web.sidebar-width',
+  // deprecated cleanups (kept so the removals still fire for old users)
+  codeFont: 'kimi-web.code-font',
+  contentAlign: 'kimi-web.content-align',
+} as const;
+
+/** Per-session composer draft key. */
+export function draftStorageKey(sid: string | undefined): string {
+  return `kimi-web.draft.${sid && sid.length > 0 ? sid : '__new__'}`;
+}
+
+export function safeGetString(key: string): string | null {
+  try {
+    return globalThis.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+export function safeSetString(key: string, value: string): void {
+  try {
+    globalThis.localStorage.setItem(key, value);
+  } catch {
+    // storage unavailable (private mode, quota, etc.) — ignore
+  }
+}
+
+export function safeRemove(key: string): void {
+  try {
+    globalThis.localStorage.removeItem(key);
+  } catch {
+    // ignore
+  }
+}
+
+export function safeGetJson<T>(key: string): T | null {
+  const raw = safeGetString(key);
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+export function safeSetJson(key: string, value: unknown): void {
+  try {
+    globalThis.localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+    // ignore
+  }
+}
diff --git a/apps/kimi-web/test/storage-logic.test.ts b/apps/kimi-web/test/storage-logic.test.ts
new file mode 100644
index 0000000000..4c72223291
--- /dev/null
+++ b/apps/kimi-web/test/storage-logic.test.ts
@@ -0,0 +1,137 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  STORAGE_KEYS,
+  draftStorageKey,
+  safeGetJson,
+  safeGetString,
+  safeRemove,
+  safeSetJson,
+  safeSetString,
+} from '../src/lib/storage';
+
+function createMemoryStorage(): Storage {
+  const data = new Map<string, string>();
+  return {
+    get length() {
+      return data.size;
+    },
+    clear() {
+      data.clear();
+    },
+    getItem(key: string) {
+      return data.get(key) ?? null;
+    },
+    key(index: number) {
+      return Array.from(data.keys()).at(index) ?? null;
+    },
+    removeItem(key: string) {
+      data.delete(key);
+    },
+    setItem(key: string, value: string) {
+      data.set(key, String(value));
+    },
+  };
+}
+
+function installStorage(storage: Storage): void {
+  Object.defineProperty(globalThis, 'localStorage', {
+    configurable: true,
+    value: storage,
+  });
+}
+
+let backing: Storage;
+
+beforeEach(() => {
+  backing = createMemoryStorage();
+  installStorage(backing);
+});
+
+afterEach(() => {
+  installStorage(createMemoryStorage());
+});
+
+describe('safeGetString / safeSetString', () => {
+  it('round-trips a value', () => {
+    safeSetString('k', 'hello');
+    expect(safeGetString('k')).toBe('hello');
+  });
+
+  it('returns null for a missing key', () => {
+    expect(safeGetString('missing')).toBeNull();
+  });
+
+  it('overwrites an existing value', () => {
+    safeSetString('k', 'a');
+    safeSetString('k', 'b');
+    expect(safeGetString('k')).toBe('b');
+  });
+});
+
+describe('safeRemove', () => {
+  it('removes an existing key', () => {
+    safeSetString('k', 'v');
+    safeRemove('k');
+    expect(safeGetString('k')).toBeNull();
+  });
+
+  it('is a no-op for a missing key', () => {
+    expect(() => safeRemove('missing')).not.toThrow();
+  });
+});
+
+describe('safeGetJson / safeSetJson', () => {
+  it('round-trips a JSON value', () => {
+    safeSetJson('k', { a: 1, b: [2, 3] });
+    expect(safeGetJson('k')).toEqual({ a: 1, b: [2, 3] });
+  });
+
+  it('returns null for a missing key', () => {
+    expect(safeGetJson('missing')).toBeNull();
+  });
+
+  it('returns null when the stored value is not valid JSON', () => {
+    safeSetString('k', '{not json');
+    expect(safeGetJson('k')).toBeNull();
+  });
+});
+
+describe('error swallowing', () => {
+  it('safeGetString returns null when storage throws', () => {
+    const throwing = createMemoryStorage();
+    throwing.getItem = () => {
+      throw new Error('denied');
+    };
+    installStorage(throwing);
+    expect(safeGetString('k')).toBeNull();
+  });
+
+  it('safeSetString does not throw when storage throws', () => {
+    const throwing = createMemoryStorage();
+    throwing.setItem = () => {
+      throw new Error('quota');
+    };
+    installStorage(throwing);
+    expect(() => safeSetString('k', 'v')).not.toThrow();
+  });
+});
+
+describe('draftStorageKey', () => {
+  it('uses the session id when present', () => {
+    expect(draftStorageKey('abc')).toBe('kimi-web.draft.abc');
+  });
+
+  it('falls back to __new__ when sid is empty/undefined', () => {
+    expect(draftStorageKey(undefined)).toBe('kimi-web.draft.__new__');
+    expect(draftStorageKey('')).toBe('kimi-web.draft.__new__');
+  });
+});
+
+describe('STORAGE_KEYS', () => {
+  it('keeps the legacy key strings unchanged', () => {
+    expect(STORAGE_KEYS.theme).toBe('kimi-web.theme');
+    expect(STORAGE_KEYS.activeWorkspace).toBe('kimi-active-workspace');
+    expect(STORAGE_KEYS.notifyOnComplete).toBe('kimi-web.notify-on-complete');
+    expect(STORAGE_KEYS.locale).toBe('kimi-locale');
+  });
+});