rowboat/apps/x/PLAN.md

HTML File Rendering — Implementation Plan

Goal

Replace the <pre> raw text fallback in the knowledge view with a proper HTML file renderer using <iframe srcdoc sandbox="allow-scripts">.

Scope

• Only HTML file rendering for now
• No layout changes, no split pane
• No other file types in this PR

---

Phase 1 — IPC: Read HTML file content and pass to renderer

What

Add an IPC handler in the main process that reads a local HTML file and returns its content as a string to the renderer.

Work

1. Add knowledge:readHtmlFile handler in apps/main/src/ipc.ts
   • Accepts a workspace-relative path
   • Resolves to absolute path, validates it stays inside workspace root (path traversal guard)
   • Reads file as UTF-8 string
   • Returns the HTML string to renderer
2. Add the channel type to packages/shared/src/ipc.ts

Test ✅

• Open a .html file from the knowledge tree
• Console log the returned string in the renderer
• Verify: correct HTML content is returned, no errors
• Verify: attempting a path like ../../secret.txt is rejected with an error

---

Phase 2 — Renderer: Detect .html files and render in iframe

What

In App.tsx, detect when selectedPath is an .html file and render it in a sandboxed <iframe srcdoc> instead of the <pre> fallback.

Work

1. In the file loading logic (App.tsx:1284–1357), when extension is .html:
   • Call knowledge:readHtmlFile via IPC
   • Store the HTML string in state
2. In the knowledge view render switch (App.tsx:4522–4527):
   • Add a condition: if extension is .html → render <HtmlFileViewer html={htmlContent} />
   • Otherwise fall through to existing <pre> fallback
3. Create apps/renderer/src/components/html-file-viewer.tsx:
   • Accepts html: string prop
   • Renders <iframe srcdoc={html} sandbox="allow-scripts" /> with full width/height, no border

Test ✅

• Open a real .html file from the knowledge tree
• Verify: file renders visually in the iframe (not raw text)
• Verify: a non-html file still shows the <pre> fallback (no regression)
• Verify: an HTML file with a <script> tag runs its JS (allow-scripts works)
• Verify: an HTML file with <script src="https://evil.com"> — open network tab, confirm no request is made (allow-same-origin is absent, so external scripts are blocked by default CSP)

---

Phase 3 — Polish: Loading state, error state, empty file handling

What

Handle edge cases so the viewer never shows a broken or confusing UI.

Work

1. Loading state — show a spinner while the IPC call is in flight
2. Error state — if knowledge:readHtmlFile throws (file deleted, permission error), show a clean error message with the file path
3. Empty file — if HTML string is empty, show "This file is empty" instead of a blank iframe
4. Large files — if file is over a reasonable size limit (e.g. 5MB), show "File too large to preview — Open in system" button that calls shell.openPath

Test ✅

• Open a valid HTML file → renders correctly
• Delete the file while it's open, trigger a reload → error state shown cleanly
• Open an empty .html file → "This file is empty" message shown
• Simulate a file over 5MB → "File too large" message with open button shown
• Verify: no console errors in any of the above scenarios

---

Out of scope for this PR

• PDF, DOCX, image, video rendering
• Split pane / resizable layout
• Relative asset loading (./style.css) — Phase 2 uses srcdoc which has no base URL; assets will not load. Acceptable for now, documented as known limitation.
• app:// custom protocol — not needed until we handle relative assets