# Change Request: CR-008

> Created: 03-18-2026
> Status: Approved
> Classification: Modification
> Related Feature: FEATURE-049-F

## Request Details

**Requestor:** Human (via UIUX Feedback Feedback-20260318-213942)
**Date Received:** 03-18-2026
**Priority:** Medium

## Description

Unify file preview across all application locations. The KB browse modal preview should match the workflow deliverable preview — supporting DOCX and all formats the deliverable viewer supports. Extract a shared `FilePreviewRenderer` component so all preview locations use the same logic, eliminating inconsistency.

User feedback: "the preview of the file should be like the deliverable preview in workflow mode. it should support docx. please also review the preview there make sure all the supported file there should be also supported here. and why not from technical perspective, can we share the same preview logic or component so we won't have this kind of inconsistancy. please check the other places, I rememeber we do have several other places have file preview function. if we can make all of them consistent"

## Business Justification

Multiple preview locations across the app use different rendering approaches:

| Location | Component | Rendering | DOCX | Images | PDF | HTML | Code |
|----------|-----------|-----------|------|--------|-----|------|------|
| KB Browse | kb-browse-modal.js | marked.js (direct) | ❌ | ✅ | ✅ | ❌ | ❌ |
| Deliverable Viewer | deliverable-viewer.js | ContentRenderer + Blob Iframe | ✅ | ✅ | ✅ | ✅ | ✅ |
| Folder Browser | folder-browser-modal.js | ContentRenderer + Blob Iframe | ❌ | ✅ | ❌ | ✅ | ✅ |
| Link Preview | link-preview-manager.js | ContentRenderer | ❌ | ❌ | ❌ | ❌ | ✅ |

This inconsistency creates:
- Poor user experience (same file previews differently in different contexts)
- Code duplication (each location implements its own file type detection and rendering)
- Maintenance burden (format support changes must be replicated across locations)

## Impact Analysis

### Classification

**Type:** Modification to FEATURE-049-F

**Reasoning:**
- Works within current system boundaries (reuses existing ContentRenderer, conversion_utils.py)
- Builds upon CR-004's rich file preview ACs (AC-049-F-16)
- Same users, extended functionality (shared component extraction)
- No new data models, workflows, user types, or integration points
- No new UI screens — same preview behavior, unified implementation

### Comparison Matrix

| Aspect | CR Requirement | Existing Feature(s) |
|--------|---------------|---------------------|
| Users | Same KB browse users | Current KB browse users |
| Workflow | Same preview flow (click file → render) | Same |
| Data Model | No changes | Existing file metadata |
| UI Elements | No new screens; same preview area | Article scene in KB browse modal |
| API Endpoints | Uses existing endpoints (CR-004's `/api/kb/files/{path}/preview` + `/api/ideas/file`) | Both exist |

### Conflict Analysis

**Conflicts Found:** Yes (all expected)

| # | Type | Affected Feature | Severity | Classification | Description |
|---|------|-----------------|----------|----------------|-------------|
| 1 | pending-CR | FEATURE-049-F (CR-004) | Low | expected | CR-004 (TASK-925, in_progress) adds rich file preview to KB browse. CR-008 extends CR-004 by extracting the preview logic into a shared component. No contradiction — CR-008 builds on top of CR-004's work. |
| 2 | dependency | FEATURE-038-C (Deliverable Viewer) | Low | expected | Deliverable viewer has the most complete preview implementation. CR-008 recommends (but does not mandate) its adoption of the shared component. |
| 3 | dependency | FEATURE-039-A/B (Folder Browser) | Low | expected | Folder browser has partial preview. CR-008 recommends (but does not mandate) its adoption of the shared component. |

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

**Mitigation Strategy:**
- CR-008 scoped to FEATURE-049-F only (shared component creation + KB browse adoption)
- Other features receive recommendations for future adoption, not mandated changes
- Link Preview Manager excluded due to architectural incompatibilities (different endpoint pattern, XSS vulnerability)

### Affected Components

| Component | Impact Level | Details |
|-----------|--------------|---------|
| `src/x_ipe/static/js/core/file-preview-renderer.js` | High | NEW: Extract shared FilePreviewRenderer class from deliverable-viewer.js pattern |
| `src/x_ipe/static/js/features/kb-browse-modal.js` | Medium | Update `_renderArticleScene` to use FilePreviewRenderer |
| `src/x_ipe/static/js/features/deliverable-viewer.js` | Medium | Refactor `showPreview` to use FilePreviewRenderer |
| `src/x_ipe/static/js/features/folder-browser-modal.js` | Low | Recommended: adopt FilePreviewRenderer (future CR) |
| `src/x_ipe/static/js/features/link-preview-manager.js` | None | Excluded — architectural gap, different endpoint pattern |

### Dependencies

- CR-004 (TASK-925) must be implemented first — CR-008 builds on its `/api/kb/files/{path}/preview` endpoint and AC-049-F-16 ACs
- ContentRenderer (`src/x_ipe/static/js/core/content-renderer.js`) — used by FilePreviewRenderer for markdown+DSL rendering
- conversion_utils.py — backend conversion shared utilities (already extracted by CR-004)

## Proposed Approach

1. **Extract** a shared `FilePreviewRenderer` class from deliverable-viewer.js's `showPreview()` pattern into `src/x_ipe/static/js/core/file-preview-renderer.js`
2. **API:** `renderPreview(filePath, container, options)` where options includes `{ apiEndpoint, onError }`
3. **File type detection:** Internal, based on file extension (mirrors deliverable-viewer.js logic)
4. **Supported formats:** Markdown+DSL (via ContentRenderer), Images, DOCX/MSG (via X-Converted detection), PDF, HTML (sandboxed iframe), Code/Text
5. **KB browse modal** uses FilePreviewRenderer instead of direct rendering
6. **Deliverable viewer** refactored to use FilePreviewRenderer (eliminating duplication)
7. **Configurable endpoint:** Supports both `/api/kb/files/{path}/preview` and `/api/ideas/file?path=` via options

## Mockup Impact

**UI/UX Change:** No — same preview behavior, just unified implementation
**Existing Mockups Referenced:** N/A — no visual changes

## Approval

- [x] Classification approved by DAO (DAO-092, confidence 0.92)
- [x] Conflict analysis reviewed by DAO
- [x] Approach approved by DAO
- [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] Next task type set: x-ipe-task-based-feature-refinement

## Links

- Feature Specification: [specification.md](./specification.md)
- Related CR: [CR-004.md](./CR-004.md) (Rich File Preview — prerequisite)
- UIUX Feedback: [Feedback-20260318-213942](../../uiux-feedback/Feedback-20260318-213942/feedback.md)

## Recommendations for Future CRs

The following locations should adopt `FilePreviewRenderer` in future CRs:

| Location | Feature | Effort | Notes |
|----------|---------|--------|-------|
| Folder Browser Modal | FEATURE-039-A/B | Low | Already uses ContentRenderer; swap preview logic |
| Link Preview Manager | FEATURE-043-A/B | High | Requires endpoint migration + XSS fix first |

---

## Change History

| Date | Change | By |
|------|--------|----|
| 03-18-2026 | CR created | Pulse 💫 (Agent) |
