refactor(navigation): replace URL canonicalization with version path resolution

ushkinaz · ushkinaz · commit c1286ad276eb · 2026-04-07T03:24:50.000+04:00
- Introduce `resolveVersionedPath` for handling versioned routes.
- Simplify bootstrap navigation logic to include preferences.
- Remove outdated `canonicalizeMalformedVersionURL` method.
- Update tests to reflect the new routing approach.
diff --git a/src/navigation.svelte.ts b/src/navigation.svelte.ts
@@ -7,20 +7,22 @@ import {
 } from "./preferences.svelte";
 import {
   buildURL,
-  canonicalizeMalformedVersionURL,
   initializeRouting,
   navigateToURL,
   page,
   replaceURLDebounced,
+  resolveVersionedPath,
   type RouteTarget,
 } from "./routing.svelte";
 import {
   buildsState,
+  type BuildsState,
   initializeBuildsState,
   resolveBuildVersion,
 } from "./builds.svelte";
 import { initializeUILocale } from "./i18n/ui-locale";
 import { DEFAULT_LOCALE } from "./constants";
+import { BASE_URL } from "./utils/env";
 
 type NavigationContext = {
   url: URL;
@@ -157,6 +159,69 @@ export function changeMods(mods: string[]): void {
   );
 }
 
+function stripBaseFromPathname(pathname: string): string {
+  const baseNoSlash = BASE_URL.endsWith("/") ? BASE_URL.slice(0, -1) : BASE_URL;
+
+  if (pathname === baseNoSlash) return "/";
+  if (pathname.startsWith(BASE_URL)) return pathname.slice(BASE_URL.length - 1);
+  if (pathname.startsWith(baseNoSlash + "/"))
+    return pathname.slice(baseNoSlash.length);
+  return pathname;
+}
+
+function hasVersionlessHomePath(pathname: string): boolean {
+  const path = stripBaseFromPathname(pathname);
+  const cleanPath = path.startsWith("/") ? path.slice(1) : path;
+  return cleanPath.length === 0;
+}
+
+function buildCanonicalBootstrapURL(
+  urlInput: string,
+  builds: BuildsState,
+): string {
+  const currentURL = new URL(urlInput, location.origin);
+
+  const canonicalPath = resolveVersionedPath(currentURL.pathname, builds);
+
+  const canonicalMods =
+    page.route.modsParam.length > 0
+      ? page.route.modsParam
+      : (preferences.defaultMods ?? []);
+
+  const canonicalLocale = page.route.localeParam;
+
+  const canonicalTileset = resolveTileset(
+    preferences.preferredTileset,
+    page.route.tilesetParam,
+  );
+
+  const builtCanonicalURL = new URL(
+    buildURL(
+      canonicalPath.versionSlug,
+      canonicalPath.target,
+      canonicalLocale,
+      canonicalTileset,
+      canonicalMods,
+    ),
+    location.origin,
+  );
+
+  // Preserve the root home route shape while still normalizing query-backed context.
+  if (
+    hasVersionlessHomePath(currentURL.pathname) &&
+    canonicalPath.target.kind === "home"
+  ) {
+    builtCanonicalURL.pathname = currentURL.pathname;
+  }
+
+  builtCanonicalURL.hash = currentURL.hash;
+  return (
+    builtCanonicalURL.pathname +
+    builtCanonicalURL.search +
+    builtCanonicalURL.hash
+  );
+}
+
 /**
  * Initializes the navigation prerequisites before the app shell mounts.
  *
@@ -167,29 +232,11 @@ export function changeMods(mods: string[]): void {
 export async function bootstrapApplication(): Promise<void> {
   initializeRouting();
   initializePreferences();
-
-  if (
-    page.route.modsParam.length === 0 &&
-    preferences.defaultMods !== null &&
-    preferences.defaultMods.length > 0
-  ) {
-    const urlWithMods = buildURL(
-      page.route.versionSlug,
-      page.route.target,
-      page.route.localeParam,
-      page.route.tilesetParam,
-      preferences.defaultMods,
-    );
-    navigateToURL(urlWithMods, "replace");
-  }
-
   const versionState = await initializeBuildsState();
+  const canonicalURL = buildCanonicalBootstrapURL(location.href, versionState);
+  const currentURL = location.pathname + location.search + location.hash;
 
-  const canonicalURL = canonicalizeMalformedVersionURL(
-    location.href,
-    versionState,
-  );
-  if (canonicalURL) {
+  if (canonicalURL !== currentURL) {
     navigateToURL(canonicalURL, "replace");
   }
 
diff --git a/src/navigation.test.ts b/src/navigation.test.ts
@@ -289,4 +289,37 @@ describe("navigation", () => {
     );
     expect(page.route.modsParam).toEqual([]);
   });
+
+  test("bootstrap canonicalizes version and saved preferences with one replaceState", async () => {
+    localStorage.setItem("cbn-guide:tileset", "retrodays");
+    localStorage.setItem(
+      "cbn-guide:default-mods",
+      JSON.stringify(["aftershock"]),
+    );
+    setWindowLocation("bogus/item/rock");
+    _resetRouting();
+    const replaceStateSpy = vi
+      .spyOn(history, "replaceState")
+      .mockImplementation((_, __, url) => {
+        const nextUrl = new URL(String(url), window.location.origin);
+        window.location.pathname = nextUrl.pathname;
+        window.location.search = nextUrl.search;
+        window.location.href = nextUrl.toString();
+      });
+
+    await bootstrapApplication();
+
+    expect(replaceStateSpy).toHaveBeenCalledOnce();
+    expect(replaceStateSpy).toHaveBeenCalledWith(
+      null,
+      "",
+      "/nightly/item/rock?t=retrodays&mods=aftershock",
+    );
+    expect(page.route).toMatchObject({
+      versionSlug: "nightly",
+      tilesetParam: "retrodays",
+      modsParam: ["aftershock"],
+      target: { kind: "item", type: "item", id: "rock" },
+    });
+  });
 });
diff --git a/src/routing.svelte.ts b/src/routing.svelte.ts
@@ -6,7 +6,6 @@
 
 import { BASE_URL } from "./utils/env";
 import {
-  buildsState,
   type BuildsState,
   NIGHTLY_VERSION,
   STABLE_VERSION,
@@ -40,7 +39,6 @@ type PageState = {
   url: URL;
   route: URLRoute;
 };
-
 // ============================================================================
 // Internal Helper Functions
 // ============================================================================
@@ -134,24 +132,6 @@ function isRouteHeadSegment(segment: string | undefined): boolean {
     segment === "search" || (segment !== undefined && isSupportedType(segment))
   );
 }
-
-function buildPathnameFromSegments(segments: string[]): string {
-  const basePath = BASE_URL.endsWith("/") ? BASE_URL : `${BASE_URL}/`;
-
-  if (segments.length === 0) {
-    return basePath;
-  }
-
-  const encodedPath = segments.map(encodeURIComponent).join("/");
-  return segments.length === 1
-    ? `${basePath}${encodedPath}/`
-    : `${basePath}${encodedPath}`;
-}
-
-function buildRelativeURL(url: URL, segments: string[]): string {
-  return buildPathnameFromSegments(segments) + url.search + url.hash;
-}
-
 /**
  * Canonicalize malformed version routes once build metadata is available.
  *
@@ -162,33 +142,39 @@ function buildRelativeURL(url: URL, segments: string[]): string {
  * The bare home route remains untouched, and any existing query string or hash
  * fragment is preserved in the returned URL.
  *
- * @param urlInput - Browser URL to inspect and potentially canonicalize
+ * @param pathname - Browser pathname to inspect and potentially canonicalize
  * @param builds - Loaded build metadata used to validate version slugs
  * @returns Canonical relative URL when a rewrite is needed, otherwise `null`
  */
-export function canonicalizeMalformedVersionURL(
-  urlInput: string,
+export function resolveVersionedPath(
+  pathname: string,
   builds: BuildsState,
-): string | null {
-  const url = new URL(urlInput, location.origin);
-  const segments = getPathSegmentsFromPath(url.pathname);
+): Pick<URLRoute, "versionSlug" | "target"> {
+  const segments = getPathSegmentsFromPath(pathname);
 
   if (segments.length === 0) {
-    return null;
+    return {
+      versionSlug: STABLE_VERSION,
+      target: { kind: "home" },
+    };
   }
 
   const [firstSegment, ...restSegments] = segments;
   if (tryResolveBuildVersion(firstSegment, builds) !== undefined) {
-    return null;
+    return {
+      versionSlug: firstSegment,
+      target: createRouteTarget(segments[1], segments[2]),
+    };
   }
 
   const rewrittenSegments = isRouteHeadSegment(firstSegment)
     ? [NIGHTLY_VERSION, ...segments]
     : [NIGHTLY_VERSION, ...restSegments];
-  const canonicalURL = buildRelativeURL(url, rewrittenSegments);
-  const currentURL = url.pathname + url.search + url.hash;
 
-  return canonicalURL === currentURL ? null : canonicalURL;
+  return {
+    versionSlug: NIGHTLY_VERSION,
+    target: createRouteTarget(rewrittenSegments[1], rewrittenSegments[2]),
+  };
 }
 
 const LOCALE_PARAM_NAME = "lang";
@@ -240,16 +226,6 @@ function ensurePopstateHandlerInstalled(): void {
   }
 
   popstateHandler = () => {
-    if (buildsState.current) {
-      const canonicalURL = canonicalizeMalformedVersionURL(
-        location.href,
-        buildsState.current,
-      );
-      if (canonicalURL) {
-        navigateToURL(canonicalURL, "replace");
-        return;
-      }
-    }
     updatePageState();
   };
 
diff --git a/src/routing.test.ts b/src/routing.test.ts
@@ -389,36 +389,4 @@ describe("App routing integration", () => {
       expectVisibleText(/rock/i);
     });
   });
-
-  test("canonicalizes malformed popstate version URLs with replaceState", async () => {
-    await renderApp();
-
-    await waitForDataLoad();
-    const replaceStateSpy = vi
-      .spyOn(history, "replaceState")
-      .mockImplementation((_, __, url) => {
-        const nextUrl = new URL(String(url), window.location.origin);
-        window.location.pathname = nextUrl.pathname;
-        window.location.search = nextUrl.search;
-        window.location.href = nextUrl.toString();
-      });
-
-    await act(async () => {
-      setWindowLocation("bogus/item/rock", "?mods=aftershock");
-      dispatchPopState();
-    });
-
-    await waitFor(() =>
-      expect(window.location.pathname).toBe("/nightly/item/rock"),
-    );
-    expect(replaceStateSpy).toHaveBeenCalledWith(
-      null,
-      "",
-      "/nightly/item/rock?mods=aftershock",
-    );
-    await waitFor(() => {
-      expectVisibleText(/rock/i);
-    });
-    replaceStateSpy.mockRestore();
-  });
 });
diff --git a/src/routing.url.test.ts b/src/routing.url.test.ts
@@ -15,11 +15,11 @@ import {
 import {
   _resetRouting,
   buildURL,
-  canonicalizeMalformedVersionURL,
   handleInternalNavigation,
   initializeRouting,
   page,
   parseRoute,
+  resolveVersionedPath,
 } from "./routing.svelte";
 import {
   createBuildsFetchMock,
@@ -242,33 +242,49 @@ describe("routing URL logic", () => {
   });
 
   describe("malformed version URL canonicalization", () => {
-    test.each([
-      ["http://localhost/monster/zombie", "/nightly/monster/zombie"],
-      ["http://localhost/item", "/nightly/item"],
-      ["http://localhost/search/rock", "/nightly/search/rock"],
-    ])("canonicalizes missing version route %s", async (input, expected) => {
+    test("resolves an intact versioned path without rewriting it", async () => {
       const state = await initializeBuildsState();
 
-      expect(canonicalizeMalformedVersionURL(input, state)).toBe(expected);
+      expect(resolveVersionedPath("/stable/item/rock", state)).toEqual({
+        versionSlug: "stable",
+        target: { kind: "item", type: "item", id: "rock" },
+      });
     });
 
-    test("canonicalizes invalid explicit versions and preserves query and hash", async () => {
+    test("resolves missing-version deep links by correcting only the path", async () => {
       const state = await initializeBuildsState();
 
-      expect(
-        canonicalizeMalformedVersionURL(
-          "http://localhost/bad/item/rock?lang=ru_RU&t=retrodays&mods=aftershock#lore",
-          state,
-        ),
-      ).toBe("/nightly/item/rock?lang=ru_RU&t=retrodays&mods=aftershock#lore");
+      expect(resolveVersionedPath("/monster/zombie", state)).toEqual({
+        versionSlug: "nightly",
+        target: { kind: "item", type: "monster", id: "zombie" },
+      });
+    });
+
+    test("resolves missing-version catalog links", async () => {
+      const state = await initializeBuildsState();
+
+      expect(resolveVersionedPath("/monster", state)).toEqual({
+        versionSlug: "nightly",
+        target: { kind: "catalog", type: "monster" },
+      });
+    });
+
+    test("resolves missing-version search links", async () => {
+      const state = await initializeBuildsState();
+
+      expect(resolveVersionedPath("/search/answer", state)).toEqual({
+        versionSlug: "nightly",
+        target: { kind: "search", query: "answer" },
+      });
     });
 
     test("keeps the bare home URL untouched", async () => {
       const state = await initializeBuildsState();
 
-      expect(
-        canonicalizeMalformedVersionURL("http://localhost/", state),
-      ).toBeNull();
+      expect(resolveVersionedPath("/", state)).toEqual({
+        versionSlug: "stable",
+        target: { kind: "home" },
+      });
     });
   });
 
