fusion/docs/research-view-ux-spec.md

# Research view UX spec: layout and capability-state messaging

## Status
- **Task:** FN-4138
- **Purpose:** Consolidate the Research view UX requirements behind the known layout/rendering defects (FN-4134) and misleading web-search messaging defects (FN-4135).
- **Scope of this document:** Product/UX specification only. No source changes are made by this task.

## Source inputs and constraints

Reviewed inputs:
- `packages/dashboard/app/components/ResearchView.tsx`
- `packages/dashboard/app/components/ResearchView.css`
- `packages/dashboard/app/hooks/useResearch.ts`
- `packages/dashboard/app/components/__tests__/ResearchView.test.tsx`
- `packages/core/src/research-settings.ts`
- `packages/core/src/types.ts`
- `packages/core/src/settings-schema.ts`
- `docs/settings-reference.md`
- `AGENTS.md` dashboard styling guidance

Important current-state constraint:
- `.fusion/tasks/FN-4134/PROMPT.md` and `.fusion/tasks/FN-4135/PROMPT.md` were not present in this worktree, and board lookup did not return resolvable task records in this execution context. This spec therefore treats the current code, tests, and repo documentation as the source of truth and calls out any implementation notes that FN-4134/FN-4135 executors must reconcile.

## Problem statement

The Research view currently mixes two unrelated defect classes:

1. **Visual/layout defects**
   - The view has an under-specified large-screen scroll model and a crowded reader card structure.
   - Long selected-run content, findings, citations, events, action rows, and the stats block all live in the same reader card without a defined internal layout contract.
   - The sidebar/history column and reader column do not have equally explicit independent scroll behavior.

2. **Capability-state messaging defects**
   - The current `setupState` branch collapses multiple causes into one blocking error-style card: unavailable subsystem, disabled research, and missing provider credentials all render through `data-testid="research-state-unavailable"`.
   - This makes the UI too binary and too error-toned for cases where research is enabled but one capability is degraded.
   - The long-term direction from the existing code/tests/settings is that web search is **always on** and should never be described as disabled when it is functioning.

These two defect classes must be implemented and tested separately even though they affect the same screen.

## Current implementation baseline

### Existing selectors and structure

Current `ResearchView.tsx` exposes these stable selectors that implementation should preserve unless explicitly noted otherwise:
- `research-state-unavailable`
- `research-state-loading`
- `research-state-error`
- `research-state-empty`
- `research-state-results`
- `research-state-running`

Current structural classes that this spec references:
- `.research-view`
- `.research-view__header`
- `.research-view__layout`
- `.research-view__sidebar`
- `.research-view__reader`
- `.research-view__history`
- `.research-view__status-row`
- `.research-view__actions`
- `.research-view__findings`
- `.research-view__stats`

### Important current-state notes

- `resolveResearchSettings()` hard-codes `enabledSources.webSearch: true`.
- `ResearchView.tsx` hard-locks the `web-search` provider on (`providerLocked`), and the checkbox label reads `Web Search (always on)`.
- There is **no live `webSearchExplicitlyDisabled` branch** in the current component.
- There is **no live `data-testid="research-state-web-search-disabled"` element** in the current component. The only in-repo reference is a negative regression assertion in `ResearchView.test.tsx`.
- `research-state-running` is currently attached to the history-list container, not to a lifecycle-status element. Because existing tests may depend on it, implementers should preserve it for now unless they update tests deliberately in the same task.

## Defect inventory

### A. Visual/layout defects

Observed from the current structure/CSS:
- The reader card does not define a dedicated content body plus footer contract; selected-run details and stats are simply stacked in one column.
- Long content can crowd the stats block because `.research-view__reader` has no dedicated inner scrolling region for the selected-run content.
- Only `.research-view__history` explicitly scrolls; the reader panel does not have an equally explicit desktop/tablet scroll region.
- `.research-view__actions` allows unrestricted wrapping, so multi-button rows can fragment into visually noisy stacks around the summary/findings area.
- The mobile stack direction is clear, but the intended order and bottom-spacing behavior are not documented as UX requirements.

### B. Capability-state messaging defects

Observed from the current `setupState` behavior:
- `availability.available === false`, `effectiveSettings.enabled === false`, and `missingCredentialProvider` all funnel into the same blocking card and error styling.
- Disabled research and degraded provider availability are not currently distinguished with different UX tone.
- The card includes low-value implementation-detail copy (`Current defaults: provider ..., max sources ...`) that should not appear in primary state messaging.
- The common case must not show any copy that implies web search is disabled or unavailable when the working backend is available.

## Capability-state model

The implementation must explicitly support these three states and no ambiguous fourth state.

### State A — Research disabled

**Trigger**
- `researchSettings.enabled === false`, or
- the merged effective research-enabled flag resolves false (`researchEnabled === false` / equivalent global fallback), or
- the subsystem is intentionally disabled for the project/runtime.

**Expected UX**
- If the experimental Research view feature itself is disabled, the Research nav entry may remain hidden as it does today.
- If the Research view is reachable but research is disabled, render a **single empty-state or setup-state card only**.
- Do **not** render the query form, provider checkboxes, history sidebar, results reader, or stats block.
- Tone is informational, not error-first.
- Primary CTA links directly to **Settings → Research** (`research-project`, or the relevant research settings section if global disablement is what the implementation exposes).

**Approved copy**
- Title/body copy allowed:
  - `Research is turned off for this project. Enable it in Settings → Research.`
- Optional CTA label:
  - `Open Research Settings`

**Disallowed copy**
- `Current defaults: provider ..., max sources ...`
- Any error-style wording implying the system is broken rather than turned off.

**Required test markers**
- Must appear: `research-state-unavailable`
- Must not appear: `research-state-empty`, `research-state-results`, query field, provider checklist, run-history list

### State B — Research enabled, web search unavailable

**Trigger**
- Research is enabled, but the active web-search backend is not currently usable at runtime.
- Valid causes include:
  - auth failure for the chosen backend,
  - connectivity/provider outage,
  - runtime missing required backend config,
  - any other true availability failure from the backend layer.

**Important rule**
- After FN-4135, this state must be driven by a **real runtime availability signal**, not by a user selecting a “disable web search” option.
- The settings model already points in this direction: `researchGlobalWebSearchProvider` selects a backend, while web search itself remains conceptually on.

**Expected UX**
- The view still renders normally.
- Query form, provider list, history list, reader, and stats remain available.
- The web-search provider row remains visible and reflects the real state.
- Show a **non-blocking advisory** near the provider controls or directly above the create-run form.
- The advisory explains what is unavailable, why, and how to fix it.
- Other usable research sources remain available.
- Do **not** replace the whole view with the blocking `research-state-unavailable` card for this state.

**Approved copy**
- `Web search is currently unreachable ({provider}). Other sources will still run. Open Settings → Research to review provider setup.`
- If the failure is specifically auth-related and the implementation can distinguish it:
  - `Web search is currently unreachable ({provider}) because its credentials are missing or invalid. Other sources will still run. Open Settings → Research.`

**Disallowed copy**
- `Web search is disabled`
- `Web search not enabled`
- Any copy that suggests the user intentionally turned web search off
- Any copy that blocks the full screen when other sources are still usable

**Required test markers**
- Must appear: normal form UI, provider checklist, `research-state-running` history container when runs exist
- Must not appear: full-screen `research-state-unavailable` card used for disabled research
- If implementation adds a dedicated advisory marker, it should be additive and tested directly, but existing selectors above must remain stable

### State C — Web search enabled and available

**Trigger**
- Research is enabled and the active web-search backend is available.
- This is the expected/common case.

**Expected UX**
- No disabled-state card.
- No warning/advisory banner.
- Web-search provider checkbox is visible, checked, and not presented as unavailable.
- Normal empty/loading/results states render as applicable.

**Approved copy**
- No capability warning copy.

**Disallowed copy**
- Any variant of `Web search is disabled`
- Any variant of `Web search not enabled`
- Any warning that contradicts the working backend state

**Required test markers**
- Must not appear: `research-state-unavailable`
- Must not appear: any dedicated web-search-unavailable advisory marker
- May appear depending on state: `research-state-loading`, `research-state-empty`, `research-state-results`

## Copy requirements

### Approved state copy

Only the following capability-state messaging is allowed:

- **State A**
  - `Research is turned off for this project. Enable it in Settings → Research.`
- **State B**
  - `Web search is currently unreachable ({provider}). Other sources will still run. Open Settings → Research to review provider setup.`
- **State C**
  - No capability-state message

### Copy rules

- Sentence case only.
- End full-sentence informational copy with a period.
- Use `Settings → Research` as the preferred path label in body copy.
- Use concise CTA labels (`Open Research Settings`, `Open Settings`) consistent with neighboring dashboard patterns.
- Do not expose implementation-detail diagnostics in the main empty/setup card unless they are intentionally placed in secondary expandable help.

### Long-term FN-4135 rule

Once FN-4135 lands, state B must never be triggered by a settings choice that conceptually disables web search. It may only be triggered by a real runtime/availability failure.

## Responsive and layout expectations

### Desktop (>= 1024px)

Required behavior:
- Two-column layout remains: history sidebar + reader.
- Sidebar and reader have **independent scroll regions**.
- No element overlaps another.
- Reader content has a clear vertical structure:
  1. status row
  2. run title/query/summary
  3. action row
  4. findings/citations/history content
  5. stats block anchored after content within the reader flow without colliding with the content above
- Action buttons should fit on one row at common desktop widths unless the viewport is unusually narrow.
- The history sidebar search and run list remain usable without affecting reader scroll.

### Tablet (769px–1024px)

Required behavior:
- Preserve the two-column structure.
- Sidebar may narrow or condense, but must remain readable/selectable.
- Reader actions may wrap to a second row only if needed; they must not visually merge with the status row.
- No overlap, clipping, or footer collisions are permitted.

### Mobile (<= 768px)

Required behavior:
- Single-column stack.
- Sidebar content appears **above** the reader.
  - Rationale: create-run controls and history selection are the primary navigation affordances on mobile and should remain first in flow.
- Use page-level vertical scrolling.
- Preserve bottom padding with the safe-area pattern:
  - `var(--mobile-nav-height)`
  - `env(safe-area-inset-bottom, 0px)`
  - `var(--standalone-bottom-gap)`
- All interactive elements must meet the existing mobile target standard from `AGENTS.md` (minimum 36px, with existing shared touch-target conventions where applicable).
- Stats collapse to a single column.
- Button groups may stack, but spacing must remain consistent and readable.

## Styling/token requirements

Implementation must use existing dashboard tokens only.

Required token families:
- spacing: `--space-*`
- radius: `--radius-*`
- color/text/surface/border tokens: `--color-*`, `--text*`, `--surface`, `--card`, `--border`
- transitions/focus/shadows where applicable: existing shared token set from `AGENTS.md`

Implementation must not:
- introduce hardcoded colors,
- introduce hardcoded spacing that duplicates tokenized values,
- bypass the established mobile bottom-padding pattern,
- replace existing shared button/card/input styling with one-off primitives.

## Selector preservation requirements

To protect the existing test surface, FN-4134/FN-4135 implementations should preserve these current selectors unless the same task updates the tests intentionally:
- `research-state-unavailable`
- `research-state-loading`
- `research-state-error`
- `research-state-empty`
- `research-state-results`
- `research-state-running`

Implementation note:
- `research-state-running` is semantically misnamed today because it is attached to the history list container rather than a running-state indicator. Preserve it for compatibility first; rename only if the implementation task updates tests at the same time.

## Acceptance criteria

### Visual/layout AC (maps to FN-4134)

Pass/fail requirements:
- **Desktop symptom 1:** the header block and the Refresh button never overlap or force content underneath them.
- **Desktop symptom 2:** the history sidebar and reader are simultaneously visible as two columns, and scrolling the run list does not move the reader content unexpectedly.
- **Desktop symptom 3:** long findings/citations/run-history content does not visually collide with the stats block at the bottom of the reader card.
- **Desktop symptom 4:** the status row remains visually separate from the action buttons; export/cancel/retry controls do not wrap upward into the status row.
- **Tablet symptom 1:** the two-column layout remains intact through the 769px–1024px range; the sidebar may narrow, but it does not collapse under or over the reader.
- **Tablet symptom 2:** wrapped action buttons remain in their own row group and do not clip the summary or findings content.
- **Mobile symptom 1:** the view becomes a single-column stack with sidebar above reader.
- **Mobile symptom 2:** page-level scrolling works end to end, with the final content still readable above the mobile-nav/safe-area bottom padding.
- **Mobile symptom 3:** stats collapse to one column and do not sit beside or overlap findings/history content.
- The implementation uses dashboard design tokens rather than hardcoded pixel/color values.
- The mobile bottom-padding safe-area pattern remains intact.
- Existing CSS-fixture-based regression coverage is preserved and expanded as needed for the finalized layout contract.

Required regression coverage:
- CSS-fixture assertion for `.research-view__layout` desktop grid structure (`display: grid` and `grid-template-columns: minmax(0, 1fr) minmax(0, 2fr)`).
- CSS-fixture assertion for the mobile media-query stack (`.research-view__layout` switches to a single-column/flex stack at `max-width: 768px`).
- CSS-fixture assertion for `.research-view` mobile scroll behavior and safe-area bottom padding using `var(--mobile-nav-height)`, `env(safe-area-inset-bottom, 0px)`, and `var(--standalone-bottom-gap)`.
- Targeted regression coverage for the finalized reader/scroll contract and any action-row wrapping rules added by FN-4134.

### Capability-state messaging AC (maps to FN-4135 plus this spec)

Pass/fail requirements:
- State A, B, and C are implemented as distinct, testable behaviors.
- Disabled research (state A) renders a single informational setup/empty state with approved copy and settings CTA.
- Web-search unavailability (state B) renders as a non-blocking advisory inside the normal view, not as a full-screen unavailable card.
- Working web search (state C) renders with no contradictory warning or disabled-state messaging.
- No approved UI string may say `web search is disabled` or `web search not enabled` when the backend is functioning.
- The current full-screen unavailable card is not used for the common working case.
- A regression test proves that the component never renders `data-testid="research-state-web-search-disabled"` when web search is functionally available, whether or not FN-4135 reintroduces a dedicated advisory marker during refactoring.
- The always-on web-search behavior stays aligned with Settings → Research, which already shows a non-editable Web Search row with `Always on` help text; ResearchView copy must not contradict that settings IA.
- Once FN-4135 removes any conceptual “disable web search” option, state B is only driven by real runtime availability failures.

## Task breakdown recommendation

### Recommendation: ship as two sequenced tasks

Recommended order:
1. **FN-4134 first** — layout/rendering contract
2. **FN-4135 second** — capability-state messaging/runtime-availability cleanup

### Rationale

These should remain separate because they have different implementation pressure:
- FN-4134 is primarily CSS/JSX layout behavior and visual regression coverage.
- FN-4135 is primarily state modeling, settings/capability interpretation, copy, and view-branch cleanup.
- They have different test surfaces.
- Sequencing the layout work first gives the messaging cleanup a stable visual baseline.
- Keeping them separate reduces review noise and avoids mixing responsive/UI structure changes with capability-state semantics.

## Implementation notes: gaps and task-alignment checks

The current codebase reveals one UX gap that neither referenced implementation task description is guaranteed to cover unless called out explicitly:

1. **State A vs. State B separation is not present today**
   - `ResearchView.tsx` currently routes disabled research, subsystem unavailability, and missing credentials through the same `setupState` card.
   - FN-4135 should explicitly own the split between:
     - true disabled state (blocking, single-card)
     - degraded runtime availability state (non-blocking advisory)

2. **Runtime availability signal for state B is not present in the current view contract**
   - `ResearchAvailability` currently exposes `available`, `code`, `reason`, `setupInstructions`, `supportedProviders`, and `supportedExportFormats`.
   - It does not currently expose a dedicated “web search available/unavailable but research still usable” signal.
   - FN-4135 must explicitly introduce or derive that signal from real runtime/backend failure handling rather than inferring it from provider selection alone.

3. **Settings IA is already partially aligned and must stay aligned**
   - `SettingsModal.tsx` already renders a non-editable `Web Search` source row in project Research settings with helper text: `Always on. The resolver ignores any older persisted enabledSources.webSearch=false value.`
   - FN-4135 should treat that settings row as the IA baseline and ensure ResearchView capability messaging matches it.

4. **Historical phantom selector reference**
   - `research-state-web-search-disabled` is not present in the live component.
   - If FN-4135 introduces a dedicated advisory marker, it should do so intentionally and update tests in the same task.
   - Until then, executors should treat the existing negative test reference as a regression intent, not as proof of a current DOM node.

### Task-alignment checks

- **FN-4134 alignment:** The layout portion of this spec is intentionally scoped to `ResearchView.tsx`/`ResearchView.css` structure, responsive behavior, and test coverage. That aligns with the existing repo evidence for FN-4134 as a rendering/layout task.
- **FN-4135 alignment:** The capability-state portion of this spec is intentionally scoped to research settings interpretation, capability messaging, and Research view branch behavior. That aligns with the existing repo evidence for FN-4135 as a web-search/default-state cleanup task.
- **Execution-context caveat:** In this task run, the sibling task `PROMPT.md` files were not readable from `.fusion/tasks/`, so the alignment statement above is based on current source/tests plus the repo's own references to FN-4134/FN-4135. If those sibling prompts contain narrower file-scope language, this spec should win for UX intent and the implementation task should note any required scope reconciliation in its own execution log.
- **Settings IA note:** Project Research settings already expose a non-editable `Web Search` row with `Always on` helper text. ResearchView capability copy must stay consistent with that settings language rather than reintroducing any “disabled” framing.

## Documentation/index update requirement

Add this document to `docs/README.md` under a fitting section when landing the spec. Because this is a canonical UX spec for future implementation tasks, it belongs in the docs index.