refactor(admin): migrate ad-hoc stores to Zustand + Jotai

Adopts lobe-chat's slice pattern (externalized action class, flattenActions,
subscribeWithSelector + shallow). Each store gets initial-state / action /
store / index split into its own folder.

- focus-scope, context-menu, modal-imperative, codemirror/editor-store →
  Zustand, with imperative wrappers preserved so callers like present.ts
  and the ContextMenu trigger keep their existing API.
- theme, codemirror/editor-setting → Zustand + persist middleware. The
  hand-rolled localStorage + custom-event broadcasts are gone; the matchMedia
  listener in theme.ts stays on useSyncExternalStore (DOM source).
- codemirror/image-popover-state → Jotai atom (small, transient).
- Add src/store/{types,utils/flatten-actions}.ts shared by every slice.

useSyncExternalStore now only remains in theme.ts for matchMedia.

Author: Innei

apps/admin/package.json

@@ -92,6 +92,7 @@
     "path-browserify": "1.0.1",
     "qier-progress": "1.0.4",
     "qs": "6.15.0",
+    "jotai": "2.20.0",
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "react-resizable-panels": "4.11.1",
@@ -102,7 +103,8 @@
     "tinykeys": "4.0.0",
     "validator": "13.15.26",
     "xss": "1.0.15",
-    "zod": "4.3.6"
+    "zod": "4.3.6",
+    "zustand": "5.0.13"
   },
   "devDependencies": {
     "@babel/core": "7.29.0",

apps/admin/src/store/theme/action.ts

@@ -0,0 +1,29 @@
+import type { StoreSetter } from '~/store/types'
+import type { ThemeMode } from './initial-state'
+import type { ThemeStore } from './store'
+
+type Setter = StoreSetter<ThemeStore>
+
+export class ThemeActionImpl {
+  readonly #get: () => ThemeStore
+  readonly #set: Setter
+
+  constructor(set: Setter, get: () => ThemeStore, _api?: unknown) {
+    void _api
+    this.#set = set
+    this.#get = get
+  }
+
+  setThemeMode = (themeMode: ThemeMode): void => {
+    if (this.#get().themeMode === themeMode) return
+    this.#set({ themeMode }, false, 'theme/setThemeMode')
+  }
+}
+
+export const createThemeSlice = (
+  set: Setter,
+  get: () => ThemeStore,
+  api: unknown,
+) => new ThemeActionImpl(set, get, api)
+
+export type ThemeAction = Pick<ThemeActionImpl, keyof ThemeActionImpl>

apps/admin/src/store/theme/index.ts

@@ -0,0 +1,4 @@
+export type { ThemeAction } from './action'
+export type { ThemeMode, ThemeState } from './initial-state'
+export type { ThemeStore } from './store'
+export { getThemeStoreState, useThemeStore } from './store'

apps/admin/src/store/theme/initial-state.ts

@@ -0,0 +1,9 @@
+export type ThemeMode = 'dark' | 'light' | 'system'
+
+export interface ThemeState {
+  themeMode: ThemeMode
+}
+
+export const initialThemeState: ThemeState = {
+  themeMode: 'system',
+}

apps/admin/src/store/theme/store.ts

@@ -0,0 +1,67 @@
+import { persist, subscribeWithSelector } from 'zustand/middleware'
+import { shallow } from 'zustand/shallow'
+import { createWithEqualityFn } from 'zustand/traditional'
+import type { StateCreator } from 'zustand/vanilla'
+import type { ThemeAction } from './action'
+import type { ThemeMode, ThemeState } from './initial-state'
+
+import { flattenActions } from '~/store/utils/flatten-actions'
+
+import { createThemeSlice } from './action'
+import { initialThemeState } from './initial-state'
+
+export interface ThemeStore extends ThemeState, ThemeAction {}
+
+const STORAGE_KEY = 'theme-mode'
+
+const isValidMode = (value: unknown): value is ThemeMode =>
+  value === 'dark' || value === 'light' || value === 'system'
+
+const createStore: StateCreator<ThemeStore> = (...params) => ({
+  ...initialThemeState,
+  ...flattenActions<ThemeAction>([createThemeSlice(...params)]),
+})
+
+export const useThemeStore = createWithEqualityFn<ThemeStore>()(
+  subscribeWithSelector(
+    persist(createStore, {
+      name: STORAGE_KEY,
+      partialize: (state) => ({ themeMode: state.themeMode }),
+      // Legacy storage layout: just the raw mode string (no JSON envelope).
+      // Read it on load and write back via the modern envelope on first set.
+      storage: {
+        getItem: (name) => {
+          if (typeof window === 'undefined') return null
+          const raw = window.localStorage.getItem(name)
+          if (!raw) return null
+          const stripped = raw.replace(/^"|"$/g, '')
+          if (isValidMode(stripped)) {
+            return { state: { themeMode: stripped }, version: 0 }
+          }
+          try {
+            return JSON.parse(raw)
+          } catch {
+            return null
+          }
+        },
+        setItem: (name, value) => {
+          if (typeof window === 'undefined') return
+          // Persist `system` as removal so the storage event mirrors the
+          // prior contract — listeners don't need to special-case it.
+          if (value.state.themeMode === 'system') {
+            window.localStorage.removeItem(name)
+          } else {
+            window.localStorage.setItem(name, JSON.stringify(value))
+          }
+        },
+        removeItem: (name) => {
+          if (typeof window === 'undefined') return
+          window.localStorage.removeItem(name)
+        },
+      },
+    }),
+  ),
+  shallow,
+)
+
+export const getThemeStoreState = () => useThemeStore.getState()

apps/admin/src/store/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Zustand setter signature mirroring the `set` parameter passed to the
+ * store creator. Includes the optional third action-name argument for
+ * the `devtools` middleware.
+ *
+ * Cribbed from lobe-chat's `src/store/types.ts` so the action-class
+ * pattern (`this.#set({...}, false, 'actionName')`) carries cleanly.
+ */
+export interface StoreSetter<TStore> {
+  (
+    partial:
+      | TStore
+      | Partial<TStore>
+      | ((state: TStore) => TStore | Partial<TStore>),
+    replace?: false | undefined,
+    action?: unknown,
+  ): void
+  (
+    state: TStore | ((state: TStore) => TStore),
+    replace: true,
+    action?: unknown,
+  ): void
+}

apps/admin/src/store/utils/flatten-actions.ts

@@ -0,0 +1,44 @@
+/**
+ * Flatten one or more action-class instances into a single object whose
+ * methods are bound to their owning instance. Used when assembling a
+ * Zustand store from slice classes — class instances can't be spread
+ * cleanly because methods live on the prototype.
+ *
+ * Each method is bound to the original instance so `this` resolves
+ * correctly when callers invoke `store.someAction()`.
+ *
+ * Cribbed from lobe-chat's `src/store/utils/flattenActions.ts`.
+ */
+export function flattenActions<T extends object>(actions: object[]): T {
+  const result = {} as T
+
+  for (const action of actions) {
+    let current: object | null = action
+    while (current && current !== Object.prototype) {
+      const keys = Object.getOwnPropertyNames(current)
+
+      for (const key of keys) {
+        if (key === 'constructor') continue
+        if (key in result) continue
+
+        const descriptor = Object.getOwnPropertyDescriptor(current, key)
+        if (!descriptor) continue
+
+        if (typeof descriptor.value === 'function') {
+          ;(result as Record<string, unknown>)[key] =
+            descriptor.value.bind(action)
+        } else {
+          Object.defineProperty(result, key, {
+            ...descriptor,
+            configurable: true,
+            enumerable: true,
+          })
+        }
+      }
+
+      current = Object.getPrototypeOf(current)
+    }
+  }
+
+  return result
+}

apps/admin/src/theme.ts

@@ -1,38 +1,40 @@
 import { useEffect, useMemo, useSyncExternalStore } from 'react'
+import type { ThemeMode } from '~/store/theme'
+
+import { useThemeStore } from '~/store/theme'
 
 export const themeColors = {
   primary: '#1a9cf3',
   primaryDeep: '#0f7ec4',
   primaryShallow: '#4fb5f7',
 } as const
 
-export type ThemeMode = 'dark' | 'light' | 'system'
+export type { ThemeMode }
 
-const themeModeChangeEvent = 'mx-admin-theme-mode-change'
+const DARK_QUERY = '(prefers-color-scheme: dark)'
 
+/**
+ * Reads the persisted theme mode from the Zustand store and resolves it
+ * against the OS preference. The OS-preference side still goes through
+ * `useSyncExternalStore` because the source is a `MediaQueryList`, not
+ * React state.
+ */
 export function useThemeMode() {
-  const query = useMemo(
-    () => window.matchMedia('(prefers-color-scheme: dark)'),
-    [],
-  )
-
-  const snapshot = useSyncExternalStore(
-    (onStoreChange) => {
-      query.addEventListener('change', onStoreChange)
-      window.addEventListener(themeModeChangeEvent, onStoreChange)
-
-      return () => {
-        query.removeEventListener('change', onStoreChange)
-        window.removeEventListener(themeModeChangeEvent, onStoreChange)
-      }
+  const themeMode = useThemeStore((s) => s.themeMode)
+  const setThemeMode = useThemeStore((s) => s.setThemeMode)
+
+  const query = useMemo(() => window.matchMedia(DARK_QUERY), [])
+  const systemMatches = useSyncExternalStore(
+    (onChange) => {
+      query.addEventListener('change', onChange)
+      return () => query.removeEventListener('change', onChange)
     },
-    () => getThemeSnapshot(query),
-    () => 'system:light',
+    () => query.matches,
+    () => false,
   )
-  const [themeMode, resolvedTheme] = snapshot.split(':') as [
-    ThemeMode,
-    'dark' | 'light',
-  ]
+
+  const resolvedTheme: 'dark' | 'light' =
+    themeMode === 'system' ? (systemMatches ? 'dark' : 'light') : themeMode
   const isDark = resolvedTheme === 'dark'
 
   useEffect(() => {
@@ -57,28 +59,7 @@ export function installThemeTokens() {
   )
 }
 
+/** Imperative setter for callers outside React. */
 export function setThemeMode(themeMode: ThemeMode) {
-  if (themeMode === 'system') {
-    localStorage.removeItem('theme-mode')
-  } else {
-    localStorage.setItem('theme-mode', themeMode)
-  }
-
-  window.dispatchEvent(new Event(themeModeChangeEvent))
-}
-
-function getThemeSnapshot(query: MediaQueryList) {
-  const themeMode = readThemeMode()
-  const resolvedTheme =
-    themeMode === 'system' ? (query.matches ? 'dark' : 'light') : themeMode
-
-  return `${themeMode}:${resolvedTheme}` as const
-}
-
-function readThemeMode(): ThemeMode {
-  const storedTheme = localStorage.getItem('theme-mode')?.replace(/^"|"$/g, '')
-
-  if (storedTheme === 'dark' || storedTheme === 'light') return storedTheme
-
-  return 'system'
+  useThemeStore.getState().setThemeMode(themeMode)
 }

apps/admin/src/ui/feedback/modal-imperative/root.tsx

@@ -1,10 +1,8 @@
-import { useSyncExternalStore } from 'react'
-
 import { Modal } from '~/ui/feedback/modal'
 import { PortalLayerScope } from '~/ui/feedback/portal-layer'
 
 import { ModalInstanceProvider } from './context'
-import { modalStore } from './store'
+import { modalStore, useModalStore } from './store'
 
 /**
  * Z-stack stride: each modal reserves this many depth steps so its descendants
@@ -14,11 +12,7 @@ import { modalStore } from './store'
 const Z_STACK_STRIDE = 10
 
 export function ModalRoot() {
-  const stack = useSyncExternalStore(
-    modalStore.subscribe,
-    modalStore.getSnapshot,
-    modalStore.getSnapshot,
-  )
+  const stack = useModalStore((s) => s.stack)
   const topIndex = stack.length - 1
 
   return (