# Phase 13: Setup Impact Preview - Research

**Researched:** 2026-03-17
**Domain:** Pure frontend — delta computation + UI (React, Zustand, React Query)
**Confidence:** HIGH

---

## Summary

Phase 13 adds a setup-selector dropdown to the thread detail header. When a user picks a setup, every candidate card and list row gains two delta indicators: weight delta and cost delta. The computation has two modes determined at render time — replace mode (a setup item exists in the same category as the thread) and add mode (no category match). The entire feature is a pure frontend addition: all required data is already available through existing hooks with zero backend or schema changes needed.

The delta logic is straightforward arithmetic over nullable numbers: `candidate.weightGrams - replacedItem.weightGrams` in replace mode, or `candidate.weightGrams` in add mode. The only real complexity is the null-weight indicator (IMPC-04) and driving the selected setup ID through Zustand state so it persists across view-mode switches within the same thread session.

**Primary recommendation:** Add `selectedSetupId: number | null` to uiStore, render a setup dropdown in the thread header, compute deltas in a `useMemo` inside a new `useImpactDeltas` hook, and render inline delta indicators below the candidate weight/price badges in both list and grid views.

---

<phase_requirements>
## Phase Requirements

| ID | Description | Research Support |
|----|-------------|-----------------|
| IMPC-01 | User can select a setup and see weight and cost delta for each candidate | `useSetups()` returns all setups for dropdown; `useSetup(id)` returns items with categoryId for matching; delta computed in useMemo |
| IMPC-02 | Impact preview auto-detects replace mode when a setup item exists in the same category as the thread | Thread has `categoryId` (from `threads.categoryId`); setup items have `categoryId` via join; match on `categoryId` equality |
| IMPC-03 | Impact preview shows add mode (pure addition) when no category match exists in the selected setup | Default when no setup item matches `thread.categoryId`; label clearly as "+add" |
| IMPC-04 | Candidates with missing weight data show a clear indicator instead of misleading zero deltas | `candidate.weightGrams == null` → render `"-- (no weight data)"` instead of computing |
</phase_requirements>

---

## Standard Stack

### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| React 19 | ^19.2.4 | UI rendering | Project foundation |
| Zustand | ^5.0.11 | `selectedSetupId` UI state | Established pattern for all UI-only state (panel open/close, view mode) |
| TanStack React Query | ^5.90.21 | `useSetup(id)` for setup items | Established data fetching pattern |
| Tailwind CSS v4 | ^4.2.1 | Delta badge styling | Project styling system |

### Supporting
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| framer-motion | ^12.37.0 | Optional entrance animation for delta indicators | Already installed; use AnimatePresence if subtle fade needed |
| lucide-react | ^0.577.0 | Dropdown chevron icon, delta arrow icons | Project icon system |

### No New Dependencies
This phase requires zero new npm dependencies. All needed libraries are installed.

**Installation:**
```bash
# No new packages needed
```

---

## Architecture Patterns

### Recommended Project Structure
```
src/client/
├── stores/uiStore.ts           # Add selectedSetupId: number | null + setter
├── hooks/
│   └── useImpactDeltas.ts      # New: compute add/replace deltas per candidate
├── components/
│   ├── SetupImpactSelector.tsx # New: setup dropdown rendered in thread header
│   └── ImpactDeltaBadge.tsx    # New (or inline): weight/cost delta pill
└── routes/threads/$threadId.tsx # Add selector to header, pass deltas down
```

### Pattern 1: selectedSetupId in Zustand

**What:** Store selected setup ID as UI state in `uiStore.ts`, not as URL state or server state.

**When to use:** The selection is ephemeral per session (no permalink needed), needs to survive view-mode switches (list/grid/compare), and must be accessible from any component in the thread page without prop drilling.

**Example:**
```typescript
// In uiStore.ts — add to UIState interface
selectedSetupId: number | null;
setSelectedSetupId: (id: number | null) => void;

// In create() initializer
selectedSetupId: null,
setSelectedSetupId: (id) => set({ selectedSetupId: id }),
```

### Pattern 2: useImpactDeltas Hook

**What:** A pure computation hook that accepts candidates + a setup's item list + the thread's categoryId, and returns per-candidate delta objects.

**When to use:** Delta computation must run in a single place so list, grid, and compare views all show consistent numbers.

**Interface:**
```typescript
// src/client/hooks/useImpactDeltas.ts
import type { SetupItemWithCategory } from "./useSetups";

interface CandidateInput {
  id: number;
  weightGrams: number | null;
  priceCents: number | null;
}

type DeltaMode = "replace" | "add" | "none"; // "none" = no setup selected

interface CandidateDelta {
  candidateId: number;
  mode: DeltaMode;
  weightDelta: number | null;    // null = candidate has no weight data
  priceDelta: number | null;     // null = candidate has no price data
  replacedItemName: string | null; // populated in replace mode for tooltip
}

interface ImpactDeltas {
  mode: DeltaMode;
  deltas: Record<number, CandidateDelta>;
}

export function useImpactDeltas(
  candidates: CandidateInput[],
  setupItems: SetupItemWithCategory[] | undefined,
  threadCategoryId: number,
): ImpactDeltas
```

**Logic:**
```typescript
// Source: project codebase pattern — mirrors ComparisonTable useMemo
const impactDeltas = useMemo(() => {
  if (!setupItems) return { mode: "none", deltas: {} };

  // Find replaced item: setup item whose categoryId matches thread's categoryId
  const replacedItem = setupItems.find(
    (item) => item.categoryId === threadCategoryId
  ) ?? null;

  const mode: DeltaMode = replacedItem ? "replace" : "add";

  const deltas: Record<number, CandidateDelta> = {};
  for (const c of candidates) {
    let weightDelta: number | null = null;
    let priceDelta: number | null = null;

    if (c.weightGrams != null) {
      weightDelta = mode === "replace" && replacedItem?.weightGrams != null
        ? c.weightGrams - replacedItem.weightGrams
        : c.weightGrams;
    }
    // priceCents is integer (cents), same arithmetic
    if (c.priceCents != null) {
      priceDelta = mode === "replace" && replacedItem?.priceCents != null
        ? c.priceCents - replacedItem.priceCents
        : c.priceCents;
    }

    deltas[c.id] = {
      candidateId: c.id,
      mode,
      weightDelta,
      priceDelta,
      replacedItemName: replacedItem?.name ?? null,
    };
  }

  return { mode, deltas };
}, [candidates, setupItems, threadCategoryId]);
```

### Pattern 3: SetupImpactSelector Component

**What:** A compact `<select>` dropdown in the thread detail header, rendered between the thread title and the toolbar.

**When to use:** Always present on active and resolved thread pages (impact preview is read-only, no mutation side effects).

**Example:**
```typescript
// Placed in thread header, after thread name row
function SetupImpactSelector() {
  const { data: setups } = useSetups();
  const selectedSetupId = useUIStore((s) => s.selectedSetupId);
  const setSelectedSetupId = useUIStore((s) => s.setSelectedSetupId);

  if (!setups || setups.length === 0) return null;

  return (
    <div className="flex items-center gap-2">
      <label className="text-xs text-gray-500 whitespace-nowrap">
        Impact on setup:
      </label>
      <select
        value={selectedSetupId ?? ""}
        onChange={(e) => setSelectedSetupId(e.target.value ? Number(e.target.value) : null)}
        className="text-sm border border-gray-200 rounded-lg px-2 py-1 text-gray-700 bg-white focus:outline-none focus:ring-1 focus:ring-gray-300"
      >
        <option value="">None</option>
        {setups.map((s) => (
          <option key={s.id} value={s.id}>{s.name}</option>
        ))}
      </select>
    </div>
  );
}
```

### Pattern 4: ImpactDeltaBadge Rendering

**What:** Small inline indicator rendered below weight/price badges on each candidate. Three rendering cases per field:

| Case | Render |
|------|--------|
| No setup selected | Nothing (no change to existing layout) |
| Candidate has no weight | `"-- (no weight data)"` in muted gray |
| Weight exists, replace mode | `"±Xg vs [ItemName]"` with sign-colored text |
| Weight exists, add mode | `"+Xg (add)"` in gray |

**Where it renders:** Below the existing `formatWeight` / `formatPrice` badges in `CandidateListItem` and `CandidateCard`. In `ComparisonTable`, can be added as a sub-row or a second line within the weight/price cells.

**Sign coloring convention:**
- Negative delta (lighter/cheaper when replacing) → green text
- Positive delta (heavier/more expensive) → red text
- Zero delta → gray text
- No weight data → muted gray, em-dash prefix

```typescript
// Reusable inline component
function ImpactDeltaBadge({
  delta,
  noDataLabel = "-- (no weight data)",
  unit,
  currency,
  type,
}: {
  delta: CandidateDelta | undefined;
  noDataLabel?: string;
  unit?: WeightUnit;
  currency?: Currency;
  type: "weight" | "price";
}) {
  if (!delta || delta.mode === "none") return null;

  const value = type === "weight" ? delta.weightDelta : delta.priceDelta;

  if (value === null) {
    // Candidate has no data for this field
    return (
      <span className="text-xs text-gray-300">{noDataLabel}</span>
    );
  }

  const formatted = type === "weight"
    ? formatWeight(Math.abs(value), unit)
    : formatPrice(Math.abs(value), currency);

  const sign = value > 0 ? "+" : value < 0 ? "−" : "±";
  const colorClass = value < 0 ? "text-green-600" : value > 0 ? "text-red-500" : "text-gray-400";
  const modeLabel = delta.mode === "add" ? " (add)" : "";

  return (
    <span className={`text-xs font-medium ${colorClass}`}>
      {sign}{formatted}{modeLabel}
    </span>
  );
}
```

### Data Flow

```
$threadId.tsx
  ├── selectedSetupId ← useUIStore
  ├── thread ← useThread(threadId)          // has thread.categoryId + candidates
  ├── setupData ← useSetup(selectedSetupId) // null when none selected
  ├── impactDeltas ← useImpactDeltas(candidates, setupData?.items, thread.categoryId)
  │
  ├── <SetupImpactSelector />               // sets selectedSetupId in uiStore
  │
  ├── <CandidateListItem delta={impactDeltas.deltas[c.id]} />
  ├── <CandidateCard delta={impactDeltas.deltas[c.id]} />
  └── <ComparisonTable deltas={impactDeltas.deltas} />
```

### Anti-Patterns to Avoid

- **Computing deltas in each candidate component:** Delta mode (add vs replace) must be determined once from the full setup. Computing per-component means each card independently decides mode — a setup with multiple items in different categories could give inconsistent signals if the logic is subtle.
- **Storing selectedSetupId in URL search params:** Adds routing complexity with no benefit; the selection is ephemeral and non-shareable per project scope.
- **Calling `useSetup` inside each candidate component:** Causes N redundant React Query calls. Call once at page level, pass deltas down.
- **Treating `priceDelta = 0` as "no data":** Zero cost delta is a valid result (exact price match). The `null` check distinguishes missing data from zero.

---

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Formatted weight delta strings | Custom formatter | Reuse `formatWeight(Math.abs(delta), unit)` + sign prefix | Already handles all 4 units (g/oz/lb/kg) correctly |
| Formatted price delta strings | Custom formatter | Reuse `formatPrice(Math.abs(delta), currency)` + sign prefix | Already handles all currencies and JPY integer case |
| Setup list fetching | Custom fetch | `useSetups()` hook | Already defined, cached by React Query |
| Setup items fetching | Custom fetch | `useSetup(id)` hook | Already defined with enabled guard |
| UI state management | Local useState | Zustand `selectedSetupId` | Persists across view mode switches within same session |

**Key insight:** All data infrastructure exists. This phase is arithmetic + UI only.

---

## Common Pitfalls

### Pitfall 1: Thread categoryId vs Candidate categoryId

**What goes wrong:** Using `candidate.categoryId` instead of `thread.categoryId` to find the replaced setup item. Candidates inherit the thread's category (they're in the same decision thread), but a user could theoretically pick a different category per candidate. The impact preview is about "what does buying something for this research thread do to my setup," so the match must be on the **thread** category, not individual candidate category.

**Why it happens:** `CandidateWithCategory` has a `categoryId` field that looks natural to use.

**How to avoid:** In `useImpactDeltas`, accept `threadCategoryId` as a separate parameter sourced from `thread.categoryId`, not from `candidate.categoryId`.

**Warning signs:** Replace mode never triggers even when a setup contains an item in the expected category.

### Pitfall 2: Null vs Zero for Missing Data (IMPC-04)

**What goes wrong:** When `candidate.weightGrams` is `null`, the delta would be `null - replacedItem.weightGrams = NaN` or JavaScript coerces to `0`. Rendering "0g" is actively misleading — it implies the candidate has been weighed at zero.

**Why it happens:** JavaScript's `null - 200 = -200` is NaN, not zero, but string formatting might swallow this silently.

**How to avoid:** Explicit null guard BEFORE arithmetic: `if (c.weightGrams == null) { weightDelta = null; }`. Render `null` delta as `"-- (no weight data)"` per IMPC-04.

**Warning signs:** Candidates with no weight show "0g" or "−200g" delta.

### Pitfall 3: useSetup Enabled Guard

**What goes wrong:** Calling `useSetup(null)` triggers a request to `/api/setups/null` — a 404 or server error.

**Why it happens:** `useSetup` has `enabled: setupId != null` guard, but if the `selectedSetupId` from Zustand is not passed correctly, it might be `undefined` rather than `null`.

**How to avoid:** Coerce to `null` explicitly: `useSetup(selectedSetupId ?? null)`.

**Warning signs:** Network errors in dev tools when no setup is selected.

### Pitfall 4: selectedSetupId Stale Across Thread Navigation

**What goes wrong:** User selects "Setup A" on thread 1, navigates to thread 2, sees impact deltas for "Setup A" which may not be relevant.

**Why it happens:** Zustand state persists in memory across route changes.

**How to avoid:** Two acceptable approaches:
1. **Accept it** — the user chose a setup globally; they can clear it. Simplest.
2. **Reset on thread change** — call `setSelectedSetupId(null)` in a `useEffect` that fires on `threadId` change.

Recommended: Accept cross-thread persistence (simpler, matches how `candidateViewMode` works currently).

### Pitfall 5: ComparisonTable Integration

**What goes wrong:** ComparisonTable already has its own `weightDeltas` computation (candidate-relative deltas: lightest vs others). Adding setup deltas as a third numeric display in the same weight cell risks visual clutter and ambiguity about which delta is which.

**Why it happens:** Two delta systems in one cell with no visual separation.

**How to avoid:** Render setup impact deltas in a **separate row** in ATTRIBUTE_ROWS, or as a clearly labeled sub-row below weight. Label it "Impact" with a small setup name indicator.

---

## Code Examples

Verified patterns from existing codebase:

### Existing Delta Pattern (ComparisonTable.tsx)
```typescript
// Source: src/client/components/ComparisonTable.tsx
// This shows the established useMemo pattern for delta computation
const { bestWeightId, bestPriceId, weightDeltas, priceDeltas } =
  useMemo(() => {
    const withWeight = candidates.filter((c) => c.weightGrams != null);
    let bestWeightId: number | null = null;
    const weightDeltas: Record<number, string | null> = {};
    // ... arithmetic over nullable numbers
    return { bestWeightId, bestPriceId, weightDeltas, priceDeltas };
  }, [candidates, unit, currency]);
```

### Existing useSetup Hook
```typescript
// Source: src/client/hooks/useSetups.ts
export function useSetup(setupId: number | null) {
  return useQuery({
    queryKey: ["setups", setupId],
    queryFn: () => apiGet<SetupWithItems>(`/api/setups/${setupId}`),
    enabled: setupId != null,  // CRITICAL: prevents null fetch
  });
}
// SetupItemWithCategory includes: categoryId, weightGrams, priceCents, name
```

### Existing formatWeight / formatPrice
```typescript
// Source: src/client/lib/formatters.ts
export function formatWeight(grams: number | null | undefined, unit: WeightUnit = "g"): string {
  if (grams == null) return "--";
  // handles g / oz / lb / kg
}
export function formatPrice(cents: number | null | undefined, currency: Currency = "USD"): string {
  if (cents == null) return "--";
  // handles JPY integer case, others to 2dp
}
// Pass Math.abs(delta) to these, prefix sign manually
```

### Existing Zustand UI State Pattern
```typescript
// Source: src/client/stores/uiStore.ts
// All ephemeral UI state lives here — follow same pattern
candidateViewMode: "list" | "grid" | "compare";
setCandidateViewMode: (mode: "list" | "grid" | "compare") => void;
// Add analogously:
// selectedSetupId: number | null;
// setSelectedSetupId: (id: number | null) => void;
```

### Thread categoryId Availability
```typescript
// Source: src/server/services/thread.service.ts — getThreadWithCandidates
// thread object from useThread() has .categoryId (integer) directly available
// Note: ThreadWithCandidates interface in useThreads.ts does NOT expose categoryId
// The raw DB thread select does, but the hook return type may need updating
```

**Important finding:** The `ThreadWithCandidates` interface in `useThreads.ts` does NOT currently include `categoryId`. The server does return it (from `db.select().from(threads)`), but the TypeScript interface omits it. The planner must add `categoryId: number` to `ThreadWithCandidates` or source it from the candidates (each `CandidateWithCategory` has `categoryId`).

---

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Fetch data inside components | Custom hooks with React Query | Established in project | All data fetching via hooks |
| Local component state for UI | Zustand store | Established in project | All UI state centralized |

**No deprecated patterns in scope for this phase.**

---

## Open Questions

1. **Thread categoryId exposure in ThreadWithCandidates**
   - What we know: `getThreadWithCandidates` in thread.service.ts returns the full thread row (including `categoryId`), but `ThreadWithCandidates` TypeScript interface in `useThreads.ts` does not declare `categoryId`
   - What's unclear: Does the API actually serialize `categoryId` in the response or is it filtered?
   - Recommendation: Planner should add `categoryId: number` to `ThreadWithCandidates` interface and verify the server route includes it. Alternatively, use `thread.candidates[0]?.categoryId` as a fallback since all candidates share the thread's category.

2. **Selector placement on narrow viewports**
   - What we know: Thread header already has breadcrumb, title/status pill, and toolbar row
   - What's unclear: Three rows in mobile header may feel cramped
   - Recommendation: Planner's discretion — can be inline with toolbar or as a third header row. Research finds no hard constraint.

3. **ComparisonTable delta row placement**
   - What we know: ATTRIBUTE_ROWS pattern is extensible (just add an object to the array)
   - What's unclear: Whether impact rows should live inside the weight/price rows or as separate "Impact Weight" / "Impact Price" rows
   - Recommendation: Separate labeled rows to avoid conflating candidate-relative deltas (lightest/cheapest highlighting) with setup impact deltas.

---

## Validation Architecture

### Test Framework
| Property | Value |
|----------|-------|
| Framework | Bun test (built-in) |
| Config file | none — bun test discovers tests automatically |
| Quick run command | `bun test tests/services/` |
| Full suite command | `bun test` |

### Phase Requirements → Test Map
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| IMPC-01 | Delta values computed and passed to candidates when setup selected | unit (hook logic) | `bun test tests/lib/impactDeltas.test.ts` | Wave 0 |
| IMPC-02 | Replace mode triggered when setup contains item in same category as thread | unit | `bun test tests/lib/impactDeltas.test.ts` | Wave 0 |
| IMPC-03 | Add mode used when no category match, delta equals candidate value | unit | `bun test tests/lib/impactDeltas.test.ts` | Wave 0 |
| IMPC-04 | Null weight candidate returns null delta (not zero, not NaN) | unit | `bun test tests/lib/impactDeltas.test.ts` | Wave 0 |

**Note:** Delta computation is pure arithmetic logic and can be tested outside React via an extracted pure function. The recommended approach is to extract `computeImpactDeltas(candidates, setupItems, threadCategoryId)` as a pure function and test it directly — no React Testing Library needed.

### Sampling Rate
- **Per task commit:** `bun test tests/lib/`
- **Per wave merge:** `bun test`
- **Phase gate:** Full suite green before `/gsd:verify-work`

### Wave 0 Gaps
- [ ] `tests/lib/impactDeltas.test.ts` — covers IMPC-01 through IMPC-04 via pure function extracted from `useImpactDeltas`
- [ ] `tests/lib/` directory — create if not exists (pure utility tests go here)

---

## Sources

### Primary (HIGH confidence)
- Direct codebase read — `src/db/schema.ts` — verified `threadCandidates.categoryId`, `items.categoryId`, `setupItems` join structure
- Direct codebase read — `src/client/hooks/useSetups.ts` — verified `SetupItemWithCategory` type includes `categoryId`, `weightGrams`, `priceCents`
- Direct codebase read — `src/client/hooks/useThreads.ts` — identified missing `categoryId` in `ThreadWithCandidates` interface
- Direct codebase read — `src/client/components/ComparisonTable.tsx` — verified ATTRIBUTE_ROWS pattern and existing delta computation pattern
- Direct codebase read — `src/client/stores/uiStore.ts` — verified `selectedSetupId` does not yet exist, pattern for adding it
- Direct codebase read — `src/client/lib/formatters.ts` — verified `formatWeight` / `formatPrice` reusability with abs values
- Direct codebase read — `tests/helpers/db.ts` — verified test infrastructure, no schema changes needed

### Secondary (MEDIUM confidence)
- `.planning/STATE.md` — confirms "Impact preview must distinguish add-mode vs replace-mode by category match" as locked architectural decision

### Tertiary (LOW confidence)
- None

---

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH — zero new dependencies; all libraries confirmed in package.json
- Architecture: HIGH — derived entirely from reading existing codebase; patterns are directly reusable
- Pitfalls: HIGH — identified from code inspection (ThreadWithCandidates missing categoryId is a concrete finding, not speculation)
- Delta math: HIGH — straightforward arithmetic, verified types from schema

**Research date:** 2026-03-17
**Valid until:** 2026-04-17 (stable codebase; no external library research)