# Plan 04-03: Validation UI and Recovery Experience

**Wave:** 2  
**Phase:** 4  
**Requirements addressed:** MODL-01, MODL-02

---

## Objective

Implement inline validation UI and recovery guidance so users can understand and fix invalid model-source combinations before applying changes.

---

## Read First

- `tauri-app/src/features/runtime/components/RuntimeSettingsDrawer.tsx` — settings form UI
- `tauri-app/src/features/runtime/runtime-settings-form.ts` — form state and validation
- `tauri-app/src/features/runtime/types.ts` — RuntimeDraftFieldMeta, RuntimeWorkspaceHealth
- `.planning/phases/04-model-source-validation/04-RESEARCH.md` — recovery guidance patterns

---

## Action

1. **Add validation message component** in the settings drawer:

   Create or extend a validation message display:
   
   ```typescript
   interface ValidationMessageProps {
     field: RuntimeDraftFieldKey;
     fieldState: RuntimeDraftFieldMeta;
     tone?: "warning" | "danger";
   }
   
   // Render below the relevant form field when fieldState.invalid is true
   // Show icon + message text
   // Use danger tone for errors, warning for recoverable issues
   ```

2. **Show validation state in form fields**:

   - Add visual indicator (red border) to invalid fields
   - Add validation message below each invalid field
   - Disable or warn when saving with invalid fields

3. **Add recovery guidance for common issues**:

   a) **Model not in directory**:
      ```
      "model_path" is not in the current models folder.
      Options:
      - Select a model from the list below
      - Browse to select a different model file
      - Change the models folder
      ```

   b) **Models folder empty**:
      ```
      No models found in this folder.
      Options:
      - Select a different folder
      - Add .gguf files to this folder
      - Import models from HuggingFace
      ```

   c) **Invalid URL format**:
      ```
      "server_url" must be a valid URL (https://...)
      ```

4. **Integrate with lifecycle apply flow** (from Phase 2):

   - Check field validation before allowing save/apply
   - Show "Cannot apply: fix validation errors first" if fields are invalid
   - Use applyImpact to determine if restart is needed after validation passes

5. **Add model count badge** in models dir field:

   - Show "📁 {dirName} ({count} models)" when scanned
   - Show "📁 {dirName} (scanning...)" during scan
   - Show "📁 {dirName} (no models)" when empty

---

## Acceptance Criteria

- [ ] Invalid fields show red border and error message
- [ ] Validation messages appear below the relevant form field
- [ ] Recovery guidance provides clear next steps
- [ ] User cannot apply/save when critical fields are invalid
- [ ] Model count is displayed after successful scan
- [ ] Scanning shows loading state

---

## Notes

- Reuse existing form field styling patterns
- Keep validation messages concise but actionable
- Consider accessibility (color-blind users should understand errors)
- Link to relevant documentation or help if needed
- Test with various invalid states: missing dir, invalid path, wrong mode