# Change Request: Rich File Preview in KB Browse

> CR ID: CR-004
> Feature: FEATURE-049-F
> Status: Approved
> Date: 03-17-2026
> Requestor: Human (via DAO)
> Priority: High

## Description

Add rich file preview support to the KB browse modal matching ideation preview capabilities. Currently KB only renders markdown via `marked.parse()`. It should support:

- **Markdown** with DSL-enhanced rendering (Mermaid diagrams, Architecture DSL, Infographic DSL) via `ContentRenderer`
- **Images** (PNG, JPG, GIF, SVG, WebP) — inline preview
- **DOCX/MSG** — converted to HTML via mammoth/extract-msg (same as ideation CR-001)
- **HTML** — iframe sandboxed preview
- **PDF** — iframe preview
- **Code/text** — syntax-highlighted via highlight.js

## Business Justification

KB stores diverse file types (documents, images, PDFs, etc.) but users can only preview markdown content. This forces users to download files to view them, breaking the browsing flow. Ideation already has this infrastructure — it should be reused in KB.

## Impact Analysis

### Classification: **modification** (extends existing KB browse modal)

### Affected Components

| Component | Impact | Description |
|-----------|--------|-------------|
| `kb_routes.py` | New route | Add `GET /api/kb/files/{path}/preview` for raw file serving with docx/msg conversion |
| `kb-browse-modal.js` | Modify `_renderArticleScene` | Use `ContentRenderer` for markdown; handle binary types (image, docx, PDF) |
| `content-renderer.js` | No change | Already supports markdown+DSL, HTML, code — reused as-is |
| `ideas_routes.py` | Extract shared utils | Move `_convert_docx`, `_convert_msg`, `_sanitize_converted_html` to shared module |

### Conflict Analysis

- **No spec conflicts** — AC-049-F-05a (Preview action) says "reusing existing preview infrastructure" which this CR fulfills
- **No design conflicts** — KB service already marks binary files; frontend just needs to handle them
- **Minor NFR conflict** — NFR-049-F.4 says "No new API routes" but this was written before binary preview was considered; preview route is necessary for binary file serving

### Specification Changes

- Add new AC section: **AC-049-F-16: Rich File Preview**
- Add FR-049-F.15: Rich File Preview
- Update NFR-049-F.4 to exclude preview route
- Update Out of Scope section

## Approach

1. **Extract shared conversion utils** from `ideas_routes.py` into `src/x_ipe/services/conversion_utils.py`
2. **Add KB preview route** `GET /api/kb/files/{path}/preview` that:
   - Serves text files as plain text
   - Converts .docx/.msg to HTML (with `X-Converted: true` header)
   - Serves images/PDFs with correct MIME type
3. **Update `_renderArticleScene`** in `kb-browse-modal.js` to:
   - Detect file type from API response (`binary` flag + `file_type` field)
   - For markdown: use `ContentRenderer` (DSL-enhanced)
   - For images: render `<img>` tag from preview endpoint
   - For docx/msg: fetch from preview, render in iframe
   - For PDF: render in iframe
   - For HTML: render in sandboxed iframe
   - For other text: syntax-highlighted `<pre>` block
