Repository navigation
fix(md-notebook): resolve root-relative images against the vault root - #23746
Conversation
A note image written as /images/a.png was only ever served as an absolute filesystem path, so a vault that keeps images at its root and links them with a leading slash (the Obsidian convention) showed them broken. NoteImage now tries the absolute path first, unchanged, and on a load error retries the same path once under the open vault's content root before falling back to the alt text. The retry is built by vaultRootImageSrc, which refuses any candidate with a . or .. segment (plain, percent-encoded or backslash-separated), an encoded separator, a NUL byte, or a protocol-relative source, so the second try cannot leave the vault. It goes through the existing /api/file-raw endpoint and its checks; no route changes. Fixes #23630
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the fix is additive (the absolute path is tried first, then one retry under the vault root), traversal is refused before the retry, and three committed screenshots show the rendered change. Notes
[DESIGN-REVIEWED] 15ea419 Description read[DESCRIPTION-READ] d34111fd5b941d68360e5411bbea66866063b6e55f7e9f1ab431d72916cddf2f That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The fallback fixes the cause named in #23630, adds no route, and its one new public function has one real consumer. What this change shipsInventory (5 items) — 5 justifiedIntent: let a Notes-app vault whose images are linked root-relative (
[FIRST-PRINCIPLES-REVIEWED] 15ea419 Description read[DESCRIPTION-READ] 8e7f7855ce615973efc6616a2795a10dd5efce3274c67372a6056dbc272912a1 That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing blocks: the change adds no control, label or string, and the before and after screenshots show the root-relative image now loading. [UX-REVIEWED] 15ea419 Description read[DESCRIPTION-READ] 3f7ede2997c0cfc32526d36004d26b8ccbe42923b79e98807c3fb9bdd0e79a51 That sha256 names everything this verdict read: the PR description, plus the 6 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
The vault-root retry decoded each segment only to validate it, then sent the still-encoded text to /api/file-raw, which reads path as a literal filesystem path. A link such as /images/System%20diagram.png therefore asked for a file literally named System%20diagram.png and fell back to alt text. Build the path from the decoded, validated segments instead. Fixes #23630
iamwhatever
left a comment
There was a problem hiding this comment.
APPROVE at 15ea4194c23601f8b191b29212dc8d475f7461e4.
The first request for every image is unchanged. Only after it fails does NoteImage retry once under the vault root, then fall back to the alt text. vaultRootImageSrc refuses ./.., encoded separators, NUL and protocol-relative sources before it builds the path, and it builds the path from the segments it checked. No route or server check changes, and /api/file-raw still applies its own checks. The Design note about an absolute file winning over the vault copy matches the issue's contract and is informational.
All AI lanes are clean and there are no deferred items. Sensitive Change Review and Publish readiness signal are still queued; protected auto-merge should wait for them.
— crew-pr-reviewer (r125)
Fixes #23630
Problem / Motivation
Goal: A Notes-app image linked with a leading slash (
) loads from the vault root when that absolute path does not exist.The Notes preview served any
/…image source as an absolute filesystem path and nothing else. A vault that keeps its images at its root and links them root-relative (the Obsidian-style convention) showed every such image as the broken-image alt text.Why it matters
Vaults imported from Obsidian and similar tools commonly use root-relative image links. Every one of those images renders broken in the Notes app today, so the note reads as missing its diagrams and screenshots.
Not a goal
MarkdownRenderer) has the same symptom; that is File preview: root-relative markdown images (/images/…) render as missing #23623 and is handled separately in fix(markdown): resolve root-relative images against the file's site root #23631. This PR touches only the Notes app./api/file-rawor any other route, and no new route.assets/a.png) resolves.What changed (motivation → approach → change)
Symptom → cause:
resolveNoteImageSrc(website/src/apps/md-notebook/utils.ts) treats any leading-slash source as rooted and requests it verbatim, so/images/a.pngis looked up at the filesystem root, never under the vault.Approach: keep the absolute path as the first request, exactly as today, so a real absolute path still loads on the first try and nothing that works now changes. Only when that load fails, retry the same path once under the open vault's content root, then fall back to the alt text. This matches the issue's expected behavior ("when the absolute path does not exist").
Change:
utils.ts: newvaultRootImageSrc(src, vaultRoot)builds the vault-rooted URL, or returns null when the source is not root-relative or any segment could leave the root lexically. A null means no retry, so a traversal source degrades to alt text as before. Each segment is percent-decoded once, checked, and the path is built from those decoded segments (soSystem%20diagram.pngasks forSystem diagram.png), because/api/file-rawtreatspathas a literal filesystem path; a segment with a malformed escape is kept as written.vaultRootContext.ts: a React context carrying the vault content root toNoteImage, because images are rendered frominline(), a plain function called by many block renderers.Preview.tsx: new optionalvaultRootprop, provided through that context.MdNotebookPage.tsx: passesvaultContentPath(activeVault)(local path plus subfolder) asvaultRoot.NoteImage.tsx: tracks which source failed; the retry state is keyed on the fallback URL so switching vault or note starts over from the absolute path.The retry asks
/api/file-rawfor a path under the vault, nothing a plain absolute source could not already request, and every check on that endpoint (sensitive paths, symlink refusal, image magic number) still applies, which covers symlink escapes out of the vault.Backwards compatibility
Compatible: the first request for every image is byte-identical to main; the vault-root retry only runs after that request has already failed, and
vaultRootis an optional prop.Removes nothing: the change only adds a fallback request after a failed load; no path, key, function or behavior that main accepts is removed or narrowed.
Tests
website/src/test/mdNotebookImages.test.tsx:vaultRootImageSrcreads/images/a.pngagainst the vault root, without doubling a trailing slash on the root.~, Windows-drive or bare/source.//host/share/a.png)./../, nested.., trailing..,.segment,%2e%2e,%2E%2E, half-encoded.%2e, encoded slash%2f, encoded backslash%5c, backslash.., raw NUL,%00.System%20diagram.png→System diagram.png,caf%C3%A9.png→café.png) and keeps a malformed escape (100%.png) as written.a..b.png,..hidden.png).resolveNoteImageSrcis unchanged.Preview: absolute path first, then the vault root, then alt text; stops at the vault root when it loads; no retry when the vault root is unknown; a traversal source is never retried under the vault; a relative image is not retried; changing vault starts over from the absolute path.Local gates:
vitestover all 14 md-notebook test files (374 tests) pass;tsc -p tsconfig.app.jsonandeslinton the changed files are clean;lint:theme-colors,lint:phantom-classes,lint:restyle-ratchet,lint:i18npass.Proof: not provable -- frontend test
Manual verification
Rendered the real
Previewin an isolated Vite capture page with/api/file-rawanswered the way the endpoint would for a vault at/home/me/vault(404 for every path except/home/me/vault/images/diagram.png). Recorded request sequence:/images/diagram.png,/../etc/secret.png; both images show alt text./images/diagram.png,/../etc/secret.png,/home/me/vault/images/diagram.png; the diagram loads and the traversal source is never retried under the vault.Not run in the full desktop app against a real vault.
Screenshots / video
Before (main, dark): the root-relative image falls back to its alt text.
After (dark and light): the image loads from the vault root; the traversal source stays refused.
Related Issues
Fixes #23630. Related: #23623 (the same symptom in the file preview, addressed in #23631).
Sibling sweep
Swept: git grep -nE "resolveNoteImageSrc|file-raw?path" -- website/src
Sibling: website/src/components/markdown/ImgWithFallback.tsx -- tracked in #23623
Sibling: website/src/apps/design-critique/api.ts -- not affected -- builds URLs from picked file paths, not markdown image sources
Sibling: website/src/apps/mochi/panel/panelBridge.ts -- not affected -- serves explicit absolute file paths, no markdown root convention
Sibling: website/src/components/FileRenderers.tsx -- not affected -- previews the opened file by its own path, not a link inside it
Pattern harvest
Not generalizable: the root a leading-slash link means depends on each renderer's context (vault root here, site root in the file preview), so there is no single rule to enforce mechanically.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license.