feat(preferences): introduce mod preset persistence using localStorage

closes #109

- Add support for saving and clearing default mod presets.
- Persist default mods via `preferences.svelte.ts` and inject into bare URLs during bootstrap.
- Update tests to cover mod persistence behavior.
- Document the feature with ADR-008: Mod Preset Persistence.

Author: ushkinaz

docs/adr/ADR-008_mod_preset_persistence.md

@@ -0,0 +1,10 @@
+# ADR-008: Mod Preset Persistence
+
+- **Status:** Accepted
+- **Context:** Users repeatedly configure the same modset. The URL is the source of truth (ADR-002), but bare URLs have no mods.
+- **Decision:** `localStorage` stores a default mod preset under `cbn-guide:default-mods`. On bootstrap, bare URLs (no `mods` param) get the saved preset injected via `replaceState`. Applying mods in the ModSelector automatically saves them. Saving an empty modset clears the preset.
+- **Consequences:**
+  - Positive: users configure once, bare URLs auto-load their preset.
+  - Negative: `localStorage` adds a persistence dependency; clearing browser data loses the preset.
+  - Neutral: shared URLs with explicit `?mods=` are unaffected.
+- **References:** `src/preferences.svelte.ts`, `src/navigation.svelte.ts`, ADR-002.

docs/adr/README.md

@@ -20,3 +20,4 @@ An Architecture Decision Record captures an important architectural decision mad
 - [ADR-005](ADR-005_data_inheritance.md) - Robust Inheritance: Migrations and Self-Copy Handling
 - [ADR-006](ADR-006_layered_navigation_bootstrap_and_page_metadata.md) - Layered Navigation Bootstrap and Page Metadata
 - [ADR-007](ADR-007_data_loading_orchestration.md) - Data Loading Orchestration, Fetch Boundary, and Retry Removal
+- [ADR-008](ADR-008_mod_preset_persistence.md) - Mod Preset Persistence

docs/routing.md

@@ -99,7 +99,7 @@ That separation matters because the app should preserve what the user is actuall
 | State kind                   | Owner                                                       | Lifetime             | Notes                                                                                       |
 | :--------------------------- | :---------------------------------------------------------- | :------------------- | :------------------------------------------------------------------------------------------ |
 | Raw route state              | [`src/routing.svelte.ts`](../src/routing.svelte.ts)         | Browser session      | Mirrors the current URL and history entry.                                                  |
-| Persisted preference state   | [`src/preferences.svelte.ts`](../src/preferences.svelte.ts) | Across sessions      | Currently stores the preferred tileset only.                                                |
+| Persisted preference state   | [`src/preferences.svelte.ts`](../src/preferences.svelte.ts) | Across sessions      | Stores the preferred tileset and an optional default mod preset.                            |
 | Bootstrap metadata           | [`src/builds.svelte.ts`](../src/builds.svelte.ts)           | Per page load        | Resolves aliases like `stable` and `nightly` into concrete builds.                          |
 | Effective navigation context | [`src/navigation.svelte.ts`](../src/navigation.svelte.ts)   | Derived at read time | Combines route state, preferences, and build metadata into the values the UI actually uses. |
 
@@ -232,7 +232,7 @@ Choose the navigation transport by intent:
 
 - Version aliases depend on build metadata. Until that metadata is available, the app only knows the requested version, not the resolved concrete build.
 - Malformed version URLs are canonicalized after build metadata loads, so invalid or missing version segments do not surface as user-facing bootstrap failures.
-- The app does not persist locale or mods as browser preferences.
+- The app does not persist locale as a browser preference. Mods can be persisted as a default preset via `preferences.svelte.ts`.
 - The route layer is browser-oriented state, so server-side initialization uses a safe placeholder URL.
 - History synchronization is global, so the routing module installs exactly one popstate listener.
 

src/navigation.svelte.ts

@@ -2,6 +2,7 @@ import { resolveTileset } from "./tile-data";
 import {
   initializePreferences,
   preferences,
+  setDefaultMods,
   setPreferredTileset,
 } from "./preferences.svelte";
 import {
@@ -146,6 +147,7 @@ export function changeVersion(buildVersion: string): void {
 }
 
 export function changeMods(mods: string[]): void {
+  setDefaultMods(mods);
   location.href = buildURL(
     navigation.buildRequestedVersion,
     navigation.target,
@@ -165,6 +167,22 @@ 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 = canonicalizeMalformedVersionURL(

src/navigation.test.ts

@@ -48,6 +48,7 @@ describe("navigation", () => {
     _resetPreferences();
     _resetBuildsState();
     localStorage.removeItem?.("cbn-guide:tileset");
+    localStorage.removeItem?.("cbn-guide:default-mods");
     global.fetch = defaultFetchMock;
   });
 
@@ -87,6 +88,7 @@ describe("navigation", () => {
     });
     expect(preferences).toEqual({
       preferredTileset: "retrodays",
+      defaultMods: null,
     });
     expect(buildLinkTo({ kind: "home" })).toBe("/stable/?t=ultica");
   });
@@ -190,6 +192,7 @@ describe("navigation", () => {
     expect(navigation.tileset).toBe("retrodays");
     expect(preferences).toEqual({
       preferredTileset: "retrodays",
+      defaultMods: null,
     });
     expect(window.location.search).toContain("t=retrodays");
     expect(replaceStateSpy).toHaveBeenCalledOnce();
@@ -225,4 +228,65 @@ describe("navigation", () => {
       target: { kind: "item", type: "item", id: "rock" },
     });
   });
+
+  test("bootstrap injects saved mods into bare URL", async () => {
+    localStorage.setItem(
+      "cbn-guide:default-mods",
+      JSON.stringify(["aftershock"]),
+    );
+    setWindowLocation("stable/");
+    _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).toHaveBeenCalledWith(
+      null,
+      "",
+      "/stable/?mods=aftershock",
+    );
+    expect(page.route.modsParam).toEqual(["aftershock"]);
+  });
+
+  test("bootstrap does not inject when URL already has mods", async () => {
+    localStorage.setItem(
+      "cbn-guide:default-mods",
+      JSON.stringify(["magiclysm"]),
+    );
+    setWindowLocation("stable/", "?mods=aftershock");
+    _resetRouting();
+    const replaceStateSpy = vi.spyOn(history, "replaceState");
+
+    await bootstrapApplication();
+
+    expect(replaceStateSpy).not.toHaveBeenCalledWith(
+      null,
+      "",
+      expect.stringContaining("magiclysm"),
+    );
+    expect(page.route.modsParam).toEqual(["aftershock"]);
+  });
+
+  test("bootstrap does not inject when no preset saved", async () => {
+    localStorage.removeItem("cbn-guide:default-mods");
+    setWindowLocation("stable/");
+    _resetRouting();
+    const replaceStateSpy = vi.spyOn(history, "replaceState");
+
+    await bootstrapApplication();
+
+    expect(replaceStateSpy).not.toHaveBeenCalledWith(
+      null,
+      "",
+      expect.stringContaining("mods="),
+    );
+    expect(page.route.modsParam).toEqual([]);
+  });
 });

src/preferences.svelte.test.ts

@@ -5,12 +5,15 @@
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import {
   _resetPreferences,
+  clearSavedDefaultMods,
   initializePreferences,
   preferences,
+  setDefaultMods,
   setPreferredTileset,
 } from "./preferences.svelte";
 
 const STORAGE_KEY = "cbn-guide:tileset";
+const DEFAULT_MODS_STORAGE_KEY = "cbn-guide:default-mods";
 const DEFAULT_TILESET = "undead_people";
 
 function installMockStorage() {
@@ -46,19 +49,21 @@ describe("preferences", () => {
   });
 
   afterEach(() => {
+    vi.restoreAllMocks();
     localStorage.removeItem?.(STORAGE_KEY);
     _resetPreferences();
-    vi.restoreAllMocks();
   });
 
   test("loads the persisted tileset preference when the route omits it", () => {
     localStorage.setItem(STORAGE_KEY, "retrodays");
 
     expect(initializePreferences()).toEqual({
       preferredTileset: "retrodays",
+      defaultMods: null,
     });
     expect(preferences).toEqual({
       preferredTileset: "retrodays",
+      defaultMods: null,
     });
   });
 
@@ -67,6 +72,7 @@ describe("preferences", () => {
 
     expect(initializePreferences()).toEqual({
       preferredTileset: DEFAULT_TILESET,
+      defaultMods: null,
     });
     expect(localStorage.getItem(STORAGE_KEY)).toBe(DEFAULT_TILESET);
   });
@@ -75,6 +81,7 @@ describe("preferences", () => {
     expect(setPreferredTileset("bad-input")).toBe(false);
     expect(preferences).toEqual({
       preferredTileset: DEFAULT_TILESET,
+      defaultMods: null,
     });
     expect(localStorage.getItem(STORAGE_KEY)).toBeNull();
   });
@@ -89,11 +96,113 @@ describe("preferences", () => {
 
     expect(initializePreferences()).toEqual({
       preferredTileset: DEFAULT_TILESET,
+      defaultMods: null,
     });
 
     expect(() => setPreferredTileset("retrodays")).not.toThrow();
     expect(preferences).toEqual({
       preferredTileset: "retrodays",
+      defaultMods: null,
+    });
+  });
+});
+
+describe("defaultMods", () => {
+  beforeEach(() => {
+    installMockStorage();
+    localStorage.removeItem?.(DEFAULT_MODS_STORAGE_KEY);
+    _resetPreferences();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    localStorage.removeItem?.(DEFAULT_MODS_STORAGE_KEY);
+    _resetPreferences();
+  });
+
+  test("loads saved modset from localStorage", () => {
+    localStorage.setItem(
+      DEFAULT_MODS_STORAGE_KEY,
+      JSON.stringify(["aftershock", "magiclysm"]),
+    );
+
+    expect(initializePreferences().defaultMods).toEqual([
+      "aftershock",
+      "magiclysm",
+    ]);
+    expect(preferences.defaultMods).toEqual(["aftershock", "magiclysm"]);
+  });
+
+  test("returns null when no key exists", () => {
+    expect(initializePreferences().defaultMods).toBeNull();
+    expect(preferences.defaultMods).toBeNull();
+  });
+
+  test("discards malformed JSON gracefully", () => {
+    localStorage.setItem(DEFAULT_MODS_STORAGE_KEY, "{ bad json }");
+
+    expect(initializePreferences().defaultMods).toBeNull();
+    expect(preferences.defaultMods).toBeNull();
+  });
+
+  test("discards non-array JSON gracefully", () => {
+    localStorage.setItem(
+      DEFAULT_MODS_STORAGE_KEY,
+      JSON.stringify({ mods: ["aftershock"] }),
+    );
+
+    expect(initializePreferences().defaultMods).toBeNull();
+    expect(preferences.defaultMods).toBeNull();
+  });
+
+  test("setDefaultMods persists and updates state", () => {
+    setDefaultMods(["aftershock"]);
+
+    expect(preferences.defaultMods).toEqual(["aftershock"]);
+    expect(localStorage.getItem(DEFAULT_MODS_STORAGE_KEY)).toBe(
+      JSON.stringify(["aftershock"]),
+    );
+  });
+
+  test("setDefaultMods([]) clears the preset", () => {
+    localStorage.setItem(
+      DEFAULT_MODS_STORAGE_KEY,
+      JSON.stringify(["aftershock"]),
+    );
+    setDefaultMods([]);
+
+    expect(preferences.defaultMods).toBeNull();
+    expect(localStorage.getItem(DEFAULT_MODS_STORAGE_KEY)).toBeNull();
+  });
+
+  test("clearSavedDefaultMods removes key and state", () => {
+    localStorage.setItem(
+      DEFAULT_MODS_STORAGE_KEY,
+      JSON.stringify(["aftershock"]),
+    );
+    clearSavedDefaultMods();
+
+    expect(preferences.defaultMods).toBeNull();
+    expect(localStorage.getItem(DEFAULT_MODS_STORAGE_KEY)).toBeNull();
+  });
+
+  test("swallows storage failures silently", () => {
+    vi.spyOn(localStorage, "getItem").mockImplementation(() => {
+      throw new Error("storage denied");
+    });
+    vi.spyOn(localStorage, "setItem").mockImplementation(() => {
+      throw new Error("storage denied");
     });
+    vi.spyOn(localStorage, "removeItem").mockImplementation(() => {
+      throw new Error("storage denied");
+    });
+
+    expect(initializePreferences().defaultMods).toBeNull();
+
+    expect(() => setDefaultMods(["aftershock"])).not.toThrow();
+    expect(preferences.defaultMods).toEqual(["aftershock"]);
+
+    expect(() => clearSavedDefaultMods()).not.toThrow();
+    expect(preferences.defaultMods).toBeNull();
   });
 });