From da84cfd4d715cc8653f9047833212776406f02a4 Mon Sep 17 00:00:00 2001
From: Markus Neusinger <2921697+MarkusNeusinger@users.noreply.github.com>
Date: Wed, 10 Jun 2026 01:04:17 +0200
Subject: [PATCH 1/2] refactor(app): central routes/ module with paths registry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- router.tsx moves to src/routes/index.tsx (git mv, route config unchanged)
- utils/paths.ts moves to src/routes/paths.ts and gains a paths registry —
  the single source of truth for app URLs (static routes, plotsFiltered
  builder, spec detail via specPath)
- ~25 hardcoded route literals across 16 files replaced with paths.*
- routes/paths.test.ts covers builders, reserved slugs, and the registry;
  routes/ added to coverage
- Updated path references in spec-create.yml and docs/reference/seo.md

Part 6 of the frontend modernization roadmap.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .github/workflows/spec-create.yml           |  2 +-
 app/src/app.tsx                             |  2 +-
 app/src/components/FeedbackWidget.tsx       |  2 +-
 app/src/components/Footer.tsx               |  5 +-
 app/src/components/HeroSection.tsx          | 11 +--
 app/src/components/MastheadRule.tsx         |  4 +-
 app/src/components/NavBar.tsx               |  7 +-
 app/src/components/PlotOfTheDay.tsx         |  2 +-
 app/src/components/PlotOfTheDayTerminal.tsx |  2 +-
 app/src/components/RelatedSpecs.tsx         |  2 +-
 app/src/components/RootLayout.tsx           |  3 +-
 app/src/components/RouteErrorBoundary.tsx   |  3 +-
 app/src/components/ScienceNote.tsx          |  3 +-
 app/src/components/SpecOverview.tsx         |  2 +-
 app/src/components/SpecTabs.tsx             |  4 +-
 app/src/components/ToolbarActions.tsx       |  3 +-
 app/src/hooks/useAnalytics.ts               |  2 +-
 app/src/pages/AboutPage.tsx                 |  7 +-
 app/src/pages/DebugPage.tsx                 |  2 +-
 app/src/pages/LandingPage.tsx               |  8 +--
 app/src/pages/LibrariesPage.tsx             |  5 +-
 app/src/pages/MapPage.tsx                   |  2 +-
 app/src/pages/NotFoundPage.tsx              |  3 +-
 app/src/pages/PalettePage.tsx               |  3 +-
 app/src/pages/PlotsPage.tsx                 |  2 +-
 app/src/pages/SpecPage.tsx                  |  4 +-
 app/src/pages/SpecsListPage.tsx             |  4 +-
 app/src/pages/StatsPage.tsx                 |  6 +-
 app/src/{router.tsx => routes/index.tsx}    |  0
 app/src/routes/paths.test.ts                | 80 +++++++++++++++++++++
 app/src/{utils => routes}/paths.ts          | 22 ++++++
 app/vitest.config.ts                        |  1 +
 docs/reference/seo.md                       |  4 +-
 33 files changed, 165 insertions(+), 47 deletions(-)
 rename app/src/{router.tsx => routes/index.tsx} (100%)
 create mode 100644 app/src/routes/paths.test.ts
 rename app/src/{utils => routes}/paths.ts (66%)

diff --git a/.github/workflows/spec-create.yml b/.github/workflows/spec-create.yml
index 8a9d11055b..77804d4488 100644
--- a/.github/workflows/spec-create.yml
+++ b/.github/workflows/spec-create.yml
@@ -297,7 +297,7 @@ jobs:
           fi
 
           # Reserved spec slugs collide with top-level frontend routes.
-          # Keep this list in sync with `RESERVED_TOP_LEVEL` in app/src/utils/paths.ts.
+          # Keep this list in sync with `RESERVED_TOP_LEVEL` in app/src/routes/paths.ts.
           RESERVED_SLUGS=(plots specs libraries palette about legal mcp stats debug map api og sitemap.xml robots.txt)
           for reserved in "${RESERVED_SLUGS[@]}"; do
             if [[ "$SPEC_ID" == "$reserved" ]]; then
diff --git a/app/src/app.tsx b/app/src/app.tsx
index f2fc46313a..0c4bb9c84f 100644
--- a/app/src/app.tsx
+++ b/app/src/app.tsx
@@ -1,7 +1,7 @@
 import CssBaseline from '@mui/material/CssBaseline';
 import { ThemeProvider } from '@mui/material/styles';
 
-import { AppRouter } from 'src/router';
+import { AppRouter } from 'src/routes';
 import { theme } from 'src/theme';
 
 export function App() {
diff --git a/app/src/components/FeedbackWidget.tsx b/app/src/components/FeedbackWidget.tsx
index f093cf6c27..e21ec8b249 100644
--- a/app/src/components/FeedbackWidget.tsx
+++ b/app/src/components/FeedbackWidget.tsx
@@ -19,7 +19,7 @@ import Tooltip from '@mui/material/Tooltip';
 import { useAnalytics } from 'src/hooks';
 import { useLocalStorage } from 'src/hooks/useLocalStorage';
 import { apiPost, endpoints } from 'src/lib/api';
-import { RESERVED_TOP_LEVEL } from 'src/utils/paths';
+import { RESERVED_TOP_LEVEL } from 'src/routes/paths';
 
 const MAX_MESSAGE_LENGTH = 500;
 const SESSION_KEY = 'anyplot_feedback_session';
diff --git a/app/src/components/Footer.tsx b/app/src/components/Footer.tsx
index 12397d6eba..0f5d0ceba0 100644
--- a/app/src/components/Footer.tsx
+++ b/app/src/components/Footer.tsx
@@ -4,6 +4,7 @@ import Box from '@mui/material/Box';
 import Link from '@mui/material/Link';
 
 import { GITHUB_URL } from 'src/constants';
+import { paths } from 'src/routes/paths';
 import { colors, fontSize, semanticColors, typography } from 'src/theme';
 
 interface FooterProps {
@@ -92,11 +93,11 @@ export function Footer({ onTrackEvent, selectedSpec, selectedLibrary }: FooterPr
         </Link>
       </Box>
       <span>·</span>
-      <Link component={RouterLink} to="/about" onClick={trackInternal('about')} sx={linkSx}>
+      <Link component={RouterLink} to={paths.about} onClick={trackInternal('about')} sx={linkSx}>
         about
       </Link>
       <span>·</span>
-      <Link component={RouterLink} to="/legal" onClick={trackInternal('legal')} sx={linkSx}>
+      <Link component={RouterLink} to={paths.legal} onClick={trackInternal('legal')} sx={linkSx}>
         legal
       </Link>
     </Box>
diff --git a/app/src/components/HeroSection.tsx b/app/src/components/HeroSection.tsx
index 2585bd9074..c3a185de08 100644
--- a/app/src/components/HeroSection.tsx
+++ b/app/src/components/HeroSection.tsx
@@ -6,6 +6,7 @@ import { PlotOfTheDayTerminal } from 'src/components/PlotOfTheDayTerminal';
 import { TypewriterText } from 'src/components/TypewriterText';
 import { useAnalytics } from 'src/hooks';
 import type { PlotOfTheDayData } from 'src/hooks/usePlotOfTheDay';
+import { paths } from 'src/routes/paths';
 import { colors, typography } from 'src/theme';
 
 interface HeroSectionProps {
@@ -170,11 +171,13 @@ export function HeroSection({ potd = null }: HeroSectionProps) {
           }}
         >
           <PrimaryCta
-            to="/plots"
+            to={paths.plots}
             subject="plots"
             verb="browse"
             ariaLabel="Browse plots"
-            onClick={() => trackEvent('nav_click', { source: 'hero_cta_browse', target: '/plots' })}
+            onClick={() =>
+              trackEvent('nav_click', { source: 'hero_cta_browse', target: paths.plots })
+            }
           />
           <Box
             aria-hidden="true"
@@ -189,11 +192,11 @@ export function HeroSection({ potd = null }: HeroSectionProps) {
           </Box>
           <Box sx={{ display: 'flex', flexDirection: 'column', gap: 0.25 }}>
             <SecondaryLink
-              to="/mcp"
+              to={paths.mcp}
               subject="mcp"
               verb="connect"
               ariaLabel="Connect via MCP"
-              onClick={() => trackEvent('nav_click', { source: 'hero_mcp', target: '/mcp' })}
+              onClick={() => trackEvent('nav_click', { source: 'hero_mcp', target: paths.mcp })}
             />
             <SecondaryLink
               href="https://github.com/MarkusNeusinger/anyplot"
diff --git a/app/src/components/MastheadRule.tsx b/app/src/components/MastheadRule.tsx
index 4e56444379..aff2e16f50 100644
--- a/app/src/components/MastheadRule.tsx
+++ b/app/src/components/MastheadRule.tsx
@@ -7,8 +7,8 @@ import Box from '@mui/material/Box';
 import { ThemeToggle } from 'src/components/ThemeToggle';
 import { LANG_EXT, LIB_ABBREV } from 'src/constants';
 import { useAnalytics, useLatestRelease, useTheme } from 'src/hooks';
+import { paths, RESERVED_TOP_LEVEL } from 'src/routes/paths';
 import { colors, typography } from 'src/theme';
-import { RESERVED_TOP_LEVEL } from 'src/utils/paths';
 
 // Symmetric block-comment delimiters used when no language context is in the URL.
 // One is picked on mount so each page load reveals a different classic.
@@ -208,7 +208,7 @@ export function MastheadRule() {
             keepRootMarkerOnXs above). */}
         <Box
           component={RouterLink}
-          to="/"
+          to={paths.home}
           onClick={() => trackEvent('nav_click', { source: 'masthead_logo', target: '/' })}
           sx={{ ...linkSx, display: rootMarkerDisplay }}
         >
diff --git a/app/src/components/NavBar.tsx b/app/src/components/NavBar.tsx
index fd69973d1d..4152ac920a 100644
--- a/app/src/components/NavBar.tsx
+++ b/app/src/components/NavBar.tsx
@@ -5,6 +5,7 @@ import { Link as RouterLink, useLocation, useNavigate } from 'react-router-dom';
 import Box from '@mui/material/Box';
 
 import { useAnalytics } from 'src/hooks';
+import { paths } from 'src/routes/paths';
 import { colors, typography } from 'src/theme';
 
 const DEBUG_CLICK_COUNT = 5;
@@ -73,7 +74,7 @@ export function NavBar() {
 
   const handleSearch = () => {
     trackEvent('nav_click', { source: 'nav_search', target: '/plots?focus=search' });
-    navigate('/plots?focus=search');
+    navigate(paths.plotsSearch);
   };
 
   // 5 rapid clicks on the logo opens /debug.
@@ -91,7 +92,7 @@ export function NavBar() {
         e.preventDefault();
         clickCountRef.current = 0;
         if (clickTimerRef.current) clearTimeout(clickTimerRef.current);
-        navigate('/debug');
+        navigate(paths.debug);
       }
     },
     [navigate, trackEvent]
@@ -119,7 +120,7 @@ export function NavBar() {
       {/* Logo */}
       <Box
         component={RouterLink}
-        to="/"
+        to={paths.home}
         onClick={handleLogoClick}
         sx={{
           gridArea: 'logo',
diff --git a/app/src/components/PlotOfTheDay.tsx b/app/src/components/PlotOfTheDay.tsx
index fa8682d08f..cb3e4f6444 100644
--- a/app/src/components/PlotOfTheDay.tsx
+++ b/app/src/components/PlotOfTheDay.tsx
@@ -13,8 +13,8 @@ import { GITHUB_URL } from 'src/constants';
 import { useAnalytics } from 'src/hooks';
 import { useTheme } from 'src/hooks/useLayoutContext';
 import { apiGet, endpoints } from 'src/lib/api';
+import { specPath } from 'src/routes/paths';
 import { colors, fontSize, semanticColors, typography } from 'src/theme';
-import { specPath } from 'src/utils/paths';
 import { buildSrcSet, getFallbackSrc } from 'src/utils/responsiveImage';
 import { selectPreviewUrl } from 'src/utils/themedPreview';
 
diff --git a/app/src/components/PlotOfTheDayTerminal.tsx b/app/src/components/PlotOfTheDayTerminal.tsx
index 686ece5e28..7bb88ac87b 100644
--- a/app/src/components/PlotOfTheDayTerminal.tsx
+++ b/app/src/components/PlotOfTheDayTerminal.tsx
@@ -6,8 +6,8 @@ import { GITHUB_URL } from 'src/constants';
 import { useAnalytics } from 'src/hooks';
 import { useTheme } from 'src/hooks/useLayoutContext';
 import type { PlotOfTheDayData } from 'src/hooks/usePlotOfTheDay';
+import { specPath } from 'src/routes/paths';
 import { colors, typography } from 'src/theme';
-import { specPath } from 'src/utils/paths';
 import { buildSrcSet, getFallbackSrc } from 'src/utils/responsiveImage';
 import { selectPreviewUrl } from 'src/utils/themedPreview';
 
diff --git a/app/src/components/RelatedSpecs.tsx b/app/src/components/RelatedSpecs.tsx
index 28978460a0..27b7b89c82 100644
--- a/app/src/components/RelatedSpecs.tsx
+++ b/app/src/components/RelatedSpecs.tsx
@@ -12,8 +12,8 @@ import Typography from '@mui/material/Typography';
 import { LIB_ABBREV } from 'src/constants';
 import { useTheme } from 'src/hooks/useLayoutContext';
 import { apiGet, endpoints } from 'src/lib/api';
+import { specPath } from 'src/routes/paths';
 import { colors, fontSize, semanticColors, typography } from 'src/theme';
-import { specPath } from 'src/utils/paths';
 import { buildSrcSet, getFallbackSrc } from 'src/utils/responsiveImage';
 import { selectPreviewUrl } from 'src/utils/themedPreview';
 
diff --git a/app/src/components/RootLayout.tsx b/app/src/components/RootLayout.tsx
index bd7020ed66..7ed1c85f99 100644
--- a/app/src/components/RootLayout.tsx
+++ b/app/src/components/RootLayout.tsx
@@ -12,6 +12,7 @@ import { NavBar } from 'src/components/NavBar';
 import { useAnalytics } from 'src/hooks';
 import { setAnalyticsAmbientProps } from 'src/hooks/useAnalytics';
 import { useTheme } from 'src/hooks/useLayoutContext';
+import { paths } from 'src/routes/paths';
 
 const containerSx = {
   px: { xs: 2, sm: 4, md: 8, lg: 12 },
@@ -31,7 +32,7 @@ export function RootLayout() {
   const { pathname, hash } = useLocation();
   const navigationType = useNavigationType();
   const { effective } = useTheme();
-  const mastheadSticks = pathname !== '/plots';
+  const mastheadSticks = pathname !== paths.plots;
 
   // Set synchronously during render so the first pageview from a child page's
   // useEffect (which runs before the parent's useEffect) carries the theme prop.
diff --git a/app/src/components/RouteErrorBoundary.tsx b/app/src/components/RouteErrorBoundary.tsx
index 9e506f1cc7..9e5ada2264 100644
--- a/app/src/components/RouteErrorBoundary.tsx
+++ b/app/src/components/RouteErrorBoundary.tsx
@@ -12,6 +12,7 @@ import Typography from '@mui/material/Typography';
 
 import { CONFIG } from 'src/global-config';
 import { NotFoundPage } from 'src/pages/NotFoundPage';
+import { paths } from 'src/routes/paths';
 
 const RELOAD_ATTEMPT_KEY = 'anyplot:chunk-reload-attempt';
 
@@ -175,7 +176,7 @@ export function RouteErrorBoundary() {
         </Button>
         <Button
           component={RouterLink}
-          to="/"
+          to={paths.home}
           variant="outlined"
           startIcon={<HomeIcon />}
           sx={{ textTransform: 'none' }}
diff --git a/app/src/components/ScienceNote.tsx b/app/src/components/ScienceNote.tsx
index b747c9a299..6b0c03a5fa 100644
--- a/app/src/components/ScienceNote.tsx
+++ b/app/src/components/ScienceNote.tsx
@@ -3,6 +3,7 @@ import { Link as RouterLink } from 'react-router-dom';
 import Box from '@mui/material/Box';
 
 import { PaletteStrip } from 'src/components/PaletteStrip';
+import { paths } from 'src/routes/paths';
 import { colors, typography } from 'src/theme';
 
 export function ScienceNote() {
@@ -94,7 +95,7 @@ export function ScienceNote() {
 
         <Box
           component={RouterLink}
-          to="/palette"
+          to={paths.palette}
           sx={{
             display: 'inline-block',
             mt: 3,
diff --git a/app/src/components/SpecOverview.tsx b/app/src/components/SpecOverview.tsx
index 0c8aeb5084..71befe36e8 100644
--- a/app/src/components/SpecOverview.tsx
+++ b/app/src/components/SpecOverview.tsx
@@ -20,9 +20,9 @@ import Tooltip from '@mui/material/Tooltip';
 import Typography from '@mui/material/Typography';
 
 import { useTheme } from 'src/hooks/useLayoutContext';
+import { specPath } from 'src/routes/paths';
 import { colors, fontSize, semanticColors, typography } from 'src/theme';
 import type { Implementation } from 'src/types';
-import { specPath } from 'src/utils/paths';
 import { buildSrcSet, OVERVIEW_SIZES } from 'src/utils/responsiveImage';
 import { selectPreviewUrl } from 'src/utils/themedPreview';
 
diff --git a/app/src/components/SpecTabs.tsx b/app/src/components/SpecTabs.tsx
index 728136e08d..dbe6a47b4c 100644
--- a/app/src/components/SpecTabs.tsx
+++ b/app/src/components/SpecTabs.tsx
@@ -19,6 +19,8 @@ import Tabs from '@mui/material/Tabs';
 import Tooltip from '@mui/material/Tooltip';
 import Typography from '@mui/material/Typography';
 
+import { paths } from 'src/routes/paths';
+
 const CodeHighlighter = lazy(() => import('src/components/CodeHighlighter'));
 import { apiGet, endpoints } from 'src/lib/api';
 import { colors, fontSize, semanticColors, typography } from 'src/theme';
@@ -231,7 +233,7 @@ export function SpecTabs({
   const handleTagClick = useCallback(
     (paramName: string, value: string) => {
       onTrackEvent?.('tag_click', { param: paramName, value, source: 'spec_detail' });
-      navigate(`/plots?${paramName}=${encodeURIComponent(value)}`);
+      navigate(paths.plotsFiltered(paramName, value));
     },
     [navigate, onTrackEvent]
   );
diff --git a/app/src/components/ToolbarActions.tsx b/app/src/components/ToolbarActions.tsx
index dc04558c40..fc66be6a8d 100644
--- a/app/src/components/ToolbarActions.tsx
+++ b/app/src/components/ToolbarActions.tsx
@@ -12,6 +12,7 @@ import Box from '@mui/material/Box';
 import Tooltip from '@mui/material/Tooltip';
 
 import type { ImageSize } from 'src/constants';
+import { paths } from 'src/routes/paths';
 import { colors, semanticColors } from 'src/theme';
 
 interface ToolbarActionsProps {
@@ -28,7 +29,7 @@ export function PlotsLink() {
     <Tooltip title="plots.list()">
       <Box
         component={Link}
-        to="/plots"
+        to={paths.plots}
         aria-label="Browse plots"
         sx={{
           display: 'flex',
diff --git a/app/src/hooks/useAnalytics.ts b/app/src/hooks/useAnalytics.ts
index 677542e4dc..64bdd0cd0c 100644
--- a/app/src/hooks/useAnalytics.ts
+++ b/app/src/hooks/useAnalytics.ts
@@ -1,6 +1,6 @@
 import { useCallback, useMemo, useRef } from 'react';
 
-import { RESERVED_TOP_LEVEL } from 'src/utils/paths';
+import { RESERVED_TOP_LEVEL } from 'src/routes/paths';
 
 interface EventProps {
   [key: string]: string | undefined;
diff --git a/app/src/pages/AboutPage.tsx b/app/src/pages/AboutPage.tsx
index 57a853bb19..641f82902a 100644
--- a/app/src/pages/AboutPage.tsx
+++ b/app/src/pages/AboutPage.tsx
@@ -9,6 +9,7 @@ import Link from '@mui/material/Link';
 import { SectionHeader } from 'src/components/SectionHeader';
 import { GITHUB_URL } from 'src/constants';
 import { useAnalytics } from 'src/hooks';
+import { paths } from 'src/routes/paths';
 import { codeBlockStyle, colors, proseLinkStyle, textStyle, typography } from 'src/theme';
 
 const PIPELINE_BLOCK = `// pipeline
@@ -44,7 +45,7 @@ export function AboutPage() {
   const { trackPageview, trackEvent } = useAnalytics();
 
   useEffect(() => {
-    trackPageview('/about');
+    trackPageview(paths.about);
   }, [trackPageview]);
 
   return (
@@ -108,7 +109,7 @@ export function AboutPage() {
             <Box sx={{ ...textStyle, mt: 1 }}>
               see the{' '}
               <Link
-                href="/palette"
+                href={paths.palette}
                 onClick={() =>
                   trackEvent('internal_link', { destination: 'palette', source: 'about' })
                 }
@@ -153,7 +154,7 @@ export function AboutPage() {
               curious about the stack, costs, or analytics? see{' '}
               <Link
                 component={RouterLink}
-                to="/legal#transparency"
+                to={`${paths.legal}#transparency`}
                 onClick={() =>
                   trackEvent('internal_link', {
                     destination: 'legal_transparency',
diff --git a/app/src/pages/DebugPage.tsx b/app/src/pages/DebugPage.tsx
index 2cfe54f2dc..b82cfd379d 100644
--- a/app/src/pages/DebugPage.tsx
+++ b/app/src/pages/DebugPage.tsx
@@ -14,9 +14,9 @@ import { SectionHeader } from 'src/components/SectionHeader';
 import { DEBUG_API_URL, LIB_ABBREV, LIB_TO_LANG, LIBRARIES } from 'src/constants';
 import { useCopyCode } from 'src/hooks';
 import { fetchWithAuth } from 'src/lib/api';
+import { specPath } from 'src/routes/paths';
 import { colors, fontSize, semanticColors, typography } from 'src/theme';
 import { buildClaudePrompt } from 'src/utils/claudePrompt';
-import { specPath } from 'src/utils/paths';
 
 // ============================================================================
 // Types
diff --git a/app/src/pages/LandingPage.tsx b/app/src/pages/LandingPage.tsx
index fc0dc58290..e8266d143a 100644
--- a/app/src/pages/LandingPage.tsx
+++ b/app/src/pages/LandingPage.tsx
@@ -14,8 +14,8 @@ import { useAnalytics, useAppData } from 'src/hooks';
 import { type FeaturedImpl, useFeaturedSpecs } from 'src/hooks/useFeaturedSpecs';
 import { useTheme } from 'src/hooks/useLayoutContext';
 import { usePlotOfTheDay } from 'src/hooks/usePlotOfTheDay';
+import { paths, specPath } from 'src/routes/paths';
 import { colors, semanticColors, typography } from 'src/theme';
-import { specPath } from 'src/utils/paths';
 import { buildSrcSet, getFallbackSrc } from 'src/utils/responsiveImage';
 import { selectPreviewUrl } from 'src/utils/themedPreview';
 
@@ -32,7 +32,7 @@ export function LandingPage() {
 
   const handleLibraryClick = (lib: string) => {
     trackEvent('nav_click', { source: 'library_card', target: '/plots', value: lib });
-    navigate(`/plots?lib=${encodeURIComponent(lib)}`);
+    navigate(paths.plotsFiltered('lib', lib));
   };
 
   return (
@@ -117,7 +117,7 @@ function MapSection({ specCount }: { specCount?: number }) {
 
         <Box
           component={RouterLink}
-          to="/map"
+          to={paths.map}
           onClick={() => trackEvent('nav_click', { source: 'map_teaser_preview', target: '/map' })}
           sx={{
             display: 'block',
@@ -475,7 +475,7 @@ function SpecsSection({
       {specCount != null && featured && featured.length < specCount && (
         <Box
           component={RouterLink}
-          to="/specs"
+          to={paths.specs}
           onClick={() => trackEvent('nav_click', { source: 'specs_more_link', target: '/specs' })}
           sx={{
             display: 'inline-block',
diff --git a/app/src/pages/LibrariesPage.tsx b/app/src/pages/LibrariesPage.tsx
index ee8bb5d34f..f7fdd091ce 100644
--- a/app/src/pages/LibrariesPage.tsx
+++ b/app/src/pages/LibrariesPage.tsx
@@ -10,6 +10,7 @@ import { LibraryCard } from 'src/components/LibraryCard';
 import { SectionHeader } from 'src/components/SectionHeader';
 import { LIB_TO_FRAMEWORK, LIBRARIES } from 'src/constants';
 import { useAnalytics, useAppData } from 'src/hooks';
+import { paths } from 'src/routes/paths';
 import { colors, textStyle, typography } from 'src/theme';
 
 // Framework filter (per library-expansion.md §6: "all JavaScript libs" vs
@@ -48,7 +49,7 @@ export function LibrariesPage() {
   const [frameworkFilter, setFrameworkFilter] = useState<FrameworkFilter>('all');
 
   useEffect(() => {
-    trackPageview('/libraries');
+    trackPageview(paths.libraries);
   }, [trackPageview]);
 
   const byId = new Map(librariesData.map(lib => [lib.id, lib]));
@@ -60,7 +61,7 @@ export function LibrariesPage() {
 
   const handleLibraryClick = (name: string) => {
     trackEvent('library_click', { source: 'libraries_page', library: name });
-    navigate(`/plots?lib=${name}`);
+    navigate(paths.plotsFiltered('lib', name));
   };
 
   const handleFilterClick = (id: FrameworkFilter) => {
diff --git a/app/src/pages/MapPage.tsx b/app/src/pages/MapPage.tsx
index 48aeb32202..af1360791a 100644
--- a/app/src/pages/MapPage.tsx
+++ b/app/src/pages/MapPage.tsx
@@ -37,8 +37,8 @@ import {
   type TagCategory,
   topCategoryValues,
 } from 'src/pages/MapPage.helpers';
+import { specPath } from 'src/routes/paths';
 import { colors, fontSize, typography } from 'src/theme';
-import { specPath } from 'src/utils/paths';
 
 const NODE_SIZE = 60; // graph-space size of a node — large enough to read the thumbnail without hovering
 const COOLDOWN_TICKS = 300; // simulation lifetime in ticks; the engine cap and alpha-decay below both derive from this so they stop together
diff --git a/app/src/pages/NotFoundPage.tsx b/app/src/pages/NotFoundPage.tsx
index ae508361ca..bb6ca64534 100644
--- a/app/src/pages/NotFoundPage.tsx
+++ b/app/src/pages/NotFoundPage.tsx
@@ -4,6 +4,7 @@ import { Link } from 'react-router-dom';
 import Box from '@mui/material/Box';
 import Typography from '@mui/material/Typography';
 
+import { paths } from 'src/routes/paths';
 import { colors, semanticColors, typography } from 'src/theme';
 
 export function NotFoundPage() {
@@ -35,7 +36,7 @@ export function NotFoundPage() {
         </Typography>
         <Box
           component={Link}
-          to="/"
+          to={paths.home}
           aria-label="Go home"
           sx={{
             color: colors.primary,
diff --git a/app/src/pages/PalettePage.tsx b/app/src/pages/PalettePage.tsx
index 890db11354..048c899c61 100644
--- a/app/src/pages/PalettePage.tsx
+++ b/app/src/pages/PalettePage.tsx
@@ -15,6 +15,7 @@ import Tooltip from '@mui/material/Tooltip';
 import { SectionHeader } from 'src/components/SectionHeader';
 import matrixData from 'src/data/paletteMatrices.json';
 import { useAnalytics, useTheme } from 'src/hooks';
+import { paths } from 'src/routes/paths';
 import { colors, fontSize, textStyle, typography } from 'src/theme';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -951,7 +952,7 @@ export function PalettePage() {
   };
 
   useEffect(() => {
-    trackPageview('/palette');
+    trackPageview(paths.palette);
   }, [trackPageview]);
 
   const sortedPalette: Swatch[] = useMemo(
diff --git a/app/src/pages/PlotsPage.tsx b/app/src/pages/PlotsPage.tsx
index fd5313be44..c08620b636 100644
--- a/app/src/pages/PlotsPage.tsx
+++ b/app/src/pages/PlotsPage.tsx
@@ -13,9 +13,9 @@ import { ImagesGrid } from 'src/components/ImagesGrid';
 import type { ImageSize } from 'src/constants';
 import { isFiltersEmpty, useAnalytics, useFilterState, useInfiniteScroll } from 'src/hooks';
 import { useAppData, useHomeState } from 'src/hooks';
+import { specPath } from 'src/routes/paths';
 import { colors } from 'src/theme';
 import type { PlotImage } from 'src/types';
-import { specPath } from 'src/utils/paths';
 
 export function PlotsPage() {
   const navigate = useNavigate();
diff --git a/app/src/pages/SpecPage.tsx b/app/src/pages/SpecPage.tsx
index e8cd6e06ab..80e79406fb 100644
--- a/app/src/pages/SpecPage.tsx
+++ b/app/src/pages/SpecPage.tsx
@@ -16,8 +16,8 @@ import { useAnalytics, useCodeFetch } from 'src/hooks';
 import { useAppData } from 'src/hooks';
 import { ApiError, apiGet, apiUrl, endpoints } from 'src/lib/api';
 import { NotFoundPage } from 'src/pages/NotFoundPage';
+import { paths, specPath } from 'src/routes/paths';
 import { colors, fontSize, semanticColors, typography } from 'src/theme';
-import { specPath } from 'src/utils/paths';
 
 const SpecTabs = lazy(() => import('src/components/SpecTabs').then(m => ({ default: m.SpecTabs })));
 const SpecOverview = lazy(() =>
@@ -372,7 +372,7 @@ export function SpecPage() {
         </Typography>
         <Button
           component={Link}
-          to="/"
+          to={paths.home}
           startIcon={<ArrowBackIcon />}
           sx={{ color: colors.primary }}
         >
diff --git a/app/src/pages/SpecsListPage.tsx b/app/src/pages/SpecsListPage.tsx
index 7e81c4a992..1508159f00 100644
--- a/app/src/pages/SpecsListPage.tsx
+++ b/app/src/pages/SpecsListPage.tsx
@@ -14,9 +14,9 @@ import { GITHUB_URL } from 'src/constants';
 import { useAnalytics } from 'src/hooks';
 import { useAppData, useHomeState } from 'src/hooks';
 import { ApiError, apiGet, endpoints } from 'src/lib/api';
+import { paths, specPath } from 'src/routes/paths';
 import { colors, fontSize, semanticColors, typography } from 'src/theme';
 import type { PlotImage } from 'src/types';
-import { specPath } from 'src/utils/paths';
 import { buildSrcSet, getFallbackSrc, SPECS_SIZES } from 'src/utils/responsiveImage';
 
 interface SpecListItem {
@@ -41,7 +41,7 @@ export function SpecsListPage() {
 
   // Track specs page view
   useEffect(() => {
-    trackPageview('/specs');
+    trackPageview(paths.specs);
   }, [trackPageview]);
 
   const [allImages, setAllImages] = useState<PlotImage[]>([]);
diff --git a/app/src/pages/StatsPage.tsx b/app/src/pages/StatsPage.tsx
index 5da9c59ad0..a5c91e1c44 100644
--- a/app/src/pages/StatsPage.tsx
+++ b/app/src/pages/StatsPage.tsx
@@ -12,8 +12,8 @@ import { SectionHeader } from 'src/components/SectionHeader';
 import { useAnalytics } from 'src/hooks';
 import { useTheme } from 'src/hooks/useLayoutContext';
 import { ApiError, apiGet, endpoints } from 'src/lib/api';
+import { paths, specPath } from 'src/routes/paths';
 import { colors, fontSize, semanticColors, typography } from 'src/theme';
-import { specPath } from 'src/utils/paths';
 import { buildSrcSet, getFallbackSrc } from 'src/utils/responsiveImage';
 import { selectPreviewUrl } from 'src/utils/themedPreview';
 
@@ -108,7 +108,7 @@ export function StatsPage() {
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
-    trackPageview('/stats');
+    trackPageview(paths.stats);
   }, [trackPageview]);
 
   useEffect(() => {
@@ -793,7 +793,7 @@ export function StatsPage() {
                       <Link
                         key={tag}
                         component={RouterLink}
-                        to={param ? `/plots?${param}=${encodeURIComponent(tag)}` : '/plots'}
+                        to={param ? paths.plotsFiltered(param, tag) : paths.plots}
                         onClick={() => {
                           if (param)
                             trackEvent('tag_click', { param, value: tag, source: 'stats' });
diff --git a/app/src/router.tsx b/app/src/routes/index.tsx
similarity index 100%
rename from app/src/router.tsx
rename to app/src/routes/index.tsx
diff --git a/app/src/routes/paths.test.ts b/app/src/routes/paths.test.ts
new file mode 100644
index 0000000000..cea56928f5
--- /dev/null
+++ b/app/src/routes/paths.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+
+import { langFromPath, paths, RESERVED_TOP_LEVEL, specPath } from 'src/routes/paths';
+
+describe('specPath', () => {
+  it('builds the cross-language hub path', () => {
+    expect(specPath('scatter-basic')).toBe('/scatter-basic');
+  });
+
+  it('builds the language overview path', () => {
+    expect(specPath('scatter-basic', 'python')).toBe('/scatter-basic/python');
+  });
+
+  it('builds the implementation detail path', () => {
+    expect(specPath('scatter-basic', 'python', 'matplotlib')).toBe(
+      '/scatter-basic/python/matplotlib'
+    );
+  });
+
+  it('ignores library without language', () => {
+    expect(specPath('scatter-basic', undefined, 'matplotlib')).toBe('/scatter-basic');
+  });
+});
+
+describe('langFromPath', () => {
+  it('returns the language segment of a spec path', () => {
+    expect(langFromPath('/scatter-basic/python')).toBe('python');
+  });
+
+  it('returns undefined for single-segment paths', () => {
+    expect(langFromPath('/scatter-basic')).toBeUndefined();
+  });
+
+  it('returns undefined when the first segment is a reserved route', () => {
+    expect(langFromPath('/plots/python')).toBeUndefined();
+  });
+});
+
+describe('paths registry', () => {
+  it('exposes every static route', () => {
+    expect(paths.home).toBe('/');
+    expect(paths.plots).toBe('/plots');
+    expect(paths.specs).toBe('/specs');
+    expect(paths.libraries).toBe('/libraries');
+    expect(paths.map).toBe('/map');
+    expect(paths.palette).toBe('/palette');
+    expect(paths.about).toBe('/about');
+    expect(paths.legal).toBe('/legal');
+    expect(paths.mcp).toBe('/mcp');
+    expect(paths.stats).toBe('/stats');
+    expect(paths.debug).toBe('/debug');
+  });
+
+  it('every static route is a reserved top-level slug', () => {
+    const staticRoutes = [
+      paths.plots,
+      paths.specs,
+      paths.libraries,
+      paths.map,
+      paths.palette,
+      paths.about,
+      paths.legal,
+      paths.mcp,
+      paths.stats,
+      paths.debug,
+    ];
+    for (const route of staticRoutes) {
+      expect(RESERVED_TOP_LEVEL.has(route.slice(1))).toBe(true);
+    }
+  });
+
+  it('builds encoded plots filter URLs', () => {
+    expect(paths.plotsFiltered('lib', 'ggplot2')).toBe('/plots?lib=ggplot2');
+    expect(paths.plotsFiltered('plot', 'scatter plot')).toBe('/plots?plot=scatter%20plot');
+  });
+
+  it('exposes specPath as paths.spec', () => {
+    expect(paths.spec('heatmap-basic', 'r', 'ggplot2')).toBe('/heatmap-basic/r/ggplot2');
+  });
+});
diff --git a/app/src/utils/paths.ts b/app/src/routes/paths.ts
similarity index 66%
rename from app/src/utils/paths.ts
rename to app/src/routes/paths.ts
index f5c2d906ee..0af6b5fcee 100644
--- a/app/src/utils/paths.ts
+++ b/app/src/routes/paths.ts
@@ -43,3 +43,25 @@ export function langFromPath(pathname: string): string | undefined {
   if (RESERVED_TOP_LEVEL.has(segments[0])) return undefined;
   return segments[1];
 }
+
+/**
+ * Central route registry — the single source of truth for app URLs.
+ * Components navigate via `paths.*` instead of hardcoded strings; spec-detail
+ * URLs go through `specPath` (also exposed as `paths.spec`).
+ */
+export const paths = {
+  home: '/',
+  about: '/about',
+  debug: '/debug',
+  legal: '/legal',
+  libraries: '/libraries',
+  map: '/map',
+  mcp: '/mcp',
+  palette: '/palette',
+  plots: '/plots',
+  plotsSearch: '/plots?focus=search',
+  specs: '/specs',
+  stats: '/stats',
+  plotsFiltered: (param: string, value: string) => `/plots?${param}=${encodeURIComponent(value)}`,
+  spec: specPath,
+} as const;
diff --git a/app/vitest.config.ts b/app/vitest.config.ts
index eb6c78d46c..b4abd2db55 100644
--- a/app/vitest.config.ts
+++ b/app/vitest.config.ts
@@ -30,6 +30,7 @@ export default defineConfig({
         'src/components/**/*.tsx',
         'src/pages/**/*.tsx',
         'src/constants/**/*.ts',
+        'src/routes/**/*.ts',
         'src/theme/**/*.ts',
         'src/types/**/*.ts',
       ],
diff --git a/docs/reference/seo.md b/docs/reference/seo.md
index 3a7484e082..6347fd72f1 100644
--- a/docs/reference/seo.md
+++ b/docs/reference/seo.md
@@ -354,7 +354,7 @@ without the query string.
 ### Reserved Spec Slugs
 
 Spec IDs are top-level path segments, so they must not collide with reserved
-routes. The blocklist is enforced at runtime in `app/src/utils/paths.ts`
+routes. The blocklist is enforced at runtime in `app/src/routes/paths.ts`
 (`RESERVED_TOP_LEVEL`) and at spec creation time in `.github/workflows/spec-create.yml`:
 
 ```
@@ -389,7 +389,7 @@ changing the canonical.
 
 ### Path Utility
 
-Frontend URL generation is centralized in `app/src/utils/paths.ts`:
+Frontend URL generation is centralized in `app/src/routes/paths.ts`:
 - `specPath(specId, language?, library?)` — builds the three-tier URL based on
   which arguments are provided.
 - `langFromPath(pathname)` — extracts the language segment from a path.

From 9985230e8c1f91aba61b3ad59f2777d04a7ea690 Mon Sep 17 00:00:00 2001
From: Markus Neusinger <2921697+MarkusNeusinger@users.noreply.github.com>
Date: Wed, 10 Jun 2026 02:05:13 +0200
Subject: [PATCH 2/2] refactor(app): use paths registry for analytics nav
 targets too
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review findings on the routes PR: trackEvent target strings stayed
hardcoded where navigation already used paths.* — aligned all six
(LandingPage x3, NavBar x2, MastheadRule x1) so analytics can't drift from
the routing source of truth.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 app/src/components/MastheadRule.tsx |  2 +-
 app/src/components/NavBar.tsx       |  4 ++--
 app/src/pages/LandingPage.tsx       | 10 +++++++---
 3 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/app/src/components/MastheadRule.tsx b/app/src/components/MastheadRule.tsx
index aff2e16f50..7f1fca42df 100644
--- a/app/src/components/MastheadRule.tsx
+++ b/app/src/components/MastheadRule.tsx
@@ -209,7 +209,7 @@ export function MastheadRule() {
         <Box
           component={RouterLink}
           to={paths.home}
-          onClick={() => trackEvent('nav_click', { source: 'masthead_logo', target: '/' })}
+          onClick={() => trackEvent('nav_click', { source: 'masthead_logo', target: paths.home })}
           sx={{ ...linkSx, display: rootMarkerDisplay }}
         >
           ~/anyplot.ai
diff --git a/app/src/components/NavBar.tsx b/app/src/components/NavBar.tsx
index 4152ac920a..913e469a8b 100644
--- a/app/src/components/NavBar.tsx
+++ b/app/src/components/NavBar.tsx
@@ -73,7 +73,7 @@ export function NavBar() {
   }, []);
 
   const handleSearch = () => {
-    trackEvent('nav_click', { source: 'nav_search', target: '/plots?focus=search' });
+    trackEvent('nav_click', { source: 'nav_search', target: paths.plotsSearch });
     navigate(paths.plotsSearch);
   };
 
@@ -81,7 +81,7 @@ export function NavBar() {
   // Non-triggering clicks fall through to RouterLink's normal `/` navigation.
   const handleLogoClick = useCallback(
     (e: React.MouseEvent) => {
-      trackEvent('nav_click', { source: 'nav_logo', target: '/' });
+      trackEvent('nav_click', { source: 'nav_logo', target: paths.home });
       if (e.ctrlKey || e.metaKey || e.shiftKey || e.button !== 0) return;
       clickCountRef.current += 1;
       if (clickTimerRef.current) clearTimeout(clickTimerRef.current);
diff --git a/app/src/pages/LandingPage.tsx b/app/src/pages/LandingPage.tsx
index e8266d143a..76ff184706 100644
--- a/app/src/pages/LandingPage.tsx
+++ b/app/src/pages/LandingPage.tsx
@@ -31,7 +31,7 @@ export function LandingPage() {
   }, [trackPageview]);
 
   const handleLibraryClick = (lib: string) => {
-    trackEvent('nav_click', { source: 'library_card', target: '/plots', value: lib });
+    trackEvent('nav_click', { source: 'library_card', target: paths.plots, value: lib });
     navigate(paths.plotsFiltered('lib', lib));
   };
 
@@ -118,7 +118,9 @@ function MapSection({ specCount }: { specCount?: number }) {
         <Box
           component={RouterLink}
           to={paths.map}
-          onClick={() => trackEvent('nav_click', { source: 'map_teaser_preview', target: '/map' })}
+          onClick={() =>
+            trackEvent('nav_click', { source: 'map_teaser_preview', target: paths.map })
+          }
           sx={{
             display: 'block',
             textDecoration: 'none',
@@ -476,7 +478,9 @@ function SpecsSection({
         <Box
           component={RouterLink}
           to={paths.specs}
-          onClick={() => trackEvent('nav_click', { source: 'specs_more_link', target: '/specs' })}
+          onClick={() =>
+            trackEvent('nav_click', { source: 'specs_more_link', target: paths.specs })
+          }
           sx={{
             display: 'inline-block',
             mt: 2.5,