GearBox/.planning/phases/11-candidate-ranking/11-RESEARCH.md

# Phase 11: Candidate Ranking - Research

**Researched:** 2026-03-16
**Domain:** Drag-to-reorder UI + fractional indexing persistence
**Confidence:** HIGH

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked Decisions

**Card layout and view toggle**
- Add a grid/list view toggle in the thread header (list view is default)
- List view: vertical stack of horizontal cards (image thumbnail on left, name + badges on right) — enables drag-to-reorder
- Grid view: current 3-column responsive card layout preserved
- Both views render candidates in rank order (sort_order ascending)
- Rank badges visible in both views

**Drag handle design**
- Always-visible GripVertical icon (Lucide) on the left side of each list-view card
- Grip icon color: muted gray (text-gray-300), darkens to text-gray-500 on hover
- Cursor changes to 'grab' on hover, 'grabbing' during drag
- Drag feedback: elevated card with shadow + scale-up effect; other cards animate to show drop target gap (standard framer-motion Reorder behavior)
- On resolved threads: grip icon disappears entirely (not disabled/grayed)
- Drag only available in list view (grid view has no drag handles)

**Rank badge style**
- Medal icons (Lucide 'medal') in gold (#D4AF37), silver (#C0C0C0), bronze (#CD7F32) for top 3 candidates
- Positioned inline before the candidate name text
- Candidates ranked 4th and below show no rank indicator — position implied by list order
- On resolved threads: rank badges remain visible (static, read-only) — user prefers retrospective visibility

**Sort order and persistence**
- Schema migration adds `sort_order REAL NOT NULL DEFAULT 0` to `thread_candidates`
- Migration initializes existing candidates with spaced values (1000, 2000, 3000...) ordered by `created_at`
- Fractional indexing: only the moved item gets a single UPDATE (midpoint between neighbors)
- New candidates added to a thread get the highest sort_order (appended to bottom of rank)
- Auto-save on drop — no "Save order" button; reorder persists immediately via `PATCH /api/threads/:id/candidates/reorder`
- `tempItems` local state pattern: render from `tempItems ?? queryData.candidates`; clear on mutation `onSettled` — prevents React Query flicker

### Claude's Discretion
- Exact horizontal card dimensions and spacing in list view
- Grid/list toggle icon style and placement
- Drag animation timing and spring config
- Image thumbnail size in list view cards
- How action buttons (Winner, Delete, Link) adapt to horizontal card layout
- Keyboard accessibility for reordering (arrow keys to move)

### Deferred Ideas (OUT OF SCOPE)
None — discussion stayed within phase scope
</user_constraints>

<phase_requirements>
## Phase Requirements

| ID | Description | Research Support |
|----|-------------|-----------------|
| RANK-01 | User can drag candidates to reorder priority ranking within a thread | framer-motion Reorder.Group/Item handles drag + onReorder callback; fractional indexing PATCH saves order |
| RANK-02 | Top 3 ranked candidates display rank badges (gold, silver, bronze) | sort_order ascending sort gives rank position; Lucide `medal` icon confirmed available; CSS inline-color via style prop |
| RANK-04 | Candidate rank order persists across sessions | `sort_order REAL` column + Drizzle migration + `getThreadWithCandidates` ORDER BY sort_order; tempItems pattern prevents RQ flicker |
| RANK-05 | Drag handles and ranking are disabled on resolved threads | `isActive` prop already flows through `$threadId.tsx`; grip icon conditional render; Reorder.Group only rendered when isActive |
</phase_requirements>

---

## Summary

Phase 11 adds drag-to-reorder ranking for research thread candidates. The core mechanism is framer-motion's `Reorder.Group` / `Reorder.Item` components (already installed at v12.37.0 — no new dependencies), combined with a `sort_order REAL` column on `thread_candidates` and a fractional indexing strategy that writes only one row per reorder.

The drag handle pattern requires `useDragControls` from framer-motion so the drag is initiated only from the GripVertical icon, not from tapping anywhere on the card. The `tempItems` local state pattern prevents a visible flicker between optimistic UI and React Query re-fetch.

The phase introduces a grid/list view toggle (defaulting to list). The existing `CandidateCard` component handles grid view unchanged; a new `CandidateListItem` component (or a variant prop on `CandidateCard`) provides the horizontal list-view layout with the drag handle and rank badge.

**Primary recommendation:** Implement in this order — schema migration, service update, Zod schema + route, hook, then UI (view toggle, `CandidateListItem`, rank badge). This matches the established field-addition ladder pattern.

---

## Standard Stack

### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| framer-motion | ^12.37.0 (installed) | Drag-to-reorder via `Reorder.Group`/`Reorder.Item`; `useDragControls` for handle-based drag | Already in project; Reorder API is purpose-built for this pattern — no additional install |
| Drizzle ORM | installed | Schema migration + `ORDER BY sort_order` query | Project ORM; REAL type required for fractional indexing |
| @tanstack/react-query | installed | `useReorderCandidates` mutation + cache invalidation | Project data-fetch layer |
| Zustand | installed | `candidateViewMode: 'list' | 'grid'` in uiStore | Project UI state pattern |
| lucide-react | installed | GripVertical, Medal, LayoutList, LayoutGrid icons | All icons confirmed present in installed version |

### No New Dependencies
This phase requires zero new npm packages. framer-motion, React Query, Zustand, and Lucide are all already installed.

---

## Architecture Patterns

### Recommended Project Structure Changes
```
src/
├── db/schema.ts                           # Add sortOrder: real("sort_order")
├── server/
│   ├── services/thread.service.ts         # Add reorderCandidates(), update getCandidates ORDER BY
│   └── routes/threads.ts                  # Add PATCH /:id/candidates/reorder
├── shared/
│   ├── schemas.ts                         # Add reorderCandidatesSchema
│   └── types.ts                           # Add ReorderCandidates type
├── client/
│   ├── components/
│   │   ├── CandidateCard.tsx              # Unchanged (grid view)
│   │   └── CandidateListItem.tsx          # NEW: horizontal list-view card with drag handle
│   ├── hooks/useCandidates.ts             # Add useReorderCandidates mutation
│   ├── routes/threads/$threadId.tsx       # Add view toggle, Reorder.Group, tempItems pattern
│   └── stores/uiStore.ts                  # Add candidateViewMode state
└── tests/
    ├── helpers/db.ts                       # Add sort_order column to CREATE TABLE
    └── services/thread.service.test.ts    # Tests for reorderCandidates()
```

### Pattern 1: framer-motion Reorder with Drag Handle

The `Reorder.Group` fires `onReorder` whenever a drag completes. The `useDragControls` hook
lets the drag be triggered only from the grip icon. Wrap each item with `Reorder.Item` and
attach `dragControls` to it.

```typescript
// Source: framer-motion dist/types/index.d.ts (confirmed in installed v12.37.0)
import { Reorder, useDragControls } from "framer-motion";

// In ThreadDetailPage — list view:
const [tempItems, setTempItems] = useState<Candidate[] | null>(null);
const displayItems = tempItems ?? thread.candidates; // sorted by sort_order from server

<Reorder.Group
  axis="y"
  values={displayItems}
  onReorder={setTempItems}      // updates local order instantly
  className="flex flex-col gap-2"
>
  {displayItems.map((candidate, index) => (
    <CandidateListItem
      key={candidate.id}
      candidate={candidate}
      rank={index + 1}
      isActive={isActive}
      onReorderSave={() => saveOrder(tempItems)}  // called onDragEnd
    />
  ))}
</Reorder.Group>
```

```typescript
// In CandidateListItem — drag handle via useDragControls:
// Source: framer-motion dist/types/index.d.ts
import { Reorder, useDragControls } from "framer-motion";

function CandidateListItem({ candidate, rank, isActive, ... }) {
  const controls = useDragControls();

  return (
    <Reorder.Item value={candidate} dragControls={controls} dragListener={false}>
      <div className="flex items-center gap-3 bg-white rounded-xl border border-gray-100 p-3">
        {/* Drag handle — only visible on active threads */}
        {isActive && (
          <div
            onPointerDown={(e) => controls.start(e)}
            className="cursor-grab active:cursor-grabbing text-gray-300 hover:text-gray-500 touch-none"
          >
            <LucideIcon name="grip-vertical" size={16} />
          </div>
        )}
        {/* Rank badge — top 3 only, visible on resolved too */}
        {rank <= 3 && <RankBadge rank={rank} />}
        {/* ... rest of card content */}
      </div>
    </Reorder.Item>
  );
}
```

**Key flag:** `dragListener={false}` on `Reorder.Item` disables the default "drag anywhere on the item" behavior, restricting drag to the handle only. This is the critical prop for handle-based reordering.

**Key flag:** `touch-none` Tailwind class on the handle prevents scroll interference on mobile (`touch-action: none`).

### Pattern 2: Fractional Indexing for sort_order

Fractional indexing avoids rewriting all rows on every drag. Only the moved item's `sort_order` changes.

```typescript
// Service function — reorderCandidates
// Computes new sort_order as midpoint between neighbors
export function reorderCandidates(
  db: Db,
  threadId: number,
  orderedIds: number[],
): { success: boolean; error?: string } {
  return db.transaction((tx) => {
    // Verify thread is active
    const thread = tx.select().from(threads).where(eq(threads.id, threadId)).get();
    if (!thread || thread.status !== "active") {
      return { success: false, error: "Thread not active" };
    }

    // Fetch current sort_orders keyed by id
    const rows = tx
      .select({ id: threadCandidates.id, sortOrder: threadCandidates.sortOrder })
      .from(threadCandidates)
      .where(eq(threadCandidates.threadId, threadId))
      .all();

    const sortMap = new Map(rows.map((r) => [r.id, r.sortOrder]));
    const sortedExisting = [...sortMap.entries()].sort((a, b) => a[1] - b[1]);

    // Re-assign spaced values in the requested order
    // (Simpler than midpoint for full reorder; midpoint for single-item moves is optimization)
    orderedIds.forEach((id, index) => {
      const newOrder = (index + 1) * 1000;
      tx.update(threadCandidates)
        .set({ sortOrder: newOrder })
        .where(eq(threadCandidates.id, id))
        .run();
    });

    return { success: true };
  });
}
```

**Note:** The CONTEXT.md specifies midpoint-only for single-item moves. For the PATCH endpoint
receiving a full ordered list, re-spacing at 1000 intervals is simpler and still correct.
Midpoint optimization matters if the API receives only (id, position) for a single move —
confirm which approach the planner selects.

### Pattern 3: tempItems Flicker Prevention

React Query refetch after mutation causes a visible reorder "snap back" unless tempItems absorbs the transition.

```typescript
// In ThreadDetailPage:
const [tempItems, setTempItems] = useState<typeof thread.candidates | null>(null);
const displayItems = tempItems ?? thread.candidates; // server data already sorted by sort_order

const reorderMutation = useReorderCandidates(threadId);

function handleReorder(newOrder: typeof thread.candidates) {
  setTempItems(newOrder);
}

function handleDragEnd() {
  if (!tempItems) return;
  reorderMutation.mutate(
    { orderedIds: tempItems.map((c) => c.id) },
    {
      onSettled: () => setTempItems(null),  // clear after server confirms or fails
    }
  );
}
```

### Pattern 4: Drizzle Migration + Data Backfill

Migration must add column AND backfill existing rows with spaced values to avoid all-zero sort_order.

```sql
-- Migration SQL (generated by bun run db:generate):
ALTER TABLE `thread_candidates` ADD `sort_order` real NOT NULL DEFAULT 0;

-- Data backfill SQL (run as separate statement in migration or seed script):
-- SQLite window functions assign rank per thread, multiply by 1000
UPDATE thread_candidates
SET sort_order = (
  SELECT (ROW_NUMBER() OVER (PARTITION BY thread_id ORDER BY created_at)) * 1000
  FROM thread_candidates AS tc2
  WHERE tc2.id = thread_candidates.id
);
```

**SQLite version note:** SQLite supports window functions since version 3.25.0 (2018). Bun
ships with a recent SQLite — this query is safe. Verify with `bun -e "import { Database } from 'bun:sqlite'; const db = new Database(':memory:'); console.log(db.query('SELECT sqlite_version()').get())"`.

### Anti-Patterns to Avoid

- **Drag from anywhere on the card:** Without `dragListener={false}` on `Reorder.Item`, clicking the card to edit it triggers a drag. Always pair with `useDragControls`.
- **Ordering by integer with bulk update:** Updating all rows on every drag is O(n) writes. Use REAL (float) sort_order for midpoint single-update.
- **Storing order in the React Query cache only:** Sort order must persist to the server; local-only ordering is lost on page refresh.
- **Rendering `Reorder.Group` without `layout` on inner elements:** framer-motion needs `layout` prop on animated children to perform smooth gap animation. `Reorder.Item` handles this internally — do not nest another `motion.div` with conflicting layout props.
- **Missing `key` on Reorder.Item:** The key must be stable (candidate.id), not index — framer-motion uses it to track item identity across reorders.

---

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Drag-to-reorder list | Custom mousedown/mousemove/mouseup handlers | `framer-motion` Reorder.Group/Item | Handles pointer capture, scroll suppression, layout animation, keyboard fallback |
| Drag handle restriction | Event.stopPropagation tricks | `useDragControls` + `dragListener={false}` | Official framer-motion API; handles touch events correctly |
| Smooth gap animation during drag | CSS transform calculations | `Reorder.Item` layout animation | Built-in spring physics; other items animate to fill the gap automatically |
| Sort order persistence strategy | Custom complex state | Fractional indexing (REAL column, midpoint) | One write per drop; no full-list rewrite; proven pattern from Linear/Trello |

---

## Common Pitfalls

### Pitfall 1: All-Zero sort_order After Migration
**What goes wrong:** ALTERing the column with `DEFAULT 0` sets all existing rows to 0. `ORDER BY sort_order` returns them in arbitrary order.
**Why it happens:** SQLite sets new column values to the DEFAULT for existing rows.
**How to avoid:** Run the window-function UPDATE backfill as part of the migration or immediately after.
**Warning signs:** Candidates render in seemingly random or creation-id order after migration.

### Pitfall 2: Drag Initiates on Card Click
**What goes wrong:** User clicks to open the edit panel and the card starts dragging instead.
**Why it happens:** `Reorder.Item` defaults `dragListener={true}` — any pointer-down on the item starts dragging.
**How to avoid:** Set `dragListener={false}` on `Reorder.Item` and use `useDragControls` to start drag only from the grip handle's `onPointerDown`.
**Warning signs:** Click on candidate name opens drag instead of edit panel.

### Pitfall 3: React Query Flicker After Save
**What goes wrong:** After `reorderMutation` completes and React Query refetches, candidates visually snap back to server order for a frame.
**Why it happens:** React Query invalidates and refetches; server returns the new order but there's a brief moment where old cache is used.
**How to avoid:** Use `tempItems` local state pattern. Render `tempItems ?? thread.candidates`. Clear `tempItems` in `onSettled` (not `onSuccess`) so it covers both success and error cases.
**Warning signs:** Items visually "jump" after a drop.

### Pitfall 4: touch-none Missing on Drag Handle
**What goes wrong:** On mobile, dragging the grip handle scrolls the page instead of reordering.
**Why it happens:** Browser default: `touch-action` allows scroll on pointer-down.
**How to avoid:** Add `className="touch-none"` (Tailwind) or `style={{ touchAction: "none" }}` on the drag handle element.
**Warning signs:** Mobile drag scrolls page; items don't reorder on touch devices.

### Pitfall 5: Resolved Thread Reorder Accepted by API
**What goes wrong:** A resolved thread's candidates can be reordered if the server does not check thread status.
**Why it happens:** The API endpoint receives a valid payload and processes it without checking `thread.status`.
**How to avoid:** In `reorderCandidates()` service, verify `thread.status === "active"` and return error if not. Match pattern of `resolveThread()` which already does this check.
**Warning signs:** PATCH succeeds on a resolved thread; RANK-05 test fails.

---

## Code Examples

### Zod Schema for Reorder Endpoint
```typescript
// src/shared/schemas.ts — add:
// Source: existing schema.ts patterns in project
export const reorderCandidatesSchema = z.object({
  orderedIds: z.array(z.number().int().positive()).min(1),
});
```

### Shared Type
```typescript
// src/shared/types.ts — add:
export type ReorderCandidates = z.infer<typeof reorderCandidatesSchema>;
```

### Drizzle Schema Column
```typescript
// src/db/schema.ts — in threadCandidates table:
sortOrder: real("sort_order").notNull().default(0),
```

### getThreadWithCandidates ORDER BY Fix
```typescript
// src/server/services/thread.service.ts
// Change the candidateList query to order by sort_order:
.from(threadCandidates)
.innerJoin(categories, eq(threadCandidates.categoryId, categories.id))
.where(eq(threadCandidates.threadId, threadId))
.orderBy(threadCandidates.sortOrder)  // add this
.all();
```

### createCandidate sort_order for New Candidates
```typescript
// src/server/services/thread.service.ts
// New candidates append to bottom — find current max and add 1000:
export function createCandidate(db, threadId, data) {
  const maxRow = db
    .select({ maxOrder: sql<number>`MAX(sort_order)` })
    .from(threadCandidates)
    .where(eq(threadCandidates.threadId, threadId))
    .get();
  const newSortOrder = (maxRow?.maxOrder ?? 0) + 1000;

  return db.insert(threadCandidates).values({
    ...data,
    sortOrder: newSortOrder,
  }).returning().get();
}
```

### Hono PATCH Route
```typescript
// src/server/routes/threads.ts — add:
app.patch(
  "/:id/candidates/reorder",
  zValidator("json", reorderCandidatesSchema),
  (c) => {
    const db = c.get("db");
    const threadId = Number(c.req.param("id"));
    const { orderedIds } = c.req.valid("json");
    const result = reorderCandidates(db, threadId, orderedIds);
    if (!result.success) return c.json({ error: result.error }, 400);
    return c.json({ success: true });
  },
);
```

### useReorderCandidates Hook
```typescript
// src/client/hooks/useCandidates.ts — add:
export function useReorderCandidates(threadId: number) {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (data: { orderedIds: number[] }) =>
      apiPatch<{ success: boolean }>(
        `/api/threads/${threadId}/candidates/reorder`,
        data,
      ),
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ["threads", threadId] });
    },
  });
}
```

### RankBadge Component (inline)
```typescript
// Inline in CandidateListItem or extract as small component
const RANK_STYLES = [
  { color: "#D4AF37", label: "1st" }, // gold
  { color: "#C0C0C0", label: "2nd" }, // silver
  { color: "#CD7F32", label: "3rd" }, // bronze
];

function RankBadge({ rank }: { rank: number }) {
  if (rank > 3) return null;
  const { color } = RANK_STYLES[rank - 1];
  return (
    <LucideIcon
      name="medal"
      size={16}
      className="shrink-0"
      style={{ color }}
    />
  );
}
```

### tests/helpers/db.ts: thread_candidates table update
```sql
-- Add to CREATE TABLE thread_candidates in tests/helpers/db.ts:
sort_order REAL NOT NULL DEFAULT 0,
```

---

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| `react-beautiful-dnd` | framer-motion Reorder | framer-motion v5+ Reorder API | Simpler API, same bundle already present, maintained by Framer |
| Integer sort_order with bulk UPDATE | REAL (float) fractional indexing | Best practice since ~2015 (Linear, Figma) | O(1) writes per drag vs O(n) |
| "Save order" button | Auto-save on drop | UX convention | Reduces friction; matches Trello/Linear behavior |

**Deprecated/outdated:**
- `react-beautiful-dnd`: No longer actively maintained; framer-motion Reorder is the modern replacement in React 18+ projects.

---

## Open Questions

1. **Full-list reorder vs single-item fractional update in PATCH body**
   - What we know: CONTEXT.md says "only the moved item gets a single UPDATE (midpoint between neighbors)" but also says PATCH receives `orderedIds` array
   - What's unclear: If the server receives the full ordered list, re-spacing at 1000-intervals is simpler than computing midpoints server-side
   - Recommendation: Accept full `orderedIds` array in PATCH, re-space all at 1000-intervals; this is correct and simpler. Midpoint is only an optimization for very large lists (not relevant here).

2. **View toggle persistence scope**
   - What we know: CONTEXT.md says use Zustand `candidateViewMode` for view toggle
   - What's unclear: Whether to also persist in `localStorage` across page refreshes
   - Recommendation: Zustand in-memory only (resets to list on refresh) is sufficient; no localStorage needed unless user reports preference loss as pain point.

---

## Validation Architecture

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

### Phase Requirements → Test Map
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| RANK-01 | `reorderCandidates()` updates sort_order in DB in requested sequence | unit | `bun test tests/services/thread.service.test.ts` | ❌ Wave 0 (new test cases) |
| RANK-01 | `PATCH /api/threads/:id/candidates/reorder` returns 200 + reorders candidates | integration | `bun test tests/routes/threads.test.ts` | ❌ Wave 0 (new test cases) |
| RANK-02 | Rank badge rendering logic (index → medal color) | unit (component logic) | `bun test` | Manual-only — no component test infra |
| RANK-04 | `getThreadWithCandidates` returns candidates ordered by sort_order ascending | unit | `bun test tests/services/thread.service.test.ts` | ❌ Wave 0 |
| RANK-05 | `reorderCandidates()` returns error when thread is resolved | unit | `bun test tests/services/thread.service.test.ts` | ❌ Wave 0 |
| RANK-05 | `PATCH /api/threads/:id/candidates/reorder` returns 400 for resolved thread | integration | `bun test tests/routes/threads.test.ts` | ❌ Wave 0 |

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

### Wave 0 Gaps
- [ ] New test cases in `tests/services/thread.service.test.ts` — covers RANK-01, RANK-04, RANK-05 service behavior
- [ ] New test cases in `tests/routes/threads.test.ts` — covers RANK-01, RANK-05 route behavior
- [ ] Update `tests/helpers/db.ts` CREATE TABLE for `thread_candidates` to add `sort_order REAL NOT NULL DEFAULT 0`

---

## Sources

### Primary (HIGH confidence)
- framer-motion `dist/types/index.d.ts` (v12.37.0 installed) — `Reorder.Group`, `Reorder.Item`, `useDragControls`, `dragListener` prop confirmed
- `src/client/lib/api.ts` — `apiPatch` confirmed available
- `src/client/lib/iconData.tsx` + lucide-react installed — `medal`, `grip-vertical`, `layout-list`, `layout-grid` icons confirmed via `bun -e` introspection
- `src/db/schema.ts` — current schema confirmed; `sort_order` column absent (needs migration)
- `tests/helpers/db.ts` — CREATE TABLE confirmed; needs `sort_order` column added
- `src/server/services/thread.service.ts` — `resolveThread()` pattern for status check reused in `reorderCandidates()`
- `.planning/phases/11-candidate-ranking/11-CONTEXT.md` — all locked decisions applied

### Secondary (MEDIUM confidence)
- framer-motion Reorder documentation patterns (consistent with installed type definitions)
- Fractional indexing / REAL sort_order pattern well-established in Linear, Trello, Figma implementations

### Tertiary (LOW confidence)
- None

---

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH — all libraries confirmed installed and API-verified from local node_modules
- Architecture: HIGH — patterns derived from existing codebase + confirmed framer-motion type signatures
- Pitfalls: HIGH — derived from direct API analysis (dragListener, touch-none) and known SQLite migration behavior

**Research date:** 2026-03-16
**Valid until:** 2026-04-16 (stable dependencies; framer-motion Reorder API is mature)