nfx-ui 0.20.0 → 0.22.0

package/src/stores/auth.ts

@@ -0,0 +1,292 @@
+import type { Tokens } from "@/types";
+
+import { DEFAULT_PROFILE_KIND, ProfileKind, ProfileKindEnum } from "@/enums";
+import { makeStore } from "@/stores/makeStore";
+
+/**
+ * Auth session: memory is source of truth.
+ * Persistence is ONE key in ONE storage: rememberMe → localStorage, else sessionStorage.
+ * Step-1 login tokens (profile not selected) stay memory-only.
+ */
+export type AuthState = {
+  isAuthValid: boolean;
+  accessToken: Nullable<string>;
+  refreshToken: Nullable<string>;
+  currentAccountId: string;
+  currentProfileId: string;
+  currentProfileKind: ProfileKindEnum;
+  rememberMe: boolean;
+};
+
+interface AuthActions {
+  setIsAuthValid: (isAuthValid: boolean) => void;
+  setTokens: (tokens: Tokens.Response.Tokens, options?: { rememberMe?: boolean }) => void;
+  setCurrentAccountId: (accountId: string) => void;
+  setCurrentProfileId: (profileId: string) => void;
+  setCurrentProfileKind: (kind: ProfileKindEnum) => void;
+  clearAuth: () => void;
+}
+
+const AUTH_STORAGE_KEY = "nfx-auth-storage";
+const AUTH_BROADCAST_CHANNEL = "nfx-auth";
+
+export const EMPTY_ACCOUNT_ID = "00000000-0000-0000-0000-000000000000";
+export const EMPTY_PROFILE_ID = "00000000-0000-0000-0000-000000000000";
+
+export function hasSelectedProfile(profileId: string): boolean {
+  return profileId !== EMPTY_PROFILE_ID && profileId.trim() !== "";
+}
+
+const LOGGED_OUT_STATE: AuthState = {
+  isAuthValid: false,
+  accessToken: null,
+  refreshToken: null,
+  currentAccountId: EMPTY_ACCOUNT_ID,
+  currentProfileId: EMPTY_PROFILE_ID,
+  currentProfileKind: DEFAULT_PROFILE_KIND,
+  rememberMe: false,
+};
+
+type AuthBroadcastMessage = { type: "auth"; snapshot: AuthState } | { type: "clear" };
+
+function parseSnapshot(raw: Nullable<string>): Nullable<AuthState> {
+  if (!raw) return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== "object") return null;
+  const target = value as Partial<AuthState>;
+
+  const accessToken = typeof target.accessToken === "string" ? target.accessToken : null;
+  const refreshToken = typeof target.refreshToken === "string" ? target.refreshToken : null;
+  const currentAccountId = typeof target.currentAccountId === "string" ? target.currentAccountId : EMPTY_ACCOUNT_ID;
+  const currentProfileId = typeof target.currentProfileId === "string" ? target.currentProfileId : EMPTY_PROFILE_ID;
+  if (!accessToken || !refreshToken || !hasSelectedProfile(currentProfileId)) return null;
+
+  return {
+    isAuthValid: typeof target.isAuthValid === "boolean" ? target.isAuthValid : false,
+    accessToken,
+    refreshToken,
+    currentAccountId,
+    currentProfileId,
+    currentProfileKind: ProfileKind(target.currentProfileKind),
+    rememberMe: target.rememberMe === true,
+  };
+}
+
+function clearPersistedAuth() {
+  if (typeof window === "undefined") return;
+  window.localStorage.removeItem(AUTH_STORAGE_KEY);
+  window.sessionStorage.removeItem(AUTH_STORAGE_KEY);
+}
+
+export function readAuthState(): Nullable<AuthState> {
+  if (typeof window === "undefined") return null;
+  const localRaw = window.localStorage.getItem(AUTH_STORAGE_KEY);
+  const sessionRaw = window.sessionStorage.getItem(AUTH_STORAGE_KEY);
+
+  if (localRaw != null && sessionRaw != null) {
+    clearPersistedAuth();
+    return null;
+  }
+
+  const snapshot = parseSnapshot(localRaw) ?? parseSnapshot(sessionRaw);
+  if (!snapshot) {
+    if (localRaw != null || sessionRaw != null) clearPersistedAuth();
+    return null;
+  }
+  return { ...snapshot, rememberMe: localRaw != null };
+}
+
+function persist(snapshot: AuthState) {
+  if (typeof window === "undefined") return;
+  if (!snapshot.isAuthValid || !snapshot.accessToken || !snapshot.refreshToken || !hasSelectedProfile(snapshot.currentProfileId)) {
+    clearPersistedAuth();
+    return;
+  }
+  const payload = JSON.stringify(snapshot);
+  if (snapshot.rememberMe) {
+    window.localStorage.setItem(AUTH_STORAGE_KEY, payload);
+    window.sessionStorage.removeItem(AUTH_STORAGE_KEY);
+  } else {
+    window.sessionStorage.setItem(AUTH_STORAGE_KEY, payload);
+    window.localStorage.removeItem(AUTH_STORAGE_KEY);
+  }
+}
+
+let authBroadcast: Nullable<BroadcastChannel> = null;
+let suppressSync = false;
+
+function getAuthBroadcast(): Nullable<BroadcastChannel> {
+  if (typeof window === "undefined" || typeof BroadcastChannel === "undefined") return null;
+  if (!authBroadcast) authBroadcast = new BroadcastChannel(AUTH_BROADCAST_CHANNEL);
+  return authBroadcast;
+}
+
+function broadcastAuth(message: AuthBroadcastMessage) {
+  if (suppressSync) return;
+  try {
+    getAuthBroadcast()?.postMessage(message);
+  } catch {
+    // single-tab still works
+  }
+}
+
+let rejectedRefreshToken: Nullable<string> = null;
+
+export function clearRejectedRefreshToken() {
+  rejectedRefreshToken = null;
+}
+
+export function markRejectedRefreshToken(token: string) {
+  rejectedRefreshToken = token;
+}
+
+export function isRejectedRefreshToken(token: string): boolean {
+  return rejectedRefreshToken != null && rejectedRefreshToken === token;
+}
+
+const initialState: AuthState = readAuthState() ?? LOGGED_OUT_STATE;
+
+function snapshotFromMemory(overrides: Partial<AuthState> = {}): AuthState {
+  const current = AuthStore.getState();
+  return {
+    isAuthValid: current.isAuthValid,
+    accessToken: current.accessToken,
+    refreshToken: current.refreshToken,
+    currentAccountId: current.currentAccountId,
+    currentProfileId: current.currentProfileId,
+    currentProfileKind: current.currentProfileKind,
+    rememberMe: current.rememberMe,
+    ...overrides,
+  };
+}
+
+function commitAuthState(snapshot: AuthState) {
+  AuthStore.setState(snapshot);
+  persist(snapshot);
+  if (hasSelectedProfile(snapshot.currentProfileId)) {
+    broadcastAuth({ type: "auth", snapshot });
+  }
+}
+
+const { store: AuthStore, useStore: useAuthStore } = makeStore<AuthState, AuthActions>(initialState, (set) => ({
+  setIsAuthValid: (isAuthValid) => {
+    commitAuthState(snapshotFromMemory({ isAuthValid }));
+  },
+
+  setTokens: (tokens, options) => {
+    clearRejectedRefreshToken();
+    commitAuthState(
+      snapshotFromMemory({
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken,
+        ...(options?.rememberMe != null ? { rememberMe: options.rememberMe } : {}),
+      }),
+    );
+  },
+
+  setCurrentAccountId: (accountId) => {
+    commitAuthState(snapshotFromMemory({ currentAccountId: accountId }));
+  },
+
+  setCurrentProfileId: (profileId) => {
+    commitAuthState(snapshotFromMemory({ currentProfileId: profileId }));
+  },
+
+  setCurrentProfileKind: (kind) => {
+    commitAuthState(snapshotFromMemory({ currentProfileKind: ProfileKind(kind) }));
+  },
+
+  clearAuth: () => {
+    clearPersistedAuth();
+    clearRejectedRefreshToken();
+    broadcastAuth({ type: "clear" });
+    set({ ...LOGGED_OUT_STATE });
+  },
+}));
+
+const setIsAuthValid = AuthStore.getState().setIsAuthValid;
+const setTokens = AuthStore.getState().setTokens;
+const setCurrentAccountId = AuthStore.getState().setCurrentAccountId;
+const setCurrentProfileId = AuthStore.getState().setCurrentProfileId;
+const setCurrentProfileKind = AuthStore.getState().setCurrentProfileKind;
+const clearAuth = AuthStore.getState().clearAuth;
+
+function statesEqual(a: AuthState, b: AuthState): boolean {
+  return (
+    a.isAuthValid === b.isAuthValid &&
+    a.accessToken === b.accessToken &&
+    a.refreshToken === b.refreshToken &&
+    a.currentAccountId === b.currentAccountId &&
+    a.currentProfileId === b.currentProfileId &&
+    a.currentProfileKind === b.currentProfileKind &&
+    a.rememberMe === b.rememberMe
+  );
+}
+
+function applyRemoteSnapshot(snapshot: AuthState): boolean {
+  if (statesEqual(AuthStore.getState(), snapshot)) return false;
+  suppressSync = true;
+  try {
+    AuthStore.setState(snapshot);
+    persist(snapshot);
+    clearRejectedRefreshToken();
+  } finally {
+    suppressSync = false;
+  }
+  return true;
+}
+
+function applyRemoteClear(): boolean {
+  const current = AuthStore.getState();
+  if (!current.isAuthValid && !current.accessToken && !current.refreshToken) return false;
+  suppressSync = true;
+  try {
+    clearPersistedAuth();
+    clearRejectedRefreshToken();
+    AuthStore.setState({ ...LOGGED_OUT_STATE });
+  } finally {
+    suppressSync = false;
+  }
+  return true;
+}
+
+export function subscribeAuthStorageSync(onSynced?: () => void): () => void {
+  if (typeof window === "undefined") return () => undefined;
+
+  const onStorage = (event: StorageEvent) => {
+    if (event.storageArea !== window.localStorage) return;
+    if (event.key != null && event.key !== AUTH_STORAGE_KEY) return;
+    const snapshot = readAuthState();
+    const changed = snapshot ? applyRemoteSnapshot(snapshot) : applyRemoteClear();
+    if (changed) onSynced?.();
+  };
+
+  const channel = getAuthBroadcast();
+  const onBroadcast = (event: MessageEvent<AuthBroadcastMessage>) => {
+    const data = event.data;
+    if (!data || typeof data !== "object") return;
+    let changed = false;
+    if (data.type === "clear") {
+      changed = applyRemoteClear();
+    } else if (data.type === "auth" && data.snapshot) {
+      changed = applyRemoteSnapshot(data.snapshot);
+    }
+    if (changed) onSynced?.();
+  };
+
+  window.addEventListener("storage", onStorage);
+  channel?.addEventListener("message", onBroadcast);
+
+  return () => {
+    window.removeEventListener("storage", onStorage);
+    channel?.removeEventListener("message", onBroadcast);
+  };
+}
+
+export { setIsAuthValid, setTokens, setCurrentAccountId, setCurrentProfileId, setCurrentProfileKind, clearAuth };
+export { AuthStore, useAuthStore };

package/src/stores/index.ts

@@ -0,0 +1,6 @@
+export * from "./makeStore";
+export * from "./preference";
+export * from "./layout";
+export * from "./auth";
+export * from "./system";
+export { DashboardBackgroundEnum, DEFAULT_DASHBOARD_BACKGROUND, DASHBOARD_BACKGROUND_VALUES } from "@/enums/dashboard";

package/src/stores/layout.ts

@@ -0,0 +1,42 @@
+import { makePersistStore } from "@/stores/makeStore";
+
+interface LayoutState {
+  headerHeight: number;
+  footerHeight: number;
+  isAsiderOpen: boolean;
+}
+
+interface LayoutActions {
+  setHeaderHeight: (headerHeight: number) => void;
+  setFooterHeight: (footerHeight: number) => void;
+  openAsider: () => void;
+  closeAsider: () => void;
+  setAsiderOpen: (isAsiderOpen: boolean) => void;
+}
+
+const LAYOUT_STORAGE_KEY = "nfx-layout-storage";
+
+const { store: LayoutStore, useStore: useLayoutStore } = makePersistStore<LayoutState, LayoutActions>({
+  name: LAYOUT_STORAGE_KEY,
+  initialState: {
+    headerHeight: 0,
+    footerHeight: 0,
+    isAsiderOpen: false,
+  },
+  actions: (set) => ({
+    setHeaderHeight: (headerHeight) => set({ headerHeight }),
+    setFooterHeight: (footerHeight) => set({ footerHeight }),
+    openAsider: () => set({ isAsiderOpen: true }),
+    closeAsider: () => set({ isAsiderOpen: false }),
+    setAsiderOpen: (isAsiderOpen) => set({ isAsiderOpen }),
+  }),
+});
+
+const setHeaderHeight = LayoutStore.getState().setHeaderHeight;
+const setFooterHeight = LayoutStore.getState().setFooterHeight;
+const openAsider = LayoutStore.getState().openAsider;
+const closeAsider = LayoutStore.getState().closeAsider;
+const setAsiderOpen = LayoutStore.getState().setAsiderOpen;
+
+export { setHeaderHeight, setFooterHeight, openAsider, closeAsider, setAsiderOpen };
+export { LayoutStore, useLayoutStore };

package/src/stores/makeStore.ts

@@ -0,0 +1,95 @@
+/**
+ * 通用 Store 工厂（学习 hooks 的 make 函数模式）。
+ * Generic persist store factory.
+ */
+
+import { createStore, useStore } from "zustand";
+import { persist, subscribeWithSelector } from "zustand/middleware";
+
+/** SetState：与 zustand 的 set 一致。Same as zustand set. */
+export type SetState<S> = (partial: Partial<S> | ((state: S) => Partial<S>)) => void;
+
+/** GetState：与 zustand 的 get 一致。Same as zustand get. */
+export type GetState<S> = () => S;
+
+/**
+ * 创建带 subscribeWithSelector 的 Store（不持久化）。
+ * Create store with subscribeWithSelector (no persist).
+ *
+ * @param initialState - 初始状态。Initial state.
+ * @param actions - (set, get) => actions 对象。(set, get) => actions object.
+ * @returns { store, useStore } 供外部使用。Returns { store, useStore }.
+ *
+ * @example
+ * ```ts
+ * const { store, useStore } = makeStore(
+ *   { count: 0 },
+ *   (set) => ({ increment: () => set((s) => ({ count: s.count + 1 })) })
+ * );
+ * const count = useStore((s) => s.count);
+ * ```
+ */
+export function makeStore<S extends object, A extends object>(initialState: S, actions: (set: SetState<S & A>, get: GetState<S & A>) => A) {
+  const store = createStore<S & A>()(
+    subscribeWithSelector((set, get) => ({
+      ...initialState,
+      ...actions(set as SetState<S & A>, get as GetState<S & A>),
+    })),
+  );
+  const useStoreBound = <T>(selector: (state: S & A) => T): T => useStore(store, selector);
+  return { store, useStore: useStoreBound };
+}
+
+/** makePersistStore 的配置。Config for makePersistStore. */
+export interface MakePersistStoreOptions<S extends object, A extends object> {
+  /** 持久化 key（localStorage）。Persist key (localStorage). */
+  name: string;
+  /** 初始状态。Initial state. */
+  initialState: S;
+  /** (set, get) => actions。(set, get) => actions. */
+  actions: (set: SetState<S & A>, get: GetState<S & A>) => A;
+  /** 只持久化部分 state；缺省则全量。Partialize state to persist; default full. */
+  partialize?: (state: S & A) => Partial<S & A>;
+  /** 版本号（用于 migrate）。Version for migrate. */
+  version?: number;
+  /** 迁移旧持久化数据。Migrate persisted state. */
+  migrate?: (persistedState: unknown, version: number) => Partial<S & A>;
+}
+
+/**
+ * 创建带 persist + subscribeWithSelector 的 Store。
+ * Create store with persist and subscribeWithSelector.
+ *
+ * @param options - name, initialState, actions, partialize?, version?, migrate?
+ * @returns { store, useStore }
+ *
+ * @example
+ * ```ts
+ * const { store, useStore } = makePersistStore({
+ *   name: "auth-storage",
+ *   initialState: { token: null },
+ *   actions: (set) => ({ setToken: (t) => set({ token: t }) }),
+ * });
+ * ```
+ */
+export function makePersistStore<S extends object, A extends object>(options: MakePersistStoreOptions<S, A>) {
+  const { name, initialState, actions: actionsFn, partialize, version, migrate } = options;
+  const store = createStore<S & A>()(
+    subscribeWithSelector(
+      persist(
+        (set, get) => ({
+          ...initialState,
+          ...actionsFn(set as SetState<S & A>, get as GetState<S & A>),
+        }),
+        {
+          name,
+          ...(partialize && { partialize }),
+          ...(version !== undefined && { version }),
+          ...(migrate && { migrate }),
+        },
+      ),
+    ),
+  );
+  const useStoreBound = <T>(selector: (state: S & A) => T): T => useStore(store, selector);
+  return { store, useStore: useStoreBound };
+}

package/src/stores/preference.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared preference store — theme + language + layout (no map/billing/event).
+ */
+import { DEFAULT_LAYOUT_MODE, LayoutModeEnum } from "@/enums/layout";
+import { DEFAULT_LANGUAGE, Language, type LanguageEnum } from "@/enums/language";
+import { DashboardBackground, DEFAULT_DASHBOARD_BACKGROUND, DashboardBackgroundEnum } from "@/enums/dashboard";
+import { getDefaultThemePreference, resolveThemePreference, type ResolvedThemePreference } from "@/themes/radix";
+import { makePersistStore } from "@/stores/makeStore";
+
+export interface ResolvedPreference {
+  language: LanguageEnum;
+  theme: ResolvedThemePreference;
+  layoutMode: LayoutModeEnum;
+  dashboardBackground: DashboardBackgroundEnum;
+}
+
+export interface PreferencePatch {
+  language?: LanguageEnum;
+  theme?: Partial<ResolvedThemePreference>;
+  layoutMode?: LayoutModeEnum;
+  dashboardBackground?: DashboardBackgroundEnum;
+}
+
+export function getDefaultPreference(): ResolvedPreference {
+  return {
+    language: DEFAULT_LANGUAGE,
+    theme: getDefaultThemePreference(),
+    layoutMode: DEFAULT_LAYOUT_MODE,
+    dashboardBackground: DEFAULT_DASHBOARD_BACKGROUND,
+  };
+}
+
+function isPlainRecord(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+export function parseServerPreference(raw: unknown): ResolvedPreference {
+  const d = getDefaultPreference();
+  if (!isPlainRecord(raw)) return d;
+  const themeRaw = isPlainRecord(raw.theme) ? (raw.theme as Partial<ResolvedThemePreference>) : undefined;
+  return {
+    language: Language(typeof raw.language === "string" ? raw.language : undefined),
+    theme: resolveThemePreference(themeRaw),
+    layoutMode: raw.layoutMode === LayoutModeEnum.HIDE ? LayoutModeEnum.HIDE : DEFAULT_LAYOUT_MODE,
+    dashboardBackground: DashboardBackground(typeof raw.dashboardBackground === "string" ? raw.dashboardBackground : undefined),
+  };
+}
+
+export function toServerPreference(state: ResolvedPreference): ResolvedPreference {
+  return {
+    language: state.language,
+    theme: { ...state.theme },
+    layoutMode: state.layoutMode,
+    dashboardBackground: state.dashboardBackground,
+  };
+}
+
+interface PreferenceActions {
+  setPreference: (patch: PreferencePatch) => void;
+  replacePreference: (next: ResolvedPreference) => void;
+}
+
+const { store: PreferenceStore, useStore: usePreferenceStore } = makePersistStore<ResolvedPreference, PreferenceActions>({
+  name: "nfx-preference",
+  initialState: getDefaultPreference(),
+  version: 2,
+  migrate: (persisted) => parseServerPreference(persisted),
+  partialize: (state) => ({
+    language: state.language,
+    theme: state.theme,
+    layoutMode: state.layoutMode,
+    dashboardBackground: state.dashboardBackground,
+  }),
+  actions: (set) => ({
+    setPreference: (patch) =>
+      set((s) => ({
+        language: patch.language ?? s.language,
+        theme: { ...s.theme, ...patch.theme },
+        layoutMode: patch.layoutMode ?? s.layoutMode,
+        dashboardBackground: patch.dashboardBackground ?? s.dashboardBackground,
+      })),
+    replacePreference: (next) => set(() => next),
+  }),
+});
+
+const setPreference = PreferenceStore.getState().setPreference;
+const replacePreference = PreferenceStore.getState().replacePreference;
+
+export { setPreference, replacePreference };
+export { PreferenceStore, usePreferenceStore };

package/src/stores/system.ts

@@ -0,0 +1,134 @@
+/**
+ * Device identity storage with priority: localStorage > IndexedDB > Cookie.
+ * Key includes port so multiple consoles on the same host do not share device_id.
+ */
+export const DEVICE_ID_STORAGE_KEY = typeof location === "undefined" ? "device_id" : `device_id_${location.port || "default"}`;
+const DEVICE_ID_DB_NAME = "nfx-system";
+const DEVICE_ID_DB_STORE = "kv";
+const DEVICE_ID_COOKIE_MAX_AGE = 60 * 60 * 24 * 365 * 10;
+
+function getDeviceIdFromLocalStorage(): Nullable<string> {
+  try {
+    return localStorage.getItem(DEVICE_ID_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+}
+
+function setDeviceIdToLocalStorage(deviceId: string): void {
+  try {
+    localStorage.setItem(DEVICE_ID_STORAGE_KEY, deviceId);
+  } catch {
+    // ignore
+  }
+}
+
+function getDeviceIdFromCookie(): Nullable<string> {
+  try {
+    const cookieParts = document.cookie.split(";").map((part) => part.trim());
+    const row = cookieParts.find((part) => part.startsWith(`${DEVICE_ID_STORAGE_KEY}=`));
+    if (!row) return null;
+    const value = decodeURIComponent(row.slice(DEVICE_ID_STORAGE_KEY.length + 1));
+    return value.trim() ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function setDeviceIdToCookie(deviceId: string): void {
+  try {
+    document.cookie = `${DEVICE_ID_STORAGE_KEY}=${encodeURIComponent(deviceId)}; path=/; max-age=${DEVICE_ID_COOKIE_MAX_AGE}; samesite=lax`;
+  } catch {
+    // ignore
+  }
+}
+
+function openDeviceIdDB(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    if (typeof indexedDB === "undefined") {
+      reject(new Error("IndexedDB is unavailable"));
+      return;
+    }
+    const request = indexedDB.open(DEVICE_ID_DB_NAME, 1);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(DEVICE_ID_DB_STORE)) {
+        db.createObjectStore(DEVICE_ID_DB_STORE);
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error("Failed to open IndexedDB"));
+  });
+}
+
+async function getDeviceIdFromIndexedDB(): Promise<Nullable<string>> {
+  try {
+    const db = await openDeviceIdDB();
+    const value = await new Promise<Nullable<string>>((resolve, reject) => {
+      const tx = db.transaction(DEVICE_ID_DB_STORE, "readonly");
+      const store = tx.objectStore(DEVICE_ID_DB_STORE);
+      const req = store.get(DEVICE_ID_STORAGE_KEY);
+      req.onsuccess = () => {
+        const result = req.result;
+        resolve(typeof result === "string" && result.trim() ? result : null);
+      };
+      req.onerror = () => reject(req.error ?? new Error("Failed to read IndexedDB"));
+      tx.oncomplete = () => db.close();
+    });
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+async function setDeviceIdToIndexedDB(deviceId: string): Promise<void> {
+  try {
+    const db = await openDeviceIdDB();
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(DEVICE_ID_DB_STORE, "readwrite");
+      const store = tx.objectStore(DEVICE_ID_DB_STORE);
+      const req = store.put(deviceId, DEVICE_ID_STORAGE_KEY);
+      req.onerror = () => reject(req.error ?? new Error("Failed to write IndexedDB"));
+      tx.oncomplete = () => {
+        db.close();
+        resolve();
+      };
+      tx.onerror = () => reject(tx.error ?? new Error("IndexedDB write transaction failed"));
+    });
+  } catch {
+    // ignore
+  }
+}
+
+function createDeviceId(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `device-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export async function ensureDeviceIdStorage(): Promise<string> {
+  const localStorageDeviceId = getDeviceIdFromLocalStorage();
+  if (localStorageDeviceId && localStorageDeviceId.trim()) {
+    setDeviceIdToCookie(localStorageDeviceId);
+    void setDeviceIdToIndexedDB(localStorageDeviceId);
+    return localStorageDeviceId;
+  }
+
+  const indexedDBDeviceId = await getDeviceIdFromIndexedDB();
+  if (indexedDBDeviceId && indexedDBDeviceId.trim()) {
+    setDeviceIdToLocalStorage(indexedDBDeviceId);
+    setDeviceIdToCookie(indexedDBDeviceId);
+    return indexedDBDeviceId;
+  }
+
+  const cookieDeviceId = getDeviceIdFromCookie();
+  if (cookieDeviceId && cookieDeviceId.trim()) {
+    setDeviceIdToLocalStorage(cookieDeviceId);
+    void setDeviceIdToIndexedDB(cookieDeviceId);
+    return cookieDeviceId;
+  }
+
+  const deviceId = createDeviceId();
+  setDeviceIdToLocalStorage(deviceId);
+  setDeviceIdToCookie(deviceId);
+  await setDeviceIdToIndexedDB(deviceId);
+  return deviceId;
+}

package/src/themes/fonts.ts

@@ -0,0 +1,20 @@
+/**
+ * Self-hosted UI fonts — JS side-effect imports so Vite resolves from the host app
+ * (CSS `@import` from Package path does not walk the host `node_modules`).
+ */
+import "@fontsource/ibm-plex-sans/400.css";
+import "@fontsource/ibm-plex-sans/500.css";
+import "@fontsource/ibm-plex-sans/700.css";
+import "@ibm/plex-sans-sc/css/ibm-plex-sans-sc-default.css";
+import "@fontsource/noto-sans/400.css";
+import "@fontsource/noto-sans/500.css";
+import "@fontsource/noto-sans/700.css";
+import "@fontsource/source-sans-3/400.css";
+import "@fontsource/source-sans-3/500.css";
+import "@fontsource/source-sans-3/700.css";
+import "@fontsource/noto-sans-sc/chinese-simplified-400.css";
+import "@fontsource/noto-sans-sc/chinese-simplified-500.css";
+import "@fontsource/noto-sans-sc/chinese-simplified-700.css";
+import "@fontsource/noto-sans-tc/chinese-traditional-400.css";
+import "@fontsource/noto-sans-tc/chinese-traditional-500.css";
+import "@fontsource/noto-sans-tc/chinese-traditional-700.css";

package/src/themes/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from "./useTheme";
+export { useResolvedAppearance } from "@/hooks/preference";