bug: rich-mode non-PDF images ignore document-relative path resolution

[chaoxu]

Summary

Rich-mode non-PDF images appear to ignore document-relative path resolution.

Why this looks wrong

src/render/image-render.ts resolves PDF targets relative to the current document before rendering them, but the non-PDF branch still passes the raw markdown target directly into <img src>.

That means a document like posts/math.md with ![](diagram.png) likely renders diagram.png relative to the app URL rather than posts/diagram.png.

Affected code

• src/render/image-render.ts
• src/lib/project-paths.ts

Impact

Rich mode can fail to render ordinary relative images from nested documents even though the project-path helpers already know how to resolve them.

Notes

This came from static audit, not a live UI repro. I did not find any file-to-webview URL bridge elsewhere in the repo that would make the raw path safe.

Related: #437

[chaoxu]

Non-PDF images now resolve relative to document path.

[chaoxu]

Static verification on current HEAD shows this is still not fixed.

src/render/image-render.ts still sends the raw markdown target through the non-PDF branch:

• the PDF branch resolves via resolveProjectPathFromDocument(...)
• the normal-image branch still does new ImageWidget(parsed.alt, parsed.src)

That means a nested document like posts/math.md with ![](diagram.png) still resolves against the app URL rather than posts/diagram.png.

I did not find a demo document in this repo that exercises this exact non-PDF relative-path case live, but the rich-mode render path itself is still using the unresolved raw target, which is the bug this issue was filed for.

[chaoxu]

Root-Cause Analysis

Two problems, not one:

1. Path resolution: Non-PDF images don't call resolveProjectPathFromDocument — they pass raw parsed.src to ImageWidget. PDF branch does this correctly.

2. URL serving: Even after resolving, there's no mechanism in Tauri mode to make <img src="posts/diagram.png"> load the file. The Tauri webview doesn't serve project files via HTTP or asset protocol. The FileSystem abstraction reads files via Rust IPC, not HTTP.

Why PDFs work but images don't

PDFs read binary via FileSystem.readFileBinary → rasterize to canvas. No <img src=""> URL resolution needed. Non-PDF images rely on the browser to fetch via URL — but there's no serving layer for project files in Tauri.

Recommended Fix: readFileBinary-to-data-URL bridge

Same architecture as the PDF preview cache:

1. Resolve path — documentPathFacet + resolveProjectPathFromDocument for all relative image paths (use existing isRelativeFilePath)
2. Image URL cache StateField — maps resolvedPath → dataUrl | "loading" | "error". On first encounter, dispatch async request; on completion, update field so plugin re-renders.
3. Async loader — reads fs.readFileBinary(resolvedPath), converts to data:image/...;base64,... URL, dispatches state update.
4. Absolute URLs (https://, data:) — pass through unchanged.

This follows the proven pdfPreviewField + requestPdfPreview pattern. Works identically in browser, Tauri, and tests. No Rust backend changes needed.

[chaoxu]

Design Decision: Tauri asset protocol (Option 1)

Register a custom asset protocol in the Rust backend that serves project files. Then image widgets use asset://project/posts/diagram.png as img.src — no base64 conversion, no memory bloat, no data URLs.

Why this is the right approach:

• Native Tauri pattern for local asset serving
• Zero JS memory overhead (browser fetches directly from Rust)
• Works for all file types (images, fonts, etc.), not just images
• Relative paths resolve naturally once the base is set correctly

Implementation:

1. Rust: Register tauri::Builder::default().register_assetprotocol("project", handler) that resolves paths against the current project root
2. TS: In image-render.ts, resolve relative paths to asset://localhost/project/... URLs in Tauri mode
3. Browser mode: Use Vite's dev server URLs (e.g., /demo/... prefix) — existing behavior
4. Abstraction: Add an imageUrlFacet that returns the correct URL scheme per runtime

For browser dev mode:

Relative images already work if served from the right path. The MemoryFileSystem fetch fallback (/demo/...) handles this. The main gap is just adding resolveProjectPathFromDocument to the non-PDF branch.

What about the PDF cache?

The canvas cache stays — it exists because CM6 rebuilds decorations (calling createDOM multiple times), and re-rasterizing a PDF on every rebuild would be expensive. The canvas is cloned, not re-rendered. This is correct for PDFs. For normal images, the browser handles caching natively via <img src="">.