Frontend Architecture

export function useQuizState(dataset: Dataset) {
  const saved = useMemo(() => loadState(), []);
  const canPersist = saved?.consentGiven === true;

  const [screen, setScreen] = useState<QuizScreen>(
    canPersist && saved?.screen ? saved.screen : 'landing',
  );
  const [currentQuestion, setCurrentQuestion] = useState(
    canPersist && saved?.currentQuestion ? saved.currentQuestion : 0,
  );
  const [responses, setResponses] = useState<Responses>(
    canPersist && saved?.responses ? saved.responses : {},
  );
  const [consentGiven, setConsentGiven] = useState<boolean | null>(
    saved?.consentGiven ?? null,
  );
  
  // ... state management logic
}

return {
  screen,
  currentQuestion,
  currentItem,        // Current question item
  currentDomain,      // Current domain metadata
  responses,
  results,            // Computed results (null if incomplete)
  totalQuestions,     // 80
  answeredCount,      // Number of answered questions
  allAnswered,        // true if all 80 answered
  consentGiven,
  answer,             // (itemId, value) => void
  nextQuestion,       // () => void
  prevQuestion,       // () => void
  goToQuestion,       // (index) => void
  startQuiz,          // () => void
  finishQuiz,         // () => void
  retake,             // () => void
  deleteAllData,      // () => void
  giveConsent,        // (consent) => void
  goToScreen,         // (screen) => void
};

// Refs to avoid stale closures in callbacks
const screenRef = useRef(screen);
const questionRef = useRef(currentQuestion);
const responsesRef = useRef(responses);
const consentRef = useRef(consentGiven);

useEffect(() => { screenRef.current = screen; }, [screen]);
useEffect(() => { questionRef.current = currentQuestion; }, [currentQuestion]);
useEffect(() => { responsesRef.current = responses; }, [responses]);
useEffect(() => { consentRef.current = consentGiven; }, [consentGiven]);

const results: Results | null = useMemo(() => {
  const answered = Object.keys(responses).length;
  if (answered < totalQuestions) return null;
  return computeResults(responses, dataset);
}, [responses, totalQuestions, dataset]);

export function useDarkMode() {
  const prefersDark =
    typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches;

  const [isDark, setIsDark] = useLocalStorage('vibe-check-dark-mode', prefersDark);

  useEffect(() => {
    document.documentElement.classList.toggle('dark', isDark);
  }, [isDark]);

  const toggle = useCallback(() => {
    setIsDark((prev: boolean) => !prev);
  }, [setIsDark]);

  return { isDark, toggle };
}

export function useLocalStorage<T>(key: string, initialValue: T) {
  const [storedValue, setStoredValue] = useState<T>(() => {
    try {
      const item = window.localStorage.getItem(key);
      return item ? (JSON.parse(item) as T) : initialValue;
    } catch {
      return initialValue;
    }
  });

  const setValue = useCallback(
    (value: T | ((val: T) => T)) => {
      const valueToStore = value instanceof Function ? value(storedValue) : value;
      setStoredValue(valueToStore);
      try {
        window.localStorage.setItem(key, JSON.stringify(valueToStore));
      } catch {
        // localStorage full or unavailable
      }
    },
    [key, storedValue],
  );

  const removeValue = useCallback(() => {
    setStoredValue(initialValue);
    try {
      window.localStorage.removeItem(key);
    } catch {
      // ignore
    }
  }, [key, initialValue]);

  return [storedValue, setValue, removeValue] as const;
}

function App() {
  const { isDark, toggle: toggleDark } = useDarkMode();
  const quiz = useQuizState(typedDataset);

  return (
    <div className="min-h-screen bg-surface-light dark:bg-surface-dark text-text-light dark:text-text-dark transition-colors duration-300">
      <a href="#main-content" className="sr-only focus:not-sr-only ...">
        Skip to main content
      </a>

      <DarkModeToggle isDark={isDark} onToggle={toggleDark} />

      <main id="main-content">
        {quiz.screen === 'landing' && (
          <Landing onStart={quiz.startQuiz} />
        )}

        {quiz.screen === 'quiz' && quiz.currentItem && (
          <Quiz
            items={typedDataset.items}
            currentQuestion={quiz.currentQuestion}
            responses={quiz.responses}
            totalQuestions={quiz.totalQuestions}
            currentItem={quiz.currentItem}
            onAnswer={quiz.answer}
            onNext={quiz.nextQuestion}
            onPrev={quiz.prevQuestion}
            onFinish={quiz.finishQuiz}
            onHome={() => quiz.goToScreen('landing')}
            allAnswered={quiz.allAnswered}
          />
        )}

        {quiz.screen === 'results' && quiz.results && (
          <Results
            results={quiz.results}
            responses={quiz.responses}
            dataset={typedDataset}
            onRetake={quiz.retake}
            onDelete={quiz.deleteAllData}
            onPrint={() => quiz.goToScreen('print')}
          />
        />
        )}

        {quiz.screen === 'print' && quiz.results && (
          <PrintView
            results={quiz.results}
            responses={quiz.responses}
            dataset={typedDataset}
            onBack={() => quiz.goToScreen('results')}
          />
        )}
      </main>

      {quiz.consentGiven === null && quiz.screen !== 'landing' && (
        <PrivacyBanner
          onAccept={() => quiz.giveConsent(true)}
          onDecline={() => quiz.giveConsent(false)}
        />
      )}
    </div>
  );
}

{/* Skip link for accessibility */}
<a
  href="#main-content"
  className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-clinical-blue focus:text-white focus:rounded"
>
  Skip to main content
</a>