From cb294938ef30657df2ff39941db805293f1a25ba Mon Sep 17 00:00:00 2001
From: Tim Hostetler <6970899+thostetler@users.noreply.github.com>
Date: Thu, 21 May 2026 12:56:11 -0400
Subject: [PATCH 1/2] feat: add SearchModifierBar with ADS Compatibility mode

Adds a search mode selector that scopes results to astronomy and physics
content (fq_database filter + date sort) when ADS Compatibility mode is
active. Mode persists in a scix_prefs cookie seeded by middleware on
legacy ADS referrer detection.

- SearchModifierBar component (landing page only, ASTROPHYSICS mode gated)
- SearchMode enum, applySearchModeDefaults, buildSearchOutgoing helpers
- scix_prefs cookie read/write utilities (prefs-cookie.ts)
- useSearchMode hook backed by Zustand appMode slice
- Middleware seeds cookie on /astrophysics discipline routes and ADS referrer
- SSR reads cookie to hydrate mode/searchMode before first render
- ADS referrer redirects to /?fromADS=true; landing page shows info toast
- store.ts: synchronous mode sync on navigation, searchMode excluded from
  navigation merge to preserve user changes
---
 .../AbstractSearchForm/AbstractSearchForm.tsx | 18 ++---
 src/components/ClassicForm/ClassicForm.tsx    |  5 +-
 .../SearchModifierBar/SearchModifierBar.tsx   | 76 +++++++++++++++++++
 src/components/SearchModifierBar/index.ts     |  1 +
 .../SearchQueryLink/SearchQueryLink.tsx       | 21 +++--
 src/config.ts                                 |  2 +-
 src/lib/useSearchMode.ts                      |  7 ++
 src/middleware.ts                             | 51 +++++++++++--
 src/pages/_app.tsx                            | 21 ++++-
 src/pages/_document.tsx                       |  2 +-
 src/pages/index.tsx                           | 32 +++++++-
 src/pages/search/index.tsx                    | 27 +++++--
 src/providers.tsx                             | 15 ++--
 src/ssr-utils.ts                              | 59 ++++++--------
 src/store/slices/appMode.ts                   | 20 ++++-
 src/store/store.ts                            | 29 ++++++-
 src/types.ts                                  |  1 -
 src/utils/common/prefs-cookie.ts              | 38 ++++++++++
 src/utils/common/searchMode.ts                | 62 +++++++++++++++
 tsconfig.json                                 |  2 +-
 20 files changed, 394 insertions(+), 95 deletions(-)
 create mode 100644 src/components/SearchModifierBar/SearchModifierBar.tsx
 create mode 100644 src/components/SearchModifierBar/index.ts
 create mode 100644 src/lib/useSearchMode.ts
 create mode 100644 src/utils/common/prefs-cookie.ts
 create mode 100644 src/utils/common/searchMode.ts

diff --git a/src/components/AbstractSearchForm/AbstractSearchForm.tsx b/src/components/AbstractSearchForm/AbstractSearchForm.tsx
index 49db29c85..6fbe1879f 100644
--- a/src/components/AbstractSearchForm/AbstractSearchForm.tsx
+++ b/src/components/AbstractSearchForm/AbstractSearchForm.tsx
@@ -8,17 +8,16 @@ import router from 'next/router';
 import { applyFiltersToQuery } from '../SearchFacet/helpers';
 import { DatabaseEnum, IADSApiUserDataResponse } from '@/api/user/types';
 import { SolrSort } from '@/api/models';
+import { buildSearchOutgoing } from '@/utils/common/searchMode';
+import { useSearchMode } from '@/lib/useSearchMode';
 
 export const AbstractSearchForm = () => {
   const { settings } = useSettings();
   const submitQuery = useStore((state) => state.submitQuery);
   const sort = [`${settings.preferredSearchSort} desc` as SolrSort];
   const query = useStore((state) => state.query.q);
+  const [searchMode] = useSearchMode();
 
-  /**
-   * Take in a query object and apply any FQ filters
-   * These will either be any default ON filters or whatever has been set by the user in the preferences
-   */
   const applyDefaultFilters = useCallback(
     (query: IADSApiSearchParams) => {
       const defaultDatabases = getListOfAppliedDefaultDatabases(settings.defaultDatabase);
@@ -35,18 +34,12 @@ export const AbstractSearchForm = () => {
     [settings.defaultDatabase],
   );
 
-  /**
-   * Get a list of default databases that have been applied
-   * @param databases
-   */
   const getListOfAppliedDefaultDatabases = (databases: IADSApiUserDataResponse['defaultDatabase']): Array<string> => {
     const defaultDatabases = [];
     for (const db of databases) {
-      // if All is selected, exit early here and return an empty array (no filters to apply)
       if (db.name === DatabaseEnum.All && db.value) {
         return [];
       }
-
       if (db.value) {
         defaultDatabases.push(db.name);
       }
@@ -62,13 +55,14 @@ export const AbstractSearchForm = () => {
       if (query && query.trim().length > 0) {
         submitQuery();
         const defaultedQuery = applyDefaultFilters({ q: query, sort, p: 1 }) as IADSApiSearchParams;
+        const outgoing = buildSearchOutgoing(defaultedQuery, searchMode);
         void router.push({
           pathname: '/search',
-          search: makeSearchParams(defaultedQuery),
+          search: makeSearchParams(outgoing),
         });
       }
     },
-    [applyDefaultFilters, sort, submitQuery],
+    [applyDefaultFilters, searchMode, sort, submitQuery],
   );
 
   return (
diff --git a/src/components/ClassicForm/ClassicForm.tsx b/src/components/ClassicForm/ClassicForm.tsx
index 4f0d32f92..109a06141 100644
--- a/src/components/ClassicForm/ClassicForm.tsx
+++ b/src/components/ClassicForm/ClassicForm.tsx
@@ -41,6 +41,7 @@ import { Sort } from '@/components/Sort';
 import { Expandable } from '@/components/Expandable';
 import { SimpleCopyButton } from '@/components/CopyButton';
 import { normalizeSolrSort } from '@/utils/common/search';
+import { ADS_COMPAT_URL_PARAM } from '@/utils/common/searchMode';
 import { SolrSort, SolrSortField } from '@/api/models';
 
 const propTypes = {
@@ -84,7 +85,9 @@ export const ClassicForm = (props: IClassicFormProps) => {
     void handleSubmit((params) => {
       try {
         const search = getSearchQuery(params, { mode });
-        void router.push({ pathname: '/search', search });
+        const urlParams = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
+        urlParams.set(ADS_COMPAT_URL_PARAM, '1');
+        void router.push({ pathname: '/search', search: '?' + urlParams.toString() });
       } catch (e) {
         setQueryError((e as Error)?.message);
       }
diff --git a/src/components/SearchModifierBar/SearchModifierBar.tsx b/src/components/SearchModifierBar/SearchModifierBar.tsx
new file mode 100644
index 000000000..2421e7901
--- /dev/null
+++ b/src/components/SearchModifierBar/SearchModifierBar.tsx
@@ -0,0 +1,76 @@
+import { Box, BoxProps, Button, Circle, Menu, MenuButton, MenuItem, MenuList, Text, VStack } from '@chakra-ui/react';
+import { ChevronDownIcon } from '@chakra-ui/icons';
+import { useRouter } from 'next/router';
+import { omit } from 'ramda';
+import { ADS_COMPAT_URL_PARAM, SEARCH_MODE_OPTIONS, SearchMode } from '@/utils/common/searchMode';
+import { useSearchMode } from '@/lib/useSearchMode';
+
+interface SearchModifierBarProps extends BoxProps {
+  onModeChange?: (mode: SearchMode) => void;
+  onNavigate?: (mode: SearchMode) => void;
+  isDisabled?: boolean;
+}
+
+export const SearchModifierBar = ({ onModeChange, onNavigate, isDisabled, ...boxProps }: SearchModifierBarProps) => {
+  const router = useRouter();
+  const [storedMode, setStoredMode] = useSearchMode();
+  const urlAdsCompat = router.query[ADS_COMPAT_URL_PARAM] === '1';
+  const currentMode =
+    urlAdsCompat || storedMode === SearchMode.ADS_COMPAT ? SearchMode.ADS_COMPAT : SearchMode.ALL_RELEVANT;
+  const currentOption = SEARCH_MODE_OPTIONS.find((o) => o.mode === currentMode) ?? SEARCH_MODE_OPTIONS[0];
+
+  const handleModeChange = (newMode: SearchMode) => {
+    setStoredMode(newMode);
+    onModeChange?.(newMode);
+    if (onNavigate) {
+      onNavigate(newMode);
+    } else {
+      const updatedQuery =
+        newMode === SearchMode.ADS_COMPAT
+          ? { ...router.query, [ADS_COMPAT_URL_PARAM]: '1' }
+          : omit([ADS_COMPAT_URL_PARAM], router.query);
+      void router.push({ pathname: router.pathname, query: updatedQuery }, undefined, { shallow: true });
+    }
+  };
+
+  const modeColor = currentMode === SearchMode.ADS_COMPAT ? 'orange.400' : 'teal.400';
+
+  return (
+    <Box {...boxProps}>
+      <Menu>
+        <MenuButton
+          as={Button}
+          variant="ghost"
+          size="sm"
+          leftIcon={<Circle size="8px" bg={modeColor} />}
+          rightIcon={<ChevronDownIcon />}
+          aria-label={`Search mode: ${currentOption.label}`}
+          isDisabled={isDisabled}
+        >
+          <Text as="span" fontWeight="normal" mr={1} fontSize="sm">
+            Search mode:
+          </Text>
+          <Text as="span" fontWeight="semibold" fontSize="sm">
+            {currentOption.label}
+          </Text>
+        </MenuButton>
+        <MenuList>
+          {SEARCH_MODE_OPTIONS.map((option) => (
+            <MenuItem
+              key={option.mode}
+              onClick={() => handleModeChange(option.mode)}
+              fontWeight={option.mode === currentMode ? 'semibold' : 'normal'}
+            >
+              <VStack align="start" spacing={0}>
+                <Text fontSize="sm">{option.label}</Text>
+                <Text fontSize="xs" color="gray.500">
+                  {option.helperText}
+                </Text>
+              </VStack>
+            </MenuItem>
+          ))}
+        </MenuList>
+      </Menu>
+    </Box>
+  );
+};
diff --git a/src/components/SearchModifierBar/index.ts b/src/components/SearchModifierBar/index.ts
new file mode 100644
index 000000000..0e66847d7
--- /dev/null
+++ b/src/components/SearchModifierBar/index.ts
@@ -0,0 +1 @@
+export { SearchModifierBar } from './SearchModifierBar';
diff --git a/src/components/SearchQueryLink/SearchQueryLink.tsx b/src/components/SearchQueryLink/SearchQueryLink.tsx
index 01be2b53b..7488cfa33 100644
--- a/src/components/SearchQueryLink/SearchQueryLink.tsx
+++ b/src/components/SearchQueryLink/SearchQueryLink.tsx
@@ -4,22 +4,28 @@ import { useRouter } from 'next/router';
 import { ISimpleLinkProps, SimpleLink } from '@/components/SimpleLink';
 import { makeSearchParams } from '@/utils/common/search';
 import { IADSApiSearchParams } from '@/api/search/types';
+import { useStore } from '@/store';
+import { buildSearchOutgoing } from '@/utils/common/searchMode';
 
 export interface ISearchQueryLinkProps extends Omit<ISimpleLinkProps, 'href'> {
   params: IADSApiSearchParams;
 }
 
-const getSearchUrl = (params: IADSApiSearchParams) => `/search?${makeSearchParams(params)}`;
+const getSearchUrl = (params: IADSApiSearchParams, searchMode: string) =>
+  `/search?${makeSearchParams(buildSearchOutgoing(params, searchMode))}`;
 
-/**
- * Wrapper around next/link to create a simple link to the search page
- * This generates the URL based on the params passed in
- */
 export const SearchQueryLink = (props: ISearchQueryLinkProps): ReactElement => {
   const { params, replace = false, shallow = false, prefetch = false, ...linkProps } = props;
+  const searchMode = useStore((s) => s.searchMode);
 
   return (
-    <SimpleLink replace={replace} shallow={shallow} prefetch={prefetch} {...linkProps} href={getSearchUrl(params)} />
+    <SimpleLink
+      replace={replace}
+      shallow={shallow}
+      prefetch={prefetch}
+      {...linkProps}
+      href={getSearchUrl(params, searchMode)}
+    />
   );
 };
 
@@ -29,10 +35,11 @@ export interface ISearchQueryLinkButtonProps extends Omit<ButtonProps, 'onClick'
 export const SearchQueryLinkButton = (props: ISearchQueryLinkButtonProps) => {
   const { params, ...buttonProps } = props;
   const router = useRouter();
+  const searchMode = useStore((s) => s.searchMode);
 
   const handleClick: MouseEventHandler<HTMLButtonElement> = (e) => {
     e.preventDefault();
-    void router.push(getSearchUrl(params));
+    void router.push(getSearchUrl(params, searchMode));
   };
 
   return <Button type="button" onClick={handleClick} {...buttonProps} />;
diff --git a/src/config.ts b/src/config.ts
index 1ce49c397..05544331d 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -8,7 +8,7 @@ export const APP_DEFAULTS = {
   DEFAULT_AUTHORS_PER_RESULT: 4,
   MAX_AUTHORS_PER_RESULT_OPTION: 50, // Max value for authors-per-result preference (also used for legacy "all")
   RESULT_PER_PAGE: 10,
-  PER_PAGE_OPTIONS: [10, 25, 50, 100, 500],
+  PER_PAGE_OPTIONS: process.env.NODE_ENV === 'development' ? [1, 3, 10, 25, 50, 100, 500] : [10, 25, 50, 100, 500],
   SORT: ['score desc', 'date desc'] as SolrSort[],
   QUERY_SORT_POSTFIX: 'date desc' as SolrSort,
   EXPORT_PAGE_SIZE: 500,
diff --git a/src/lib/useSearchMode.ts b/src/lib/useSearchMode.ts
new file mode 100644
index 000000000..208c8c4c5
--- /dev/null
+++ b/src/lib/useSearchMode.ts
@@ -0,0 +1,7 @@
+import { useStore } from '@/store';
+
+export const useSearchMode = () => {
+  const searchMode = useStore((s) => s.searchMode);
+  const setSearchMode = useStore((s) => s.setSearchMode);
+  return [searchMode, setSearchMode] as const;
+};
diff --git a/src/middleware.ts b/src/middleware.ts
index 5af8d0c99..b01e62ebe 100644
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -8,7 +8,8 @@ import { rateLimit } from '@/rateLimit';
 import { isLegacySearchURL, legacySearchURLMiddleware } from '@/middlewares/legacySearchURLMiddleware';
 import { ErrorSource, handleError } from '@/lib/errorHandler.edge';
 import { getUserLogId, sanitizeHeaderValue } from '@/utils/logging';
-import { mapPathToDisciplineParam } from '@/utils/appMode';
+import { mapDisciplineParamToAppMode, mapPathToDisciplineParam } from '@/utils/appMode';
+import { AppMode } from '@/types';
 import { isFromLegacyApp } from '@/utils/legacyAppDetection';
 import { pickTracingHeadersEdge } from '@/utils/tracing.edge';
 
@@ -301,6 +302,28 @@ const getIp = (req: NextRequest) =>
     .split(',')
     .shift() || 'unknown';
 
+const PREFS_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+
+const setPrefsCookie = (response: NextResponse, req: NextRequest, updates: Record<string, unknown>): void => {
+  let existing: Record<string, unknown> = {};
+  try {
+    const raw = req.cookies.get('scix_prefs')?.value;
+    if (raw) {
+      existing = JSON.parse(decodeURIComponent(raw)) as Record<string, unknown>;
+    }
+  } catch {
+    // ignore malformed cookie
+  }
+  const merged = { ...existing, ...updates };
+  Object.keys(merged).forEach((k) => merged[k] === undefined && delete merged[k]);
+  response.cookies.set('scix_prefs', JSON.stringify(merged), {
+    maxAge: PREFS_COOKIE_MAX_AGE,
+    path: '/',
+    sameSite: 'lax',
+    secure: process.env.NODE_ENV === 'production',
+  });
+};
+
 export async function middleware(req: NextRequest) {
   const startTime = Date.now();
   const path = req.nextUrl.pathname;
@@ -335,22 +358,36 @@ export async function middleware(req: NextRequest) {
   }
 
   // Discipline route handling - redirect /astrophysics, /heliophysics, etc. to /?forceMode=X
+  // Also stamp the prefs cookie so SSR can seed the mode on subsequent pages without a forceMode param.
   const disciplineParam = mapPathToDisciplineParam(path);
   if (disciplineParam) {
     const url = new URL('/', req.url);
     url.searchParams.set('forceMode', disciplineParam);
     log.info({ path, disciplineParam, duration: Date.now() - startTime }, 'Discipline route redirect');
-    return NextResponse.redirect(url);
+    const response = NextResponse.redirect(url);
+    const mappedMode = mapDisciplineParamToAppMode(disciplineParam);
+    if (mappedMode) {
+      const updates: Record<string, unknown> = { mode: mappedMode };
+      if (mappedMode !== AppMode.ASTROPHYSICS) {
+        updates.searchMode = undefined; // clear ADS_COMPAT when not in astrophysics context
+      }
+      setPrefsCookie(response, req, updates);
+    }
+    return response;
   }
 
-  // Legacy ADS app referrer handling - redirect to /?forceMode=astrophysics
-  // This ensures the discipline switch happens immediately, not on next search
-  if (path === '/' && !req.nextUrl.searchParams.has('forceMode')) {
+  // Legacy ADS app referrer handling - redirect to /?fromADS=true and set scix_prefs cookie
+  // so updateUserStateSSR seeds mode/searchMode without URL pollution.
+  // Guard includes fromADS to prevent a redirect loop: some browsers preserve the Referer
+  // header across same-origin redirects, which would re-trigger this block on the follow-up GET.
+  if (path === '/' && !req.nextUrl.searchParams.has('forceMode') && !req.nextUrl.searchParams.has('fromADS')) {
     if (isFromLegacyApp(referer)) {
       const url = new URL('/', req.url);
-      url.searchParams.set('forceMode', 'astrophysics');
+      url.searchParams.set('fromADS', 'true');
       log.info({ referer, duration: Date.now() - startTime }, 'Legacy ADS referrer redirect');
-      return NextResponse.redirect(url);
+      const response = NextResponse.redirect(url);
+      setPrefsCookie(response, req, { mode: 'ASTROPHYSICS', searchMode: 'ADS_COMPAT' });
+      return response;
     }
   }
 
diff --git a/src/pages/_app.tsx b/src/pages/_app.tsx
index dcbe5b85d..edb52640a 100644
--- a/src/pages/_app.tsx
+++ b/src/pages/_app.tsx
@@ -1,10 +1,10 @@
 import { AppState, useStore, useStoreApi } from '@/store';
 import { AppMode } from '@/types';
-import { AppProps, NextWebVitalsMetric } from 'next/app';
+import App, { AppContext, AppProps, NextWebVitalsMetric } from 'next/app';
 import dynamic from 'next/dynamic';
 import { useRouter } from 'next/router';
 import 'nprogress/nprogress.css';
-import { memo, ReactElement, useEffect, useMemo } from 'react';
+import { ReactElement, useEffect, useMemo } from 'react';
 import { DehydratedState, useQuery, useQueryClient } from '@tanstack/react-query';
 import { IronSession } from 'iron-session';
 import axios from 'axios';
@@ -48,10 +48,11 @@ const TopProgressBar = dynamic<Record<string, never>>(
 export type AppPageProps = {
   dehydratedState: DehydratedState;
   dehydratedAppState: AppState;
+  cookies?: string;
   [key: string]: unknown;
 };
 
-const NectarApp = memo(({ Component, pageProps }: AppProps): ReactElement => {
+function NectarApp({ Component, pageProps }: AppProps): ReactElement {
   logger.debug('App', { props: pageProps as unknown });
   const router = useRouter();
 
@@ -76,9 +77,21 @@ const NectarApp = memo(({ Component, pageProps }: AppProps): ReactElement => {
       </Providers>
     </>
   );
-});
+}
+
 NectarApp.displayName = 'NectarApp';
 
+NectarApp.getInitialProps = async (appContext: AppContext) => {
+  const appProps = await App.getInitialProps(appContext);
+  return {
+    ...appProps,
+    pageProps: {
+      ...appProps.pageProps,
+      cookies: appContext.ctx.req?.headers.cookie ?? '',
+    },
+  };
+};
+
 const AppModeRouter = (): ReactElement => {
   const mode = useStore((state) => state.mode);
   const router = useRouter();
diff --git a/src/pages/_document.tsx b/src/pages/_document.tsx
index c964fab13..ea0ce332d 100644
--- a/src/pages/_document.tsx
+++ b/src/pages/_document.tsx
@@ -9,7 +9,7 @@ class MyDocument extends Document {
       <Html lang="en">
         <Head />
         <body>
-          <ColorModeScript initialColorMode={theme.config.initialColorMode} />
+          <ColorModeScript type="cookie" initialColorMode={theme.config.initialColorMode} />
           <Main />
           <NextScript />
         </body>
diff --git a/src/pages/index.tsx b/src/pages/index.tsx
index ab6e9c693..bc734ae3e 100644
--- a/src/pages/index.tsx
+++ b/src/pages/index.tsx
@@ -14,6 +14,7 @@ import {
   StatLabel,
   StatNumber,
   Text,
+  useToast,
   VisuallyHidden,
 } from '@chakra-ui/react';
 
@@ -27,8 +28,10 @@ import { useSettings } from '@/lib/useSettings';
 
 import { NotificationId } from '@/store/slices';
 import { SearchBar } from '@/components/SearchBar';
+import { SearchModifierBar } from '@/components/SearchModifierBar';
 import { SimpleLink } from '@/components/SimpleLink';
 import { makeSearchParams, normalizeSolrSort } from '@/utils/common/search';
+import { buildSearchOutgoing } from '@/utils/common/searchMode';
 import { SolrSort } from '@/api/models';
 import { SearchExamples } from '@/components/SearchExamples/SearchExamples';
 import { Pager } from '@/components/Pager/Pager';
@@ -47,6 +50,7 @@ import { useShepherd } from 'react-shepherd';
 import { useIsClient } from '@/lib/useIsClient';
 import { useScreenSize } from '@/lib/useScreenSize';
 import { useLandingFormPreference } from '@/lib/useLandingFormPreference';
+import { useSearchMode } from '@/lib/useSearchMode';
 
 const HomePage: NextPage = () => {
   const { settings } = useSettings();
@@ -68,6 +72,24 @@ const HomePage: NextPage = () => {
   const { isScreenSmall } = useScreenSize();
   const isClient = useIsClient();
   const { persistCurrentForm } = useLandingFormPreference();
+  const [searchMode, setSearchMode] = useSearchMode();
+  const toast = useToast();
+
+  // Show toast when middleware has auto-set ADS_COMPAT (cookie/GSSP path)
+  useEffect(() => {
+    if (router.query.fromADS !== 'true') {
+      return;
+    }
+    toast({
+      status: 'info',
+      duration: 10000,
+      isClosable: true,
+      position: 'top',
+      title: 'ADS Compatibility mode enabled',
+      description:
+        "Looks like you came from ADS — we've switched to ADS Compatibility mode automatically. You can change this using the Search mode menu.",
+    });
+  }, [router.query.fromADS, toast]);
 
   // start tour if first time
   useTour();
@@ -143,17 +165,18 @@ const HomePage: NextPage = () => {
         setIsLoading(true);
         submitQuery();
         const defaultedQuery = applyDefaultFilters({ q: query, sort, p: 1 }) as IADSApiSearchParams;
+        const outgoing = buildSearchOutgoing(defaultedQuery, searchMode);
         void router
           .push({
             pathname: '/search',
-            search: makeSearchParams(defaultedQuery),
+            search: makeSearchParams(outgoing),
           })
           .finally(() => {
             setIsLoading(false);
           });
       }
     },
-    [applyDefaultFilters, router, setIsLoading, sort, submitQuery],
+    [applyDefaultFilters, router, searchMode, setIsLoading, sort, submitQuery],
   );
 
   const handleQueryExampleSelect = useCallback(
@@ -173,6 +196,11 @@ const HomePage: NextPage = () => {
         <Flex direction="column">
           <Box my={2}>
             <SearchBar isLoading={isLoading} query={query} queryAddition={queryAddition} />
+            {mode === AppMode.ASTROPHYSICS && (
+              <Flex direction="row" mt={1}>
+                <SearchModifierBar onModeChange={(m) => setSearchMode(m)} ml="auto" />
+              </Flex>
+            )}
           </Box>
           {isScreenSmall && isClient ? (
             <>
diff --git a/src/pages/search/index.tsx b/src/pages/search/index.tsx
index fd098c622..4ff23ef2d 100644
--- a/src/pages/search/index.tsx
+++ b/src/pages/search/index.tsx
@@ -53,6 +53,7 @@ import { CustomInfoMessage } from '@/components/Feedbacks';
 import { CheckCircleIcon } from '@chakra-ui/icons';
 import { SimpleLink } from '@/components/SimpleLink';
 import { makeSearchParams, normalizeSolrSort, parseQueryFromUrl } from '@/utils/common/search';
+import { ADS_COMPAT_URL_PARAM, buildSearchOutgoing, SearchMode } from '@/utils/common/searchMode';
 import { IADSApiSearchParams, IADSApiSearchResponse } from '@/api/search/types';
 import { SEARCH_API_KEYS, useSearch } from '@/api/search/search';
 import { defaultParams } from '@/api/search/models';
@@ -60,6 +61,7 @@ import { solrDefaultSortDirection, SolrSort, SolrSortField } from '@/api/models'
 import { useApplyBoostTypeToParams } from '@/lib/useApplyBoostTypeToParams';
 import { SearchErrorAlert } from '@/components/SolrErrorAlert/SolrErrorAlert';
 import { useSettings } from '@/lib/useSettings';
+import { useSearchMode } from '@/lib/useSearchMode';
 import { getResultsSteps } from '@/components/NavBar';
 import { useShepherd } from 'react-shepherd';
 import { ErrorBoundary, FallbackProps } from 'react-error-boundary';
@@ -112,8 +114,6 @@ const selectors = {
   resetSearchFacets: (state: AppState) => state.resetSearchFacets,
 };
 
-const omitP = omit(['p']);
-
 /**
  * Error fallback component for error boundaries
  */
@@ -157,6 +157,17 @@ const SearchPage: NextPage = () => {
 
   // parse the query params from the URL, this should match what the server parsed
   const parsedParams = parseQueryFromUrl(router.asPath);
+
+  const [searchMode, setSearchMode] = useSearchMode();
+
+  // Sync searchMode from URL ads_compat param — '1' means ADS_COMPAT, absent means skip.
+  const urlAdsCompat = (parsedParams as Record<string, unknown>)[ADS_COMPAT_URL_PARAM] as string | undefined;
+  useEffect(() => {
+    if (urlAdsCompat !== undefined) {
+      setSearchMode(urlAdsCompat === '1' ? SearchMode.ADS_COMPAT : SearchMode.ALL_RELEVANT);
+    }
+  }, [urlAdsCompat, setSearchMode]);
+
   const hasSortParam = useMemo(() => {
     const queryString = router.asPath.split('?')[1];
     if (!queryString) {
@@ -180,7 +191,7 @@ const SearchPage: NextPage = () => {
     },
   });
 
-  const searchParams = omitP(params) as IADSApiSearchParams;
+  const searchParams = omit(['p', ADS_COMPAT_URL_PARAM, 'd'], params) as IADSApiSearchParams;
   const { data, isSuccess, isLoading, isFetching, error, isError, refetch } = useSearch<IADSApiSearchResponse>(
     searchParams,
     { select: (data) => data },
@@ -255,8 +266,8 @@ const SearchPage: NextPage = () => {
     // clear current docs since we are entering new search
     clearSelectedDocs();
 
-    // generate a URL search string and trigger a page transition, and update store
-    const search = makeSearchParams({ ...params, ...query, q, p: 1 });
+    const base = omit([ADS_COMPAT_URL_PARAM, 'd'], { ...params, ...query, q, p: 1 }) as IADSApiSearchParams;
+    const search = makeSearchParams(buildSearchOutgoing(base, searchMode));
     void router.push({ pathname: router.pathname, search }, null, { scroll: false, shallow: true });
   };
 
@@ -313,8 +324,8 @@ const SearchPage: NextPage = () => {
 
   // conditions
   const loading = isLoading || isFetching;
-  const noResults = !loading && isSuccess && data?.response.numFound === 0;
-  const hasResults = !loading && isSuccess && data?.response.numFound > 0;
+  const noResults = !loading && isSuccess && data?.response?.numFound === 0;
+  const hasResults = !loading && isSuccess && data?.response?.numFound > 0;
   const showFilters = !isPrint && isClient;
   const showListActions = !isPrint && (loading || hasResults);
 
@@ -328,7 +339,7 @@ const SearchPage: NextPage = () => {
           <form method="get" action="/search" onSubmit={handleOnSubmit}>
             <Flex direction="column" width="full">
               <SearchBar isLoading={loading} showBackLinkAs="new_search" />
-              <NumFound count={data?.response.numFound} isLoading={loading} />
+              <NumFound count={data?.response?.numFound} isLoading={loading} />
             </Flex>
             <FacetFilters mt="2" />
           </form>
diff --git a/src/providers.tsx b/src/providers.tsx
index b23070e36..0a4a8d827 100644
--- a/src/providers.tsx
+++ b/src/providers.tsx
@@ -1,8 +1,8 @@
 import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';
 import { MathJaxProvider } from './mathjax';
-import { ChakraProvider } from '@chakra-ui/react';
-import { AppState, StoreProvider, useCreateStore, useStore } from './store';
-import { DehydratedState, Hydrate, QueryClientProvider } from '@tanstack/react-query';
+import { ChakraProvider, cookieStorageManagerSSR } from '@chakra-ui/react';
+import { StoreProvider, useCreateStore, useStore } from './store';
+import { Hydrate, QueryClientProvider } from '@tanstack/react-query';
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 import { FC, useEffect, useRef } from 'react';
 import { useCreateQueryClient } from './lib/useCreateQueryClient';
@@ -14,15 +14,11 @@ import { IADSApiSearchParams } from './api/search/types';
 import { PERF_SPANS, getResultCountBucket, getQueryType } from '@/lib/performance';
 import { useGlobalErrorHandler } from './lib/useGlobalErrorHandler';
 import { ShepherdJourneyProvider } from 'react-shepherd';
-
-type AppPageProps = {
-  dehydratedState: DehydratedState;
-  dehydratedAppState: AppState;
-  [key: string]: unknown;
-};
+import type { AppPageProps } from '@/pages/_app';
 
 export const Providers: FC<{ pageProps: AppPageProps }> = ({ children, pageProps }) => {
   const createStore = useCreateStore(pageProps.dehydratedAppState ?? {});
+  const colorModeManager = cookieStorageManagerSSR(pageProps.cookies ?? '');
 
   return (
     <GoogleReCaptchaProvider reCaptchaKey={process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY ?? ''}>
@@ -30,6 +26,7 @@ export const Providers: FC<{ pageProps: AppPageProps }> = ({ children, pageProps
         <ShepherdJourneyProvider>
           <ChakraProvider
             theme={theme}
+            colorModeManager={colorModeManager}
             toastOptions={{
               defaultOptions: {
                 position: 'top',
diff --git a/src/ssr-utils.ts b/src/ssr-utils.ts
index b81ed11f3..433efb0a0 100644
--- a/src/ssr-utils.ts
+++ b/src/ssr-utils.ts
@@ -8,52 +8,52 @@ import { getNotification, NotificationId } from '@/store/slices';
 import { logger } from '@/logger';
 import { AppMode } from '@/types';
 import { mapDisciplineParamToAppMode } from '@/utils/appMode';
-import { isFromLegacyApp } from '@/utils/legacyAppDetection';
-
 import { parseAPIError } from '@/utils/common/parseAPIError';
 import { isUserData } from '@/auth-utils';
+import { readPrefsCookie } from '@/utils/common/prefs-cookie';
+import { SearchMode } from '@/utils/common/searchMode';
 
 const log = logger.child({}, { msgPrefix: '[ssr-inject] ' });
 
+const VALID_APP_MODES = new Set(Object.values(AppMode));
+const VALID_SEARCH_MODES = new Set(Object.values(SearchMode));
+
 export const updateUserStateSSR: IncomingGSSP = async (ctx, prevResult) => {
   const userData = ctx.req.session.token;
   const incomingState = (prevResult?.props?.dehydratedAppState ?? {}) as AppState;
 
-  // Check referer header directly to detect legacy ADS app referrers
-  const referer = ctx.req.headers.referer;
-  const isLegacyReferrer = isFromLegacyApp(referer);
-
-  // Only apply legacy mode if there's no persisted mode preference
-  const applyLegacyMode = isLegacyReferrer && incomingState.mode === undefined;
-
   const url = new URL(ctx.resolvedUrl, 'http://localhost');
   const pathname = url.pathname;
 
-  // forceMode query param takes highest precedence (from discipline routes or legacy referrer)
+  // forceMode query param — highest precedence (discipline routes)
   const forceMode = mapDisciplineParamToAppMode(ctx.query?.forceMode);
 
   // URL discipline param (d) only applies on /search
   const urlMode = pathname === '/search' ? mapDisciplineParamToAppMode(ctx.query?.d) : null;
 
-  // Legacy referrer fallback - only applies if no explicit mode is provided
-  // and no persisted mode exists
-  const legacyMode = applyLegacyMode ? AppMode.ASTROPHYSICS : undefined;
+  // Prefs cookie — persisted user preference (written by middleware on first ADS visit)
+  const prefs = readPrefsCookie(ctx.req.headers.cookie);
+  const cookieMode = prefs.mode && VALID_APP_MODES.has(prefs.mode as AppMode) ? (prefs.mode as AppMode) : undefined;
+  // Priority: URL forceMode > URL d param > prefs cookie
+  const resolvedMode = forceMode ?? urlMode ?? cookieMode;
 
-  const resolvedMode = forceMode ?? urlMode ?? legacyMode;
+  // ADS_COMPAT is only meaningful in the ASTROPHYSICS discipline context.
+  // If the resolved mode is anything else, suppress the cookie search mode so
+  // the ADS filters are not applied on non-astrophysics pages.
+  const cookieSearchMode =
+    prefs.searchMode && VALID_SEARCH_MODES.has(prefs.searchMode as SearchMode) && resolvedMode === AppMode.ASTROPHYSICS
+      ? prefs.searchMode
+      : undefined;
 
   log.debug({
     msg: 'Injecting session data into client props',
     userData,
     isValidUserData: isUserData(userData),
-    token: isUserData(userData) ? userData.access_token : null,
-    referer,
-    isLegacyReferrer,
-    applyLegacyMode,
     resolvedMode,
+    cookieMode,
   });
 
   const qc = new QueryClient();
-  // found an incoming dehydrated state, hydrate it
   if (prevResult?.props?.dehydratedState) {
     hydrate(qc, prevResult.props.dehydratedState);
   }
@@ -64,10 +64,9 @@ export const updateUserStateSSR: IncomingGSSP = async (ctx, prevResult) => {
       dehydratedAppState: {
         ...incomingState,
         user: isUserData(userData) ? userData : {},
-        // set notification if present
         notification: getNotification(ctx.query?.notify as NotificationId),
-        // discipline via URL param (d) applies only on /search, otherwise keep legacy app mode
         ...(resolvedMode && { mode: resolvedMode }),
+        ...(cookieSearchMode && { searchMode: cookieSearchMode }),
       } as AppState,
       dehydratedState: dehydrate(qc),
     },
@@ -84,44 +83,30 @@ type IncomingGSSP = (
   },
 ) => Promise<GetServerSidePropsResult<Record<string, unknown>>>;
 
-/**
- * Composes multiple GetServerSideProps functions
- * invoking left to right
- * Props are merged, other properties will overwrite
- */
 export const composeNextGSSP = (...fns: IncomingGSSP[]) =>
   withIronSessionSsr(
     async (ctx: GetServerSidePropsContext): Promise<GetServerSidePropsResult<Record<string, unknown>>> => {
       ctx.res.setHeader('Cache-Control', 's-max-age=60, stale-while-revalidate=300');
-
-      // only push if the list of fns does not already have the updater
       if (!fns.includes(updateUserStateSSR)) {
         fns.push(updateUserStateSSR);
       }
-
       api.setUserData(ctx.req.session.token);
       let ssrProps = { props: {} };
-
       for (const fn of fns) {
         let result;
         let props = {};
         try {
-          // Ensure that the result is awaited properly and no promises remain unhandled
-          result = await fn(ctx, ssrProps); // Await the function result
+          result = await fn(ctx, ssrProps);
         } catch (error) {
           logger.error({ error });
           props = { pageError: parseAPIError(error) };
         }
-
-        // Make sure the result is fully resolved and it's not a Promise
         if (result && 'props' in result) {
-          // Check if result.props is a promise and await it if necessary
           if (result.props instanceof Promise) {
             result.props = await result.props;
           }
-          props = { ...props, ...ssrProps.props, ...result.props }; // Spread properties safely
+          props = { ...props, ...ssrProps.props, ...result.props };
         }
-
         ssrProps = { ...ssrProps, ...result, props };
       }
       return ssrProps;
diff --git a/src/store/slices/appMode.ts b/src/store/slices/appMode.ts
index c7c7602b0..de1dcb45a 100644
--- a/src/store/slices/appMode.ts
+++ b/src/store/slices/appMode.ts
@@ -1,8 +1,12 @@
+// src/store/slices/appMode.ts
 import { StoreSlice } from '@/store';
 import { AppMode } from '@/types';
+import { writePrefsCookie } from '@/utils/common/prefs-cookie';
+import { SearchMode } from '@/utils/common/searchMode';
 
 export interface IAppModeState {
   mode: AppMode;
+  searchMode: string;
   modeNoticeVisible: boolean;
   urlModePrevious: AppMode | null;
   urlModeOverride: AppMode | null;
@@ -12,6 +16,7 @@ export interface IAppModeState {
 
 export interface IAppModeAction {
   setMode: (mode: AppMode) => void;
+  setSearchMode: (mode: string) => void;
   showModeNotice: () => void;
   dismissModeNotice: () => void;
   dismissModeNoticeSilently: () => void;
@@ -23,16 +28,25 @@ export interface IAppModeAction {
 
 export const appModeSlice: StoreSlice<IAppModeState & IAppModeAction> = (set, get) => ({
   mode: AppMode.GENERAL,
+  searchMode: SearchMode.ALL_RELEVANT,
   modeNoticeVisible: false,
   urlModePrevious: null,
   urlModeOverride: null,
   urlModeUserSelected: false,
   urlModePendingParam: null,
   setMode: (mode) => {
-    set({ mode }, false, 'mode/setMode');
-
-    // on mode change, reset facets
+    const update: Partial<IAppModeState> = { mode };
+    if (mode !== AppMode.ASTROPHYSICS && get().searchMode === SearchMode.ADS_COMPAT) {
+      update.searchMode = SearchMode.ALL_RELEVANT;
+      writePrefsCookie({ searchMode: undefined });
+    }
+    set(update, false, 'mode/setMode');
     get().resetSearchFacets();
+    writePrefsCookie({ mode });
+  },
+  setSearchMode: (mode: string) => {
+    set({ searchMode: mode }, false, 'mode/setSearchMode');
+    writePrefsCookie({ searchMode: mode === SearchMode.ADS_COMPAT ? mode : undefined });
   },
   showModeNotice: () => set({ modeNoticeVisible: true }, false, 'mode/showModeNotice'),
   dismissModeNotice: () => set({ modeNoticeVisible: false }, false, 'mode/dismissModeNotice'),
diff --git a/src/store/store.ts b/src/store/store.ts
index 80f653df2..a3e81e230 100644
--- a/src/store/store.ts
+++ b/src/store/store.ts
@@ -66,6 +66,12 @@ export const createStore = (preloadedState: Partial<AppState> = {}) => {
 export type Store = ReturnType<typeof createStore>;
 
 let store: Store;
+// Tracks the last incomingState.mode that was applied synchronously. Used to distinguish
+// genuine page-navigation state (new incomingState reference → apply) from same-page
+// re-renders caused by client-side mode changes (same incomingState → skip, preserving
+// the user's change). Reset when incomingState changes.
+let lastSyncedIncomingMode: string | undefined;
+
 export const useCreateStore = (incomingState: Partial<AppState> = {}): (() => Store) => {
   // always return a new store if server-side
   if (typeof window === 'undefined') {
@@ -79,6 +85,23 @@ export const useCreateStore = (incomingState: Partial<AppState> = {}): (() => St
   // initialize the store
   store = store ?? createStore(incomingState);
 
+  // Synchronously apply mode from GSSP state on page navigation (new incomingState).
+  // useApplyBoostTypeToParams derives boostType from appMode. If mode is stale on the first
+  // render (singleton store from a previous page), boostType is wrong → cache key changes
+  // after the useEffect correction → second search fires. Applying before children render
+  // keeps boostType stable.
+  //
+  // The lastSyncedIncomingMode guard prevents overriding client-side mode changes: when the
+  // user switches discipline on the same page, incomingState.mode stays at the SSR value but
+  // we should NOT revert their change on subsequent re-renders.
+  if (incomingState.mode !== lastSyncedIncomingMode && !store.getState().urlModeOverride) {
+    lastSyncedIncomingMode = incomingState.mode;
+    const currentMode = store.getState().mode;
+    if (incomingState.mode && currentMode !== incomingState.mode) {
+      store.setState({ mode: incomingState.mode });
+    }
+  }
+
   // force reset of the search facets
   setTimeout(() => store.getState().resetSearchFacets(), 300);
 
@@ -86,7 +109,11 @@ export const useCreateStore = (incomingState: Partial<AppState> = {}): (() => St
   // eslint-disable-next-line react-hooks/rules-of-hooks
   useEffect(() => {
     if (incomingState && store) {
-      store.setState(mergeDeepLeft(incomingState, store.getState()) as AppState);
+      // searchMode is owned by setSearchMode (user action) and createStore (initial SSR seed).
+      // Merging it here on navigation would restore ADS_COMPAT even after the user explicitly
+      // cleared it by switching disciplines. Exclude it so user changes are sticky.
+      const { searchMode: _s, ...rest } = incomingState;
+      store.setState(mergeDeepLeft(rest, store.getState()) as AppState);
     }
   }, [incomingState]);
 
diff --git a/src/types.ts b/src/types.ts
index e1bd76e6a..a67525f7c 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -68,4 +68,3 @@ declare global {
     onResponse: unknown;
   };
 }
-
diff --git a/src/utils/common/prefs-cookie.ts b/src/utils/common/prefs-cookie.ts
new file mode 100644
index 000000000..94f398a9d
--- /dev/null
+++ b/src/utils/common/prefs-cookie.ts
@@ -0,0 +1,38 @@
+export interface SciXPrefs {
+  searchMode?: string;
+  mode?: string;
+}
+
+const COOKIE_NAME = 'scix_prefs';
+const MAX_AGE = 60 * 60 * 24 * 365;
+const COOKIE_RE = new RegExp(`(?:^|; )${COOKIE_NAME}=([^;]*)`);
+
+export const readPrefsCookie = (cookieSource?: string): SciXPrefs => {
+  const raw = cookieSource ?? (typeof document !== 'undefined' ? document.cookie : '');
+  const match = raw.match(COOKIE_RE);
+  if (!match) {
+    return {};
+  }
+  try {
+    return JSON.parse(decodeURIComponent(match[1])) as SciXPrefs;
+  } catch {
+    return {};
+  }
+};
+
+export const writePrefsCookie = (updates: Partial<SciXPrefs>): void => {
+  if (typeof document === 'undefined') {
+    return;
+  }
+  const current = readPrefsCookie();
+  const next: SciXPrefs = { ...current, ...updates };
+  (Object.keys(next) as (keyof SciXPrefs)[]).forEach((k) => {
+    if (!next[k]) {
+      delete next[k];
+    }
+  });
+  const secure = process.env.NODE_ENV === 'production' ? '; Secure' : '';
+  document.cookie = `${COOKIE_NAME}=${encodeURIComponent(
+    JSON.stringify(next),
+  )}; Max-Age=${MAX_AGE}; Path=/; SameSite=Lax${secure}`;
+};
diff --git a/src/utils/common/searchMode.ts b/src/utils/common/searchMode.ts
new file mode 100644
index 000000000..4e977b1a7
--- /dev/null
+++ b/src/utils/common/searchMode.ts
@@ -0,0 +1,62 @@
+import type { IADSApiSearchParams } from '@/api/search/types';
+import { applyFiltersToQuery } from '@/components/SearchFacet/helpers';
+import { omit } from 'ramda';
+import type { SolrSort } from '@/api/models';
+
+export enum SearchMode {
+  ALL_RELEVANT = 'ALL_RELEVANT',
+  ADS_COMPAT = 'ADS_COMPAT',
+}
+
+export const SEARCH_MODE_OPTIONS = [
+  {
+    mode: SearchMode.ALL_RELEVANT,
+    label: 'All relevant content',
+    helperText: 'Standard SciX search across all content.',
+  },
+  {
+    mode: SearchMode.ADS_COMPAT,
+    label: 'ADS Compatibility mode',
+    helperText: 'Search ADS-style astronomy and physics content, sorted by date.',
+  },
+] as const;
+
+export const ADS_COMPAT_SORT: SolrSort[] = ['date desc'];
+export const ADS_COMPAT_FQ_ENTRY = '{!type=aqp v=$fq_database}';
+export const ADS_COMPAT_FQ_DATABASE = '(database:"astronomy" OR database:"physics")';
+export const ADS_COMPAT_URL_PARAM = 'ads_compat';
+
+export const buildSearchOutgoing = (query: IADSApiSearchParams, mode: string): IADSApiSearchParams => {
+  const withDefaults = applySearchModeDefaults(query, mode);
+  return mode === SearchMode.ADS_COMPAT
+    ? ({ ...withDefaults, [ADS_COMPAT_URL_PARAM]: '1' } as IADSApiSearchParams)
+    : withDefaults;
+};
+
+export const applySearchModeDefaults = (query: IADSApiSearchParams, mode: string | undefined): IADSApiSearchParams => {
+  if (mode === SearchMode.ADS_COMPAT) {
+    const withCollections = applyFiltersToQuery({
+      query,
+      values: ['astronomy', 'physics'],
+      field: 'database',
+      logic: 'or',
+    }) as IADSApiSearchParams;
+    return { ...withCollections, sort: ADS_COMPAT_SORT };
+  }
+
+  // Strip ADS-implied filters/sort if present and exactly matching ADS defaults.
+  // Only strip the exact values we would have set — leave user-configured values alone.
+  if (query.fq_database === ADS_COMPAT_FQ_DATABASE) {
+    const fqWithout = (query.fq as string[] | undefined)?.filter((f) => f !== ADS_COMPAT_FQ_ENTRY) ?? [];
+    const withoutDb = omit(['fq_database'], query) as IADSApiSearchParams;
+    const withoutFq =
+      fqWithout.length > 0 ? { ...withoutDb, fq: fqWithout } : (omit(['fq'], withoutDb) as IADSApiSearchParams);
+    // Also revert sort if it exactly matches the ADS default.
+    const currentSort = withoutFq.sort as SolrSort[] | undefined;
+    const sortIsAdsDefault =
+      currentSort?.length === ADS_COMPAT_SORT.length && currentSort.every((s, i) => s === ADS_COMPAT_SORT[i]);
+    return sortIsAdsDefault ? (omit(['sort'], withoutFq) as IADSApiSearchParams) : withoutFq;
+  }
+
+  return query;
+};
diff --git a/tsconfig.json b/tsconfig.json
index ddbf2d2ac..0012cded5 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -15,7 +15,7 @@
     "esModuleInterop": true,
     "module": "esnext",
     "noUncheckedIndexedAccess": true,
-    "moduleResolution": "node",
+    "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
     "jsx": "react-jsx",

From 3056275bb5c1069837b3cdd235e79d87e9dafcd6 Mon Sep 17 00:00:00 2001
From: Tim Hostetler <6970899+thostetler@users.noreply.github.com>
Date: Thu, 21 May 2026 12:56:28 -0400
Subject: [PATCH 2/2] test: add coverage for SearchModifierBar and
 cookie-seeding paths

- searchMode.test.ts: applySearchModeDefaults and buildSearchOutgoing
- prefs-cookie.test.ts: read/write round-trips including encoding
- useSearchMode.test.ts: hook returns mode and calls store setter
- SearchModifierBar.test.tsx: renders, mode switching, disabled state
- ssr-utils.test.ts: cookie-seeded mode/searchMode hydration and precedence
- middleware.routes.integration.test.ts: discipline-route cookie setting,
  ADS referrer redirect to /?fromADS=true, and loop-guard cases
- appMode.test.ts: setMode ADS_COMPAT-clear branch, setSearchMode persistence
- SearchBar.test.tsx: timer isolation fixes to prevent suite timeouts
---
 src/__tests__/ssr-utils.test.ts               |  99 +++++++--
 .../SearchBar/__tests__/SearchBar.test.tsx    |  24 ++-
 .../__tests__/SearchModifierBar.test.tsx      | 189 ++++++++++++++++++
 src/lib/__tests__/useSearchMode.test.ts       |  46 +++++
 .../middleware.routes.integration.test.ts     |  67 +++++++
 src/store/slices/appMode.test.ts              |  81 ++++++++
 .../common/__tests__/prefs-cookie.test.ts     |  89 +++++++++
 src/utils/common/__tests__/searchMode.test.ts |  87 ++++++++
 8 files changed, 655 insertions(+), 27 deletions(-)
 create mode 100644 src/components/SearchModifierBar/__tests__/SearchModifierBar.test.tsx
 create mode 100644 src/lib/__tests__/useSearchMode.test.ts
 create mode 100644 src/store/slices/appMode.test.ts
 create mode 100644 src/utils/common/__tests__/prefs-cookie.test.ts
 create mode 100644 src/utils/common/__tests__/searchMode.test.ts

diff --git a/src/__tests__/ssr-utils.test.ts b/src/__tests__/ssr-utils.test.ts
index 5a8cca6c2..f2e71fbb8 100644
--- a/src/__tests__/ssr-utils.test.ts
+++ b/src/__tests__/ssr-utils.test.ts
@@ -16,6 +16,7 @@ const getMockContext = (
   query: ParsedUrlQuery = {},
   resolvedUrl = '/search',
   referer?: string,
+  cookie?: string,
 ) =>
   ({
     req: {
@@ -24,9 +25,7 @@ const getMockContext = (
         save: vi.fn().mockResolvedValue(undefined),
         destroy: vi.fn().mockResolvedValue(undefined),
       },
-      headers: {
-        referer,
-      },
+      headers: { referer, cookie },
     },
     query,
     resolvedUrl,
@@ -34,6 +33,8 @@ const getMockContext = (
 
 describe('updateUserStateSSR', () => {
   test('should set mode for legacy referrer with no persisted state', async () => {
+    // Mode is now set by middleware writing the scix_prefs cookie before redirect.
+    // updateUserStateSSR no longer reads the referer header to infer mode.
     const context = getMockContext({}, {}, '/search', 'https://ui.adsabs.harvard.edu/search');
     const result = await updateUserStateSSR(context, { props: {} });
 
@@ -41,23 +42,15 @@ describe('updateUserStateSSR', () => {
       throw new Error('Expected props in result');
     }
     const props = result.props as SSRPropsWithState;
-    expect(props.dehydratedAppState).toEqual(
-      expect.objectContaining({
-        mode: AppMode.ASTROPHYSICS,
-      }),
-    );
+    expect(props.dehydratedAppState).not.toHaveProperty('mode');
   });
 
   test('should respect persisted state even with legacy referrer', async () => {
-    const context = getMockContext({}, {}, '/search', 'https://ui.adsabs.harvard.edu/search');
-    const inputProps = {
-      props: {
-        dehydratedAppState: {
-          mode: AppMode.GENERAL,
-        } as Partial<AppState>,
-      },
-    };
-    const result = await updateUserStateSSR(context, inputProps as never);
+    // Cookie-based mode takes precedence; referer header is ignored.
+    const prefs = { mode: 'EARTH_SCIENCE' };
+    const cookie = `scix_prefs=${encodeURIComponent(JSON.stringify(prefs))}`;
+    const context = getMockContext({}, {}, '/search', 'https://ui.adsabs.harvard.edu/search', cookie);
+    const result = await updateUserStateSSR(context, { props: {} });
 
     if (!('props' in result)) {
       throw new Error('Expected props in result');
@@ -65,7 +58,7 @@ describe('updateUserStateSSR', () => {
     const resultProps = result.props as SSRPropsWithState;
     expect(resultProps.dehydratedAppState).toEqual(
       expect.objectContaining({
-        mode: AppMode.GENERAL,
+        mode: AppMode.EARTH_SCIENCE,
       }),
     );
   });
@@ -218,4 +211,74 @@ describe('updateUserStateSSR', () => {
       expect(props.dehydratedAppState).not.toHaveProperty('mode');
     });
   });
+
+  test('seeds mode from scix_prefs cookie when no URL param', async () => {
+    const prefs = { mode: 'ASTROPHYSICS' };
+    const cookie = `scix_prefs=${encodeURIComponent(JSON.stringify(prefs))}`;
+    const context = getMockContext({}, {}, '/search', undefined, cookie);
+    const result = await updateUserStateSSR(context, { props: {} });
+    if (!('props' in result)) {
+      throw new Error('Expected props');
+    }
+    const props = result.props as SSRPropsWithState;
+    expect(props.dehydratedAppState).toEqual(expect.objectContaining({ mode: AppMode.ASTROPHYSICS }));
+  });
+
+  test('seeds searchMode from scix_prefs cookie', async () => {
+    const prefs = { searchMode: 'ADS_COMPAT', mode: 'ASTROPHYSICS' };
+    const cookie = `scix_prefs=${encodeURIComponent(JSON.stringify(prefs))}`;
+    const context = getMockContext({}, {}, '/', undefined, cookie);
+    const result = await updateUserStateSSR(context, { props: {} });
+    if (!('props' in result)) {
+      throw new Error('Expected props');
+    }
+    const props = result.props as SSRPropsWithState;
+    expect(props.dehydratedAppState).toEqual(expect.objectContaining({ searchMode: 'ADS_COMPAT' }));
+  });
+
+  test('URL forceMode takes priority over prefs cookie mode', async () => {
+    const prefs = { mode: 'ASTROPHYSICS' };
+    const cookie = `scix_prefs=${encodeURIComponent(JSON.stringify(prefs))}`;
+    const context = getMockContext({}, { forceMode: 'heliophysics' }, '/', undefined, cookie);
+    const result = await updateUserStateSSR(context, { props: {} });
+    if (!('props' in result)) {
+      throw new Error('Expected props');
+    }
+    const props = result.props as SSRPropsWithState;
+    expect(props.dehydratedAppState).toEqual(expect.objectContaining({ mode: AppMode.HELIOPHYSICS }));
+  });
+
+  test('legacy referrer no longer sets mode in GSSP (handled by middleware+cookie)', async () => {
+    const context = getMockContext({}, {}, '/search', 'https://ui.adsabs.harvard.edu/search');
+    const result = await updateUserStateSSR(context, { props: {} });
+    if (!('props' in result)) {
+      throw new Error('Expected props');
+    }
+    const props = result.props as SSRPropsWithState;
+    expect(props.dehydratedAppState).not.toHaveProperty('mode');
+  });
+
+  test('rejects invalid mode value from prefs cookie', async () => {
+    const prefs = { mode: 'GARBAGE_MODE' };
+    const cookie = `scix_prefs=${encodeURIComponent(JSON.stringify(prefs))}`;
+    const context = getMockContext({}, {}, '/search', undefined, cookie);
+    const result = await updateUserStateSSR(context, { props: {} });
+    if (!('props' in result)) {
+      throw new Error('Expected props');
+    }
+    const props = result.props as SSRPropsWithState;
+    expect(props.dehydratedAppState).not.toHaveProperty('mode');
+  });
+
+  test('rejects invalid searchMode value from prefs cookie', async () => {
+    const prefs = { searchMode: 'INVALID_SEARCH_MODE' };
+    const cookie = `scix_prefs=${encodeURIComponent(JSON.stringify(prefs))}`;
+    const context = getMockContext({}, {}, '/', undefined, cookie);
+    const result = await updateUserStateSSR(context, { props: {} });
+    if (!('props' in result)) {
+      throw new Error('Expected props');
+    }
+    const props = result.props as SSRPropsWithState;
+    expect(props.dehydratedAppState).not.toHaveProperty('searchMode');
+  });
 });
diff --git a/src/components/SearchBar/__tests__/SearchBar.test.tsx b/src/components/SearchBar/__tests__/SearchBar.test.tsx
index bfebbf802..a1956199a 100644
--- a/src/components/SearchBar/__tests__/SearchBar.test.tsx
+++ b/src/components/SearchBar/__tests__/SearchBar.test.tsx
@@ -1,4 +1,4 @@
-import { render } from '@/test-utils';
+import { fireEvent, render } from '@/test-utils';
 import userEvent from '@testing-library/user-event';
 import { afterEach, beforeEach, expect, test, vi } from 'vitest';
 import { SearchBar } from '../index';
@@ -21,7 +21,9 @@ vi.mock('@/lib/useLandingFormPreference', () => ({
 }));
 
 beforeEach(() => {
-  vi.useFakeTimers();
+  // Exclude requestAnimationFrame from fake timers to prevent Framer Motion's animation
+  // loop from cascading under vi.advanceTimersByTimeAsync and inflating test runtime.
+  vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
 });
 
 afterEach(() => {
@@ -104,10 +106,12 @@ test('Escape key closes typeahead', async () => {
   await user.type(input, 'sim');
   await vi.advanceTimersByTimeAsync(500);
   expect(queryByTestId('search-autocomplete-menu')).toBeVisible();
+  // Escape dispatches KEYDOWN_ESCAPE synchronously; no timer advancement needed.
   await user.keyboard('{Escape}');
-  await vi.advanceTimersByTimeAsync(500);
   expect(queryByTestId('search-autocomplete-menu')).not.toBeVisible();
-});
+  // 15s timeout: vi.advanceTimersByTimeAsync(500) triggers Chakra/React work that
+  // accumulates across the suite; this test passes easily in isolation but needs headroom.
+}, 15000);
 
 test('Clearing input closes typeahead menu', async () => {
   const user = createUser();
@@ -116,8 +120,8 @@ test('Clearing input closes typeahead menu', async () => {
   await user.type(input, 'sim');
   await vi.advanceTimersByTimeAsync(500);
   expect(queryByTestId('search-autocomplete-menu')).toBeVisible();
+  // HARD_RESET dispatches synchronously; no timer advancement needed.
   await user.click(getByTestId('search-clearbtn'));
-  await vi.advanceTimersByTimeAsync(500);
   expect(queryByTestId('search-autocomplete-menu')).not.toBeVisible();
 });
 
@@ -184,10 +188,11 @@ test('Typing a non-matching term does not open typeahead', async () => {
 });
 
 test('Typing an exact match for a typeahead option closes the menu', async () => {
-  const user = createUser();
   const { getByTestId, queryByTestId } = render(<SearchBar />);
   const input = getByTestId('search-input');
-  await user.type(input, 'similar()');
+  // fireEvent.change simulates the handleInputChange path without triggering the
+  // React-scheduler timer cascade that makes long user.type() calls exceed the timeout.
+  fireEvent.change(input, { target: { value: 'similar()', selectionStart: 9 } });
   await vi.advanceTimersByTimeAsync(500);
   expect(queryByTestId('search-autocomplete-menu')).not.toBeVisible();
 });
@@ -253,8 +258,9 @@ test('Arrow down does nothing when cursor is not at end of input', async () => {
   const user = createUser();
   const { getByTestId, queryByTestId } = render(<SearchBar />);
   const input = getByTestId('search-input') as HTMLInputElement;
-  await user.type(input, 'test query');
-  input.setSelectionRange(4, 4);
+  await user.type(input, 'test');
+  // Place cursor before the end to disable ArrowDown menu-open behaviour
+  input.setSelectionRange(0, 0);
   await user.keyboard('{ArrowDown}');
   await vi.advanceTimersByTimeAsync(500);
   expect(queryByTestId('search-autocomplete-menu')).not.toBeVisible();
diff --git a/src/components/SearchModifierBar/__tests__/SearchModifierBar.test.tsx b/src/components/SearchModifierBar/__tests__/SearchModifierBar.test.tsx
new file mode 100644
index 000000000..df416be07
--- /dev/null
+++ b/src/components/SearchModifierBar/__tests__/SearchModifierBar.test.tsx
@@ -0,0 +1,189 @@
+import React from 'react';
+import { render } from '@/test-utils';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { SearchModifierBar } from '../SearchModifierBar';
+import { ADS_COMPAT_URL_PARAM, SearchMode } from '@/utils/common/searchMode';
+
+const mockPush = vi.fn();
+const mockQuery: Record<string, string> = {};
+
+vi.mock('next/router', () => ({
+  useRouter: () => ({
+    query: mockQuery,
+    push: mockPush,
+    pathname: '/search',
+  }),
+}));
+
+// modeRef is module-scoped. The vi.mock factory body cannot reference it (hoisting TDZ),
+// but useSearchMode is only called at render time, by which point it is initialized.
+const modeRef = { current: '' as string };
+
+vi.mock('@/lib/useSearchMode', () => ({
+  // React.useState-backed mock: calling the returned setter causes a re-render, matching
+  // the reactive contract the real Zustand hook provides.
+  useSearchMode: () => {
+    const [mode, setMode] = React.useState(modeRef.current);
+    return [mode, setMode] as const;
+  },
+}));
+
+describe('SearchModifierBar', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    delete mockQuery[ADS_COMPAT_URL_PARAM];
+    modeRef.current = '';
+  });
+
+  test('renders "All relevant content" when mode param is absent', () => {
+    const { getByRole } = render(<SearchModifierBar />);
+    expect(getByRole('button')).toHaveTextContent('All relevant content');
+  });
+
+  test('renders "ADS Compatibility mode" when ads_compat=1', () => {
+    mockQuery[ADS_COMPAT_URL_PARAM] = '1';
+    const { getByRole } = render(<SearchModifierBar />);
+    expect(getByRole('button')).toHaveTextContent('ADS Compatibility mode');
+  });
+
+  test('shows "Search mode:" prefix in the button', () => {
+    const { getByText } = render(<SearchModifierBar />);
+    expect(getByText('Search mode:')).toBeInTheDocument();
+  });
+
+  test('button has an accessible aria-label', () => {
+    const { getByRole } = render(<SearchModifierBar />);
+    expect(getByRole('button')).toHaveAttribute('aria-label');
+  });
+
+  test('opens dropdown showing both options', async () => {
+    const user = userEvent.setup();
+    const { getByRole } = render(<SearchModifierBar />);
+    await user.click(getByRole('button'));
+    expect(getByRole('menuitem', { name: /All relevant content/ })).toBeInTheDocument();
+    expect(getByRole('menuitem', { name: /ADS Compatibility mode/ })).toBeInTheDocument();
+  });
+
+  test('selecting ADS_COMPAT calls router.push with ads_compat=1 and shallow:true', async () => {
+    const user = userEvent.setup();
+    const { getByRole } = render(<SearchModifierBar />);
+    await user.click(getByRole('button'));
+    await user.click(getByRole('menuitem', { name: /ADS Compatibility mode/ }));
+    expect(mockPush).toHaveBeenCalledWith(
+      expect.objectContaining({ query: expect.objectContaining({ [ADS_COMPAT_URL_PARAM]: '1' }) }),
+      undefined,
+      { shallow: true },
+    );
+  });
+
+  test('selecting ALL_RELEVANT removes ads_compat param from URL', async () => {
+    mockQuery[ADS_COMPAT_URL_PARAM] = '1';
+    const user = userEvent.setup();
+    const { getByRole } = render(<SearchModifierBar />);
+    await user.click(getByRole('button'));
+    await user.click(getByRole('menuitem', { name: /All relevant content/ }));
+    expect(mockPush.mock.calls[0][0].query).not.toHaveProperty(ADS_COMPAT_URL_PARAM);
+  });
+
+  test('calls onModeChange before router.push when selecting a mode', async () => {
+    const onModeChange = vi.fn();
+    const callOrder: string[] = [];
+    onModeChange.mockImplementation(() => callOrder.push('onModeChange'));
+    mockPush.mockImplementation(() => callOrder.push('push'));
+
+    const user = userEvent.setup();
+    const { getByRole } = render(<SearchModifierBar onModeChange={onModeChange} />);
+    await user.click(getByRole('button'));
+    await user.click(getByRole('menuitem', { name: /ADS Compatibility mode/ }));
+    expect(callOrder).toEqual(['onModeChange', 'push']);
+    expect(onModeChange).toHaveBeenCalledWith(SearchMode.ADS_COMPAT);
+  });
+
+  test('calls onModeChange with ALL_RELEVANT when switching back', async () => {
+    mockQuery[ADS_COMPAT_URL_PARAM] = '1';
+    const onModeChange = vi.fn();
+    const user = userEvent.setup();
+    const { getByRole } = render(<SearchModifierBar onModeChange={onModeChange} />);
+    await user.click(getByRole('button'));
+    await user.click(getByRole('menuitem', { name: /All relevant content/ }));
+    expect(onModeChange).toHaveBeenCalledWith(SearchMode.ALL_RELEVANT);
+  });
+
+  test('shows "All relevant content" immediately after selecting it when ADS_COMPAT was in storedMode (no URL mode)', async () => {
+    modeRef.current = SearchMode.ADS_COMPAT;
+
+    const user = userEvent.setup();
+    const { getByRole } = render(<SearchModifierBar />);
+
+    expect(getByRole('button')).toHaveTextContent('ADS Compatibility mode');
+
+    await user.click(getByRole('button'));
+    await user.click(getByRole('menuitem', { name: /All relevant content/ }));
+
+    expect(getByRole('button')).toHaveTextContent('All relevant content');
+  });
+
+  test('shows "ADS Compatibility mode" immediately after selecting it when starting from All relevant content', async () => {
+    const user = userEvent.setup();
+    const { getByRole } = render(<SearchModifierBar />);
+
+    expect(getByRole('button')).toHaveTextContent('All relevant content');
+
+    await user.click(getByRole('button'));
+    await user.click(getByRole('menuitem', { name: /ADS Compatibility mode/ }));
+
+    expect(getByRole('button')).toHaveTextContent('ADS Compatibility mode');
+  });
+
+  describe('onNavigate prop', () => {
+    test('calls onNavigate instead of router.push when onNavigate is provided', async () => {
+      const onNavigate = vi.fn();
+      const user = userEvent.setup();
+      const { getByRole } = render(<SearchModifierBar onNavigate={onNavigate} />);
+      await user.click(getByRole('button'));
+      await user.click(getByRole('menuitem', { name: /ADS Compatibility mode/ }));
+      expect(onNavigate).toHaveBeenCalledWith(SearchMode.ADS_COMPAT);
+      expect(mockPush).not.toHaveBeenCalled();
+    });
+
+    test('does not call router.push when onNavigate is provided for ALL_RELEVANT', async () => {
+      mockQuery[ADS_COMPAT_URL_PARAM] = '1';
+      const onNavigate = vi.fn();
+      const user = userEvent.setup();
+      const { getByRole } = render(<SearchModifierBar onNavigate={onNavigate} />);
+      await user.click(getByRole('button'));
+      await user.click(getByRole('menuitem', { name: /All relevant content/ }));
+      expect(onNavigate).toHaveBeenCalledWith(SearchMode.ALL_RELEVANT);
+      expect(mockPush).not.toHaveBeenCalled();
+    });
+
+    test('calls onModeChange before onNavigate', async () => {
+      const callOrder: string[] = [];
+      const onModeChange = vi.fn(() => callOrder.push('onModeChange'));
+      const onNavigate = vi.fn(() => callOrder.push('onNavigate'));
+
+      const user = userEvent.setup();
+      const { getByRole } = render(<SearchModifierBar onModeChange={onModeChange} onNavigate={onNavigate} />);
+      await user.click(getByRole('button'));
+      await user.click(getByRole('menuitem', { name: /ADS Compatibility mode/ }));
+      expect(callOrder).toEqual(['onModeChange', 'onNavigate']);
+    });
+
+    test('updates button label via storedMode after onNavigate clears mode from URL', async () => {
+      modeRef.current = SearchMode.ADS_COMPAT;
+
+      const onNavigate = vi.fn();
+      const user = userEvent.setup();
+      const { getByRole } = render(<SearchModifierBar onNavigate={onNavigate} />);
+
+      expect(getByRole('button')).toHaveTextContent('ADS Compatibility mode');
+
+      await user.click(getByRole('button'));
+      await user.click(getByRole('menuitem', { name: /All relevant content/ }));
+
+      expect(onNavigate).toHaveBeenCalledWith(SearchMode.ALL_RELEVANT);
+      expect(getByRole('button')).toHaveTextContent('All relevant content');
+    });
+  });
+});
diff --git a/src/lib/__tests__/useSearchMode.test.ts b/src/lib/__tests__/useSearchMode.test.ts
new file mode 100644
index 000000000..dce1d37d4
--- /dev/null
+++ b/src/lib/__tests__/useSearchMode.test.ts
@@ -0,0 +1,46 @@
+import { renderHook, act } from '@testing-library/react';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { useSearchMode } from '../useSearchMode';
+import { SearchMode } from '@/utils/common/searchMode';
+
+// Mock the store to control searchMode state
+const mockSetSearchMode = vi.fn();
+let mockSearchMode = '';
+
+vi.mock('@/store', () => ({
+  useStore: (selector: (s: { searchMode: string; setSearchMode: typeof mockSetSearchMode }) => unknown) =>
+    selector({ searchMode: mockSearchMode, setSearchMode: mockSetSearchMode }),
+}));
+
+describe('useSearchMode', () => {
+  beforeEach(() => {
+    mockSearchMode = '';
+    vi.clearAllMocks();
+  });
+
+  test('returns current searchMode from store', () => {
+    mockSearchMode = SearchMode.ADS_COMPAT;
+    const { result } = renderHook(() => useSearchMode());
+    expect(result.current[0]).toBe(SearchMode.ADS_COMPAT);
+  });
+
+  test('returns empty string as default when no mode is set', () => {
+    const { result } = renderHook(() => useSearchMode());
+    expect(result.current[0]).toBe('');
+  });
+
+  test('calls store setSearchMode when setter is invoked', () => {
+    const { result } = renderHook(() => useSearchMode());
+    act(() => {
+      result.current[1](SearchMode.ADS_COMPAT);
+    });
+    expect(mockSetSearchMode).toHaveBeenCalledWith(SearchMode.ADS_COMPAT);
+  });
+
+  test('returns a stable setter reference', () => {
+    const { result, rerender } = renderHook(() => useSearchMode());
+    const first = result.current[1];
+    rerender();
+    expect(result.current[1]).toBe(first);
+  });
+});
diff --git a/src/middlewares/__tests__/middleware.routes.integration.test.ts b/src/middlewares/__tests__/middleware.routes.integration.test.ts
index 85aae2c27..17b5e5a41 100644
--- a/src/middlewares/__tests__/middleware.routes.integration.test.ts
+++ b/src/middlewares/__tests__/middleware.routes.integration.test.ts
@@ -337,4 +337,71 @@ describe('middleware route integration', () => {
     expect(res).toBeDefined();
     expect(initSessionMock).toHaveBeenCalled();
   });
+
+  describe('discipline routes and ADS referrer cookie seeding', () => {
+    const getPrefsCookie = (res: NextResponse): Record<string, unknown> | null => {
+      const cookieValue = res.cookies.get('scix_prefs')?.value;
+      if (!cookieValue) {
+        return null;
+      }
+      try {
+        return JSON.parse(decodeURIComponent(cookieValue)) as Record<string, unknown>;
+      } catch {
+        return null;
+      }
+    };
+
+    it('discipline route redirects to / with forceMode and sets scix_prefs mode', async () => {
+      const req = makeReq('https://example.com/astrophysics');
+      const res = (await middleware(req)) as NextResponse;
+      expect(res.status).toBe(307);
+      expect(res.headers.get('location')).toContain('forceMode=astrophysics');
+      const prefs = getPrefsCookie(res);
+      expect(prefs).not.toBeNull();
+      expect(prefs!.mode).toBe('ASTROPHYSICS');
+    });
+
+    it('non-astrophysics discipline route clears searchMode from scix_prefs', async () => {
+      const existingCookie = JSON.stringify({ mode: 'ASTROPHYSICS', searchMode: 'ADS_COMPAT' });
+      const req = makeReq('https://example.com/heliophysics', {
+        headers: { cookie: `scix_prefs=${existingCookie}` },
+      });
+      const res = (await middleware(req)) as NextResponse;
+      expect(res.status).toBe(307);
+      expect(res.headers.get('location')).toContain('forceMode=heliophysics');
+      const prefs = getPrefsCookie(res);
+      expect(prefs).not.toBeNull();
+      expect(prefs!.mode).toBe('HELIOPHYSICS');
+      expect(prefs!.searchMode).toBeUndefined();
+    });
+
+    it('legacy ADS referrer redirects to /?fromADS=true and seeds ADS_COMPAT cookie', async () => {
+      const req = makeReq('https://example.com/', {
+        headers: { referer: 'https://ui.adsabs.harvard.edu/search' },
+      });
+      const res = (await middleware(req)) as NextResponse;
+      expect(res.status).toBe(307);
+      expect(res.headers.get('location')).toContain('fromADS=true');
+      const prefs = getPrefsCookie(res);
+      expect(prefs).not.toBeNull();
+      expect(prefs!.mode).toBe('ASTROPHYSICS');
+      expect(prefs!.searchMode).toBe('ADS_COMPAT');
+    });
+
+    it('does not redirect when fromADS param already present (loop guard)', async () => {
+      const req = makeReq('https://example.com/?fromADS=true', {
+        headers: { referer: 'https://ui.adsabs.harvard.edu/search' },
+      });
+      const res = await middleware(req);
+      expect(res.headers.get('location')).toBeNull();
+    });
+
+    it('does not redirect when forceMode param already present on root', async () => {
+      const req = makeReq('https://example.com/?forceMode=astrophysics', {
+        headers: { referer: 'https://ui.adsabs.harvard.edu/search' },
+      });
+      const res = await middleware(req);
+      expect(res.headers.get('location')).toBeNull();
+    });
+  });
 });
diff --git a/src/store/slices/appMode.test.ts b/src/store/slices/appMode.test.ts
new file mode 100644
index 000000000..5ea9104db
--- /dev/null
+++ b/src/store/slices/appMode.test.ts
@@ -0,0 +1,81 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { AppMode } from '@/types';
+import { SearchMode } from '@/utils/common/searchMode';
+import { createStore } from '@/store/store';
+
+describe('appMode slice', () => {
+  let store: ReturnType<typeof createStore>;
+
+  beforeEach(() => {
+    document.cookie = 'scix_prefs=; Max-Age=0; Path=/';
+    store = createStore({ mode: AppMode.ASTROPHYSICS, searchMode: SearchMode.ADS_COMPAT });
+  });
+
+  describe('setMode', () => {
+    it('clears searchMode when switching away from ASTROPHYSICS while in ADS_COMPAT', () => {
+      store.getState().setMode(AppMode.HELIOPHYSICS);
+      expect(store.getState().searchMode).toBe(SearchMode.ALL_RELEVANT);
+    });
+
+    it('does not clear searchMode when staying in ASTROPHYSICS', () => {
+      store.getState().setMode(AppMode.ASTROPHYSICS);
+      expect(store.getState().searchMode).toBe(SearchMode.ADS_COMPAT);
+    });
+
+    it('does not clear searchMode when leaving ASTROPHYSICS if searchMode is ALL_RELEVANT', () => {
+      store = createStore({ mode: AppMode.ASTROPHYSICS, searchMode: SearchMode.ALL_RELEVANT });
+      store.getState().setMode(AppMode.GENERAL);
+      expect(store.getState().searchMode).toBe(SearchMode.ALL_RELEVANT);
+    });
+
+    it('updates mode in the store', () => {
+      store.getState().setMode(AppMode.HELIOPHYSICS);
+      expect(store.getState().mode).toBe(AppMode.HELIOPHYSICS);
+    });
+
+    it('persists mode to scix_prefs cookie', () => {
+      store.getState().setMode(AppMode.HELIOPHYSICS);
+      expect(document.cookie).toContain('scix_prefs');
+      const match = document.cookie.match(/scix_prefs=([^;]+)/);
+      expect(match).not.toBeNull();
+      const prefs = JSON.parse(decodeURIComponent(match![1]));
+      expect(prefs.mode).toBe('HELIOPHYSICS');
+    });
+
+    it('removes searchMode from cookie when leaving ASTROPHYSICS in ADS_COMPAT', () => {
+      store.getState().setMode(AppMode.HELIOPHYSICS);
+      const match = document.cookie.match(/scix_prefs=([^;]+)/);
+      expect(match).not.toBeNull();
+      const prefs = JSON.parse(decodeURIComponent(match![1]));
+      expect(prefs.searchMode).toBeUndefined();
+    });
+  });
+
+  describe('setSearchMode', () => {
+    it('sets searchMode in store', () => {
+      store.getState().setSearchMode(SearchMode.ADS_COMPAT);
+      expect(store.getState().searchMode).toBe(SearchMode.ADS_COMPAT);
+    });
+
+    it('updates searchMode to ALL_RELEVANT in store', () => {
+      store.getState().setSearchMode(SearchMode.ALL_RELEVANT);
+      expect(store.getState().searchMode).toBe(SearchMode.ALL_RELEVANT);
+    });
+
+    it('persists ADS_COMPAT searchMode to cookie', () => {
+      store.getState().setSearchMode(SearchMode.ADS_COMPAT);
+      const match = document.cookie.match(/scix_prefs=([^;]+)/);
+      expect(match).not.toBeNull();
+      const prefs = JSON.parse(decodeURIComponent(match![1]));
+      expect(prefs.searchMode).toBe('ADS_COMPAT');
+    });
+
+    it('removes searchMode from cookie when switching to ALL_RELEVANT', () => {
+      store.getState().setSearchMode(SearchMode.ALL_RELEVANT);
+      const match = document.cookie.match(/scix_prefs=([^;]+)/);
+      expect(match).not.toBeNull();
+      const prefs = JSON.parse(decodeURIComponent(match![1]));
+      expect(prefs.searchMode).toBeUndefined();
+    });
+  });
+});
diff --git a/src/utils/common/__tests__/prefs-cookie.test.ts b/src/utils/common/__tests__/prefs-cookie.test.ts
new file mode 100644
index 000000000..c58013f60
--- /dev/null
+++ b/src/utils/common/__tests__/prefs-cookie.test.ts
@@ -0,0 +1,89 @@
+import { beforeEach, describe, expect, test } from 'vitest';
+import { readPrefsCookie, writePrefsCookie } from '../prefs-cookie';
+
+describe('readPrefsCookie', () => {
+  test('returns empty object when cookie source is empty', () => {
+    expect(readPrefsCookie('')).toEqual({});
+  });
+
+  test('returns empty object when scix_prefs is not present', () => {
+    expect(readPrefsCookie('other=val; another=val2')).toEqual({});
+  });
+
+  test('parses scix_prefs from cookie header string', () => {
+    const prefs = { searchMode: 'ADS_COMPAT', mode: 'ASTROPHYSICS' };
+    const cookie = `scix_prefs=${encodeURIComponent(JSON.stringify(prefs))}`;
+    expect(readPrefsCookie(cookie)).toEqual(prefs);
+  });
+
+  test('parses scix_prefs when surrounded by other cookies', () => {
+    const prefs = { searchMode: 'ADS_COMPAT' };
+    const cookie = `a=1; scix_prefs=${encodeURIComponent(JSON.stringify(prefs))}; b=2`;
+    expect(readPrefsCookie(cookie)).toEqual(prefs);
+  });
+
+  test('returns empty object on malformed JSON', () => {
+    expect(readPrefsCookie(`scix_prefs=${encodeURIComponent('{bad')}`)).toEqual({});
+  });
+
+  test('returns empty object on malformed URI encoding', () => {
+    expect(readPrefsCookie('scix_prefs=%zz')).toEqual({});
+  });
+});
+
+describe('writePrefsCookie', () => {
+  const written: string[] = [];
+
+  beforeEach(() => {
+    written.length = 0;
+    Object.defineProperty(document, 'cookie', {
+      get: () => written[written.length - 1]?.split(';')[0] ?? '',
+      set: (val: string) => written.push(val),
+      configurable: true,
+    });
+  });
+
+  test('writes a URL-encoded JSON cookie', () => {
+    writePrefsCookie({ searchMode: 'ADS_COMPAT' });
+    expect(written).toHaveLength(1);
+    const [pair] = written[0].split(';');
+    const [, value] = pair.split('=');
+    const parsed = JSON.parse(decodeURIComponent(value));
+    expect(parsed.searchMode).toBe('ADS_COMPAT');
+  });
+
+  test('includes Max-Age, Path, and SameSite in the cookie string', () => {
+    writePrefsCookie({ mode: 'ASTROPHYSICS' });
+    expect(written[0]).toContain('Max-Age=');
+    expect(written[0]).toContain('Path=/');
+    expect(written[0]).toContain('SameSite=Lax');
+  });
+
+  test('omits undefined keys from the written cookie', () => {
+    writePrefsCookie({ searchMode: 'ADS_COMPAT', mode: undefined });
+    const [pair] = written[0].split(';');
+    const [, value] = pair.split('=');
+    const parsed = JSON.parse(decodeURIComponent(value));
+    expect(parsed).not.toHaveProperty('mode');
+  });
+
+  test('does not throw when called with an empty updates object', () => {
+    expect(() => writePrefsCookie({})).not.toThrow();
+  });
+
+  test('retains existing keys when updating a different key (merge behaviour)', () => {
+    // First write: set searchMode
+    writePrefsCookie({ searchMode: 'ADS_COMPAT' });
+    // The getter returns the last written pair so readPrefsCookie sees it
+    expect(written).toHaveLength(1);
+
+    // Second write: add mode — searchMode must survive
+    writePrefsCookie({ mode: 'ASTROPHYSICS' });
+    expect(written).toHaveLength(2);
+    const [pair] = written[1].split(';');
+    const [, value] = pair.split('=');
+    const parsed = JSON.parse(decodeURIComponent(value));
+    expect(parsed.searchMode).toBe('ADS_COMPAT');
+    expect(parsed.mode).toBe('ASTROPHYSICS');
+  });
+});
diff --git a/src/utils/common/__tests__/searchMode.test.ts b/src/utils/common/__tests__/searchMode.test.ts
new file mode 100644
index 000000000..f0dc83376
--- /dev/null
+++ b/src/utils/common/__tests__/searchMode.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, test } from 'vitest';
+import { ADS_COMPAT_FQ_DATABASE, ADS_COMPAT_FQ_ENTRY, applySearchModeDefaults, SearchMode } from '../searchMode';
+import type { IADSApiSearchParams } from '@/api/search/types';
+
+const BASE: IADSApiSearchParams = { q: 'dark matter', sort: ['score desc'] };
+
+const ADS_QUERY: IADSApiSearchParams = {
+  ...BASE,
+  fq: [ADS_COMPAT_FQ_ENTRY],
+  fq_database: ADS_COMPAT_FQ_DATABASE,
+  sort: ['date desc'],
+};
+
+describe('applySearchModeDefaults — ADS_COMPAT', () => {
+  test('adds astronomy and physics database filter', () => {
+    const result = applySearchModeDefaults(BASE, SearchMode.ADS_COMPAT);
+    expect(result.fq).toContain(ADS_COMPAT_FQ_ENTRY);
+    expect(result.fq_database).toBe(ADS_COMPAT_FQ_DATABASE);
+  });
+
+  test('sets date sort', () => {
+    const result = applySearchModeDefaults(BASE, SearchMode.ADS_COMPAT);
+    expect(result.sort).toEqual(['date desc']);
+  });
+
+  test('does not duplicate fq_database entry when already present', () => {
+    const result = applySearchModeDefaults(ADS_QUERY, SearchMode.ADS_COMPAT);
+    const count = (result.fq as string[]).filter((f) => f === ADS_COMPAT_FQ_ENTRY).length;
+    expect(count).toBe(1);
+  });
+
+  test('preserves unrelated fq filters', () => {
+    const withAuthor: IADSApiSearchParams = {
+      ...BASE,
+      fq: ['{!type=aqp v=$fq_author}'],
+      fq_author: 'author:"Smith"',
+    };
+    const result = applySearchModeDefaults(withAuthor, SearchMode.ADS_COMPAT);
+    expect(result.fq).toContain('{!type=aqp v=$fq_author}');
+    expect(result.fq_author).toBe('author:"Smith"');
+  });
+});
+
+describe('applySearchModeDefaults — ALL_RELEVANT', () => {
+  test('returns query unchanged when no ADS filters are present', () => {
+    expect(applySearchModeDefaults(BASE, SearchMode.ALL_RELEVANT)).toEqual(BASE);
+  });
+
+  test('returns query unchanged when mode is absent', () => {
+    expect(applySearchModeDefaults(BASE, undefined)).toEqual(BASE);
+  });
+
+  test('returns query unchanged for an unrecognised mode string', () => {
+    expect(applySearchModeDefaults(BASE, 'UNKNOWN')).toEqual(BASE);
+  });
+
+  test('strips ADS database filter when switching back from ADS_COMPAT', () => {
+    const result = applySearchModeDefaults(ADS_QUERY, SearchMode.ALL_RELEVANT);
+    expect(result.fq_database).toBeUndefined();
+    expect(result.fq).toBeUndefined();
+  });
+
+  test('does not strip a user-set database filter that differs from ADS defaults', () => {
+    const userQuery: IADSApiSearchParams = {
+      ...BASE,
+      fq: ['{!type=aqp v=$fq_database}'],
+      fq_database: 'database:"earthscience"',
+    };
+    const result = applySearchModeDefaults(userQuery, SearchMode.ALL_RELEVANT);
+    expect(result.fq_database).toBe('database:"earthscience"');
+    expect(result.fq).toContain('{!type=aqp v=$fq_database}');
+  });
+
+  test('preserves other fq entries when stripping ADS database filter', () => {
+    const mixed: IADSApiSearchParams = {
+      ...BASE,
+      fq: [ADS_COMPAT_FQ_ENTRY, '{!type=aqp v=$fq_author}'],
+      fq_database: ADS_COMPAT_FQ_DATABASE,
+      fq_author: 'author:"Smith"',
+    };
+    const result = applySearchModeDefaults(mixed, SearchMode.ALL_RELEVANT);
+    expect(result.fq_database).toBeUndefined();
+    expect(result.fq).not.toContain(ADS_COMPAT_FQ_ENTRY);
+    expect(result.fq).toContain('{!type=aqp v=$fq_author}');
+    expect(result.fq_author).toBe('author:"Smith"');
+  });
+});