ADR-006: State Management — Zustand

Status

Accepted

Context

The HUD UI needs to juggle session data, live feed items, bookmarks, and preference toggles without drowning in boilerplate. We wanted something that plays well with React Server Components and client islands.

Options considered

  • Zustand — Tiny API, selector-friendly, easy to split into slices (web/src/store/*).
  • Redux Toolkit — Powerful but heavier, and we didn’t need global reducers.
  • React Context — Great for a few values, less great for frequently updated lists.

Decision

Adopt Zustand with isolated slices: session, sources, feed, preferences, and bookmarks. Each slice lives in web/src/store/. We hydrate from Supabase on load and persist lightweight bits (like auto-scroll state) in localStorage when it helps.

Consequences

Upside

  • Minimal ceremony; actions read like plain functions.
  • Easy to unit test slices in isolation.
  • Plays nicely with suspense/streaming boundaries.

Trade-offs

  • Less structure than Redux—discipline required to avoid tangled effects.
  • For advanced dev tools we may need to add middleware later.
  • Store directory: web/src/store/
  • Example slice: web/src/store/feed-store.ts
  • Related ADR: ADR-002