[inariku]

Problem / Motivation

Goal: A markdown file opened in the file preview shows images written as root-relative paths (/images/…) instead of "Image file no longer exists".

Every image written as ![…](/images/post/shot.png) rendered as the broken-image chip "Image file no longer exists", although the files were on disk next to the markdown. The preview sent the path to /api/file-raw as an absolute filesystem path (/images/… at the root of the disk), which 404s.

Why it matters

A leading slash is the conventional way to reference an image from the root of the repository or site a markdown file belongs to: GitHub resolves it against the repository root in a README, and Zenn, Docusaurus and similar setups write images the same way. Anyone previewing such a repository in the dashboard sees none of its images, and the chip tells them the files are gone when they are not. The only workaround, rewriting the link relative to the file, breaks the image on the site the markdown is published to.

Not a goal

• Changing how images resolve outside a file preview (chat transcripts, artifacts): there is no file to anchor a site root to, so a leading slash stays absolute there.
• The Notes app's own resolver (resolveNoteImageSrc), which knows the vault root and should use it directly; tracked in Notes app: root-relative images (/images/…) do not resolve against the vault root #23630.
• Reading a site generator's config (Docusaurus static/, Hugo static/) to map /img/… onto a different directory.
• Any backend change to /api/file-raw.

What changed (motivation → approach → change)

Symptom: root-relative images in a previewed file render as missing. Root cause: in ImgWithFallback, the BasePathCtx branch resolves only paths that do not start with /, ~ or a drive letter, so a leading-slash path went to /api/file-raw verbatim.

Nothing in the file says where its site root is, so the directories above the file are the candidates. When a BasePathCtx is set and src starts with a single /, the image now tries:

1. the absolute path, exactly as before, so a real absolute path (/Users/…/shot.png) still loads on the first request;
2. then <dir>/<path> for each directory above the file, nearest first (starting with the file's own directory), up to eight levels.

The next candidate is tried on each <img> error; the broken-image fallback appears only after the last one fails, and still names and probes the path as written (the same single HEAD probe as on main, so a refused (403) as-written file keeps the generic wording). siteRootImageCandidates builds the list; it treats \ as a separator only when the file sits on a drive-rooted Windows path, matching the existing rule that a backslash is a legal POSIX file-name character. The attempt index resets when src changes. When the list of candidate paths changes (another previewed file), the index and the failed state reset, because an unkeyed FileViewer reuses the same image instance across tabs; the loaded state resets only when the path on screen changes, since an unchanged <img src> fires no new load event. Every candidate goes through /api/file-raw, so the fallback asks for nothing the absolute path could not already ask for.

Because this changes when the broken-image fallback appears, the fallback moves to ErrorNotice (errors-use-error-notice): the failure ("Image failed to load" / "Image file no longer exists") is an inline ErrorNotice without the agent hand-off, with a No hand-off comment naming the draft it protects: the same renderer previews the meeting note's unsaved draft (NoteSidebar), which withholds the hand-off on its own notice because the navigation would unmount that draft, and a shared renderer cannot tell which host holds one. The chip beside it keeps copying the on-disk path. That applies to every surface that renders markdown images, not only file previews.

Alternatives considered: resolving against the project directory or the git root needs the backend (the frontend knows neither for an arbitrary previewed file), and a single fixed guess (the file's parent) fails for deeper layouts like docs/guide/page.md.

website/docs/frontend-conventions.md documents the behaviour next to the existing Windows-path rule. website/capture/ adds the harness used for the screenshots below.

Backwards compatibility

Compatible: the absolute path is still tried first and the fallback runs only after it 404s, so every image that loads today loads from the same path on the same first request.

Removes nothing: the change only adds fallback candidates after an image would already have failed.

Tests

website/src/test/MarkdownRenderer.rootRelativeImage.test.tsx:

• siteRootImageCandidates walks nearest-first without the disk root, stops at a Windows drive, keeps a POSIX backslash as a file-name character, caps at eight levels, and returns nothing without a directory.
• In a file preview, the <img> tries the absolute path, then each directory above the file, and stops at the one that loads with no chip.
• When every candidate fails, the chip shows the path as written; only the path as written is probed, and a 403 there keeps the generic wording.
• Switching between two files in one folder that show the same image keeps the loaded image visible (fails without the fix).

website/src/test/MarkdownRenderer.brokenImage.test.tsx: the failure is an ErrorNotice (role="alert", the wording, and no "Ask the agent" button) and the wording is not in the copy chip; the existing copy, keyboard and probe tests now address the chip by test id.

• Outside a file preview, a leading-slash path tries only the absolute path.
• A new src, or a different previewed file, starts over from the absolute path, including after every candidate failed for the previous file.

Proof: not provable -- frontend test (prove.py runs Python only)

Run by hand instead: with ImgWithFallback.tsx reverted to main, 8 of the first 10 tests in the new file failed (the two that passed pin unchanged behaviour); with the fix, all pass. Shuffled order, five runs, green.

Also run, on the final head: every test vitest related finds for ImgWithFallback.tsx (923 files, 13,967 tests), tsc, eslint, i18n:check, scripts/docs-lint.sh. Earlier rounds: vitest on MarkdownRenderer*, MarkdownPanel*, mdNotebook*, FileViewer*, ContentRenderer* and overlayKeyGuard.inventory (95 files, 1,689 tests; after the review fix, the same set minus mdNotebook* and overlayKeyGuard: 82 files, 1,364 tests), tsc -b, eslint, i18n:check, scripts/docs-lint.sh, jscpd.

Manual verification

website/capture/shoot-root-relative-image.mjs builds a throwaway repository on disk (articles/post.md, images/post/architecture.png), renders the real MarkdownRenderer inside the BasePathCtx the file preview provides, and answers every /api/file-raw request from the real filesystem (existing file served, anything else 404). Its log showed the order: /images/post/architecture.png 404, <repo>/articles/images/post/architecture.png 404, <repo>/images/post/architecture.png 200. The truly missing image tried eight directories and then showed the chip.

Not yet checked in a running gateway with a real repository open in the file panel.

Screenshots / video

Before (current main): the site-root image renders as "Image file no longer exists".

After: the site-root image loads; an image that really is missing shows the path chip and an inline error notice.

After, light theme

Related Issues

Fixes #23623

Sibling sweep

Swept: git grep -nE "file-raw\?path=" -- website/src ':!website/src/test' for every place that turns a markdown or file path into a /api/file-raw URL.
Sibling: website/src/apps/md-notebook/utils.ts:165 -- tracked in #23630
Sibling: website/src/components/FileRenderers.tsx:92 -- not affected -- serves the previewed file itself by its own absolute path, no markdown reference
Sibling: website/src/pages/chat/ToolImageThumbnails.tsx:29 -- not affected -- tool output paths are absolute, no file to anchor a site root
Sibling: website/src/components/chat-input/FilePreviewStrip.tsx:116 -- not affected -- attachments are absolute paths picked by the user

Pattern harvest

Not generalizable: the defect is one missing branch in the single markdown image resolver; the other resolver (Notes app) has a different, known root and is tracked separately.

Checklist

• At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
• Existing tests pass and new tests added for new functionality
• Self-review completed; code follows project style guidelines
• Documentation updated (if applicable)
• No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

[github-actions]

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 0d92d4ad0b2dcf7f70cc9bce6e8dbd66297ec056 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: trying the absolute path first keeps today's first request unchanged, and every fallback goes through /api/file-raw, so it can read nothing the absolute path could not already ask for.

Notes

• The broken-image chip's move to ErrorNotice affects every markdown surface, chat transcripts included, and adds a role="alert" for each missing image. That is a separate UX change bundled with a file-preview fix; it would be easier to judge and revert as its own PR.
• Because the nearest directory wins, a same-named image in a closer folder will silently replace the real site-root one. This is documented, and the fix belongs with Notes app: root-relative images (/images/…) do not resolve against the vault root #23630's knowledge of the vault and project root, not in more guesses here.

[DESIGN-REVIEWED] 0d92d4a

Description read

[DESCRIPTION-READ] 7f7ad464cca346aa4cd061c446bbe2c6c33709ffe55bf14af74f726e97377b94

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

[github-actions]

UX Review (Opus 5.5, fork) — ✅ PASS

UX-level review of 0d92d4ad0b2dcf7f70cc9bce6e8dbd66297ec056 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks. The committed screenshots show the resolved image and the new chip-plus-notice failure state in both themes. No blind reader has seen them, a limit of this fork lane; a same-repo run would add that read.

Notes

• ErrorNotice variant="inline" now renders the image-load failure in red with role="alert" everywhere markdown renders, including old chat transcripts whose temp screenshots were cleaned up. A long transcript can now show a column of red alerts, and a screen reader announces each one, for files the user can do nothing about. Before this PR the same state was muted chip text. A quieter, non-alert notice variant would fit the chat transcript better.
• The screenshots show only the "Image file no longer exists" wording. They don't show "Image failed to load", the 403 / generic case.

[UX-REVIEWED] 0d92d4a

Description read

[DESCRIPTION-READ] 7b07c2b45fba922f6c47793f27b6937bf58a549bf7bd6e47240d9f495c4163c1

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

[github-actions]

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 722f1e4e76c277ef5b9bb41c36b6b71c2f1acc6f via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks: the fallback walk fixes #23623 in ImgWithFallback, where the bug is, and the one rider (the switch to ErrorNotice) is required by the blocking errors-use-error-notice rule for the code this PR touches.

What this change ships

Inventory (7 items) — 7 justified

Intent: in a file preview, show markdown images written as /images/… instead of saying the file no longer exists — a FIX.

1. In a file preview, a root-relative image tries the absolute path, then each directory above the file, up to eight levels — justified
2. A switched preview tab, or a new src, starts its candidate list over — justified
3. On every markdown surface, including chat, the broken-image wording moves out of the copy chip into an inline ErrorNotice alert — justified
4. Every broken image gets an "Ask the agent" button — justified
5. The broken-image chip carries a new test id, md-broken-image-chip — justified
6. A capture harness website/capture/shoot-root-relative-image.mjs, plus screenshots under temp-screenshots/ — justified
7. A frontend-conventions.md paragraph describes how root-relative images resolve — justified

[FIRST-PRINCIPLES-REVIEWED] 722f1e4

Description read

[DESCRIPTION-READ] 4ce01793daa03d657663b8156bcd36bc561c7780055fee5899415e02ee19d343

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

[github-actions]

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 0d92d4ad0b2dcf7f70cc9bce6e8dbd66297ec056 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 0d92d4a

[github-actions]

GPT 6.1 Review (fork) — 🔴 changes requested (blocking)

Reviewed 0d92d4ad0b2dcf7f70cc9bce6e8dbd66297ec056 via the fork AI-review pipeline; updated in place on each push.

Adjudication upheld 1 of 1 blocking finding(s); those must be resolved before merging.

BLOCKING -- website/src/components/markdown/ImgWithFallback.tsx:177 -- Windows fallbacks omit the previewed drive’s root

while (dir && !/^[A-Za-z]:$/.test(dir) && out.length < MAX_SITE_ROOT_ANCESTORS) {
Trigger: Preview D:\docs\post.md containing ![](/images/a.png), with the image at D:\images\a.png and the gateway running from C:. FileViewer supplies BasePathCtx; ImgWithFallback builds these candidates, while /api/file-raw canonicalizes the initial slash-rooted path through os.path.abspath on C:.
Outcome: The initial request targets C:\images\a.png, and the only fallback targets D:\docs\images\a.png. Neither reaches the existing image, so the preview displays a broken-image notice.
Anchor: defect
Fix: Include the previewed Windows drive’s root within the bounded candidate list; it is not necessarily equivalent to the initial absolute request.

[BLOCK-MERGE] 0d92d4a
[GPT-REVIEWED] 0d92d4a

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 — LOW harm. Confirmed in the patch: the ancestor loop stops before adding a bare drive dir like D: (authentic.patch:321). The only other candidate is the as-written localPath (patch:398–399), which /api/file-raw resolves on the gateway's drive (editor.py:275–278). When the last candidate fails, setErrored shows a visible broken-image chip (patch:445–447). Nothing retries, and this path also failed before the PR, so it is not a regression.
The real fix is about one line: push ${dir}/${rel} once when dir is the drive root. That adds no new state, invariants or coordination between modules, so the fix costs less than the harm it prevents.

[ADJUDICATION] 0d92d4ad0b2dcf7f70cc9bce6e8dbd66297ec056 total=1 uphold=1 downgrade=0
UPHOLD F1 website/src/components/markdown/ImgWithFallback.tsx:177 reason=harm-warrants-remedy
[GPT-ADJUDICATED] 0d92d4ad0b2dcf7f70cc9bce6e8dbd66297ec056

[inariku]

Thanks for the reviews. Pushed 21629b6fa (squashed into the fix commit, still two commits).

GPT 6.1 BLOCKING — ImgWithFallback.tsx: clear the failed-image state when the previewed file changes. Fixed. Confirmed: the basePath reset cleared only attempt, so after every candidate failed in one tab, switching the unkeyed FileViewer to another tab with the same src kept errored=true and never tried that file's candidates. The basePath change now resets attempt, errored and loaded together. New test tries the new file's candidates after every candidate failed for the previous file fails without the reset and passes with it.

Design Review notes.

• Nearest-first wins over the real root for a same-named image: added a sentence saying so to the frontend-conventions.md paragraph.
• The fix also reaches other BasePathCtx surfaces (file explorer, meeting notes sidebar): the same paragraph now names them.

UX Review note (chip wording after eight failed paths). Not changed here. The "Image file no longer exists" wording comes from the existing HEAD probe and predates this PR; rewording it affects every surface that shows the chip, chat included, so it belongs in its own change rather than this fix.

Fork PR, so the new head may need its workflows approved again.

[inariku]

Fixed in 2803085 (re: the Opus 5.5 blocking finding on 21629b6, which has since been overwritten in place by the fd9d994 run).

The finding: when the image exists but the server refuses it (403, e.g. an unsupported format or a sensitive path), every site-root fallback candidate 404s, and the broken-image chip only probed the last candidate, so it claimed "Image file no longer exists" for a file that is there.

The chip now probes every candidate it tried. It says the file no longer exists only when all of them return 404; any other response gives the generic "could not load" chip. Two regression tests cover the 403-then-404 chain and the all-404 case; both fail with the fix reverted.

Also rebased onto main 5d7a22d to drop the two "Merge branch main" commits that took the PR past the two-commit limit. The PR content is unchanged apart from this fix.

[inariku]

Both blocking findings on d9ba318 are fixed in 3af253c (still two commits).

Opus 5.5: loaded image stuck under the skeleton. Fixed. The reset no longer keys on BasePathCtx. It keys on the list of candidate paths, and clears loaded only when the path on screen changes, so two files in one folder showing ![](images/logo.png) keep the loaded image visible. Added keeps a loaded image visible when another file in the same folder shows the same image, which fails on d9ba318 and passes now.

GPT 6.1: BrokenImage no longer grandfathered under errors-use-error-notice. Fixed by reverting the change that took it out of the grandfathering: BrokenImage is byte-identical to main again, single probeUrl, and the caller hands it the URL of the path as written, which is the URL main probed for every image. The chip names that path, so its "no longer exists" wording now speaks for that path only, and a refused (403) as-written file still keeps the generic wording (keeps the generic wording when the as-written file is refused (403) and the fallbacks 404 still passes, now with one probe). website/docs/frontend-conventions.md says which path the chip probes.

Checks: tsc, eslint, docs lint, markdown vitest (1,028) pass locally.

[inariku]

GPT 6.1 finding on 3af253c (errors-use-error-notice, touched failure surface): fixed in 722f1e4 by migrating, as the rule asks.

• The load failure is now an inline ErrorNotice ("Image failed to load" / "Image file no longer exists", unchanged wording and probe), with askAgent on: a rendered image holds no draft, the same call InlineCode's reveal notice already makes in this renderer (comment at the call site).
• The copy-path chip stays beside it, so the one recovery the transcript itself can offer is kept.
• This applies to every surface that renders markdown images, so the PR description now says so, and the screenshots (dark and light) are re-shot with the new look.
• Tests: MarkdownRenderer.brokenImage.test.tsx gains a test that the failure is an ErrorNotice with the hand-off and that the wording is not in the chip; the existing copy, keyboard and probe tests address the chip by test id now that the notice adds a second button.

Checks on this head: every test vitest related finds for ImgWithFallback.tsx (923 files, 13,967 tests), tsc, eslint, i18n:check, docs lint.

[inariku]

Opus 5.5 and GPT 6.1 on 722f1e4 (the hand-off in the meeting note Preview): fixed in 0d92d4a by dropping the hand-off from the broken-image notice.

The fallback renders in every MarkdownRenderer host, including NoteSidebar's Preview of the unsaved note draft, which withholds the hand-off on its own notice for exactly this reason. A shared renderer cannot tell which host holds a draft, so the notice now carries no askAgent, with a No hand-off comment at the call site naming the meeting-note draft. That is one of the sanctioned states of errors-use-error-notice, and it needs no new context or plumbing through the hosts. The failure still renders through ErrorNotice, and the copy-path chip is unchanged.

Test: the ErrorNotice test now asserts there is no "Ask the agent" button. Screenshots re-shot. Checks on this head: every test vitest related finds for ImgWithFallback.tsx (923 files, 13,967 tests), tsc, eslint, docs lint.

[inariku]

GPT 6.1 on 0d92d4a (Windows fallbacks omit the previewed drive's root): fixed in ff1414b.

siteRootImageCandidates now ends with the file's own drive root on Windows, so D:\docs\post.md with ![](/images/a.png) tries D:\docs/images/a.png and then D:/images/a.png. The POSIX disk root is still left out, since there it is the same path as the absolute reading tried first; the doc comment says why the two differ. The test now uses a D: file and expects the drive-root candidate; it fails on 0d92d4a and passes now.

Checks on this head: every test vitest related finds for ImgWithFallback.tsx (923 files, 13,967 tests), tsc, eslint.