familysync/.planning/phases/04-shared-lists-live-sync/04-05-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, user_setup, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	user_setup	must_haves
04-shared-lists-live-sync	05	execute	4	04-04	apps/pwa/src/routes/ListDetail.tsx apps/pwa/src/components/ItemRow.tsx apps/pwa/src/api/listsClient.ts apps/api/src/lib/rank.test.ts apps/api/tests/routes/lists.test.ts	true	LIST-03		truths artifacts key_links A member can drag an active item to a new position and the order persists A reorder writes only the moved item's rank (one-row write), not a renumber Touch drag requires a deliberate long-press on the handle (no accidental drags while scrolling) A reorder arriving from another member animates to the new position rather than hard-snapping (D-14) path provides contains apps/pwa/src/components/ItemRow.tsx dnd-kit sortable item with drag handle useSortable path provides contains apps/pwa/src/routes/ListDetail.tsx DndContext/SortableContext over active items with onDragEnd → rank PATCH DndContext from to via pattern apps/pwa/src/routes/ListDetail.tsx PATCH /api/list-items/:id { position } onDragEnd computes generateKeyBetween + optimistic patch generateKeyBetween|position from to via pattern apps/pwa/src/components/ItemRow.tsx @dnd-kit/sortable useSortable handle listeners useSortable

Deliver the drag-to-reorder vertical slice (LIST-03): a member can drag an active item to a new position using @dnd-kit, and the move persists as a single-row fractional-rank write (D-13). Touch drag requires a 200ms long-press on the handle (no accidental drags); concurrent reorders converge via last-write-wins (D-15); and a reorder that arrives from another member animates to its new position rather than hard-snapping (D-14).

MVP slice: after this plan a real user can reorder list items — the last interactive capability of the lists surface — building directly on the items rendered in Plan 04.

Purpose: Layer drag-and-drop and client-side fractional-rank computation onto the existing ItemRow/ListDetail, reusing the server-side per-field position PATCH already built in Plan 04. Output: dnd-kit DndContext/SortableContext in ListDetail; sortable ItemRow with handle-scoped listeners + sensors; client computes the new rank via generateKeyBetween and PATCHes position optimistically.

<execution_context> @$HOME/.claude/gsd-core/workflows/execute-plan.md @$HOME/.claude/gsd-core/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/phases/04-shared-lists-live-sync/04-CONTEXT.md @.planning/phases/04-shared-lists-live-sync/04-RESEARCH.md @.planning/phases/04-shared-lists-live-sync/04-PATTERNS.md @.planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md @.planning/phases/04-shared-lists-live-sync/04-VALIDATION.md Task 1: Sortable ItemRow + DndContext reorder with optimistic rank PATCH (LIST-03, D-13/D-14/D-15) apps/pwa/src/components/ItemRow.tsx, apps/pwa/src/routes/ListDetail.tsx, apps/pwa/src/api/listsClient.ts - apps/pwa/src/components/ItemRow.tsx (from Plan 04 — add useSortable; handle slot already present) - apps/pwa/src/routes/ListDetail.tsx (active-items rendering from Plan 04) - apps/pwa/src/api/listsClient.ts (patchListItem supports { position }) - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md Finding 7 (dnd-kit + handle + sensors + rank-on-drop) - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"ItemRow.tsx" - .planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md §"Drag-to-Reorder", §"Accessibility Baseline" (keyboard reorder) Make ItemRow sortable: use useSortable({ id: item.id }) from @dnd-kit/sortable; attach setNodeRef + style (CSS.Transform.toString(transform), transition fallback 'transform 150ms ease-out' for D-14 remote animation, opacity 0.8 + slight scale-down when isDragging). Attach drag listeners to the GripVertical handle button ONLY (not the whole row) so taps on checkbox/text/delete still work. Drag handle only on active items (completed items not reorderable per UI-SPEC).

In ListDetail, wrap the active-items list in DndContext (collisionDetection={closestCenter}) + SortableContext (items = active item ids, verticalListSortingStrategy). Configure sensors via useSensors: PointerSensor/MouseSensor immediate, TouchSensor with activationConstraint { delay: 200, tolerance: 5 } (no accidental drags), and KeyboardSensor for the accessibility keyboard-reorder fallback.

onDragEnd: ignore no-op (no over / same id). Compute the destination index after the move; derive prevRank/nextRank from the active list at the destination and compute newRank = generateKeyBetween(prevRank, nextRank) (fractional-indexing). Fire an optimistic reorder mutation: setQueryData(['list', listId]) to reflect the new order immediately (snap), then patchListItem(itemId, { position: newRank }); onError animate back / rollback to previous; onSettled invalidate. Only the moved item's rank is written (one-row PATCH — D-13). Concurrent same-item reorder converges by server LWW on updatedAt (D-15) — no drag-state broadcasting.

pnpm --filter @familysync/pwa exec tsc --noEmit && grep -q "useSortable" apps/pwa/src/components/ItemRow.tsx && grep -q "DndContext" apps/pwa/src/routes/ListDetail.tsx && grep -q "generateKeyBetween" apps/pwa/src/routes/ListDetail.tsx - ItemRow uses useSortable with listeners on the handle only; completed items have no handle. - ListDetail wraps active items in DndContext/SortableContext with Pointer/Touch(delay 200)/Keyboard sensors. - onDragEnd computes newRank via generateKeyBetween and issues a single-item position PATCH optimistically with rollback. - PWA typecheck passes. - Browser check (`playwright-cli`): drag an item to a new position; the new order persists after a reload (rank written). Record in SUMMARY. (Touch long-press + keyboard reorder are dnd-kit built-ins; note manual/device coverage where playwright cannot simulate long-press reliably.) User can drag-reorder active items; move persists as a one-row rank write; remote reorders animate. Task 2: Strengthen server-side reorder ordering tests (LIST-03, D-13) apps/api/src/lib/rank.test.ts, apps/api/tests/routes/lists.test.ts - apps/api/src/lib/rank.test.ts (from Plan 04) - apps/api/tests/routes/lists.test.ts (PATCH position coverage) - .planning/phases/04-shared-lists-live-sync/04-VALIDATION.md (LIST-03 row: "PATCH new rank produces correct fractional order") - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md §"Common Pitfalls" Pitfall 2 (precision) Add server-side tests proving reorder correctness: (a) repeated mid-point inserts via rankBetween produce strictly increasing distinct strings over many iterations (precision does not collapse — Pitfall 2); (b) PATCH /api/list-items/:id { position } updates only rank and a subsequent GET returns items in the new ASC order; (c) moving an item between two neighbors yields a rank strictly between theirs. These align the LIST-03 row in 04-VALIDATION.md to a green automated check. No production behavior change — Plan 04 already implements the PATCH position path. pnpm --filter @familysync/api exec vitest run src/lib/rank.test.ts tests/routes/lists.test.ts - LIST-03 ordering test ("PATCH new rank produces correct fractional order") is present and green. - Mid-point-insert precision test passes for many iterations. Server-side reorder ordering + rank precision are covered by green automated tests.

<threat_model>

Trust Boundaries

Boundary	Description
browser → PATCH /api/list-items/:id { position }	client supplies the new rank string — untrusted

STRIDE Threat Register

Threat ID	Category	Component	Disposition	Mitigation Plan
T-04-07	Tampering	client sending position alongside other fields	mitigate	zod patchItemSchema refine (exactly one field) already enforces position-only PATCH (Plan 04); reasserted by tests
T-04-05	Elevation of Privilege	reordering items in an inaccessible list	mitigate	PATCH list-items access-gated (owner OR list_shares) from Plan 04
T-04-10	Denial of Service	pathological "zipper" inserts growing rank strings	accept	VARCHAR(255) headroom; fractional-indexing degrades gracefully; rebalance available via generateNKeysBetween if ever needed (not in scope)
</threat_model>

pnpm --filter @familysync/api exec vitest run src/lib/rank.test.ts tests/routes/lists.test.ts && pnpm --filter @familysync/pwa exec tsc --noEmit - `playwright-cli`: drag-reorder persists across reload.

<success_criteria>

• LIST-03 satisfied: drag-to-reorder works, persists as a single-row rank write.
• Touch long-press + keyboard reorder available; remote reorders animate (D-14).
• Reorder ordering + precision covered by automated tests. </success_criteria>

<artifacts_produced> Symbols/files this plan creates (exclude from drift verification):

• ItemRow gains useSortable + handle-scoped drag listeners
• ListDetail gains DndContext/SortableContext + useSensors + onDragEnd rank computation
• Additional rank/order tests in rank.test.ts and lists.test.ts (no new production endpoints — reuses Plan 04 PATCH position) </artifacts_produced>

Create `.planning/phases/04-shared-lists-live-sync/04-05-SUMMARY.md` when done.