# Change Request: CR-002

> Created: 2026-03-26
> Status: Approved
> Classification: Modification
> Related Feature: FEATURE-038-C

## Request Details

**Requestor:** User (UIUX Feedback)
**Date Received:** 2026-03-26
**Priority:** Medium
**Source:** [Feedback-20260326-212334](../../../uiux-feedback/Feedback-20260326-212334/feedback.md)

## Description

Add toolbar icons to the deliverable preview modal header (`.preview-header`) in workflow mode:
1. **Download icon** — allows users to download the currently previewed file directly from the modal
2. **Preview/Raw toggle icon** — switches between rendered preview mode (markdown→HTML, syntax-highlighted code) and raw text mode (plain `<pre>` without rendering)
3. **Smart default mode** — files default to preview mode, but files under `*/src/*` paths default to raw mode (source code is more useful as raw text)

## Business Justification

- **Download:** Users currently must close the preview modal to download files. The folder browser modal (FEATURE-039-A) already has a download button in its header, creating an inconsistency with the single-file preview modal.
- **Preview/Raw toggle:** Rendered markdown is useful for documentation, but source code and config files benefit from viewing as raw text. Users have no way to see the unprocessed content.
- **Smart defaults:** Source files under `*/src/*` are overwhelmingly code — defaulting to raw mode reduces toggle clicks for the most common use case.

## Impact Analysis

### Classification

**Type:** Modification to FEATURE-038-C

**Reasoning:**
- Same target users (workflow users reviewing deliverables)
- Same UI modal (`.deliverable-preview-backdrop` / `.deliverable-preview`)
- Same data model (existing `GET /api/ideas/file` API)
- Extends existing preview header (adds icons alongside filename + close button)
- No new API endpoints, screens, or data models required
- Scoring: MODIFICATION +6 (existing data model +2, same users +1, extends workflow +2, reuses UI +1) vs NEW_FEATURE 0

### Comparison Matrix

| Aspect | CR Requirement | Existing Feature(s) |
|--------|---------------|---------------------|
| Users | Workflow users reviewing deliverables | Same |
| Workflow | Open modal → use header icons → download/toggle view | Open modal → view → close |
| Data Model | No changes — same file content API | `GET /api/ideas/file?path=` |
| UI Elements | 2 new icons in existing preview header | Filename + close button only |
| API Endpoints | None new | Existing endpoints sufficient |

### Conflict Analysis

**Conflicts Found:** Yes (4 expected, 0 unexpected)

| # | Type | Affected Feature | Severity | Classification | Description |
|---|------|-----------------|----------|----------------|-------------|
| 1 | specification | FEATURE-038-C | Medium | expected | "File download" listed in Out-of-Scope. CR-002 moves it in-scope. Folder browser modal (FEATURE-039-A) already has download — this brings parity. |
| 2 | design | FEATURE-049-F (CR-008) | Medium | expected | FilePreviewRenderer (shared component) has no `renderMode` support. Needs extension with `renderMode` parameter. Must verify no regression in KB browse and folder browser consumers. |
| 3 | specification | FEATURE-038-C | Low | expected | Smart defaults (`*/src/*` → raw) need formal path pattern definition. Not currently specified anywhere. |
| 4 | design | FilePreviewRenderer | Low | expected | "Raw" vs "preview" for code files: raw = plain `<pre>` without highlight.js; preview = syntax highlighted. Both are `<pre>` but with different rendering. |

**Unexpected Conflict Resolution:** N/A — all conflicts expected.

**Mitigation Strategy:**
- Conflict 1: Update FEATURE-038-C Out-of-Scope section to note scope evolution
- Conflict 2: Add `renderMode` option to `FilePreviewRenderer` constructor; test all existing consumers
- Conflict 3: Define path pattern as regex `/\/src\//` (matches any path segment named `src`)
- Conflict 4: Clarify in ACs that raw = no highlight.js, no markdown rendering

### Affected Components

| Component | Impact Level | Details |
|-----------|--------------|---------|
| `deliverable-viewer.js` | High | Add download + toggle icons to `showPreview()` header; pass render mode to FilePreviewRenderer |
| `file-preview-renderer.js` | High | Add `renderMode` option (`auto` / `raw`); when `raw`, skip type-specific rendering and show plain `<pre>` |
| `workflow.css` | Medium | Style new header icons (download button, toggle button) |
| `folder-browser-modal.js` | Low | May optionally gain raw toggle for consistency (follow-up) |

### Dependencies

- FilePreviewRenderer (CR-008 for FEATURE-049-F) — shared component needs `renderMode` extension
- `GET /api/ideas/file?path=` — existing API, no changes needed

## Proposed Approach

1. **Extend `FilePreviewRenderer`** with `renderMode` option:
   - `'auto'` (default): current behavior — detect type and render appropriately
   - `'raw'`: always render as plain `<pre>` text, no markdown/HTML/highlight.js processing
   - Add `setRenderMode(mode)` method for runtime toggling + re-render

2. **Update `DeliverableViewer.showPreview()`** header:
   - Add download `<a>` icon (pattern from folder-browser-modal.js `_makePreviewHeader`)
   - Add toggle icon (e.g., `👁️` for preview / `</>` for raw)
   - Detect `*/src/*` path pattern to set initial render mode
   - Wire toggle click to switch `renderMode` and re-render

3. **Update CSS** for new header layout (flex with spacer between filename and icon group)

## Mockup Impact

**UI/UX Change:** Yes
**Existing Mockups Referenced:** None applicable (FEATURE-038-C mockup is for folder tree, not preview header)

**Updated Mockup(s):** N/A — text-based specification sufficient for icon placement in existing header.

## Approval

- [x] Classification approved by human
- [x] Conflict analysis reviewed by human
- [x] Approach approved by human
- [x] Ready for execution

## Execution

**Classification Result:** modification
**Conflicts Resolution:** all_expected

**Actions Taken:**
- [x] CR document created in feature folder
- [x] Conflict analysis completed and documented
- [x] Specification Version History updated with CR link
- [x] Specification Out-of-Scope updated (download moved in-scope)
- [x] Next task type set: x-ipe-task-based-feature-refinement

## Links

- Feature Specification: [specification.md](./specification.md)
- UIUX Feedback: [Feedback-20260326-212334](../../../uiux-feedback/Feedback-20260326-212334/feedback.md)
- Related: [FEATURE-039-A](../EPIC-039/FEATURE-039-A/specification.md) (folder browser modal — already has download)
- Related: [CR-008 FilePreviewRenderer](../../EPIC-049/FEATURE-049-F/CR-008.md) (shared preview component)

---

## Change History

| Date | Change | By |
|------|--------|----|
| 2026-03-26 | CR created | Quill ✒️ (Agent) |
