localStorage / sessionStorage key inventory

Catalog of every hj:* / hj-* storage key in the frontend (apps/frontend/src/). Backend and the Chrome extension run in different storage realms and are out of scope here.

This is an inventory, not a migration plan — existing keys are recorded as-is. Naming convention for new keys: prefer hj:<surface>-<purpose>-v<n> going forward (colon separator distinguishes from older hj-… keys). Flagged inconsistencies are called out per row but not renamed.

For the design pattern behind filter-state keys (the *-filters-v1 family), see docs/ai/CONVENTIONS.md → Filter persistence pattern.

How keys are grouped

flowchart LR
    A[hj* keys] --> B[Filter persistence<br/>hj:*-filters-v1]
    A --> C[Cache snapshots<br/>for instant first paint]
    A --> D[UI preferences]
    A --> E[Skeleton-sizing counts]
    A --> F[Draft state]
    A --> G[Per-feature flags / auth]

Each row below names the storage realm (local = localStorage, persists across browser sessions; session = sessionStorage, cleared on tab close).

Filter persistence

Two-effect hydrate/write pattern documented in CONVENTIONS.md. Always local, always JSON blob, always per-field validated on read.

Cache snapshots (instant first paint)

JSON blobs primed into TanStack Query via queryClient.setQueryData in a post-mount effect. See CONVENTIONS.md → Progressive loading.

Skeleton-sizing counts

Tiny integer values consulted before the real fetch lands so the skeleton grid is the right shape on first paint.

UI preferences (per-browser)

Pure UI state — boolean toggles, hidden lists, expand/collapse — that's a nicety to remember but not load-bearing.

Resume state (reader progress)

Position tracking for resumable content — cleared on completion so re-opening a finished story starts fresh.

Draft state (in-flight authoring)

User input that would be lost on accidental navigation. Cleared after successful submission.

Feature flags / auth

Cached server-derived booleans that gate UI surfaces.

Out-of-pattern keys (legacy / non-prefixed)

Not hj* but live in the same storage realm; included so a future audit doesn't re-discover them. These keys predate the convention and should be migrated to hj:* if/when touched.

Adding a new key

1. Pick a name in the form hj:<surface>-<purpose>-v<n> (colon, not hyphen).
2. Pick the realm — sessionStorage if it shouldn't survive tab close (caches that can re-fetch cheaply), localStorage otherwise.
3. Guard reads + writes with typeof window !== 'undefined' and try/catch (private mode + quota errors).
4. Add a row above. If the key fits an existing category, drop it in that table; if not, add a new category section.
5. If it's a filter blob, follow the persistence pattern.