{/* Eyebrow */}
-
-
+
+
Trending now
@@ -150,17 +143,17 @@ export default function TrendingCreators() {
{/* Heading + View all */}
-
+
Creators worth holding,
-
+
before the price tells you so.
View all
diff --git a/src/components/ui/switch.tsx b/src/components/ui/switch.tsx
new file mode 100644
index 00000000..81cf9705
--- /dev/null
+++ b/src/components/ui/switch.tsx
@@ -0,0 +1,50 @@
+import * as React from 'react';
+import { cn } from '@/lib/utils';
+
+interface SwitchProps extends Omit<
+ React.ButtonHTMLAttributes
,
+ 'onChange'
+> {
+ checked: boolean;
+ onCheckedChange: (checked: boolean) => void;
+}
+
+/**
+ * Accessible on/off switch. Renders a native button with `role="switch"`
+ * so it is keyboard operable (Space/Enter) and announces its state.
+ */
+function Switch({
+ checked,
+ onCheckedChange,
+ className,
+ disabled,
+ ...props
+}: SwitchProps) {
+ return (
+
+ );
+}
+
+export { Switch };
diff --git a/src/constants/notificationPreferences.ts b/src/constants/notificationPreferences.ts
new file mode 100644
index 00000000..c09ad914
--- /dev/null
+++ b/src/constants/notificationPreferences.ts
@@ -0,0 +1,39 @@
+import type { NotificationPreferenceType } from '@/services/notificationPreferences.service';
+
+export const NOTIFICATION_PREFERENCE_COPY: Record<
+ NotificationPreferenceType,
+ { label: string; description: string }
+> = {
+ price_alert: {
+ label: 'Price alert triggered',
+ description: 'A key you set an alert on crosses your target price.',
+ },
+ milestone_reached: {
+ label: 'Milestone reached',
+ description: 'A creator you hold hits a bonding curve milestone.',
+ },
+ vesting_cliff: {
+ label: 'Vesting cliff',
+ description: 'A vesting cliff on your keys is about to unlock.',
+ },
+ staking_reward: {
+ label: 'Staking reward',
+ description: 'New staking rewards are ready to claim.',
+ },
+ governance_vote: {
+ label: 'Governance vote',
+ description: 'A vote opens or closes for a creator you hold.',
+ },
+ referral_earned: {
+ label: 'Referral earned',
+ description: 'Someone you referred makes their first trade.',
+ },
+ key_deprecated: {
+ label: 'Key deprecated',
+ description: 'A creator key you hold is deprecated or migrated.',
+ },
+};
+
+export const SAVE_SUCCESS_COPY = 'Notification preferences saved';
+export const SAVE_ERROR_COPY =
+ "We couldn't save your notification preferences.";
diff --git a/src/hooks/useCompareStore.ts b/src/hooks/useCompareStore.ts
new file mode 100644
index 00000000..a832b5cc
--- /dev/null
+++ b/src/hooks/useCompareStore.ts
@@ -0,0 +1,75 @@
+import { create } from 'zustand';
+import { createJSONStorage, persist } from 'zustand/middleware';
+import type { Course } from '@/services/course.service';
+
+export const MAX_COMPARE_KEYS = 3;
+export const COMPARE_STORAGE_KEY = 'accesslayer.compare';
+export const COMPARE_LIMIT_REASON = `You can compare up to ${MAX_COMPARE_KEYS} keys. Remove one to add another.`;
+
+/**
+ * Snapshot of a creator key taken when it is added to the comparison, so
+ * the sticky bar can render immediately without refetching.
+ */
+export interface CompareKey {
+ id: string;
+ title: string;
+ instructorId?: string;
+ thumbnail?: string;
+ walletAddress?: string;
+ price: number;
+ priceStroops?: number | null;
+ volume24h?: number;
+ creatorShareSupply?: number;
+}
+
+export function toCompareKey(
+ creator: Course & { walletAddress?: string }
+): CompareKey {
+ return {
+ id: creator.id,
+ title: creator.title,
+ instructorId: creator.instructorId,
+ thumbnail: creator.thumbnail,
+ walletAddress: creator.walletAddress,
+ price: creator.price,
+ priceStroops: creator.priceStroops,
+ volume24h: creator.volume24h,
+ creatorShareSupply: creator.creatorShareSupply,
+ };
+}
+
+interface CompareStore {
+ keys: CompareKey[];
+ /** Adds a key; ignored when already selected or the limit is reached. */
+ add: (key: CompareKey) => void;
+ remove: (id: string) => void;
+ clear: () => void;
+}
+
+/**
+ * Keys selected for side-by-side comparison (#1086). Persisted to
+ * sessionStorage so the selection survives navigating to the compare page
+ * and reloads, but doesn't linger across browsing sessions.
+ */
+export const useCompareStore = create()(
+ persist(
+ set => ({
+ keys: [],
+ add: key =>
+ set(state =>
+ state.keys.length >= MAX_COMPARE_KEYS ||
+ state.keys.some(existing => existing.id === key.id)
+ ? state
+ : { keys: [...state.keys, key] }
+ ),
+ remove: id =>
+ set(state => ({ keys: state.keys.filter(key => key.id !== id) })),
+ clear: () => set({ keys: [] }),
+ }),
+ {
+ name: COMPARE_STORAGE_KEY,
+ storage: createJSONStorage(() => sessionStorage),
+ partialize: state => ({ keys: state.keys }),
+ }
+ )
+);
diff --git a/src/hooks/useKeyComparisonMetrics.ts b/src/hooks/useKeyComparisonMetrics.ts
new file mode 100644
index 00000000..cc8922de
--- /dev/null
+++ b/src/hooks/useKeyComparisonMetrics.ts
@@ -0,0 +1,70 @@
+import { useEffect, useRef, useState } from 'react';
+import {
+ keyMetricsService,
+ type KeyMetrics,
+} from '@/services/keyMetrics.service';
+
+export type KeyMetricsEntry =
+ | { status: 'loading' }
+ | { status: 'error' }
+ | { status: 'ready'; metrics: KeyMetrics };
+
+export type FetchKeyMetrics = (creatorId: string) => Promise;
+
+/**
+ * Loads metrics for each compared key independently, so one failing
+ * creator doesn't blank the whole comparison table.
+ */
+export function useKeyComparisonMetrics(
+ creatorIds: string[],
+ fetchMetrics: FetchKeyMetrics = id => keyMetricsService.getKeyMetrics(id)
+): Record {
+ const [entries, setEntries] = useState>({});
+ const fetchRef = useRef(fetchMetrics);
+ useEffect(() => {
+ fetchRef.current = fetchMetrics;
+ });
+
+ const idsKey = creatorIds.join(',');
+
+ useEffect(() => {
+ let cancelled = false;
+ const ids = idsKey ? idsKey.split(',') : [];
+
+ setEntries(current => {
+ const next: Record = {};
+ for (const id of ids) next[id] = current[id] ?? { status: 'loading' };
+ return next;
+ });
+
+ for (const id of ids) {
+ fetchRef
+ .current(id)
+ .then(metrics => {
+ if (cancelled) return;
+ // Treat an empty payload like a failure so the table falls
+ // back to card data instead of rendering blanks as "ready".
+ if (!metrics) throw new Error('Missing key metrics');
+ setEntries(current =>
+ id in current
+ ? { ...current, [id]: { status: 'ready', metrics } }
+ : current
+ );
+ })
+ .catch(() => {
+ if (cancelled) return;
+ setEntries(current =>
+ id in current
+ ? { ...current, [id]: { status: 'error' } }
+ : current
+ );
+ });
+ }
+
+ return () => {
+ cancelled = true;
+ };
+ }, [idsKey]);
+
+ return entries;
+}
diff --git a/src/hooks/useNotificationPreferences.ts b/src/hooks/useNotificationPreferences.ts
new file mode 100644
index 00000000..3b438d04
--- /dev/null
+++ b/src/hooks/useNotificationPreferences.ts
@@ -0,0 +1,220 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+ NOTIFICATION_CHANNELS,
+ NOTIFICATION_PREFERENCE_TYPES,
+ notificationPreferencesService,
+ type NotificationChannel,
+ type NotificationPreferences,
+ type NotificationPreferenceType,
+} from '@/services/notificationPreferences.service';
+
+/**
+ * Channel defaults used when the API omits a notification type (e.g. a
+ * type added on the client before the backend knows about it). In-app is
+ * on so users still see the event; email stays opt-in.
+ */
+const DEFAULT_CHANNEL_PREFERENCES = { email: false, inApp: true } as const;
+
+/**
+ * Fills any notification types or channels missing from the API payload so
+ * every row always renders with a defined boolean state.
+ */
+export function normalizeNotificationPreferences(
+ raw:
+ | Partial>>>
+ | null
+ | undefined
+): NotificationPreferences {
+ const result = {} as NotificationPreferences;
+ for (const type of NOTIFICATION_PREFERENCE_TYPES) {
+ const source = raw?.[type] ?? {};
+ result[type] = {
+ email:
+ typeof source.email === 'boolean'
+ ? source.email
+ : DEFAULT_CHANNEL_PREFERENCES.email,
+ inApp:
+ typeof source.inApp === 'boolean'
+ ? source.inApp
+ : DEFAULT_CHANNEL_PREFERENCES.inApp,
+ };
+ }
+ return result;
+}
+
+export function areAllNotificationsEnabled(
+ preferences: NotificationPreferences
+): boolean {
+ return NOTIFICATION_PREFERENCE_TYPES.every(type =>
+ NOTIFICATION_CHANNELS.every(channel => preferences[type][channel])
+ );
+}
+
+export function setAllNotificationPreferences(
+ enabled: boolean
+): NotificationPreferences {
+ const result = {} as NotificationPreferences;
+ for (const type of NOTIFICATION_PREFERENCE_TYPES) {
+ result[type] = { email: enabled, inApp: enabled };
+ }
+ return result;
+}
+
+export type PreferencesLoadStatus = 'loading' | 'ready' | 'error';
+export type PreferencesSaveStatus = 'idle' | 'saving' | 'error';
+
+export interface UseNotificationPreferencesOptions {
+ /** Injectable for tests; defaults to the API service. */
+ fetchPreferences?: () => Promise;
+ /** Injectable for tests; defaults to the API service. */
+ updatePreferences?: (
+ preferences: NotificationPreferences
+ ) => Promise;
+ onSaveSuccess?: () => void;
+ onSaveError?: (error: unknown) => void;
+}
+
+export interface UseNotificationPreferencesResult {
+ preferences: NotificationPreferences | null;
+ loadStatus: PreferencesLoadStatus;
+ saveStatus: PreferencesSaveStatus;
+ allEnabled: boolean;
+ setChannel: (
+ type: NotificationPreferenceType,
+ channel: NotificationChannel,
+ enabled: boolean
+ ) => void;
+ setAll: (enabled: boolean) => void;
+ /** Re-sends the last change that failed to save. */
+ retrySave: () => void;
+ /** Re-fetches preferences after a failed initial load. */
+ reload: () => void;
+}
+
+/**
+ * Loads the user's notification preferences and saves every change
+ * immediately. Changes are applied optimistically; if a save fails the UI
+ * rolls back to the last server-confirmed state and the failed change is
+ * kept so `retrySave` can re-send it.
+ */
+export function useNotificationPreferences({
+ fetchPreferences = () => notificationPreferencesService.getPreferences(),
+ updatePreferences = preferences =>
+ notificationPreferencesService.updatePreferences(preferences),
+ onSaveSuccess,
+ onSaveError,
+}: UseNotificationPreferencesOptions = {}): UseNotificationPreferencesResult {
+ const [preferences, setPreferences] =
+ useState(null);
+ const [loadStatus, setLoadStatus] =
+ useState('loading');
+ const [saveStatus, setSaveStatus] = useState('idle');
+ const [reloadToken, setReloadToken] = useState(0);
+
+ const confirmedRef = useRef(null);
+ const failedRef = useRef(null);
+ const latestRequestRef = useRef(0);
+
+ // Keep the latest callbacks without re-running the load effect.
+ const fetchRef = useRef(fetchPreferences);
+ const updateRef = useRef(updatePreferences);
+ const onSaveSuccessRef = useRef(onSaveSuccess);
+ const onSaveErrorRef = useRef(onSaveError);
+ useEffect(() => {
+ fetchRef.current = fetchPreferences;
+ updateRef.current = updatePreferences;
+ onSaveSuccessRef.current = onSaveSuccess;
+ onSaveErrorRef.current = onSaveError;
+ });
+
+ useEffect(() => {
+ let cancelled = false;
+ setLoadStatus('loading');
+
+ fetchRef
+ .current()
+ .then(data => {
+ if (cancelled) return;
+ const normalized = normalizeNotificationPreferences(data);
+ confirmedRef.current = normalized;
+ setPreferences(normalized);
+ setLoadStatus('ready');
+ })
+ .catch(() => {
+ if (cancelled) return;
+ setLoadStatus('error');
+ });
+
+ return () => {
+ cancelled = true;
+ };
+ }, [reloadToken]);
+
+ const save = useCallback((next: NotificationPreferences) => {
+ const requestId = ++latestRequestRef.current;
+ setPreferences(next);
+ setSaveStatus('saving');
+
+ updateRef
+ .current(next)
+ .then(saved => {
+ const confirmed = saved
+ ? normalizeNotificationPreferences(saved)
+ : next;
+ confirmedRef.current = confirmed;
+ // A newer change is already in flight; let it own the UI.
+ if (requestId !== latestRequestRef.current) return;
+ failedRef.current = null;
+ setPreferences(confirmed);
+ setSaveStatus('idle');
+ onSaveSuccessRef.current?.();
+ })
+ .catch(error => {
+ if (requestId !== latestRequestRef.current) return;
+ failedRef.current = next;
+ setPreferences(confirmedRef.current);
+ setSaveStatus('error');
+ onSaveErrorRef.current?.(error);
+ });
+ }, []);
+
+ const setChannel = useCallback(
+ (
+ type: NotificationPreferenceType,
+ channel: NotificationChannel,
+ enabled: boolean
+ ) => {
+ if (!preferences) return;
+ save({
+ ...preferences,
+ [type]: { ...preferences[type], [channel]: enabled },
+ });
+ },
+ [preferences, save]
+ );
+
+ const setAll = useCallback(
+ (enabled: boolean) => {
+ if (!preferences) return;
+ save(setAllNotificationPreferences(enabled));
+ },
+ [preferences, save]
+ );
+
+ const retrySave = useCallback(() => {
+ if (failedRef.current) save(failedRef.current);
+ }, [save]);
+
+ const reload = useCallback(() => setReloadToken(token => token + 1), []);
+
+ return {
+ preferences,
+ loadStatus,
+ saveStatus,
+ allEnabled: preferences ? areAllNotificationsEnabled(preferences) : false,
+ setChannel,
+ setAll,
+ retrySave,
+ reload,
+ };
+}
diff --git a/src/hooks/useTheme.ts b/src/hooks/useTheme.ts
new file mode 100644
index 00000000..e02add33
--- /dev/null
+++ b/src/hooks/useTheme.ts
@@ -0,0 +1,41 @@
+import { useSyncExternalStore } from 'react';
+import {
+ getThemeState,
+ setThemePreference,
+ subscribeToTheme,
+ toggleTheme,
+ type ThemePreference,
+ type ResolvedTheme,
+} from '@/lib/theme';
+
+export interface UseThemeResult {
+ /** What the user picked: an explicit theme or "follow the system". */
+ preference: ThemePreference;
+ /** The theme actually on screen. */
+ resolvedTheme: ResolvedTheme;
+ isDark: boolean;
+ setPreference: (preference: ThemePreference) => void;
+ toggleTheme: () => void;
+}
+
+const SERVER_SNAPSHOT = {
+ preference: 'system',
+ resolvedTheme: 'light',
+} as const;
+const getServerSnapshot = () => SERVER_SNAPSHOT;
+
+export function useTheme(): UseThemeResult {
+ const { preference, resolvedTheme } = useSyncExternalStore(
+ subscribeToTheme,
+ getThemeState,
+ getServerSnapshot
+ );
+
+ return {
+ preference,
+ resolvedTheme,
+ isDark: resolvedTheme === 'dark',
+ setPreference: setThemePreference,
+ toggleTheme,
+ };
+}
diff --git a/src/hooks/useTransactionHistory.ts b/src/hooks/useTransactionHistory.ts
new file mode 100644
index 00000000..d8a4137b
--- /dev/null
+++ b/src/hooks/useTransactionHistory.ts
@@ -0,0 +1,155 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+ transactionHistoryService,
+ type GetWalletTransactionsParams,
+ type WalletTransaction,
+ type WalletTransactionPage,
+} from '@/services/transactionHistory.service';
+import {
+ getTypesForFilter,
+ matchesTransactionFilters,
+ mergeTransactionPages,
+ type ResolvedDateRange,
+ type TransactionTypeFilter,
+} from '@/utils/transactionHistory.utils';
+
+export type FetchTransactionPage = (
+ params: GetWalletTransactionsParams
+) => Promise;
+
+export interface UseTransactionHistoryOptions {
+ address: string | undefined;
+ filter: TransactionTypeFilter;
+ /** `null` while a custom range is incomplete; nothing is fetched. */
+ range: ResolvedDateRange | null;
+ /** Injectable for tests; defaults to the API service. */
+ fetchPage?: FetchTransactionPage;
+}
+
+export type TransactionHistoryStatus = 'idle' | 'loading' | 'ready' | 'error';
+
+export interface UseTransactionHistoryResult {
+ transactions: WalletTransaction[];
+ status: TransactionHistoryStatus;
+ hasMore: boolean;
+ isLoadingMore: boolean;
+ loadMoreError: boolean;
+ loadMore: () => void;
+ retry: () => void;
+}
+
+/**
+ * Cursor-paginated wallet activity. Changing the address, type filter or
+ * date range resets the list and fetches a fresh first page; `loadMore`
+ * appends the next page, skipping any rows already shown.
+ */
+export function useTransactionHistory({
+ address,
+ filter,
+ range,
+ fetchPage = params => transactionHistoryService.getTransactions(params),
+}: UseTransactionHistoryOptions): UseTransactionHistoryResult {
+ const [transactions, setTransactions] = useState([]);
+ const [nextCursor, setNextCursor] = useState(null);
+ const [status, setStatus] = useState('idle');
+ const [isLoadingMore, setIsLoadingMore] = useState(false);
+ const [loadMoreError, setLoadMoreError] = useState(false);
+ const [retryToken, setRetryToken] = useState(0);
+
+ // Bumped whenever the query changes so late responses from a previous
+ // filter/range never leak into the current list.
+ const generationRef = useRef(0);
+ const fetchPageRef = useRef(fetchPage);
+ useEffect(() => {
+ fetchPageRef.current = fetchPage;
+ });
+
+ const from = range?.from;
+ const to = range?.to;
+ const hasRange = range !== null;
+
+ const buildParams = useCallback(
+ (cursor: string | null): GetWalletTransactionsParams => ({
+ address: address ?? '',
+ types: getTypesForFilter(filter),
+ from,
+ to,
+ cursor,
+ }),
+ [address, filter, from, to]
+ );
+
+ const keepMatching = useCallback(
+ (items: WalletTransaction[]) =>
+ items.filter(tx =>
+ matchesTransactionFilters(tx, filter, { from, to })
+ ),
+ [filter, from, to]
+ );
+
+ useEffect(() => {
+ const generation = ++generationRef.current;
+ setTransactions([]);
+ setNextCursor(null);
+ setIsLoadingMore(false);
+ setLoadMoreError(false);
+
+ if (!address || !hasRange) {
+ setStatus('idle');
+ return;
+ }
+
+ setStatus('loading');
+ fetchPageRef
+ .current(buildParams(null))
+ .then(page => {
+ if (generation !== generationRef.current) return;
+ setTransactions(
+ mergeTransactionPages([], keepMatching(page.items))
+ );
+ setNextCursor(page.nextCursor);
+ setStatus('ready');
+ })
+ .catch(() => {
+ if (generation !== generationRef.current) return;
+ setStatus('error');
+ });
+ }, [address, hasRange, buildParams, keepMatching, retryToken]);
+
+ const loadMore = useCallback(() => {
+ if (!nextCursor || isLoadingMore || status !== 'ready') return;
+ const generation = generationRef.current;
+ setIsLoadingMore(true);
+ setLoadMoreError(false);
+
+ fetchPageRef
+ .current(buildParams(nextCursor))
+ .then(page => {
+ if (generation !== generationRef.current) return;
+ setTransactions(current =>
+ mergeTransactionPages(current, keepMatching(page.items))
+ );
+ setNextCursor(page.nextCursor);
+ })
+ .catch(() => {
+ if (generation !== generationRef.current) return;
+ setLoadMoreError(true);
+ })
+ .finally(() => {
+ if (generation !== generationRef.current) return;
+ setIsLoadingMore(false);
+ });
+ }, [nextCursor, isLoadingMore, status, buildParams, keepMatching]);
+
+ const retry = useCallback(() => setRetryToken(token => token + 1), []);
+
+ return {
+ transactions,
+ status,
+ hasMore: nextCursor !== null,
+ isLoadingMore,
+ loadMoreError,
+ loadMore,
+ retry,
+ };
+}
diff --git a/src/index.css b/src/index.css
index 1946f6f8..0c8f2270 100644
--- a/src/index.css
+++ b/src/index.css
@@ -147,6 +147,30 @@
}
}
+/*
+ * #1085: colour fade while switching themes. The class is only added for
+ * the duration of a user-initiated switch (see src/lib/theme.ts) so page
+ * loads and hover states keep their normal timing.
+ */
+.theme-transition,
+.theme-transition *,
+.theme-transition *::before,
+.theme-transition *::after {
+ transition-property:
+ background-color, border-color, color, fill, stroke, box-shadow !important;
+ transition-duration: 300ms !important;
+ transition-timing-function: ease !important;
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .theme-transition,
+ .theme-transition *,
+ .theme-transition *::before,
+ .theme-transition *::after {
+ transition: none !important;
+ }
+}
+
@layer base {
* {
@apply border-border outline-ring/50;
diff --git a/src/lib/__tests__/theme.test.tsx b/src/lib/__tests__/theme.test.tsx
new file mode 100644
index 00000000..8aed049b
--- /dev/null
+++ b/src/lib/__tests__/theme.test.tsx
@@ -0,0 +1,204 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import ThemeToggle from '@/components/common/ThemeToggle';
+import {
+ THEME_STORAGE_KEY,
+ getThemeState,
+ initTheme,
+ resetThemeStateForTests,
+ setThemePreference,
+ subscribeToTheme,
+} from '@/lib/theme';
+
+type ChangeListener = (event: MediaQueryListEvent) => void;
+
+/** Controllable `prefers-color-scheme` stub. */
+function mockSystemTheme(initialDark: boolean) {
+ let matches = initialDark;
+ const listeners = new Set();
+ vi.stubGlobal(
+ 'matchMedia',
+ vi.fn((query: string) => ({
+ get matches() {
+ return matches;
+ },
+ media: query,
+ addEventListener: (_: string, cb: ChangeListener) => listeners.add(cb),
+ removeEventListener: (_: string, cb: ChangeListener) =>
+ listeners.delete(cb),
+ }))
+ );
+ return {
+ setDark(next: boolean) {
+ matches = next;
+ listeners.forEach(cb => cb({ matches: next } as MediaQueryListEvent));
+ },
+ };
+}
+
+const html = () => document.documentElement;
+
+beforeEach(() => {
+ vi.useFakeTimers();
+ localStorage.clear();
+ html().className = '';
+ html().style.colorScheme = '';
+ resetThemeStateForTests();
+});
+
+afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+});
+
+describe('theme', () => {
+ it('applies the system dark preference on first visit', () => {
+ mockSystemTheme(true);
+ initTheme();
+ expect(getThemeState()).toEqual({
+ preference: 'system',
+ resolvedTheme: 'dark',
+ });
+ expect(html()).toHaveClass('dark');
+ expect(html().style.colorScheme).toBe('dark');
+ // Initial load must not animate (would read as a flash).
+ expect(html()).not.toHaveClass('theme-transition');
+ });
+
+ it('applies the system light preference on first visit', () => {
+ mockSystemTheme(false);
+ initTheme();
+ expect(getThemeState().resolvedTheme).toBe('light');
+ expect(html()).not.toHaveClass('dark');
+ });
+
+ it('lets a manual choice override the system and persist across loads', () => {
+ mockSystemTheme(true);
+ initTheme();
+
+ setThemePreference('light');
+ expect(localStorage.getItem(THEME_STORAGE_KEY)).toBe('light');
+ expect(html()).not.toHaveClass('dark');
+
+ // Simulate a fresh page load with the system still dark.
+ resetThemeStateForTests();
+ html().className = '';
+ initTheme();
+ expect(getThemeState()).toEqual({
+ preference: 'light',
+ resolvedTheme: 'light',
+ });
+ expect(html()).not.toHaveClass('dark');
+ });
+
+ it('choosing "system" clears the override', () => {
+ mockSystemTheme(true);
+ initTheme();
+ setThemePreference('light');
+ setThemePreference('system');
+ expect(localStorage.getItem(THEME_STORAGE_KEY)).toBeNull();
+ expect(html()).toHaveClass('dark');
+ });
+
+ it('follows live OS changes only while on "system"', () => {
+ const system = mockSystemTheme(false);
+ initTheme();
+ const unsubscribe = subscribeToTheme(() => {});
+
+ act(() => system.setDark(true));
+ expect(html()).toHaveClass('dark');
+
+ setThemePreference('light');
+ act(() => system.setDark(false));
+ act(() => system.setDark(true));
+ expect(html()).not.toHaveClass('dark');
+ unsubscribe();
+ });
+
+ it('animates user-initiated switches and then removes the transition class', () => {
+ mockSystemTheme(false);
+ initTheme();
+ setThemePreference('dark');
+ expect(html()).toHaveClass('theme-transition');
+ vi.advanceTimersByTime(300);
+ expect(html()).not.toHaveClass('theme-transition');
+ });
+
+ it('ignores corrupted stored values', () => {
+ mockSystemTheme(true);
+ localStorage.setItem(THEME_STORAGE_KEY, 'purple');
+ initTheme();
+ expect(getThemeState()).toEqual({
+ preference: 'system',
+ resolvedTheme: 'dark',
+ });
+ });
+});
+
+describe('ThemeToggle', () => {
+ it('toggles the theme, stores the override and updates its label', () => {
+ mockSystemTheme(false);
+ initTheme();
+ render();
+
+ const button = screen.getByRole('button', {
+ name: 'Switch to dark mode',
+ });
+ fireEvent.click(button);
+
+ expect(html()).toHaveClass('dark');
+ expect(localStorage.getItem(THEME_STORAGE_KEY)).toBe('dark');
+ expect(
+ screen.getByRole('button', { name: 'Switch to light mode' })
+ ).toBeInTheDocument();
+ });
+
+ it('syncs with changes made in another tab', () => {
+ mockSystemTheme(false);
+ initTheme();
+ render();
+
+ // Another tab writes the override, then the browser fires `storage`.
+ localStorage.setItem(THEME_STORAGE_KEY, 'dark');
+ act(() => {
+ window.dispatchEvent(
+ new StorageEvent('storage', {
+ key: THEME_STORAGE_KEY,
+ newValue: 'dark',
+ })
+ );
+ });
+
+ expect(html()).toHaveClass('dark');
+ expect(
+ screen.getByRole('button', { name: 'Switch to light mode' })
+ ).toBeInTheDocument();
+
+ localStorage.removeItem(THEME_STORAGE_KEY);
+ act(() => {
+ window.dispatchEvent(
+ new StorageEvent('storage', {
+ key: THEME_STORAGE_KEY,
+ newValue: null,
+ })
+ );
+ });
+ expect(html()).not.toHaveClass('dark');
+ });
+
+ it('ignores storage events for unrelated keys', () => {
+ mockSystemTheme(false);
+ initTheme();
+ render();
+ localStorage.setItem(THEME_STORAGE_KEY, 'dark');
+ act(() => {
+ window.dispatchEvent(
+ new StorageEvent('storage', {
+ key: 'something-else',
+ newValue: 'x',
+ })
+ );
+ });
+ expect(html()).not.toHaveClass('dark');
+ });
+});
diff --git a/src/lib/theme.ts b/src/lib/theme.ts
new file mode 100644
index 00000000..c26b2ab7
--- /dev/null
+++ b/src/lib/theme.ts
@@ -0,0 +1,168 @@
+/**
+ * App-wide light/dark theme state (#1085).
+ *
+ * - First visit: follows `prefers-color-scheme` (and keeps following it if
+ * the OS setting changes).
+ * - Manual choice: stored in localStorage and wins over the OS setting on
+ * every later load. Choosing "system" clears the override.
+ * - Other tabs pick up changes through the `storage` event.
+ *
+ * The initial class is applied by an inline script in `index.html` before
+ * first paint so there is no flash of the wrong theme; keep the storage
+ * key and class name there in sync with this file.
+ */
+
+export const THEME_STORAGE_KEY = 'accesslayer.theme';
+export const DARK_CLASS = 'dark';
+const TRANSITION_CLASS = 'theme-transition';
+const TRANSITION_MS = 300;
+const DARK_QUERY = '(prefers-color-scheme: dark)';
+
+export type ThemePreference = 'light' | 'dark' | 'system';
+export type ResolvedTheme = 'light' | 'dark';
+
+export interface ThemeState {
+ preference: ThemePreference;
+ resolvedTheme: ResolvedTheme;
+}
+
+function isManualTheme(value: unknown): value is ResolvedTheme {
+ return value === 'light' || value === 'dark';
+}
+
+export function readStoredPreference(): ThemePreference {
+ try {
+ const stored = window.localStorage.getItem(THEME_STORAGE_KEY);
+ return isManualTheme(stored) ? stored : 'system';
+ } catch {
+ return 'system';
+ }
+}
+
+function writeStoredPreference(preference: ThemePreference) {
+ try {
+ if (preference === 'system') {
+ window.localStorage.removeItem(THEME_STORAGE_KEY);
+ } else {
+ window.localStorage.setItem(THEME_STORAGE_KEY, preference);
+ }
+ } catch {
+ // Storage can be unavailable (private mode, quota); the choice still
+ // applies for this session.
+ }
+}
+
+export function getSystemTheme(): ResolvedTheme {
+ if (typeof window === 'undefined' || !window.matchMedia) return 'light';
+ return window.matchMedia(DARK_QUERY).matches ? 'dark' : 'light';
+}
+
+export function resolveTheme(preference: ThemePreference): ResolvedTheme {
+ return preference === 'system' ? getSystemTheme() : preference;
+}
+
+let transitionTimer: ReturnType | undefined;
+
+/**
+ * Applies the theme to ``. `animate` briefly enables colour
+ * transitions so user-initiated switches fade instead of snapping; it is
+ * never used on initial load, which would itself look like a flash.
+ */
+export function applyTheme(theme: ResolvedTheme, animate = false) {
+ const root = document.documentElement;
+ if (animate) {
+ root.classList.add(TRANSITION_CLASS);
+ clearTimeout(transitionTimer);
+ transitionTimer = setTimeout(
+ () => root.classList.remove(TRANSITION_CLASS),
+ TRANSITION_MS
+ );
+ }
+ root.classList.toggle(DARK_CLASS, theme === 'dark');
+ root.style.colorScheme = theme;
+}
+
+type Listener = () => void;
+const listeners = new Set();
+let state: ThemeState | null = null;
+
+function computeState(): ThemeState {
+ const preference = readStoredPreference();
+ return { preference, resolvedTheme: resolveTheme(preference) };
+}
+
+function update(next: ThemeState, animate: boolean) {
+ const changed =
+ !state ||
+ state.preference !== next.preference ||
+ state.resolvedTheme !== next.resolvedTheme;
+ state = next;
+ applyTheme(next.resolvedTheme, animate);
+ if (changed) listeners.forEach(listener => listener());
+}
+
+function handleStorage(event: StorageEvent) {
+ if (event.key !== THEME_STORAGE_KEY && event.key !== null) return;
+ update(computeState(), true);
+}
+
+function handleSystemChange() {
+ if (getThemeState().preference !== 'system') return;
+ update(computeState(), true);
+}
+
+let mediaQuery: MediaQueryList | null = null;
+
+function startListening() {
+ window.addEventListener('storage', handleStorage);
+ mediaQuery = window.matchMedia?.(DARK_QUERY) ?? null;
+ mediaQuery?.addEventListener('change', handleSystemChange);
+}
+
+function stopListening() {
+ window.removeEventListener('storage', handleStorage);
+ mediaQuery?.removeEventListener('change', handleSystemChange);
+ mediaQuery = null;
+}
+
+export function getThemeState(): ThemeState {
+ if (!state) state = computeState();
+ return state;
+}
+
+export function subscribeToTheme(listener: Listener): () => void {
+ if (listeners.size === 0) startListening();
+ listeners.add(listener);
+ return () => {
+ listeners.delete(listener);
+ if (listeners.size === 0) stopListening();
+ };
+}
+
+export function setThemePreference(preference: ThemePreference) {
+ writeStoredPreference(preference);
+ update({ preference, resolvedTheme: resolveTheme(preference) }, true);
+}
+
+/** Flips between light and dark, storing the result as a manual override. */
+export function toggleTheme() {
+ setThemePreference(
+ getThemeState().resolvedTheme === 'dark' ? 'light' : 'dark'
+ );
+}
+
+/**
+ * Syncs `` with the stored/system theme. Called once at startup as a
+ * safety net in case the inline script in `index.html` did not run.
+ */
+export function initTheme() {
+ state = computeState();
+ applyTheme(state.resolvedTheme);
+}
+
+/** Test helper: drops cached state so each test starts fresh. */
+export function resetThemeStateForTests() {
+ state = null;
+ stopListening();
+ listeners.clear();
+}
diff --git a/src/main.tsx b/src/main.tsx
index 42193255..d7e753ae 100644
--- a/src/main.tsx
+++ b/src/main.tsx
@@ -3,6 +3,7 @@ import { createRoot } from 'react-dom/client';
import './index.css';
import App from './App.tsx';
import { registerUnhandledRejectionLogger } from './utils/unhandledRejectionLogger';
+import { initTheme } from './lib/theme';
import { queryClient } from './providers/web3Utils';
import {
restorePersistedQueries,
@@ -10,6 +11,7 @@ import {
} from './lib/queryPersistence';
registerUnhandledRejectionLogger();
+initTheme();
// Restore IndexedDB-persisted queries before the first render so the UI
// has stale data available immediately (#754).
diff --git a/src/pages/ComparePage.tsx b/src/pages/ComparePage.tsx
new file mode 100644
index 00000000..7636ff40
--- /dev/null
+++ b/src/pages/ComparePage.tsx
@@ -0,0 +1,322 @@
+import { ArrowLeft, ArrowRight, GitCompareArrows, X } from 'lucide-react';
+import { Link } from 'react-router';
+import CreatorInitialsAvatar from '@/components/common/CreatorInitialsAvatar';
+import { Button } from '@/components/ui/button';
+import { STROOPS_PER_XLM } from '@/constants/stellar';
+import {
+ MAX_COMPARE_KEYS,
+ useCompareStore,
+ type CompareKey,
+} from '@/hooks/useCompareStore';
+import {
+ useKeyComparisonMetrics,
+ type FetchKeyMetrics,
+ type KeyMetricsEntry,
+} from '@/hooks/useKeyComparisonMetrics';
+import { useNavigationTiming } from '@/hooks/useNavigationTiming';
+import type { KeyMetrics } from '@/services/keyMetrics.service';
+import { formatNumber } from '@/utils/numberFormat.utils';
+
+const EMPTY = '—';
+
+function formatXlm(value: number | null | undefined) {
+ return value == null
+ ? EMPTY
+ : `${formatNumber(value, { maximumFractionDigits: 2 })} XLM`;
+}
+
+function snapshotPrice(key: CompareKey) {
+ return key.priceStroops != null
+ ? key.priceStroops / STROOPS_PER_XLM
+ : key.price;
+}
+
+interface MetricRow {
+ id: string;
+ label: string;
+ render: (key: CompareKey, metrics: KeyMetrics | null) => React.ReactNode;
+ /** Rows that can fall back to the card snapshot while metrics load/fail. */
+ usesSnapshot?: boolean;
+}
+
+const METRIC_ROWS: MetricRow[] = [
+ {
+ id: 'price',
+ label: 'Key price',
+ usesSnapshot: true,
+ render: (key, metrics) => formatXlm(metrics?.price ?? snapshotPrice(key)),
+ },
+ {
+ id: 'volume',
+ label: '24h volume',
+ usesSnapshot: true,
+ render: (key, metrics) => formatXlm(metrics?.volume24h ?? key.volume24h),
+ },
+ {
+ id: 'holders',
+ label: 'Holders',
+ render: (_, metrics) => formatNumber(metrics?.holders),
+ },
+ {
+ id: 'traders',
+ label: 'Unique traders (30d)',
+ render: (_, metrics) => formatNumber(metrics?.uniqueTraders),
+ },
+ {
+ id: 'rating',
+ label: 'Rating',
+ render: (_, metrics) =>
+ !metrics
+ ? EMPTY
+ : metrics.rating == null
+ ? 'Unrated'
+ : `${formatNumber(metrics.rating, { maximumFractionDigits: 1 })} / 5`,
+ },
+ {
+ id: 'milestone',
+ label: 'Curve milestone',
+ render: (_, metrics) => {
+ const milestone = metrics?.curveMilestone;
+ if (!milestone) return EMPTY;
+ const progress = Math.min(100, Math.max(0, milestone.progressPercent));
+ return (
+
+
{milestone.label}
+
+
+ {Math.round(progress)}% to next milestone
+
+
+
+
+
+
+ Compare creator keys
+
+
+ Side-by-side metrics for up to {MAX_COMPARE_KEYS} keys.
+
+
+
+ {keys.length > 0 && (
+
+ )}
+
+
+ No keys selected. Use “Compare” on any creator card to add
+ one.
+
+
+
+ Add at least one more key to see a side-by-side comparison.
+
+ )}
+ {hasMetricsError && (
+
+ Some live metrics are unavailable right now. Missing values
+ are shown as {EMPTY}.
+
+ )}
+
+
+
+
+ Comparison of {keys.map(key => key.title).join(', ')}
+
+
+
+ |
+ {keys.map(key => (
+
+
+
+
+
+
+
+
+ {key.title}
+
+ {key.instructorId && (
+
+ @{key.instructorId}
+
+ )}
+
+
+
+ |
+ ))}
+
+
+
+ {METRIC_ROWS.map(row => (
+
+ |
+ {row.label}
+ |
+ {keys.map(key => (
+
+
+ |
+ ))}
+
+ ))}
+
+ |
+ {keys.map(key => (
+
+
+ |
+ ))}
+
+
+
+
+
+
+
+ Notification preferences
+
+
+ Choose which platform events reach you by email or in the app.
+ Changes save automatically.
+
+
+
+ {NOTIFICATION_PREFERENCE_TYPES.map(type => (
+
+ ))}
+
+
+
+ We couldn't load your notification preferences.
+
+
+
+
+
+ {SAVE_ERROR_COPY} Your last change was undone.
+
+
+
+
+
+ All notifications
+
+
+ {allEnabled
+ ? 'Every type is on for email and in-app.'
+ : 'Turn every type on for both channels.'}
+
+
+
+
+ {saveStatus === 'saving' ? 'Saving…' : ''}
+
+
+
+
+
+
+ |
+ Event
+ |
+ {(
+ Object.keys(CHANNEL_LABELS) as NotificationChannel[]
+ ).map(channel => (
+
+ {CHANNEL_LABELS[channel]}
+ |
+ ))}
+
+
+
+ {NOTIFICATION_PREFERENCE_TYPES.map(type => {
+ const copy = NOTIFICATION_PREFERENCE_COPY[type];
+ return (
+
+ |
+
+ {copy.label}
+
+
+ {copy.description}
+
+ |
+ {(
+ Object.keys(
+ CHANNEL_LABELS
+ ) as NotificationChannel[]
+ ).map(channel => (
+
+
+ setChannel(type, channel, enabled)
+ }
+ aria-label={`${copy.label} ${CHANNEL_LABELS[channel].toLowerCase()} notifications`}
+ />
+ |
+ ))}
+
+ );
+ })}
+
+
+
+ )}
+
+ );
+}
diff --git a/src/pages/NotificationsPage.tsx b/src/pages/NotificationsPage.tsx
index 71a003dc..410010bb 100644
--- a/src/pages/NotificationsPage.tsx
+++ b/src/pages/NotificationsPage.tsx
@@ -1,5 +1,5 @@
import { Bell } from 'lucide-react';
-import { useNavigate } from 'react-router';
+import { Link, useNavigate } from 'react-router';
import { cn } from '@/lib/utils';
import { useNotifications } from '@/hooks/useNotifications';
import { useProfileStore } from '@/hooks/useProfileStore';
@@ -36,6 +36,12 @@ export default function NotificationsPage() {
{unreadCount} unread
)}
+
+ Preferences
+
{isLoading && (
diff --git a/src/pages/SettingsPage.tsx b/src/pages/SettingsPage.tsx
new file mode 100644
index 00000000..8922424d
--- /dev/null
+++ b/src/pages/SettingsPage.tsx
@@ -0,0 +1,96 @@
+import { Monitor, Moon, Settings, Sun, type LucideIcon } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { useTheme } from '@/hooks/useTheme';
+import { useNavigationTiming } from '@/hooks/useNavigationTiming';
+import type { ThemePreference } from '@/lib/theme';
+
+const THEME_OPTIONS: {
+ value: ThemePreference;
+ label: string;
+ description: string;
+ icon: LucideIcon;
+}[] = [
+ {
+ value: 'light',
+ label: 'Light',
+ description: 'Always use the light theme.',
+ icon: Sun,
+ },
+ {
+ value: 'dark',
+ label: 'Dark',
+ description: 'Always use the dark theme.',
+ icon: Moon,
+ },
+ {
+ value: 'system',
+ label: 'System',
+ description: "Match your device's appearance setting.",
+ icon: Monitor,
+ },
+];
+
+export default function SettingsPage() {
+ useNavigationTiming('settings');
+ const { preference, setPreference } = useTheme();
+
+ return (
+
+
+
+
Settings
+
+
+
+
+ );
+}
diff --git a/src/pages/TransactionHistoryPage.tsx b/src/pages/TransactionHistoryPage.tsx
new file mode 100644
index 00000000..c2b40f65
--- /dev/null
+++ b/src/pages/TransactionHistoryPage.tsx
@@ -0,0 +1,393 @@
+import { useMemo, useState } from 'react';
+import { useAccount } from 'wagmi';
+import {
+ AlertCircle,
+ ArrowLeftRight,
+ Download,
+ Gift,
+ History,
+ Lock,
+ ShoppingCart,
+ Tag,
+ Unlock,
+ Users,
+ type LucideIcon,
+} from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import ConnectWalletButton from '@/components/common/ConnectWalletButton';
+import Web3Provider from '@/providers/Web3Provider';
+import { cn } from '@/lib/utils';
+import { useNavigationTiming } from '@/hooks/useNavigationTiming';
+import {
+ useTransactionHistory,
+ type FetchTransactionPage,
+} from '@/hooks/useTransactionHistory';
+import type {
+ WalletTransaction,
+ WalletTransactionType,
+} from '@/services/transactionHistory.service';
+import {
+ DATE_RANGE_PRESETS,
+ TRANSACTION_TYPE_FILTERS,
+ TRANSACTION_TYPE_LABELS,
+ buildTransactionCsvFilename,
+ describeTransaction,
+ downloadCsv,
+ resolveDateRange,
+ transactionsToCsv,
+ type CustomDateRange,
+ type DateRangePreset,
+ type TransactionTypeFilter,
+} from '@/utils/transactionHistory.utils';
+import { formatNumber } from '@/utils/numberFormat.utils';
+import { formatRelativeTime } from '@/utils/time.utils';
+
+const TRANSACTION_TYPE_ICONS: Record
= {
+ buy: ShoppingCart,
+ sell: Tag,
+ stake: Lock,
+ unstake: Unlock,
+ claim: Gift,
+ referral: Users,
+ swap: ArrowLeftRight,
+};
+
+const FILTER_PILL_CLASS =
+ 'rounded-full border px-3 py-1.5 text-xs font-medium transition-colors outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50';
+
+function formatXlm(value: number) {
+ return `${formatNumber(value, { maximumFractionDigits: 4 })} XLM`;
+}
+
+function TransactionRow({ tx }: { tx: WalletTransaction }) {
+ const Icon = TRANSACTION_TYPE_ICONS[tx.type];
+ const isIn = tx.direction === 'in';
+
+ return (
+
+
+
+
+
+
+ {describeTransaction(tx)}
+
+
+ {TRANSACTION_TYPE_LABELS[tx.type]}
+ •
+ {tx.keyName}
+ •
+
+
+
+
+ {isIn ? 'Received' : 'Sent'}
+ {isIn ? '+' : '−'}
+ {formatXlm(tx.amount)}
+
+
+ Fee {formatXlm(tx.fee)}
+
+
+
+ {TRANSACTION_TYPE_FILTERS.map(option => (
+
+ ))}
+
+
+
+
+ {customRangeInvalid && (
+
+ The start date must be on or before the end date.
+
+ )}
+ {preset === 'custom' && !range && !customRangeInvalid && (
+
+ Pick a start and end date to see activity.
+
+ )}
+
+ {Array.from({ length: 5 }).map((_, i) => (
+
+ ))}
+
+
+
+ We couldn't load your transaction history.
+
+
+
+
+
+ No activity matches these filters.
+
+
+ {transactions.map(tx => (
+
+ ))}
+
+
+ {loadMoreError && (
+
+ Couldn't load more activity. Try again.
+
+ )}
+ {hasMore ? (
+
+ ) : (
+
+ You've reached the end of your activity.
+
+ )}
+
+
+
+
+ Transaction history
+
+
+ Buys, sells, stakes, claims, swaps and referral payouts from
+ your wallet.
+
+
+
+
+ Connect your wallet to see your transaction history.
+
+
+
Creator detail page
},
+ ],
+ { initialEntries: ['/compare'] }
+ );
+ render();
+ return { router, fetchMetrics };
+ }
+
+ function selectKeys(...ids: string[]) {
+ act(() => {
+ for (const id of ids) useCompareStore.getState().add(makeKey(id));
+ });
+ }
+
+ it('renders every metric for each compared key', async () => {
+ selectKeys('1', '2');
+ const { fetchMetrics } = renderComparePage();
+
+ await waitFor(() =>
+ expect(screen.getByTestId('compare-cell-holders-2')).toHaveTextContent(
+ '100'
+ )
+ );
+ expect(fetchMetrics).toHaveBeenCalledWith('1');
+ expect(fetchMetrics).toHaveBeenCalledWith('2');
+
+ expect(
+ screen.getByRole('columnheader', { name: /Creator 1/ })
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('columnheader', { name: /Creator 2/ })
+ ).toBeInTheDocument();
+
+ const expectations: Record = {
+ price: ['11 XLM', '12 XLM'],
+ volume: ['100 XLM', '200 XLM'],
+ holders: ['50', '100'],
+ traders: ['20', '40'],
+ rating: ['4.5 / 5', '4.5 / 5'],
+ milestone: ['Tier 1', 'Tier 2'],
+ yield: ['7.25%', '7.25%'],
+ };
+ for (const [row, [first, second]] of Object.entries(expectations)) {
+ expect(screen.getByTestId(`compare-cell-${row}-1`)).toHaveTextContent(
+ first
+ );
+ expect(screen.getByTestId(`compare-cell-${row}-2`)).toHaveTextContent(
+ second
+ );
+ }
+ expect(
+ within(screen.getByTestId('compare-cell-milestone-1')).getByRole(
+ 'progressbar'
+ )
+ ).toHaveAttribute('aria-valuenow', '40');
+ });
+
+ it('falls back to card data and placeholders when metrics fail', async () => {
+ selectKeys('1', '2');
+ renderComparePage(
+ vi.fn(async (id: string) => {
+ if (id === '2') throw new Error('boom');
+ return makeMetrics(id, { rating: null, yieldPercent: null });
+ })
+ );
+
+ expect(
+ await screen.findByText(/some live metrics are unavailable/i)
+ ).toBeInTheDocument();
+ // Snapshot price/volume for the failed key.
+ expect(screen.getByTestId('compare-cell-price-2')).toHaveTextContent(
+ '4 XLM'
+ );
+ expect(screen.getByTestId('compare-cell-volume-2')).toHaveTextContent(
+ '2 XLM'
+ );
+ expect(screen.getByTestId('compare-cell-holders-2')).toHaveTextContent(
+ '—'
+ );
+ // Null metrics on the healthy key.
+ expect(screen.getByTestId('compare-cell-rating-1')).toHaveTextContent(
+ 'Unrated'
+ );
+ expect(screen.getByTestId('compare-cell-yield-1')).toHaveTextContent('—');
+ });
+
+ it('removing a key drops its column', async () => {
+ selectKeys('1', '2', '3');
+ renderComparePage();
+ await screen.findByTestId('compare-cell-holders-3');
+
+ fireEvent.click(
+ screen.getByRole('button', { name: 'Remove Creator 2 from compare' })
+ );
+ expect(
+ screen.queryByTestId('compare-cell-price-2')
+ ).not.toBeInTheDocument();
+ expect(screen.getByTestId('compare-cell-price-3')).toBeInTheDocument();
+ });
+
+ it('clear all resets the comparison completely', async () => {
+ selectKeys('1', '2', '3');
+ renderComparePage();
+ await screen.findByTestId('compare-cell-holders-1');
+
+ fireEvent.click(screen.getByRole('button', { name: 'Clear all' }));
+
+ expect(screen.getByTestId('compare-empty')).toBeInTheDocument();
+ expect(screen.queryByRole('table')).not.toBeInTheDocument();
+ expect(useCompareStore.getState().keys).toEqual([]);
+ const stored = JSON.parse(sessionStorage.getItem(COMPARE_STORAGE_KEY)!);
+ expect(stored.state.keys).toEqual([]);
+ });
+
+ it('invest CTA routes to the key detail page', async () => {
+ selectKeys('1', '2');
+ const { router } = renderComparePage();
+ await screen.findByTestId('compare-cell-holders-2');
+
+ const invest = screen.getByRole('link', { name: 'Invest in Creator 2' });
+ expect(invest).toHaveAttribute('href', '/creator/2');
+ fireEvent.click(invest);
+
+ expect(
+ await screen.findByText('Creator detail page')
+ ).toBeInTheDocument();
+ expect(router.state.location.pathname).toBe('/creator/2');
+ });
+});
diff --git a/src/pages/__tests__/NotificationPreferencesPage.test.tsx b/src/pages/__tests__/NotificationPreferencesPage.test.tsx
new file mode 100644
index 00000000..166445b6
--- /dev/null
+++ b/src/pages/__tests__/NotificationPreferencesPage.test.tsx
@@ -0,0 +1,221 @@
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { MemoryRouter } from 'react-router';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import NotificationPreferencesPage from '@/pages/NotificationPreferencesPage';
+import {
+ NOTIFICATION_PREFERENCE_COPY,
+ SAVE_ERROR_COPY,
+ SAVE_SUCCESS_COPY,
+} from '@/constants/notificationPreferences';
+import {
+ NOTIFICATION_PREFERENCE_TYPES,
+ type NotificationPreferences,
+} from '@/services/notificationPreferences.service';
+import { setAllNotificationPreferences } from '@/hooks/useNotificationPreferences';
+
+const { toastSuccess, toastError } = vi.hoisted(() => ({
+ toastSuccess: vi.fn(),
+ toastError: vi.fn(),
+}));
+
+vi.mock('@/utils/toast.util', () => ({
+ default: { success: toastSuccess, error: toastError },
+}));
+
+function makePreferences(): NotificationPreferences {
+ return {
+ ...setAllNotificationPreferences(false),
+ price_alert: { email: true, inApp: true },
+ staking_reward: { email: false, inApp: true },
+ };
+}
+
+function getSwitch(name: string) {
+ return screen.getByRole('switch', { name });
+}
+
+function renderPage(
+ fetchPreferences = vi.fn(async () => makePreferences()),
+ updatePreferences = vi.fn(async (next: NotificationPreferences) => next)
+) {
+ render(
+
+
+
+ );
+ return { fetchPreferences, updatePreferences };
+}
+
+// Multi-step render flows; allow headroom on loaded CI runners.
+describe('NotificationPreferencesPage', { timeout: 15_000 }, () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('renders every notification type with the state returned by the API', async () => {
+ renderPage();
+
+ await screen.findByText('Price alert triggered');
+
+ for (const type of NOTIFICATION_PREFERENCE_TYPES) {
+ expect(
+ screen.getByText(NOTIFICATION_PREFERENCE_COPY[type].label)
+ ).toBeInTheDocument();
+ }
+
+ expect(
+ getSwitch('Price alert triggered email notifications')
+ ).toHaveAttribute('aria-checked', 'true');
+ expect(getSwitch('Staking reward email notifications')).toHaveAttribute(
+ 'aria-checked',
+ 'false'
+ );
+ expect(getSwitch('Staking reward in-app notifications')).toHaveAttribute(
+ 'aria-checked',
+ 'true'
+ );
+ expect(getSwitch('Key deprecated in-app notifications')).toHaveAttribute(
+ 'aria-checked',
+ 'false'
+ );
+ });
+
+ it('fills in types the API omits instead of crashing', async () => {
+ renderPage(
+ vi.fn(
+ async () =>
+ ({
+ price_alert: { email: true, inApp: false },
+ }) as unknown as NotificationPreferences
+ )
+ );
+
+ await screen.findByText('Key deprecated');
+ expect(
+ getSwitch('Price alert triggered in-app notifications')
+ ).toHaveAttribute('aria-checked', 'false');
+ expect(getSwitch('Key deprecated in-app notifications')).toHaveAttribute(
+ 'aria-checked',
+ 'true'
+ );
+ });
+
+ it('saves a single per-type, per-channel toggle and confirms with a toast', async () => {
+ const { updatePreferences } = renderPage();
+ await screen.findByText('Governance vote');
+
+ fireEvent.click(getSwitch('Governance vote email notifications'));
+
+ expect(getSwitch('Governance vote email notifications')).toHaveAttribute(
+ 'aria-checked',
+ 'true'
+ );
+ await waitFor(() =>
+ expect(toastSuccess).toHaveBeenCalledWith(SAVE_SUCCESS_COPY)
+ );
+
+ expect(updatePreferences).toHaveBeenCalledTimes(1);
+ const sent = updatePreferences.mock.calls[0][0];
+ expect(sent.governance_vote).toEqual({ email: true, inApp: false });
+ // Other rows are untouched.
+ expect(sent.price_alert).toEqual({ email: true, inApp: true });
+ expect(sent.staking_reward).toEqual({ email: false, inApp: true });
+ });
+
+ it('bulk toggle enables every type on both channels', async () => {
+ const { updatePreferences } = renderPage();
+ await screen.findByText('Governance vote');
+
+ const bulk = getSwitch('All notifications');
+ expect(bulk).toHaveAttribute('aria-checked', 'false');
+ fireEvent.click(bulk);
+
+ await waitFor(() => expect(toastSuccess).toHaveBeenCalled());
+ expect(updatePreferences).toHaveBeenLastCalledWith(
+ setAllNotificationPreferences(true)
+ );
+ expect(getSwitch('All notifications')).toHaveAttribute(
+ 'aria-checked',
+ 'true'
+ );
+ for (const sw of screen.getAllByRole('switch')) {
+ expect(sw).toHaveAttribute('aria-checked', 'true');
+ }
+ });
+
+ it('bulk toggle disables every type when all are enabled', async () => {
+ const { updatePreferences } = renderPage(
+ vi.fn(async () => setAllNotificationPreferences(true))
+ );
+ await screen.findByText('Governance vote');
+
+ const bulk = getSwitch('All notifications');
+ expect(bulk).toHaveAttribute('aria-checked', 'true');
+ fireEvent.click(bulk);
+
+ await waitFor(() => expect(toastSuccess).toHaveBeenCalled());
+ expect(updatePreferences).toHaveBeenLastCalledWith(
+ setAllNotificationPreferences(false)
+ );
+ for (const sw of screen.getAllByRole('switch')) {
+ expect(sw).toHaveAttribute('aria-checked', 'false');
+ }
+ });
+
+ it('rolls back a failed save, shows an error, and retries the same change', async () => {
+ const updatePreferences = vi
+ .fn<
+ (next: NotificationPreferences) => Promise
+ >()
+ .mockRejectedValueOnce(new Error('Network error'))
+ .mockImplementation(async next => next);
+ renderPage(undefined, updatePreferences);
+ await screen.findByText('Vesting cliff');
+
+ fireEvent.click(getSwitch('Vesting cliff email notifications'));
+
+ const alert = await screen.findByRole('alert');
+ expect(alert).toHaveTextContent(SAVE_ERROR_COPY);
+ expect(toastError).toHaveBeenCalledWith(SAVE_ERROR_COPY);
+ expect(toastSuccess).not.toHaveBeenCalled();
+ expect(getSwitch('Vesting cliff email notifications')).toHaveAttribute(
+ 'aria-checked',
+ 'false'
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Retry' }));
+
+ await waitFor(() =>
+ expect(toastSuccess).toHaveBeenCalledWith(SAVE_SUCCESS_COPY)
+ );
+ expect(updatePreferences).toHaveBeenCalledTimes(2);
+ expect(updatePreferences.mock.calls[1][0].vesting_cliff).toEqual({
+ email: true,
+ inApp: false,
+ });
+ expect(getSwitch('Vesting cliff email notifications')).toHaveAttribute(
+ 'aria-checked',
+ 'true'
+ );
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+ });
+
+ it('shows a load error with a working retry', async () => {
+ const fetchPreferences = vi
+ .fn<() => Promise>()
+ .mockRejectedValueOnce(new Error('boom'))
+ .mockResolvedValue(makePreferences());
+ renderPage(fetchPreferences);
+
+ const alert = await screen.findByRole('alert');
+ expect(alert).toHaveTextContent(/couldn't load/i);
+
+ fireEvent.click(screen.getByRole('button', { name: 'Try again' }));
+
+ await screen.findByText('Price alert triggered');
+ expect(fetchPreferences).toHaveBeenCalledTimes(2);
+ });
+});
diff --git a/src/pages/__tests__/TransactionHistoryPage.test.tsx b/src/pages/__tests__/TransactionHistoryPage.test.tsx
new file mode 100644
index 00000000..c8cb17fe
--- /dev/null
+++ b/src/pages/__tests__/TransactionHistoryPage.test.tsx
@@ -0,0 +1,296 @@
+import {
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+ within,
+} from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { TransactionHistoryView } from '@/pages/TransactionHistoryPage';
+import type {
+ GetWalletTransactionsParams,
+ WalletTransaction,
+ WalletTransactionPage,
+ WalletTransactionType,
+} from '@/services/transactionHistory.service';
+import * as historyUtils from '@/utils/transactionHistory.utils';
+
+const ADDRESS = 'GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5';
+const HOUR = 60 * 60 * 1000;
+
+const TYPES: WalletTransactionType[] = [
+ 'buy',
+ 'sell',
+ 'stake',
+ 'unstake',
+ 'claim',
+ 'referral',
+ 'swap',
+];
+
+function makeTx(
+ id: string,
+ type: WalletTransactionType,
+ hoursAgo: number
+): WalletTransaction {
+ return {
+ id,
+ type,
+ keyName: `Creator ${id}`,
+ amount: 10,
+ direction: type === 'buy' || type === 'stake' ? 'out' : 'in',
+ fee: 0.01,
+ timestamp: Date.now() - hoursAgo * HOUR,
+ txHash: `hash-${id}`,
+ };
+}
+
+/** Fake API that honours type, range and cursor params. */
+function makeFakeApi(all: WalletTransaction[], pageSize = 100) {
+ return vi.fn(
+ async ({
+ types,
+ from,
+ to,
+ cursor,
+ }: GetWalletTransactionsParams): Promise => {
+ const matching = all.filter(
+ tx =>
+ (!types || types.includes(tx.type)) &&
+ (from === undefined || tx.timestamp >= from) &&
+ (to === undefined || tx.timestamp <= to)
+ );
+ const start = cursor ? Number(cursor) : 0;
+ const end = start + pageSize;
+ return {
+ items: matching.slice(start, end),
+ nextCursor: end < matching.length ? String(end) : null,
+ };
+ }
+ );
+}
+
+function getRowIds() {
+ const list = screen.getByTestId('transaction-history-list');
+ return within(list)
+ .getAllByRole('listitem')
+ .map(li =>
+ li.getAttribute('data-testid')?.replace('transaction-row-', '')
+ );
+}
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+// Multi-step render flows; allow headroom on loaded CI runners.
+describe('TransactionHistoryView', { timeout: 15_000 }, () => {
+ it('renders every event type with its icon and description', async () => {
+ const all = TYPES.map((type, i) => makeTx(type, type, i + 1));
+ render(
+
+ );
+
+ await screen.findByTestId('transaction-history-list');
+
+ for (const type of TYPES) {
+ const row = screen.getByTestId(`transaction-row-${type}`);
+ expect(
+ within(row).getByTestId(`transaction-icon-${type}`)
+ ).toBeInTheDocument();
+ expect(row).toHaveTextContent(
+ historyUtils.describeTransaction(all.find(t => t.type === type)!)
+ );
+ expect(row).toHaveTextContent('Fee 0.01 XLM');
+ }
+ expect(screen.getByTestId('transaction-row-referral')).toHaveTextContent(
+ '+10 XLM'
+ );
+ expect(screen.getByTestId('transaction-row-buy')).toHaveTextContent(
+ '−10 XLM'
+ );
+ });
+
+ it('narrows results with the type filter and sends the types to the API', async () => {
+ const all = TYPES.map((type, i) => makeTx(type, type, i + 1));
+ const fetchPage = makeFakeApi(all);
+ render(
+
+ );
+ await screen.findByTestId('transaction-history-list');
+
+ fireEvent.click(screen.getByRole('button', { name: 'Stakes' }));
+
+ await waitFor(() => expect(getRowIds()).toEqual(['stake', 'unstake']));
+ expect(fetchPage).toHaveBeenLastCalledWith(
+ expect.objectContaining({ types: ['stake', 'unstake'] })
+ );
+ expect(screen.getByRole('button', { name: 'Stakes' })).toHaveAttribute(
+ 'aria-pressed',
+ 'true'
+ );
+ });
+
+ it('drops rows outside the filter even if the API ignores it', async () => {
+ const all = [makeTx('a', 'buy', 1), makeTx('b', 'swap', 2)];
+ const ignoresFilters = vi.fn(async () => ({
+ items: all,
+ nextCursor: null,
+ }));
+ render(
+
+ );
+ await screen.findByTestId('transaction-history-list');
+
+ fireEvent.click(screen.getByRole('button', { name: 'Swaps' }));
+ await waitFor(() => expect(getRowIds()).toEqual(['b']));
+ });
+
+ it('applies date presets and custom ranges', async () => {
+ const all = [
+ makeTx('recent', 'buy', 1),
+ makeTx('week', 'buy', 24 * 5),
+ makeTx('month', 'buy', 24 * 20),
+ makeTx('old', 'buy', 24 * 60),
+ ];
+ render(
+
+ );
+
+ // Default preset is 30 days.
+ await waitFor(() =>
+ expect(getRowIds()).toEqual(['recent', 'week', 'month'])
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: '7 days' }));
+ await waitFor(() => expect(getRowIds()).toEqual(['recent', 'week']));
+
+ fireEvent.click(screen.getByRole('button', { name: 'All time' }));
+ await waitFor(() =>
+ expect(getRowIds()).toEqual(['recent', 'week', 'month', 'old'])
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Custom' }));
+ const day = (d: Date) =>
+ `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+ const old = new Date(all[3].timestamp);
+ fireEvent.change(screen.getByLabelText('From'), {
+ target: { value: day(old) },
+ });
+ fireEvent.change(screen.getByLabelText('To'), {
+ target: { value: day(old) },
+ });
+ await waitFor(() => expect(getRowIds()).toEqual(['old']));
+ });
+
+ it('flags an inverted custom range without fetching', async () => {
+ const fetchPage = makeFakeApi([makeTx('a', 'buy', 1)]);
+ render(
+
+ );
+ await screen.findByTestId('transaction-history-list');
+ const callsBefore = fetchPage.mock.calls.length;
+
+ fireEvent.click(screen.getByRole('button', { name: 'Custom' }));
+ fireEvent.change(screen.getByLabelText('From'), {
+ target: { value: '2026-10-10' },
+ });
+ fireEvent.change(screen.getByLabelText('To'), {
+ target: { value: '2026-10-01' },
+ });
+
+ expect(await screen.findByRole('alert')).toHaveTextContent(
+ /start date must be on or before/i
+ );
+ expect(fetchPage.mock.calls.length).toBe(callsBefore);
+ });
+
+ it('exports the filtered rows to CSV', async () => {
+ const all = [
+ makeTx('a', 'buy', 1),
+ makeTx('b', 'claim', 2),
+ makeTx('c', 'buy', 3),
+ ];
+ const download = vi
+ .spyOn(historyUtils, 'downloadCsv')
+ .mockImplementation(() => {});
+ render(
+
+ );
+ await screen.findByTestId('transaction-history-list');
+
+ fireEvent.click(screen.getByRole('button', { name: 'Buys' }));
+ await waitFor(() => expect(getRowIds()).toEqual(['a', 'c']));
+
+ fireEvent.click(screen.getByRole('button', { name: /export csv/i }));
+
+ expect(download).toHaveBeenCalledTimes(1);
+ const [filename, csv] = download.mock.calls[0];
+ expect(filename).toMatch(
+ /^accesslayer-transactions-buys-30d-\d{4}-\d{2}-\d{2}\.csv$/
+ );
+ expect(csv).toBe(historyUtils.transactionsToCsv([all[0], all[2]]));
+ });
+
+ it('load more appends the next page without duplicates', async () => {
+ const all = Array.from({ length: 5 }, (_, i) =>
+ makeTx(`t${i}`, 'buy', i + 1)
+ );
+ // Page 2 overlaps page 1 by one row, as can happen when new activity
+ // shifts an offset-backed cursor.
+ const fetchPage = vi
+ .fn<
+ (p: GetWalletTransactionsParams) => Promise
+ >()
+ .mockResolvedValueOnce({ items: all.slice(0, 3), nextCursor: 'c1' })
+ .mockResolvedValueOnce({ items: all.slice(2, 5), nextCursor: null });
+
+ render(
+
+ );
+ await waitFor(() => expect(getRowIds()).toEqual(['t0', 't1', 't2']));
+
+ fireEvent.click(screen.getByRole('button', { name: 'Load more' }));
+
+ await waitFor(() =>
+ expect(getRowIds()).toEqual(['t0', 't1', 't2', 't3', 't4'])
+ );
+ expect(fetchPage).toHaveBeenLastCalledWith(
+ expect.objectContaining({ cursor: 'c1' })
+ );
+ expect(
+ screen.queryByRole('button', { name: 'Load more' })
+ ).not.toBeInTheDocument();
+ expect(screen.getByText(/reached the end/i)).toBeInTheDocument();
+ });
+
+ it('shows an error state with retry', async () => {
+ const fetchPage = vi
+ .fn<
+ (p: GetWalletTransactionsParams) => Promise
+ >()
+ .mockRejectedValueOnce(new Error('boom'))
+ .mockResolvedValue({
+ items: [makeTx('a', 'buy', 1)],
+ nextCursor: null,
+ });
+ render(
+
+ );
+
+ expect(await screen.findByRole('alert')).toHaveTextContent(
+ /couldn't load/i
+ );
+ fireEvent.click(screen.getByRole('button', { name: 'Try again' }));
+ await waitFor(() => expect(getRowIds()).toEqual(['a']));
+ });
+});
diff --git a/src/routes.tsx b/src/routes.tsx
index b4add511..dd2891ca 100644
--- a/src/routes.tsx
+++ b/src/routes.tsx
@@ -2,6 +2,10 @@ import HomePage from './pages/HomePage';
import NotFoundPage from './pages/NotFoundPage';
import CreatorDetailPage from './pages/CreatorDetailPage';
import NotificationsPage from './pages/NotificationsPage';
+import NotificationPreferencesPage from './pages/NotificationPreferencesPage';
+import TransactionHistoryPage from './pages/TransactionHistoryPage';
+import SettingsPage from './pages/SettingsPage';
+import ComparePage from './pages/ComparePage';
export const routes = [
{
@@ -24,6 +28,22 @@ export const routes = [
path: '/notifications',
element: ,
},
+ {
+ path: '/settings/notifications',
+ element: ,
+ },
+ {
+ path: '/transactions',
+ element: ,
+ },
+ {
+ path: '/settings',
+ element: ,
+ },
+ {
+ path: '/compare',
+ element: ,
+ },
{
path: '*',
element: ,
diff --git a/src/services/keyMetrics.service.ts b/src/services/keyMetrics.service.ts
new file mode 100644
index 00000000..0e72dd12
--- /dev/null
+++ b/src/services/keyMetrics.service.ts
@@ -0,0 +1,42 @@
+// src/services/keyMetrics.service.ts
+import { BaseApiService, type APIResponse } from './api.service';
+
+export interface CurveMilestone {
+ /** Human-readable milestone name, e.g. "Tier 2". */
+ label: string;
+ /** Progress towards the next milestone, 0–100. */
+ progressPercent: number;
+}
+
+/** Market metrics used by the key comparison page. */
+export interface KeyMetrics {
+ creatorId: string;
+ /** Current key price in XLM. */
+ price: number;
+ /** 24h trading volume in XLM. */
+ volume24h: number;
+ holders: number;
+ /** Distinct wallets that traded the key in the last 30 days. */
+ uniqueTraders: number;
+ /** Average community rating, 0–5. `null` when unrated. */
+ rating: number | null;
+ curveMilestone: CurveMilestone | null;
+ /** Annualised holder yield as a percentage. `null` when not applicable. */
+ yieldPercent: number | null;
+}
+
+class KeyMetricsService extends BaseApiService {
+ /** GET /creators/:id/metrics */
+ async getKeyMetrics(creatorId: string): Promise {
+ try {
+ const response = await this.api.get>(
+ `/creators/${creatorId}/metrics`
+ );
+ return response.data.data;
+ } catch (error) {
+ throw this.handleError(error);
+ }
+ }
+}
+
+export const keyMetricsService = new KeyMetricsService();
diff --git a/src/services/notificationPreferences.service.ts b/src/services/notificationPreferences.service.ts
new file mode 100644
index 00000000..ab103174
--- /dev/null
+++ b/src/services/notificationPreferences.service.ts
@@ -0,0 +1,64 @@
+// src/services/notificationPreferences.service.ts
+import { BaseApiService, type APIResponse } from './api.service';
+
+/** Platform events a user can opt in or out of being notified about. */
+export const NOTIFICATION_PREFERENCE_TYPES = [
+ 'price_alert',
+ 'milestone_reached',
+ 'vesting_cliff',
+ 'staking_reward',
+ 'governance_vote',
+ 'referral_earned',
+ 'key_deprecated',
+] as const;
+
+export type NotificationPreferenceType =
+ (typeof NOTIFICATION_PREFERENCE_TYPES)[number];
+
+/** Delivery channels each notification type can be routed to. */
+export const NOTIFICATION_CHANNELS = ['email', 'inApp'] as const;
+
+export type NotificationChannel = (typeof NOTIFICATION_CHANNELS)[number];
+
+export type ChannelPreferences = Record;
+
+export type NotificationPreferences = Record<
+ NotificationPreferenceType,
+ ChannelPreferences
+>;
+
+class NotificationPreferencesService extends BaseApiService {
+ /** Fetch the current user's preferences — GET /notifications/preferences */
+ async getPreferences(): Promise {
+ try {
+ const response = await this.api.get<
+ APIResponse
+ >('/notifications/preferences');
+ return response.data.data;
+ } catch (error) {
+ throw this.handleError(error);
+ }
+ }
+
+ /**
+ * Replace the current user's preferences — PUT /notifications/preferences
+ *
+ * The full map is sent on every save so the server never has to merge
+ * partial updates that may arrive out of order.
+ */
+ async updatePreferences(
+ preferences: NotificationPreferences
+ ): Promise {
+ try {
+ const response = await this.api.put<
+ APIResponse
+ >('/notifications/preferences', preferences);
+ return response.data.data;
+ } catch (error) {
+ throw this.handleError(error);
+ }
+ }
+}
+
+export const notificationPreferencesService =
+ new NotificationPreferencesService();
diff --git a/src/services/transactionHistory.service.ts b/src/services/transactionHistory.service.ts
new file mode 100644
index 00000000..78a99abe
--- /dev/null
+++ b/src/services/transactionHistory.service.ts
@@ -0,0 +1,78 @@
+// src/services/transactionHistory.service.ts
+import { BaseApiService, type APIResponse } from './api.service';
+
+/** Every kind of wallet event the history page can show. */
+export type WalletTransactionType =
+ 'buy' | 'sell' | 'stake' | 'unstake' | 'claim' | 'referral' | 'swap';
+
+/** Whether value moved into or out of the wallet. */
+export type WalletTransactionDirection = 'in' | 'out';
+
+export interface WalletTransaction {
+ id: string;
+ type: WalletTransactionType;
+ /** Display name of the creator key involved (or the swap pair). */
+ keyName: string;
+ creatorId?: string;
+ /** Transaction value in XLM. */
+ amount: number;
+ direction: WalletTransactionDirection;
+ /** Network + protocol fee paid, in XLM. */
+ fee: number;
+ /** Unix epoch milliseconds. */
+ timestamp: number;
+ txHash?: string;
+}
+
+export interface WalletTransactionPage {
+ items: WalletTransaction[];
+ /** Opaque cursor for the next page; `null` when there are no more. */
+ nextCursor: string | null;
+}
+
+export interface GetWalletTransactionsParams {
+ address: string;
+ /** Restrict to these types; omitted means all types. */
+ types?: WalletTransactionType[];
+ /** Inclusive lower bound, epoch ms. */
+ from?: number;
+ /** Inclusive upper bound, epoch ms. */
+ to?: number;
+ cursor?: string | null;
+ limit?: number;
+}
+
+export const TRANSACTION_HISTORY_PAGE_SIZE = 20;
+
+class TransactionHistoryService extends BaseApiService {
+ /** GET /wallet/:address/transactions */
+ async getTransactions({
+ address,
+ types,
+ from,
+ to,
+ cursor,
+ limit = TRANSACTION_HISTORY_PAGE_SIZE,
+ }: GetWalletTransactionsParams): Promise {
+ try {
+ const response = await this.api.get<
+ APIResponse
+ >(`/wallet/${address}/transactions`, {
+ params: {
+ limit,
+ ...(types?.length ? { types: types.join(',') } : {}),
+ ...(from !== undefined
+ ? { from: new Date(from).toISOString() }
+ : {}),
+ ...(to !== undefined ? { to: new Date(to).toISOString() } : {}),
+ ...(cursor ? { cursor } : {}),
+ },
+ });
+ return response.data.data;
+ } catch (error) {
+ throw this.handleError(error);
+ }
+ }
+}
+
+export const transactionHistoryService = new TransactionHistoryService();
diff --git a/src/utils/__tests__/transactionHistory.utils.test.ts b/src/utils/__tests__/transactionHistory.utils.test.ts
new file mode 100644
index 00000000..68e6985c
--- /dev/null
+++ b/src/utils/__tests__/transactionHistory.utils.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+import type { WalletTransaction } from '@/services/transactionHistory.service';
+import {
+ getTypesForFilter,
+ matchesTransactionFilters,
+ mergeTransactionPages,
+ resolveDateRange,
+ transactionsToCsv,
+} from '@/utils/transactionHistory.utils';
+
+const DAY = 24 * 60 * 60 * 1000;
+// 15 Oct 2026, 15:30 local time.
+const NOW = new Date(2026, 9, 15, 15, 30).getTime();
+
+function tx(overrides: Partial = {}): WalletTransaction {
+ return {
+ id: 'tx-1',
+ type: 'buy',
+ keyName: 'Lena Markov',
+ amount: 12.5,
+ direction: 'out',
+ fee: 0.01,
+ timestamp: NOW - 1000,
+ txHash: 'abc123',
+ ...overrides,
+ };
+}
+
+describe('getTypesForFilter', () => {
+ it('returns no restriction for "all"', () => {
+ expect(getTypesForFilter('all')).toBeUndefined();
+ });
+
+ it('groups stake and unstake under "stakes"', () => {
+ expect(getTypesForFilter('stakes')).toEqual(['stake', 'unstake']);
+ });
+
+ it('maps plural filters to their single type', () => {
+ expect(getTypesForFilter('referrals')).toEqual(['referral']);
+ expect(getTypesForFilter('swaps')).toEqual(['swap']);
+ });
+});
+
+describe('resolveDateRange', () => {
+ it('returns an open range for "all"', () => {
+ expect(resolveDateRange('all', { start: '', end: '' }, NOW)).toEqual({});
+ });
+
+ it('starts "today" at local midnight', () => {
+ const range = resolveDateRange('today', { start: '', end: '' }, NOW);
+ expect(range).toEqual({
+ from: new Date(2026, 9, 15).getTime(),
+ to: NOW,
+ });
+ });
+
+ it('covers the trailing 7 and 30 days', () => {
+ expect(resolveDateRange('7d', { start: '', end: '' }, NOW)).toEqual({
+ from: NOW - 7 * DAY,
+ to: NOW,
+ });
+ expect(resolveDateRange('30d', { start: '', end: '' }, NOW)).toEqual({
+ from: NOW - 30 * DAY,
+ to: NOW,
+ });
+ });
+
+ it('spans whole local days for a custom range', () => {
+ const range = resolveDateRange(
+ 'custom',
+ { start: '2026-10-01', end: '2026-10-03' },
+ NOW
+ );
+ expect(range).toEqual({
+ from: new Date(2026, 9, 1).getTime(),
+ to: new Date(2026, 9, 3, 23, 59, 59, 999).getTime(),
+ });
+ });
+
+ it('returns null for incomplete or inverted custom ranges', () => {
+ expect(
+ resolveDateRange('custom', { start: '2026-10-01', end: '' }, NOW)
+ ).toBeNull();
+ expect(
+ resolveDateRange(
+ 'custom',
+ { start: '2026-10-05', end: '2026-10-01' },
+ NOW
+ )
+ ).toBeNull();
+ });
+});
+
+describe('matchesTransactionFilters', () => {
+ it('filters by type group', () => {
+ expect(
+ matchesTransactionFilters(tx({ type: 'unstake' }), 'stakes', {})
+ ).toBe(true);
+ expect(matchesTransactionFilters(tx({ type: 'buy' }), 'stakes', {})).toBe(
+ false
+ );
+ });
+
+ it('includes both range bounds', () => {
+ const range = { from: 100, to: 200 };
+ expect(
+ matchesTransactionFilters(tx({ timestamp: 100 }), 'all', range)
+ ).toBe(true);
+ expect(
+ matchesTransactionFilters(tx({ timestamp: 200 }), 'all', range)
+ ).toBe(true);
+ expect(
+ matchesTransactionFilters(tx({ timestamp: 99 }), 'all', range)
+ ).toBe(false);
+ expect(
+ matchesTransactionFilters(tx({ timestamp: 201 }), 'all', range)
+ ).toBe(false);
+ });
+});
+
+describe('mergeTransactionPages', () => {
+ it('appends new rows and skips ids already present', () => {
+ const merged = mergeTransactionPages(
+ [tx({ id: 'a' }), tx({ id: 'b' })],
+ [tx({ id: 'b' }), tx({ id: 'c' }), tx({ id: 'c' })]
+ );
+ expect(merged.map(t => t.id)).toEqual(['a', 'b', 'c']);
+ });
+});
+
+describe('transactionsToCsv', () => {
+ it('writes a header and one row per transaction', () => {
+ const csv = transactionsToCsv([
+ tx({ id: 'a', timestamp: Date.UTC(2026, 9, 15, 12) }),
+ tx({
+ id: 'b',
+ type: 'referral',
+ direction: 'in',
+ keyName: 'Kai Osei',
+ amount: 2,
+ fee: 0,
+ txHash: undefined,
+ timestamp: Date.UTC(2026, 9, 14, 8),
+ }),
+ ]);
+ expect(csv.split('\r\n')).toEqual([
+ 'Date,Type,Key,Direction,Amount (XLM),Fee (XLM),Transaction hash',
+ '2026-10-15T12:00:00.000Z,Buy,Lena Markov,Out,12.5,0.01,abc123',
+ '2026-10-14T08:00:00.000Z,Referral payout,Kai Osei,In,2,0,',
+ ]);
+ });
+
+ it('quotes special characters and neutralises formulas', () => {
+ const csv = transactionsToCsv([
+ tx({ keyName: 'Smith, "The" Artist' }),
+ tx({ id: 'x', keyName: '=HYPERLINK("evil")' }),
+ ]);
+ const [, first, second] = csv.split('\r\n');
+ expect(first).toContain('"Smith, ""The"" Artist"');
+ expect(second).toContain(`"'=HYPERLINK(""evil"")"`);
+ });
+});
diff --git a/src/utils/transactionHistory.utils.ts b/src/utils/transactionHistory.utils.ts
new file mode 100644
index 00000000..857f171d
--- /dev/null
+++ b/src/utils/transactionHistory.utils.ts
@@ -0,0 +1,236 @@
+import type {
+ WalletTransaction,
+ WalletTransactionType,
+} from '@/services/transactionHistory.service';
+
+export type TransactionTypeFilter =
+ 'all' | 'buys' | 'sells' | 'stakes' | 'claims' | 'swaps' | 'referrals';
+
+export const TRANSACTION_TYPE_FILTERS: {
+ value: TransactionTypeFilter;
+ label: string;
+}[] = [
+ { value: 'all', label: 'All' },
+ { value: 'buys', label: 'Buys' },
+ { value: 'sells', label: 'Sells' },
+ { value: 'stakes', label: 'Stakes' },
+ { value: 'claims', label: 'Claims' },
+ { value: 'swaps', label: 'Swaps' },
+ { value: 'referrals', label: 'Referrals' },
+];
+
+/**
+ * Maps each filter chip to the event types it includes. "Stakes" covers
+ * both staking and unstaking so users see the full lifecycle in one view.
+ * `null` means no type restriction.
+ */
+const FILTER_TYPES: Record<
+ TransactionTypeFilter,
+ WalletTransactionType[] | null
+> = {
+ all: null,
+ buys: ['buy'],
+ sells: ['sell'],
+ stakes: ['stake', 'unstake'],
+ claims: ['claim'],
+ swaps: ['swap'],
+ referrals: ['referral'],
+};
+
+export function getTypesForFilter(
+ filter: TransactionTypeFilter
+): WalletTransactionType[] | undefined {
+ return FILTER_TYPES[filter] ?? undefined;
+}
+
+export type DateRangePreset = 'all' | 'today' | '7d' | '30d' | 'custom';
+
+export const DATE_RANGE_PRESETS: { value: DateRangePreset; label: string }[] = [
+ { value: 'all', label: 'All time' },
+ { value: 'today', label: 'Today' },
+ { value: '7d', label: '7 days' },
+ { value: '30d', label: '30 days' },
+ { value: 'custom', label: 'Custom' },
+];
+
+export interface CustomDateRange {
+ /** `YYYY-MM-DD` from a date input, interpreted in local time. */
+ start: string;
+ end: string;
+}
+
+export interface ResolvedDateRange {
+ from?: number;
+ to?: number;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function parseLocalDate(value: string): Date | null {
+ const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+ if (!match) return null;
+ const date = new Date(
+ Number(match[1]),
+ Number(match[2]) - 1,
+ Number(match[3])
+ );
+ return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function startOfDay(date: Date): number {
+ const copy = new Date(date);
+ copy.setHours(0, 0, 0, 0);
+ return copy.getTime();
+}
+
+function endOfDay(date: Date): number {
+ const copy = new Date(date);
+ copy.setHours(23, 59, 59, 999);
+ return copy.getTime();
+}
+
+/**
+ * Converts a preset (or custom inputs) into epoch-ms bounds. Returns
+ * `null` when a custom range is incomplete or inverted so callers can
+ * hold off fetching and show a validation hint instead.
+ */
+export function resolveDateRange(
+ preset: DateRangePreset,
+ custom: CustomDateRange,
+ now: number = Date.now()
+): ResolvedDateRange | null {
+ switch (preset) {
+ case 'all':
+ return {};
+ case 'today':
+ return { from: startOfDay(new Date(now)), to: now };
+ case '7d':
+ return { from: now - 7 * DAY_MS, to: now };
+ case '30d':
+ return { from: now - 30 * DAY_MS, to: now };
+ case 'custom': {
+ const start = parseLocalDate(custom.start);
+ const end = parseLocalDate(custom.end);
+ if (!start || !end) return null;
+ const from = startOfDay(start);
+ const to = endOfDay(end);
+ if (from > to) return null;
+ return { from, to };
+ }
+ }
+}
+
+/**
+ * Client-side guard applied on top of the server query so the list never
+ * shows rows outside the active filter, even if the API ignores a param.
+ */
+export function matchesTransactionFilters(
+ tx: WalletTransaction,
+ filter: TransactionTypeFilter,
+ range: ResolvedDateRange
+): boolean {
+ const types = getTypesForFilter(filter);
+ if (types && !types.includes(tx.type)) return false;
+ if (range.from !== undefined && tx.timestamp < range.from) return false;
+ if (range.to !== undefined && tx.timestamp > range.to) return false;
+ return true;
+}
+
+/** Appends a page while dropping rows already shown (cursor overlap). */
+export function mergeTransactionPages(
+ existing: WalletTransaction[],
+ incoming: WalletTransaction[]
+): WalletTransaction[] {
+ const seen = new Set(existing.map(tx => tx.id));
+ const merged = [...existing];
+ for (const tx of incoming) {
+ if (seen.has(tx.id)) continue;
+ seen.add(tx.id);
+ merged.push(tx);
+ }
+ return merged;
+}
+
+export const TRANSACTION_TYPE_LABELS: Record = {
+ buy: 'Buy',
+ sell: 'Sell',
+ stake: 'Stake',
+ unstake: 'Unstake',
+ claim: 'Claim',
+ referral: 'Referral payout',
+ swap: 'Swap',
+};
+
+export function describeTransaction(tx: WalletTransaction): string {
+ switch (tx.type) {
+ case 'buy':
+ return `Bought ${tx.keyName} keys`;
+ case 'sell':
+ return `Sold ${tx.keyName} keys`;
+ case 'stake':
+ return `Staked ${tx.keyName} keys`;
+ case 'unstake':
+ return `Unstaked ${tx.keyName} keys`;
+ case 'claim':
+ return `Claimed ${tx.keyName} rewards`;
+ case 'referral':
+ return `Referral payout from ${tx.keyName}`;
+ case 'swap':
+ return `Swapped ${tx.keyName}`;
+ }
+}
+
+const CSV_HEADERS = [
+ 'Date',
+ 'Type',
+ 'Key',
+ 'Direction',
+ 'Amount (XLM)',
+ 'Fee (XLM)',
+ 'Transaction hash',
+];
+
+/**
+ * Quotes a CSV field when needed and neutralises spreadsheet formula
+ * injection, since key names are creator-controlled text.
+ */
+function escapeCsvField(value: string): string {
+ const safe = /^[=+\-@\t\r]/.test(value) ? `'${value}` : value;
+ return /[",\r\n]/.test(safe) ? `"${safe.replace(/"/g, '""')}"` : safe;
+}
+
+export function transactionsToCsv(transactions: WalletTransaction[]): string {
+ const rows = transactions.map(tx =>
+ [
+ new Date(tx.timestamp).toISOString(),
+ TRANSACTION_TYPE_LABELS[tx.type],
+ tx.keyName,
+ tx.direction === 'in' ? 'In' : 'Out',
+ String(tx.amount),
+ String(tx.fee),
+ tx.txHash ?? '',
+ ].map(escapeCsvField)
+ );
+ return [CSV_HEADERS, ...rows].map(row => row.join(',')).join('\r\n');
+}
+
+export function buildTransactionCsvFilename(
+ filter: TransactionTypeFilter,
+ preset: DateRangePreset,
+ now: number = Date.now()
+): string {
+ const date = new Date(now).toISOString().slice(0, 10);
+ return `accesslayer-transactions-${filter}-${preset}-${date}.csv`;
+}
+
+export function downloadCsv(filename: string, csv: string): void {
+ const blob = new Blob([csv], { type: 'text/csv;charset=utf-8' });
+ const url = URL.createObjectURL(blob);
+ const link = document.createElement('a');
+ link.href = url;
+ link.download = filename;
+ document.body.appendChild(link);
+ link.click();
+ link.remove();
+ URL.revokeObjectURL(url);
+}
diff --git a/src/utils/useSystemTheme.ts b/src/utils/useSystemTheme.ts
index 0cdf5018..cfe7a80f 100644
--- a/src/utils/useSystemTheme.ts
+++ b/src/utils/useSystemTheme.ts
@@ -1,23 +1,14 @@
-import { useState, useEffect } from 'react';
-
+import { useTheme } from '@/hooks/useTheme';
+
+/**
+ * Whether the app is currently rendering in dark mode.
+ *
+ * Kept for existing callers (e.g. sparkline colours). Since #1085 this
+ * follows the app theme — which defaults to the OS preference but can be
+ * overridden by the user — rather than reading `prefers-color-scheme`
+ * directly.
+ */
export function useSystemTheme() {
- const [isDarkMode, setIsDarkMode] = useState(() => {
- if (typeof window === 'undefined') return false;
- return window.matchMedia('(prefers-color-scheme: dark)').matches;
- });
-
- useEffect(() => {
- if (typeof window === 'undefined') return;
-
- const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
-
- const callback = (e: MediaQueryListEvent) => {
- setIsDarkMode(e.matches);
- };
-
- mediaQuery.addEventListener('change', callback);
- return () => mediaQuery.removeEventListener('change', callback);
- }, []);
-
- return { isDarkMode };
+ const { isDark } = useTheme();
+ return { isDarkMode: isDark };
}