5chan/docs/agent-runs/codebase-audit-2026-04-23/02-state-management.md

# State Management Audit

## Summary

The Zustand layer is mostly a loose collection of 32 single-purpose stores, many of which are healthy (tiny modal stores, preference toggles). The biggest systemic problems are: (1) near-universal whole-store destructuring in consumers — there is no `useShallow` anywhere in the codebase, so every call to `const { a, b } = useXStore()` re-renders on any state change, (2) `use-catalog-filters-store` has ballooned into a 400 LOC kitchen-sink with a live filter function cached in state, a `setTimeout` that mutates state from a render-time selector path, and an imperative top-level self-kick on module import, and (3) ~7 stores roll their own ad-hoc localStorage handlers instead of using the `persist` middleware that the project already depends on.

## Store Inventory

| Store | Responsibility | LOC | Main concern |
|---|---|---|---|
| `use-catalog-filters-store.ts` | Catalog filter text list, per-community counts, search, match highlights | 400 | Kitchen-sink; stores a `(comment) => boolean` function; `setTimeout` side-effect inside selector; top-level `.getState().updateFilter()` at module load |
| `use-boards-bar-visibility-store.ts` | Boards-bar directory/subscription visibility | 128 | Hand-rolled localStorage reads/writes (4 keys + legacy fallbacks); should use `persist` |
| `use-reply-modal-store.ts` | Reply modal open state + quote-insertion signals | 117 | Mixes transient reply target (cid/number/community) and quote-insert event stream; DOM read (`window.innerWidth`) inside store action; cross-store write to `useSelectedTextStore` on close |
| `use-mod-queue-store.ts` | Mod queue alert threshold, dismissed cids, queue history, view mode, selected board | 115 | Mixes unrelated concerns: ephemeral UI (`viewMode`, `selectedBoardFilter`) with persisted data (`queuedCommentHistory`, `dismissedCommentCids`, thresholds); action `getAlertThresholdSeconds` is a derived getter masquerading as a method |
| `use-post-number-store.ts` | Post number <-> cid maps keyed by community | 86 | Reasonable; but `getScopedNumberToCidMap` is a non-trivial selector computed outside memoization boundary |
| `use-publish-post-store.ts` | Draft state for a single top-level post | 85 | Singleton draft; ties publish-option construction to state shape; `publishCommentOptions` cached in state duplicates fields already in state |
| `use-disclaimer-modal-store.ts` | NSFW disclaimer modal + acceptance | 84 | Takes a `NavigateFunction` into store actions (coupling); hand-rolled localStorage |
| `use-publish-reply-store.ts` | Draft reply state keyed by parentCid | 80 | 6 parallel dictionaries keyed by cid (should be one map of objects); leaks memory — `resetPublishReplyStore` sets `undefined` but never deletes keys |
| `use-feed-cache-store.ts` | LRU of recent feed keys (size 2) | 61 | Tiny LRU over an array; `maxCacheSize` is state but never changed |
| `use-theme-store.ts` | Current theme per sfw/nsfw category | 56 | Side-effect `loadThemes()` called at import; `getTheme` is an action that also mutates state (`currentTheme`) |
| `use-community-offline-store.ts` | Per-community offline state + 30s initial-load window | 52 | `setTimeout(..., 30_000)` inside store action leaks if community unmounts; `initialLoad` flag is derivable from timestamp |
| `use-boards-filter-store.ts` | Boards page sfw/nsfw filter + catalog-link toggle | 51 | Hand-rolled localStorage; two unrelated concerns in one store |
| `use-media-hosting-store.ts` | Media host provider + upload mode | 46 | Good — uses `persist` with version+migrate |
| `use-communities-loading-start-timestamps-store.ts` | First-seen timestamp per community | 44 | Exports a hook wrapper with its own `useEffect` + `useMemo`; selector returns a new array every render (`.map()`), defeats memo |
| `use-app-update-store.ts` | App update availability/apply state | 41 | Clean; minor — 3 booleans where a discriminated `status` would be clearer |
| `use-thread-live-updates-store.ts` | Thread auto-update enable + request id counter | 40 | Clean |
| `use-challenges-store.ts` | Queue of active challenges | 38 | Module-level `nextChallengeId` mutable counter outside store |
| `use-external-quote-status-store.ts` | Temporary error banner for external quote resolution | 37 | Module-level `hideTimeout` outside store |
| `use-special-theme-store.ts` | Christmas theme toggle | 34 | Clean |
| `use-publish-post-store.ts`+`use-publish-reply-store.ts` | — | — | Two stores that are 90% the same logic |
| `use-post-number-store.ts` | — | — | See above |
| `use-popular-threads-options-store.ts` | Home popular-threads sfw/nsfw toggles | 24 | Hand-rolled localStorage; imported under a misleading `useHomeFiltersStore` alias |
| `use-directory-modal-store.ts` | Directory modal open/close | 26 | Duplicate of two other modal stores |
| `use-create-board-modal-store.ts` | Create-board modal open/close | 26 | Duplicate |
| `use-boards-bar-edit-modal-store.ts` | Boards-bar edit modal open/close | 25 | Duplicate |
| `use-blotter-visibility-store.ts` | Blotter show/hide | 25 | Clean — uses `persist` |
| `use-expanded-media-store.ts` | Image fit + video mute prefs | 26 | Clean — uses `persist` |
| `use-feed-view-settings-store.ts` | Infinite-scroll toggle | 22 | Clean — uses `persist` |
| `use-catalog-style-store.ts` | Image size + show OP comment | 24 | Hand-rolled localStorage |
| `use-all-feed-filter-store.ts` | All-feed sfw/nsfw filter | 32 | Hand-rolled localStorage |
| `use-sorting-store.ts` | Catalog sort type | 17 | Clean |
| `use-feed-reset-store.ts` | Stores a reset function reference | 14 | Stores a function — this is a ref/pub-sub, not state |
| `use-selected-text-store.ts` | Selected-text string | 16 | Clean, but could be `useReplyModalStore` field |

## Findings

### Critical

- **`src/stores/use-catalog-filters-store.ts:206-250`** — `updateFilter` stores a new `(comment) => boolean` closure inside the store state. The closure captures `state` via `set((state) => ({ filter: ... }))`, so every subsequent mutation to `filterItems`, `searchText`, or `currentCommunityAddress` requires re-running `updateFilter()` to refresh the closure. Missing any of those paths produces a stale filter. Additionally, inside the filter at line 232 it calls `setTimeout(...)` to schedule `incrementFilterCount`, which mutates the store **from render-time consumers** (the filter is called during a render pass by whoever uses it). That is a store mutation as a render side-effect — exactly the Zustand anti-pattern the React 19 rules call out. *Fix:* stop storing a closure in state. Expose `matchesFilter(comment, communityAddress)` as a pure selector (or a utility that takes `filterItems` + `searchText` as arguments). Track per-community filtered cids in a separate update path triggered by the owning component after it has filtered its own list, not inside a predicate called during render.
- **`src/stores/use-catalog-filters-store.ts:398`** — Top-level `useCatalogFiltersStore.getState().updateFilter();` runs at module import. This executes before React is mounted and before the `persist` rehydration completes, so the initial filter closure sees empty `filterItems` even though persisted filters exist. Consumers then get a stale filter until another action happens to call `updateFilter`. *Fix:* trigger `updateFilter` from `onRehydrateStorage`, or replace with a pure selector so there is nothing to prime.
- **`src/stores/use-catalog-filters-store.ts:361-370`** — `partialize` drops all non-text fields (`count`, `filteredCids`, `communityCounts`, `communityFilteredCids`) but the `deserialize` migration on the next load calls `normalizeFilterItem` which re-creates empty `Map`/`Set` instances. That is fine, but the `deserialize` function never accounts for the version, and the branch at line 372 does `JSON.parse` manually — but the default `persist` storage already parses. On repeat calls it is parsing a plain object as a string, swallowing the error in the `typeof persisted === 'string'` check. *Fix:* drop the custom `deserialize` entirely; persisted data is already plain strings, and `Map`/`Set` revival should go through `storage: createJSONStorage(() => localStorage, { reviver, replacer })`.

### High

- **`src/app.tsx:183`** — `GlobalLayout` destructures 8 fields off `useReplyModalStore()` with no selector. This is a top-level always-mounted component; it re-renders every time any field (`quoteInsertRequestId` counter, `openEmpty`, `scrollY`, etc.) changes. *Fix:* split into per-field `useReplyModalStore((s) => s.activeCid)` selectors (already the pattern used inside `reply-modal.tsx` itself) or use `useShallow` on the destructured object.
- **`src/components/catalog-filters/catalog-filters.tsx:50-54`, `src/hooks/use-publish-post.ts:12-19`, `src/hooks/use-publish-reply.ts:25-31`** — Selectors that return a new object literal `(state) => ({ a: state.a, b: state.b })` without `useShallow`. Zustand compares the selector result with `Object.is` by default, so the new object is never equal and the hook re-fires on every store change. *Fix:* wrap with `useShallow` from `zustand/react/shallow`, or split into one-field selectors.
- **`src/stores/use-catalog-filters-store.ts:25`, `205`, `208`** — `filter: ((comment: Comment) => boolean) | undefined` is a function stored in state. Every consumer that reads `state.filter` re-subscribes to identity of this function. Combined with `updateFilter` rebuilding it on every filter/search/community change, anything reading it re-renders unnecessarily. *Fix:* as above, make it a pure selector — `selectCatalogFilterPredicate(state)` returns a stable-ish function based on current state, memoized via `zustand/middleware` or Zustand's `createSelector` equivalent.
- **`src/stores/use-mod-queue-store.ts:9-23`** — One store carries (a) persisted moderation data (dismissed cids, 500-entry history, thresholds) and (b) ephemeral UI (`viewMode: 'compact'|'feed'`, `selectedBoardFilter`). Every `rememberCommentsInQueue` mutation re-renders every consumer of `viewMode` across `board-buttons.tsx` and `mod-queue.tsx`. *Fix:* split into `use-mod-queue-data-store` (persisted) and `use-mod-queue-view-store` (session UI); alternatively, partialize the persist layer so UI fields are not saved and subscribers can select precisely.
- **`src/stores/use-publish-reply-store.ts:8-13, 69-77`** — State shape is 6 parallel `{ [parentCid]: T }` dictionaries. Any reply draft update spreads all 6 objects. Worse, `resetPublishReplyStore` sets each `[parentCid]: undefined` instead of deleting, so the dictionaries grow unboundedly for the lifetime of the session. *Fix:* collapse to `drafts: Record<string, ReplyDraft>` with a single `setDraft(parentCid, patch)` and `deleteDraft(parentCid)` that does `const { [parentCid]: _, ...rest } = state.drafts`.
- **`src/stores/use-reply-modal-store.ts:82-95`** — `window.innerWidth` read inside the store action; the store action is therefore non-deterministic across test environments and SSR. *Fix:* move the mobile check to the caller (there is already a `use-is-mobile` hook), and accept a `scrollY` argument.
- **`src/stores/use-reply-modal-store.ts:53, 79, 99`** — `useReplyModalStore` writes into `useSelectedTextStore` via `.getState()`. Bidirectional coupling: the two stores are really one feature. *Fix:* merge `selectedText` into `useReplyModalStore` (it is only ever used by the reply modal), and delete `use-selected-text-store.ts`.

### Medium

- **`src/stores/use-community-offline-store.ts:38-48`** — `initializeCommunityOfflineState` schedules a naked `setTimeout(..., 30_000)` that mutates the store. If the user navigates away, the timer still fires and flips `initialLoad: false` on unmounted communities. And `initialLoad` itself is derivable — `Date.now()/1000 - loadingStartTimestamp < 30` (the hook already computes this at `use-is-community-offline.ts:36`). *Fix:* delete `initialLoad` and the timer; derive from the already-persisted timestamp in `use-communities-loading-start-timestamps-store`.
- **`src/stores/use-communities-loading-start-timestamps-store.ts:37-39`** — `communitiesLoadingStartTimestamps` selector returns `communityAddresses.map(addr => timestampsStore[addr])` — a new array every render even when unchanged. The outer `useMemo` prevents re-renders of *this* hook but its consumers still see a new array reference each time `timestampsStore` mutates for any address. *Fix:* select the specific timestamps via `useShallow`, or compute a stable signature outside.
- **`src/stores/use-boards-bar-visibility-store.ts` (whole file)**, **`src/stores/use-boards-filter-store.ts`**, **`src/stores/use-catalog-style-store.ts`**, **`src/stores/use-all-feed-filter-store.ts`**, **`src/stores/use-popular-threads-options-store.ts`**, **`src/stores/use-disclaimer-modal-store.ts`** — All hand-roll `localStorage.getItem/setItem` inside store definitions instead of using the `persist` middleware that's already imported elsewhere. This multiplies the serialization bugs (e.g. `use-boards-bar-visibility-store.ts:54` parses an array as a boolean; `use-popular-threads-options-store.ts:11` has the "default true unless false" logic duplicated). *Fix:* migrate to `persist({ name, version, migrate, partialize })`. The existing keys can be mapped via `storage: createJSONStorage(() => localStorage)` with a `migrate` fn to copy from the legacy keys.
- **`src/stores/use-disclaimer-modal-store.ts:10, 36, 63`** — Store actions accept a React Router `NavigateFunction`. That makes the store coupled to the call site's router context and forces the component to thread navigate through props. *Fix:* have the store expose target state (`acceptedTargetPath`) and let a tiny `useDisclaimerNavigation` hook subscribe and call `navigate`.
- **`src/stores/use-theme-store.ts:32-39`** — `getTheme` is named like a selector but also mutates state (`set({ currentTheme: theme })`). Plus there's a `updateCurrentTheme=true` parameter that silently toggles side-effect behavior. *Fix:* split into a pure `getTheme(category)` selector and an explicit `setCurrentTheme` action.
- **`src/stores/use-theme-store.ts:54`** — `useThemeStore.getState().loadThemes()` runs at import time. `loadThemes` is async (reads from `localforage`). Any component that renders before that promise resolves sees the default `{ nsfw: 'yotsuba', sfw: 'yotsuba-b' }`, flickers, then re-renders when the real theme loads. *Fix:* expose an `isLoaded` flag so `useTheme()` can gate rendering, or call `loadThemes` from the root provider where the hydration lifecycle is explicit.
- **`src/stores/use-publish-post-store.ts:28-71`** — Store holds both the raw draft fields (`title`, `content`, `link`) **and** a pre-built `publishCommentOptions` derived from those fields. They can drift. And `setPublishPostStore` re-derives the options on every keystroke even though `use-publish-post.ts:73-81` wraps them again with `useMemo` + `onChallenge`. *Fix:* keep only raw draft fields in state; compute `publishCommentOptions` in `use-publish-post.ts` via `useMemo`.
- **`src/stores/use-boards-bar-visibility-store.ts:77-82`** — Store loads `getAllBoardCodes()` on first-render of any consumer. If the board-codes module changes size between releases (which it does; 5chan ships a new board list regularly), existing users keep their old set and new boards are invisibly hidden. *Fix:* store only the *hidden* set, not the visible one; default "visible" becomes "not in hidden set", and new boards appear automatically.
- **`src/stores/use-reply-modal-store.ts:14-16, 65-96`** — Event-stream fields (`quoteInsertRequestId`, `quoteInsertNumber`, `quoteInsertSelectedText`) are abusing persisted state as a pub/sub channel. Consumers (`reply-modal.tsx:59-61`) diff the request id in a `useEffect` to react to the event. *Fix:* either use a proper event emitter/ref, or at minimum document the pattern; consider a `useReplyQuoteInsertEvents` subscription helper.
- **`src/components/boards-bar/boards-bar.tsx:100-103`** — 4 modal stores opened in one component. These three modal stores (`directory`, `create-board`, `boards-bar-edit`) and `disclaimer` are structurally identical. *Fix:* one `useModalsStore` with `openModal(name)` / `closeModal()` — drops ~80 LOC and three files.

### Low

- **`src/stores/use-challenges-store.ts:4`** — `let nextChallengeId = 0;` is module-level mutable state that survives HMR inconsistently. *Fix:* move into the store.
- **`src/stores/use-external-quote-status-store.ts:9`** — `let hideTimeout` at module scope, same concern. *Fix:* move into state or use a ref stored in the store.
- **`src/stores/use-popular-threads-options-store.ts`** is aliased as `useHomeFiltersStore` in `src/views/home/box-modal/box-modal.tsx:3`. Misleading. *Fix:* rename the store or the import.
- **`src/stores/use-feed-reset-store.ts`** — stores a function to cross-cut-call "reset the current feed". This is a ref/command bus, not state. *Fix:* Zustand is OK for this, but document it, or switch to a simple module-level `{ reset?: () => void }` with a setter to avoid the re-render on every subscribe.
- **`src/stores/use-catalog-filters-store.ts:311-325`** — `getFilteredCountForCurrentCommunity` is a pure function over state but it is an action on the store. Callers that depend on it won't re-render when state changes. *Fix:* expose as a selector `selectFilteredCountForCurrentCommunity(state)`.
- **`src/stores/use-mod-queue-store.ts:77-80`** — Same pattern: `getAlertThresholdSeconds` is a pure derivation (`value * 3600` or `value * 60`) stored as an action. Callers like `post-desktop.tsx:247` read it at render and compute against it, missing re-renders when the threshold changes. *Fix:* make it a selector `(s) => s.alertThresholdUnit === 'hours' ? s.alertThresholdValue * 3600 : s.alertThresholdValue * 60`.
- **`src/stores/use-app-update-store.ts:6-10`** — `isApplyingUpdate` + `isCheckingForUpdate` + `availableUpdate` is flag soup; only one of (`idle`, `checking`, `available`, `applying`) is true at a time. *Fix:* a discriminated `status` union.
- **`src/stores/use-feed-cache-store.ts:22-42`** — `accessFeed` manually sorts + slices an array to simulate an LRU. With `maxCacheSize: 2`, this is fine in practice but the sort-slice semantics are wrong for size > 2 (keeps oldest plus newest). *Fix:* replace with `Map` insertion-order semantics (delete + re-set).

## Top 5 Actions

1. **Fix `use-catalog-filters-store`** (Critical). Remove the stored closure `filter`, remove the `setTimeout` that mutates state from inside a predicate, and delete the module-level `.getState().updateFilter()` primer. Make filtering a pure selector over `filterItems`/`searchText`/`communityAddress`, and move per-community counting into the catalog view where filtering already happens. This one store change eliminates the biggest re-render and correctness hazards in the codebase.
2. **Introduce `useShallow` as the default pattern for multi-field reads.** Add it to `src/app.tsx:183` (Reply modal wrapping everything), `src/components/catalog-filters/catalog-filters.tsx:50`, `src/hooks/use-publish-post.ts:12`, `src/hooks/use-publish-reply.ts:25`, and the ~30 `const { a, b } = useXStore()` call sites in components/views. Low-risk, mechanical, immediately cuts re-renders.
3. **Migrate the six hand-rolled-localStorage stores to `persist` middleware.** `use-boards-bar-visibility-store`, `use-boards-filter-store`, `use-catalog-style-store`, `use-all-feed-filter-store`, `use-popular-threads-options-store`, `use-disclaimer-modal-store`. Use `migrate` to copy values from the legacy keys once. Deletes serialization code, unifies hydration semantics with the rest of the codebase, and removes a class of "default-true vs stored-false" bugs.
4. **Collapse the three near-identical modal stores (`use-directory-modal-store`, `use-create-board-modal-store`, `use-boards-bar-edit-modal-store`) into one `useModalsStore`** keyed by modal name. Merge `use-selected-text-store` into `use-reply-modal-store` (it has no other consumer). Net: -4 files, less cross-store wiring.
5. **Split `use-mod-queue-store` into persisted data vs session UI, and convert `getAlertThresholdSeconds` + `use-catalog-filters-store.getFilteredCountForCurrentCommunity` from actions to selectors.** Fixes stale-on-change reads in `post-desktop.tsx`, `post-mobile.tsx`, and `mod-queue.tsx`, and stops the `viewMode` toggle from invalidating every consumer of the 500-entry persisted history array.