# V1-AWEB-094 — Queue List + Detail Composition Redesign Spec

Implementation spec for the Phase 17.10 redesign of admin queue list / detail
composition. Goal: **triage, inspection, and action-taking require less context
switching**. Today every queue ships its own list shape and every detail panel
ships its own column layout; the redesign defines a single canonical composition
that the existing panels migrate to.

## Reference: as-is composition

Queue surfaces (per `V1_AWEB_092_REDESIGN_INVENTORY.md`):

- `/inbox` (`UnifiedInboxPanel`), `/review` (`ReviewPackageList` +
  `KeyboardTriageReviewPanel`), `/research-integrity`
  (`ResearchIntegrityQueuePanel` + `CitationValidationWorkspacePanel`),
  `/privacy` (`PrivacyRequestQueuePanel`), `/support` (`SupportCaseInboxPanel`),
  `/trust-safety` (`AppealQueueList` + 10 other lists), `/rights`
  (`RightsProvenancePanel` queue).

Detail surfaces:

- `/review/[reviewId]` (12-panel stack: package detail + blockers + stage
  graph + history + high-risk approval + SLA timer + copilot
  - decision actions + delegation + template + audit log + entity comments +
    entity links).
- `/incidents` (`IncidentDetailPanel` + impact comms + runbook postmortem).

### As-is pain points

1. **List ↔ detail context loss.** Clicking a queue row navigates to a detail
   route; back navigation drops the queue's filter state and scroll position.
2. **Per-row action drawers are inconsistent.** Some lists open a modal, some
   inline-expand, some push to a detail route.
3. **Detail-route stack overload.** `/review/[reviewId]` mounts 12 panels
   vertically; the operator scrolls 4–5 screens to find the decision actions on
   a busy review.
4. **No persistent decision rail.** The decision actions
   (approve/reject/escalate) live below the fold of a review detail page;
   operators must scroll to take action.
5. **No comparison view convention.** Comparative-text reviews today render as a
   vertical card pair inside `ResearchComparativePromotionPanel`; the design
   language for left/right comparison is not formalised.

## Design principles

1. **Triage and inspect on the same screen.** Default to a master-detail split
   (queue on the left, active detail on the right) rather than a navigation
   jump.
2. **Action rail is always reachable.** A right-edge action rail pins decision
   actions to the viewport on detail pages.
3. **Navigate without losing filter state.** Filter + sort + search state is
   encoded in the URL hash on every queue route so reload + back-navigation
   restore the operator's view.
4. **One drawer pattern, one modal pattern.** Drawers for inline inspection,
   modals for destructive confirmation, never both for the same flow.
5. **Comparison is a first-class layout.** A canonical 2-up comparison wrapper
   (`<CompareView left={...} right={...} />`) for diff / compare surfaces.

## Master-detail split

Every queue route renders a master-detail split when the viewport is ≥1280px
wide; below 1280px the existing single-column layout stays. The split uses CSS
grid:

```
.queueDetailSplit {
  display: grid;
  grid-template-columns: minmax(380px, 0.4fr) 1fr;
  gap: 0.85rem;
}
```

The queue panel (left) renders the existing list as-is. The detail panel (right)
renders the panel that the active row maps to. Clicking a row updates the URL
hash to `#detail=<entity-id>`; the detail panel reads the hash on mount and
re-renders.

For routes that today push to a separate detail route (`/review` →
`/review/[reviewId]`), the detail route remains the canonical permalink but the
master-detail split renders the same detail panels on `/review` directly when an
entity id is in the hash.

## Action rail

Every detail panel that ships decision actions renders them in a right-edge
sticky rail (`<aside>` with
`position: sticky; top: 64px; align-self: start; width: 280px;`). The rail is
collapsed below 1280px (actions move inline at the bottom of the panel).

## Filter / sort / search state in URL

Every queue panel reads + writes its filter state to the URL hash via a shared
`useAdminQueueState()` hook (new). The hook serialises filter + sort + search
into a hash like
`#filter=status:open,priority:critical&sort=sla_due_at&q=billing`.

Routes that already have saved-view surfaces (`/review` with
`ReviewSavedViewsSurface`) layer the saved view as a base on top of which the
URL hash overrides apply.

## Drawer + modal patterns

- **Inline drawer:** for read-only inspection of a row's evidence / metadata.
  Slides in from the right of the queue panel, doesn't navigate. Used for
  citation evidence, incident timeline preview, persona governance preview.
- **Modal:** for destructive confirmation only (revoke consent, block content,
  force-resolve incident). Modal traps focus, requires explicit `Cancel` or
  `Confirm` action.

The redesign deletes the existing inconsistent drawer / modal implementations in
favour of two shared components: `AdminInlineDrawer.tsx` and
`AdminConfirmationModal.tsx`.

## Comparison view

`<AdminCompareView left={...} right={...} />` (new component) renders two
columns with synchronised scroll, optional diff highlighting on a per-segment
basis, and a centre column for operator notes / verdict UI. The
`ResearchComparativePromotionPanel` comparative-text section migrates to this
wrapper.

## Implementation deliverables

1. `apps/oshun/admin/src/lib/use-admin-queue-state.ts` — `useAdminQueueState()`
   hook with serialise/parse helpers.
2. `apps/oshun/admin/src/components/AdminInlineDrawer.tsx` + `.module.css`.
3. `apps/oshun/admin/src/components/AdminConfirmationModal.tsx` + `.module.css`.
4. `apps/oshun/admin/src/components/AdminCompareView.tsx` + `.module.css`.
5. Migration: `UnifiedInboxPanel`, `ReviewPackageList`,
   `ResearchIntegrityQueuePanel`, `PrivacyRequestQueuePanel`,
   `SupportCaseInboxPanel`, `AppealQueueList` adopt the master-detail split +
   URL hash queue state.
6. Migration: `ReviewDecisionActions` becomes the canonical action rail content
   for `/review/[reviewId]`.
7. Tests: queue-state hook unit test (parse + serialise round trip with edge
   cases), `AdminInlineDrawer` + `AdminCompareView` component tests,
   master-detail Playwright spec.

## Out of scope

- Multi-row select + bulk action surface (covered by V1-AWEB-099 + V1-AWEB-100).
- Saved view editor redesign (covered by V1-AWEB-096).
- Severity / SLA visuals (covered by V1-AWEB-098).

## Acceptance criteria

- All 7 named queue panels render the master-detail split at ≥1280px and degrade
  gracefully below 1280px.
- Filter + sort + search state round-trips through the URL hash.
- Decision actions on `/review/[reviewId]` render in the right- edge action rail
  (sticky) at ≥1280px.
- Drawers used for inline inspection only; modals used for destructive
  confirmation only — no mixed usage.
- The comparative-text section of `ResearchComparativePromotionPanel` renders
  inside `AdminCompareView`.
- All existing panel tests stay green; the new tests above pass.
