# Retailer Filtering (include / exclude) — design + open questions

Living design doc for the retailer-filtering feature on
arpartsfinder.com. Captures the current state, the discussions that
shaped it, the open design questions worth coming back to, and the
side-effects / consequences we identified along the way.

This is the canonical place to track this work; the TODO.md "exclude
follow-ups" entry points here. Revisit as new things land.

---

## Current state (2026-05-30)

Two saved sets per visitor, both client-side (localStorage, anonymous,
no account required):

- **Include set** (`arpf_include_retailers`): retailers the visitor
  has saved as their preferred default. Renders the emerald "⭐ Saved
  as preferred" affordance in the Retailers popover footer.
- **Exclude set** (`arpf_exclude_retailers`): retailers the visitor
  wants permanently hidden from their default browse view. Per-row
  ⊘ button in the popover toggles a retailer into/out of this set.

URL surface (server-honored):

- `?r=A&r=B` — include filter (`WHERE company IN (...)`).
- `?rx=X` — exclude filter (`WHERE company NOT IN (...)`).
- `?company=A` — legacy alias for `?r=A`, honored for ~30 days post
  rename so URLs in browser history / bookmarks / shared links still
  filter correctly. Drop after the grace window.
- `?_pref=1` — purely-client marker: "the current `r=` set matches
  the saved include set, render the emerald 'filtered to preferred'
  pill." Server is stateless to it.

Auto-apply on first paint of `/browse?type=…`: if the visitor has a
saved include/exclude set AND the URL has no explicit retailer params
AND no session widen flag, redirect with the saved sets expressed as
`?r=…&rx=…&_pref=1`.

Cross-tab live sync via `storage` event listener — changes in one tab
update the popover indicators in other open tabs without reload. The
filter applied to each tab's URL stays per-tab (each tab is its own
view; changing it would surprise the user). Reload in another tab
re-runs autoApply, picking up the new saved set.

Per-pill / per-chip UI:

- **Emerald "⭐ Filtered to your N preferred retailers"** pill: shows
  when `?_pref=1` is in URL. "Show all" link strips retailer params
  + sets the session-widen flag.
- **Amber per-retailer exclude chip** (`⊘ Bear Creek Arsenal ×`):
  server-rendered, one per `rx=` value. Click × to remove just that
  one exclude. Bulk "Clear hidden" lives in the popover footer.

---

## Design pivots that got us here

### 1. Phase 0 → Phase 0.5 → rx= migration

- **Phase 0**: client-only preferred set, server only knew `company=`.
  Auto-apply just enumerated the saved preferred as positive
  `company=` params. Shipped 2026-05-29.
- **Phase 0.5**: client-only exclude set, also client-computed. Auto-
  apply had to translate "all minus excluded" into a positive
  enumeration of the OTHER 9-of-10 retailers, because the server only
  had `company IN`. This caused the "visually confusing all-but-one"
  problem — the chip strip filled up with 9 emerald inclusion chips
  for what the user thought of as a single exclusion. Shipped same
  day, then revisited next day.
- **rx= migration** (this doc): added server-side `company NOT IN`
  via `?rx=` param. Now the JS no longer has to enumerate the inverse,
  the chip strip shows one amber exclude chip per `rx=` value, and the
  popover stays in implicit-all state when no preferred is set.
  Cleaner all the way through.

### 2. Naming: include / exclude (not preferred / excluded)

Mike's pivot 2026-05-30: "preferred is really just a save of the
state of those items." So we standardized on **include** / **exclude**
in internal naming (localStorage keys, URL params, code variables,
this doc). UI-visible copy still says "preferred" in places where
"Save as preferred" reads more naturally than "Save as included"
— wording-level decision, not a structural one.

### 3. URL param naming: r / rx (not inc / exc)

Picked over `inc=` / `exc=`, `c=` / `cx=`, etc. Reasoning:
- `r` = "retailer", matches the internal vocab (`retailer_config`,
  `RetailerConfig`, etc.) — Mike's preferred term for the entity.
- `rx` = "retailer exclude", `x` suffix as exclude reads naturally.
- Shorter than `company` was anyway. Sets a precedent: future filter
  dimensions (brand, manufacturer, attr) could mirror the pattern
  (`b` / `bx`, `m` / `mx`, etc.).

### 4. Auto-fill-9-others hack (Phase 0.5, gone)

Before rx=, ⊘-ing a retailer from the implicit-all view had to flip
the popover into "all 9 OTHER boxes checked" to serialize the inverse.
Mike called out the UX confusion ("every retailer listed in the filter
on pages"). The rx= migration killed the hack — the popover now stays
in its natural state (no boxes checked = implicit all = show
everything except the rx= excluded set).

---

## Open design questions (worth revisiting)

### 1. Pref pill on partial-preferred view

Today the emerald "Filtered to your N preferred retailers" pill shows
when `prefActive()` returns true — i.e. the current checked set is a
non-empty subset of preferred. What happens when preferred =
[Brownells, PSA] and the user ⊘'s Brownells? Net effect = filter
narrows to PSA + BCA excluded. Is "Filtered to your 2 preferred" still
the right pill text when only 1 of the 2 is visible? Or should it
read "Filtered to 1 of your 2 preferred"?

Status: unverified — the pill semantics in this composite case aren't
documented in code or visually tested yet.

### 2. Bulk un-exclude from chip strip

Today each `rx=` exclude renders an individual amber chip with × for
single removal. To un-exclude all in one shot, the visitor opens the
popover and clicks "Clear hidden." If they have many excludes, this
is more clicks than necessary; a chip-strip "Clear all excludes" link
could shortcut it.

Status: not built; defer until visitor feedback shows the per-chip ×
is clumsy.

### 3. Auto-fill experience post-rx=

The rx= migration removed the auto-fill hack, which means a visitor
who ⊘'s the only retailer in implicit-all now sees… the same view
they had before, minus one retailer. No "9 checks suddenly appear"
weirdness. Mike was happy with this resolution; capture for the
record so we don't reintroduce the hack.

Status: resolved by the rx= migration.

### 4. Excludes for retailers not on current type

⊘'ing BCA on /browse?type=completeupper then navigating to a type
BCA doesn't sell: BCA is still in the saved exclude set, but it's not
in the popover (the popover only renders retailers selling the
current type). configRequest still injects `rx=BCA` into form GETs
even though BCA isn't visible. Server-side this is a no-op (BCA isn't
in this type's parts anyway). The amber exclude chip would still
render in the chip strip though — slightly noisy on a view where the
exclude isn't doing anything.

Status: open. Options:
- Suppress chips for excludes that don't affect the current type.
- Leave as-is — surfaces the "global state" of excludes consistently
  across types.

### 5. Form-state + manual-check + Save preferred interaction

A visitor manually unchecks Brownells (manually deviating from
preferred). They click "Save as preferred" — does the new preferred
become the now-deviated set, or does the existing preferred stay?
Currently Save takes a snapshot of CURRENT checked state, so the
deviated set becomes the new preferred. That matches "save what
you're looking at as your default," which is the intended UX, but
worth verifying with the visitor's intuition.

Status: ambiguous; matches Save semantics but could be confusing.
Probably fine as-is; revisit if visitors complain.

### 6. Account-backed sync (Phase 1)

Today everything is localStorage = device + browser. A visitor
switching laptops, browsers, or clearing cache loses their saved
sets. Phase 1 of the original phasing was "account-backed persistence"
to fix this, but site-ng has no account system yet. Phase 1 gated on:
- Email-keyed prefs OR full account model
- Decision about whether email-for-restock-alerts UX is the right
  identity hook
- Server endpoints to read/write a `visitor_prefs` table

Status: deferred. See `feature-preferred-retailers-filter` memory.

### 7. Build-creator integration (Phase 2)

The build composer should let visitors lock a build to a single
retailer (e.g., "only show Brownells parts when adding to this
build") with a per-build override of the global include set. This is
where the feature really pays off — single-retailer builds = one
checkout, one return policy, one affiliate. Captured in the original
phasing.

Status: deferred until the build feature lands more pieces.

### 8. Cross-retailer merge interaction (Phase 3)

Once `feature-cross-retailer-merge` lands, the include/exclude sets
should influence merged cards too: prefer the include-side retailer's
price as the "primary" price; collapse merged cards to just the
included retailer when there's only one match in the merged set.

Status: blocked on feature-cross-retailer-merge landing.

---

## Other consequences worth knowing

### Server statelessness

Server reads `?r=` / `?rx=` as ordinary multi-value query params.
There's no session, no cookie, no account dependency. `_pref=1` is
purely a UI hint the server passes through unchanged. This means:
- URLs are fully shareable (someone pasted `?r=Brownells&rx=BCA` lands
  on the same view).
- The server has zero state about which retailers a visitor "trusts."
  All identity-level info lives in their localStorage.
- A server log shows real filter usage (you can grep access logs for
  `r=` / `rx=` to understand which retailers visitors actually
  include or exclude — useful for product decisions).

### Mobile UX

Popover footer is denser than it used to be (Save preferred / Clear
preferred row + Hiding N retailer(s) / Clear hidden row, plus per-row
⊘ buttons). Worth a phone check pre-public-launch. Likely fine — the
popover is 64rem wide and footer rows are flex with `justify-between`
so they collapse cleanly — but unverified.

### Search / build pages

This filter machinery currently only fires on `/browse?type=…`. The
existing `/search` and `/build` pages don't have the retailer popover
or the include/exclude affordances. When those features mature,
consider whether the same JS should drive parallel widgets there.

### Tailwind safelist

The dynamic classes applied by the ⊘ paint logic (`line-through`,
`opacity-60`, `text-red-700`, `dark:text-red-400`) are kept in the
JIT compile output via a hidden safelist span in `filter_bar.html`.
If those classes ever stop applying visually, check that span first
— the JIT only compiles literal class strings it sees in source.

### Cap interactions

`/instock/new` got a hard 10-page cap recently because of the bulk-
onboarding flood pattern (every freshly-onboarded retailer's catalog
has `parts.added=today`). The include/exclude filter is orthogonal to
that cap — `/instock/new` doesn't use the popover today. If we ever
push include/exclude into the "Recent" pages, the cap needs to apply
AFTER the include/exclude filter or the visitor's "show me my
preferred retailers in Newest" view gets unintuitive truncation.

---

## Related memories

- `feature-preferred-retailers-filter` — the original feature memory
  with the full phasing (P0 / P0.5 / P1 / P2 / P3).
- `feature-cross-retailer-merge` — the merged-products feature that
  Phase 3 of preferred/exclude composes with.
- `feature-build-comparison`, `feature-site-share-builds` — build-
  feature work that Phase 2 lands inside.
- `sister-sites-shared-infrastructure` — the include/exclude feature
  should port cleanly to handgunfinder / longgunfinder / ammofinder
  since it's pure-presentation and platform-agnostic.

---

## Change log on this doc

- 2026-05-30: initial doc, captured Phase 0 / 0.5 / rx= migration
  state + the design questions surfaced during the same-week iteration
  cycle. Will revisit as visitor feedback comes in and as Phase 1+
  pieces land.
