Persist fight state and stabilize tests

Author: kabaka

README.md

@@ -58,6 +58,7 @@ Vitest (unit tests) and Playwright (e2e tests) validate that core sections rende
 - **Categorized attack logging with undo/redo:** Nail strikes, spell casts, and advanced techniques each expose context-aware damage values that respect build modifiers like Unbreakable Strength or Shaman Stone, while new undo/redo controls make correcting mistakes effortless.
 - **Keyboard shortcuts and finishing guidance:** Each attack button surfaces the remaining hits required to reach zero HP if you relied solely on that move, and keyboard shortcuts (number row followed by QWERTY order) allow spectators to log attacks or press <kbd>Esc</kbd> for a quick reset without leaving the action.
 - **Live combat analytics:** Remaining HP, DPS, average damage, and actions per minute update instantly as attacks are logged, giving immediate feedback on fight pacing.
+- **Automatic session persistence:** Build selections, logged attacks, and boss progress are stored locally so the tracker survives accidental refreshes or browser restarts.
 
 Automated workflows in `.github/workflows/` run linting, unit tests, end-to-end tests, and GitHub Pages deployments on every push.
 

src/app/App.test.tsx

@@ -21,7 +21,7 @@ describe('App', () => {
     render(<App />);
 
     expect(
-      screen.getByText(/hollow knight damage tracker/i, { selector: 'p' }),
+      screen.getByRole('heading', { name: /hollow knight damage tracker/i, level: 1 }),
     ).toBeInTheDocument();
     expect(screen.getByText(/plan your build/i)).toBeVisible();
   });

src/app/App.tsx

@@ -32,7 +32,7 @@ export const App: FC = () => {
     <FightStateProvider>
       <PageLayout sections={SECTIONS}>
         <div>
-          <p className="page__title">Hollow Knight Damage Tracker</p>
+          <h1 className="page__title">Hollow Knight Damage Tracker</h1>
           <p className="page__subtitle">
             Plan your build, record every strike, and monitor fight-ending damage stats in
             real time. This prototype now tracks damage totals with configurable builds

src/features/attack-log/AttackLogPanel.test.tsx

@@ -7,6 +7,14 @@ import { CombatStatsPanel } from '../combat-stats/CombatStatsPanel';
 import { renderWithFightProvider } from '../../test-utils/renderWithFightProvider';
 
 describe('AttackLogPanel', () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+  });
+
   it('updates nail damage when upgrading the nail and activating strength charms', async () => {
     const user = userEvent.setup();
 

src/features/build-config/BuildConfigPanel.test.tsx

@@ -6,6 +6,14 @@ import { CombatStatsPanel } from '../combat-stats/CombatStatsPanel';
 import { renderWithFightProvider } from '../../test-utils/renderWithFightProvider';
 
 describe('BuildConfigPanel', () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+  });
+
   it('allows selecting a custom boss target and updates stats', async () => {
     const user = userEvent.setup();
 

src/features/fight-state/FightStateContext.test.tsx

@@ -0,0 +1,113 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { CUSTOM_BOSS_ID, FightStateProvider, useFightState } from './FightStateContext';
+
+const STORAGE_KEY = 'hollow-knight-damage-tracker:fight-state';
+
+describe('FightStateProvider persistence', () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+  });
+
+  it('hydrates state from localStorage when data is available', () => {
+    const persistedState = {
+      version: 1,
+      state: {
+        selectedBossId: CUSTOM_BOSS_ID,
+        customTargetHp: 3333.7,
+        build: {
+          nailUpgradeId: 'pure-nail',
+          activeCharmIds: ['shaman-stone', 'quick-slash'],
+          spellLevels: {
+            'vengeful-spirit': 'upgrade',
+          },
+        },
+        damageLog: [
+          {
+            id: 'spell-vengeful-1',
+            label: 'Vengeful Spirit',
+            damage: 45,
+            category: 'spell',
+            timestamp: 1700000000000,
+            soulCost: 33,
+          },
+        ],
+        redoStack: [],
+      },
+    } satisfies Record<string, unknown>;
+
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(persistedState));
+
+    const Consumer = () => {
+      const { state } = useFightState();
+      return (
+        <div>
+          <span data-testid="selected-boss">{state.selectedBossId}</span>
+          <span data-testid="custom-hp">{state.customTargetHp}</span>
+          <span data-testid="nail-upgrade">{state.build.nailUpgradeId}</span>
+          <span data-testid="charms">{state.build.activeCharmIds.join(',')}</span>
+          <span data-testid="spell-level">
+            {state.build.spellLevels['vengeful-spirit']}
+          </span>
+          <span data-testid="logged-attacks">{state.damageLog.length}</span>
+        </div>
+      );
+    };
+
+    render(
+      <FightStateProvider>
+        <Consumer />
+      </FightStateProvider>,
+    );
+
+    expect(screen.getByTestId('selected-boss').textContent).toBe(CUSTOM_BOSS_ID);
+    expect(screen.getByTestId('custom-hp').textContent).toBe('3334');
+    expect(screen.getByTestId('nail-upgrade').textContent).toBe('pure-nail');
+    expect(screen.getByTestId('charms').textContent).toBe('shaman-stone,quick-slash');
+    expect(screen.getByTestId('spell-level').textContent).toBe('upgrade');
+    expect(screen.getByTestId('logged-attacks').textContent).toBe('1');
+  });
+
+  it('persists updates to localStorage whenever state changes', async () => {
+    const user = userEvent.setup();
+
+    const Consumer = () => {
+      const { actions, state } = useFightState();
+      return (
+        <button type="button" onClick={() => actions.setCustomTargetHp(4321)}>
+          {state.customTargetHp}
+        </button>
+      );
+    };
+
+    render(
+      <FightStateProvider>
+        <Consumer />
+      </FightStateProvider>,
+    );
+
+    await user.click(screen.getByRole('button'));
+
+    await waitFor(() => {
+      const stored = window.localStorage.getItem(STORAGE_KEY);
+      expect(stored).not.toBeNull();
+      if (!stored) {
+        throw new Error('Expected persisted fight state');
+      }
+
+      const parsed = JSON.parse(stored) as {
+        version: number;
+        state: { selectedBossId: string; customTargetHp: number };
+      };
+      expect(parsed.version).toBe(1);
+      expect(parsed.state.selectedBossId).toBe(CUSTOM_BOSS_ID);
+      expect(parsed.state.customTargetHp).toBe(4321);
+    });
+  });
+});

src/features/fight-state/FightStateContext.tsx

@@ -1,5 +1,5 @@
 import type { FC, PropsWithChildren } from 'react';
-import { createContext, useContext, useMemo, useReducer } from 'react';
+import { createContext, useContext, useEffect, useMemo, useReducer } from 'react';
 
 import {
   DEFAULT_BOSS_ID,
@@ -10,6 +10,110 @@ import {
   strengthCharmIds,
 } from '../../data';
 
+const STORAGE_KEY = 'hollow-knight-damage-tracker:fight-state';
+const STORAGE_VERSION = 1;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const toFiniteNumber = (value: unknown): number | null => {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+
+  return null;
+};
+
+const sanitizePositiveInteger = (value: unknown, fallback: number): number => {
+  const numeric = toFiniteNumber(value);
+  if (numeric === null) {
+    return fallback;
+  }
+  return Math.max(1, Math.round(numeric));
+};
+
+const sanitizeStringArray = (value: unknown, fallback: string[]): string[] => {
+  if (!Array.isArray(value)) {
+    return [...fallback];
+  }
+
+  const seen = new Set<string>();
+  const sanitized: string[] = [];
+  for (const item of value) {
+    if (typeof item === 'string' && !seen.has(item)) {
+      seen.add(item);
+      sanitized.push(item);
+    }
+  }
+
+  return sanitized;
+};
+
+const sanitizeSpellLevels = (
+  value: unknown,
+  fallback: Record<string, SpellLevel>,
+): Record<string, SpellLevel> => {
+  if (!isRecord(value)) {
+    return { ...fallback };
+  }
+
+  const sanitized: Record<string, SpellLevel> = { ...fallback };
+  for (const [spellId, level] of Object.entries(value)) {
+    if (level === 'base' || level === 'upgrade') {
+      sanitized[spellId] = level;
+    }
+  }
+
+  return sanitized;
+};
+
+const sanitizeAttackEvents = (value: unknown, fallback: AttackEvent[]): AttackEvent[] => {
+  if (!Array.isArray(value)) {
+    return [...fallback];
+  }
+
+  const events: AttackEvent[] = [];
+  for (const item of value) {
+    if (!isRecord(item)) {
+      continue;
+    }
+
+    const id = typeof item.id === 'string' ? item.id : null;
+    const label = typeof item.label === 'string' ? item.label : null;
+    const damage = toFiniteNumber(item.damage);
+    const timestamp = toFiniteNumber(item.timestamp);
+    const category = item.category;
+
+    if (!id || !label || damage === null || timestamp === null) {
+      continue;
+    }
+
+    if (category !== 'nail' && category !== 'spell' && category !== 'advanced') {
+      continue;
+    }
+
+    const rawSoulCost = item.soulCost;
+    const soulCost =
+      rawSoulCost === undefined ? undefined : (toFiniteNumber(rawSoulCost) ?? undefined);
+
+    events.push({
+      id,
+      label,
+      damage,
+      category,
+      timestamp,
+      soulCost,
+    });
+  }
+
+  return events;
+};
+
 export type AttackCategory = 'nail' | 'spell' | 'advanced';
 export type SpellLevel = 'base' | 'upgrade';
 
@@ -249,11 +353,106 @@ const ensureSpellLevels = (state: FightState): FightState => {
   };
 };
 
+const mergePersistedState = (
+  persisted: Record<string, unknown>,
+  fallback: FightState,
+): FightState => {
+  const selectedBossId =
+    typeof persisted.selectedBossId === 'string'
+      ? persisted.selectedBossId
+      : fallback.selectedBossId;
+  const customTargetHp = sanitizePositiveInteger(
+    persisted.customTargetHp,
+    fallback.customTargetHp,
+  );
+
+  const persistedBuild = isRecord(persisted.build) ? persisted.build : {};
+  const nailUpgradeId =
+    typeof persistedBuild.nailUpgradeId === 'string'
+      ? persistedBuild.nailUpgradeId
+      : fallback.build.nailUpgradeId;
+  const activeCharmIds = sanitizeStringArray(
+    persistedBuild.activeCharmIds,
+    fallback.build.activeCharmIds,
+  );
+  const spellLevels = sanitizeSpellLevels(
+    persistedBuild.spellLevels,
+    fallback.build.spellLevels,
+  );
+
+  const damageLog = sanitizeAttackEvents(persisted.damageLog, fallback.damageLog);
+  const redoStack = sanitizeAttackEvents(persisted.redoStack, fallback.redoStack);
+
+  return ensureSpellLevels({
+    selectedBossId,
+    customTargetHp,
+    build: {
+      nailUpgradeId,
+      activeCharmIds,
+      spellLevels,
+    },
+    damageLog,
+    redoStack,
+  });
+};
+
+const restorePersistedState = (fallback: FightState): FightState => {
+  if (typeof window === 'undefined') {
+    return fallback;
+  }
+
+  try {
+    const serialized = window.localStorage.getItem(STORAGE_KEY);
+    if (!serialized) {
+      return fallback;
+    }
+
+    const parsed = JSON.parse(serialized);
+    if (!isRecord(parsed)) {
+      return fallback;
+    }
+
+    const { version, state } = parsed as {
+      version?: unknown;
+      state?: unknown;
+    };
+
+    if (typeof version !== 'number' || version !== STORAGE_VERSION) {
+      return fallback;
+    }
+
+    if (!isRecord(state)) {
+      return fallback;
+    }
+
+    return mergePersistedState(state, fallback);
+  } catch {
+    return fallback;
+  }
+};
+
+const persistStateToStorage = (state: FightState) => {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  try {
+    const payload = JSON.stringify({ version: STORAGE_VERSION, state });
+    window.localStorage.setItem(STORAGE_KEY, payload);
+  } catch {
+    // Silently ignore storage errors so the tracker keeps functioning.
+  }
+};
+
 export const FightStateProvider: FC<PropsWithChildren> = ({ children }) => {
   const [state, dispatch] = useReducer(fightReducer, undefined, () =>
-    ensureSpellLevels(createInitialState()),
+    restorePersistedState(ensureSpellLevels(createInitialState())),
   );
 
+  useEffect(() => {
+    persistStateToStorage(state);
+  }, [state]);
+
   const derived = useMemo(() => calculateDerivedStats(state), [state]);
 
   const actions = useMemo<FightContextValue['actions']>(