feat: path-based page routing instead of query params

austenstone · austenstone · commit bddb7d0cdaa1 · 2026-03-28T13:08:09.000-04:00
- Pages now use URL paths: /usage, /copilot, /files, etc.
- Root / defaults to copilot page
- Old ?page= URLs still work (backward compat)
- Added 404.html SPA fallback for GitHub Pages
- Added sessionStorage redirect restore in index.html
- Sidebar nav links use real paths for accessibility
- Other state (groupBy, tab, filters) stays as query params
diff --git a/index.html b/index.html
@@ -97,6 +97,17 @@
         -moz-osx-font-smoothing: grayscale;
       }
     </style>
+
+    <!-- SPA redirect restore: GitHub Pages 404.html saves the original path -->
+    <script>
+      (function() {
+        var redirect = sessionStorage.getItem('spa-redirect');
+        if (redirect) {
+          sessionStorage.removeItem('spa-redirect');
+          history.replaceState(null, '', redirect);
+        }
+      })();
+    </script>
   </head>
   <body>
     <noscript>
diff --git a/public/404.html b/public/404.html
@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Redirecting...</title>
+    <script>
+      // GitHub Pages SPA fallback: save the path so index.html can restore it
+      sessionStorage.setItem('spa-redirect', window.location.pathname + window.location.search + window.location.hash);
+      // Redirect to the app root — BASE_PATH is injected at build time, but since
+      // this is a static file we derive it from the repo path (first two segments)
+      var segments = window.location.pathname.split('/');
+      var base = '/' + (segments[1] || '') + '/';
+      window.location.replace(base);
+    </script>
+  </head>
+  <body>
+    <p>Redirecting&hellip;</p>
+  </body>
+</html>
diff --git a/src/components/InsightsSidebar.tsx b/src/components/InsightsSidebar.tsx
@@ -32,6 +32,7 @@ import {
   PAGE_TYPES,
   type PageType,
 } from '../lib/report-schema';
+import { buildPathForPage } from '../lib/url-state';
 import type { ParsedReport, UsageReportRow } from '../lib/types';
 import { parseCSV } from '../lib/csv-parser';
 import { useReport } from '../context/useReport';
@@ -138,7 +139,7 @@ export function InsightsSidebar({
           return (
             <NavList.Item
               key={id}
-              href="#"
+              href={buildPathForPage(id)}
               aria-current={activePage === id && !activeProductFilter ? 'page' : undefined}
               defaultOpen={isUsagePage && activePage === PAGE_TYPES.USAGE}
               onClick={(event) => {
@@ -229,7 +230,7 @@ export function InsightsSidebar({
         {UTILITY_NAV_PAGES.map(({ id, label, icon: Icon }) => (
           <NavList.Item
             key={id}
-            href="#"
+            href={buildPathForPage(id)}
             aria-current={activePage === id ? 'page' : undefined}
             onClick={(event) => {
               event.preventDefault();
diff --git a/src/lib/url-state.ts b/src/lib/url-state.ts
@@ -1,4 +1,4 @@
-/** Read/write filter state to URL search params */
+/** Read/write filter state to URL search params + path-based page routing */
 
 export interface URLFilterState {
   page?: string;
@@ -11,13 +11,38 @@ export interface URLFilterState {
   filters?: Record<string, string[]>;
 }
 
-/** Parse filter state from current URL search params */
+const BASE_PATH = import.meta.env.BASE_URL || '/';
+const DEFAULT_PAGE = 'copilot';
+
+/** Extract the page segment from the pathname (after the base path) */
+function getPageFromPath(): string | undefined {
+  const path = window.location.pathname;
+  const afterBase = path.startsWith(BASE_PATH)
+    ? path.slice(BASE_PATH.length)
+    : path.slice(1);
+  const segment = afterBase.replace(/\/$/, '');
+  return segment || undefined;
+}
+
+/** Build the pathname for a given page */
+export function buildPathForPage(page: string | undefined): string {
+  if (!page || page === DEFAULT_PAGE) return BASE_PATH;
+  return `${BASE_PATH}${page}`;
+}
+
+/** Parse filter state from current URL path + search params */
 export function readURLFilterState(): URLFilterState {
   const params = new URLSearchParams(window.location.search);
   const state: URLFilterState = {};
 
-  const page = params.get('page');
-  if (page) state.page = page;
+  // Read page from path first, fall back to ?page= for backward compat
+  const pathPage = getPageFromPath();
+  const queryPage = params.get('page');
+  if (pathPage) {
+    state.page = pathPage;
+  } else if (queryPage) {
+    state.page = queryPage;
+  }
 
   const groupBy = params.get('groupBy');
   if (groupBy) state.groupBy = groupBy;
@@ -51,15 +76,16 @@ export function readURLFilterState(): URLFilterState {
   return state;
 }
 
-/** Write filter state to URL search params without triggering navigation.
- *  Merges with existing params so multiple callers don't clobber each other. */
+/** Write filter state to URL path + search params without triggering navigation.
+ *  Page goes in the path, everything else in query params. */
 export function writeURLFilterState(state: URLFilterState): void {
-  // Start from current URL params to preserve values set by other callers
   const params = new URLSearchParams(window.location.search);
 
-  // Scalar params: set if provided, use defaults to omit default values
+  // Remove legacy ?page= param if present
+  params.delete('page');
+
+  // Scalar params (excluding page, which goes in the path)
   const SCALAR_DEFAULTS: Record<string, string> = {
-    page: 'copilot',
     groupBy: 'username',
     timeBucket: 'daily',
     period: 'all',
@@ -101,7 +127,8 @@ export function writeURLFilterState(state: URLFilterState): void {
   }
 
   const search = params.toString();
-  const newURL = search ? `${window.location.pathname}?${search}` : window.location.pathname;
+  const pagePath = buildPathForPage(state.page);
+  const newURL = search ? `${pagePath}?${search}` : pagePath;
 
   window.history.replaceState(null, '', newURL);
 }
