Skip to content

fix(markdown): resolve root-relative images against the file's site root - #23631

Merged
KiroCrewCaptain merged 2 commits into
kirodotdev:mainfrom
inariku:fix/md-root-relative-images
Oct 25, 2026
Merged

KiroCrewCaptain merged 2 commits into
kirodotdev:mainfrom
inariku:fix/md-root-relative-images

Conversation

@inariku

@inariku inariku commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

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".

Before: both images show the broken-image chip

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

After, dark theme

After, light theme

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.

@inariku
inariku requested review from a team and KiroCrewCaptain as code owners October 24, 2026 01:56
@inariku
inariku requested a review from buluoray October 24, 2026 01:56
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 24, 2026
@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of e9381ec2edd8d8cb6a27e75e2580baf581cd9819 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: the change is narrow and easy to revert. It only adds fallback paths after the absolute path has already failed, and every candidate still goes through /api/file-raw.

Notes

  • Moving the failure text into ErrorNotice (an element with role="alert") affects every surface that renders markdown, including chat, not only the file preview. A chat transcript with many deleted screenshots will now announce one alert per image when it loads. This is outside the PR's stated goal and could be its own PR.
  • The walk up the directory tree can pick the wrong image: a file with the same name in a nearer directory wins over the one at the real site root. Showing the image that was actually loaded, for example in its tooltip, would make that mismatch easy to diagnose.

[DESIGN-REVIEWED] e9381ec

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

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ✅ PASS

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

UX-Verdict: PASS

The committed dark and light screenshots show every changed element: the chip that now holds only the name and copy icon, and the inline "Image file no longer exists" notice beside it. Nobody has given the screenshots a blind read, because this is the fork lane. Pushing the branch to this repository adds one.

Notes

  • ErrorNotice variant="inline" makes the "Image file no longer exists" text red, and this renderer is used on every surface that shows markdown images. Old chat transcripts, where cleaned-up temp screenshots are the usual failure, will fill with red alarms the user can't act on. Make the notice muted (text-muted) there, or keep it muted unless the user can fix the file.
  • The notice carries role="alert", so a screen reader announces every broken image each time a transcript renders. A non-interrupting status role (polite) would avoid that.

[UX-REVIEWED] e9381ec

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

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

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

Premise-level review of e9381ec2edd8d8cb6a27e75e2580baf581cd9819 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

The root-relative fix works at the level of the code that produces the bug. The one rider, the move to ErrorNotice, is required by website/AGENTS.md (errors-use-error-notice). The one other caller with the same root cause, md-notebook's resolver, is tracked in #23630.

What this change ships

Inventory (6 items) — 6 justified

Intent: let someone previewing a repo's markdown file see images written as /images/… instead of a false "file no longer exists" (FIX, #23623).

  1. In a file preview, a /… image falls back to each folder above the file, nearest first, up to eight levels, after the absolute path fails — justified
  2. In every markdown surface, the broken-image failure text moves out of the copy chip into an inline ErrorNotice with no agent hand-off — justified
  3. Every link-image src gets a test id (md-broken-image-chip); tests now find it by that id, not by role — justified
  4. frontend-conventions.md paragraph describing the resolution order — justified
  5. Capture harness website/capture/shoot-root-relative-image.mjs + entry (an existing pattern: 17 sibling shoot-*.mjs) — justified
  6. Screenshots committed under temp-screenshots/ (sanctioned by .gitignore:121 and ux-review.yml) — justified

[FIRST-PRINCIPLES-REVIEWED] e9381ec

Description read

[DESCRIPTION-READ] 3307971ed61646fb20536147881bb49a6703d731e002a85d8a5e767d44b853a0

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

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] e9381ec

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] e9381ec

@inariku
inariku force-pushed the fix/md-root-relative-images branch from 3e3a39a to 21629b6 Compare October 24, 2026 02:16
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 24, 2026
@inariku

inariku commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 24, 2026
@inariku
inariku force-pushed the fix/md-root-relative-images branch from dc255af to 2803085 Compare October 24, 2026 04:52
@inariku

inariku commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 24, 2026
@inariku
inariku force-pushed the fix/md-root-relative-images branch from 2803085 to d9ba318 Compare October 24, 2026 09:36
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 24, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 24, 2026
@inariku
inariku force-pushed the fix/md-root-relative-images branch from 0d92d4a to ff1414b Compare October 24, 2026 13:44
@inariku

inariku commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 24, 2026
@inariku

inariku commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

@bolichen97 @iamwhatever @CrysisDeu could one of you re-run Security Scope Review on ff1414b69? Its generate job hit the 30-minute job timeout before the review started (scope-floor:unsettled, run 40100778783), so there is no verdict to answer. A fork PR cannot re-run it. Everything else is green, including GPT 6.1, Opus 5.5, Design, First Principles and UX; PR Readiness is waiting on that one lane.

@inariku
inariku force-pushed the fix/md-root-relative-images branch from ff1414b to dbf2ab7 Compare October 24, 2026 23:13
@inariku

inariku commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto current main as dbf2ab7e4 (49 commits behind, none touching these files; range-diff shows both commits unchanged). The new head runs every lane again, including Security Scope Review, so the re-run I asked for above is no longer needed.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 24, 2026
@inariku

inariku commented Oct 25, 2026

Copy link
Copy Markdown
Contributor Author

Two reds on dbf2ab7e4, neither from this branch:

Security Scope Review passed on this head, so the earlier re-run request is settled. All five AI review lanes pass.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 25, 2026
A markdown file opened in the file preview showed every image written
as /images/... as "Image file no longer exists", although the files
were on disk. GitHub, Zenn, Docusaurus and similar setups write a
leading slash to mean the root of the repository or site, but the
preview sent the path to /api/file-raw as an absolute filesystem path.

Inside a file preview (a BasePathCtx is set), a root-relative image now
tries the absolute path first, so a real absolute path still loads on
the first request, then each directory above the file, nearest first,
up to eight levels. The broken-image chip still names the path as
written. Outside a file preview nothing changes.

Fixes kirodotdev#23623
@inariku
inariku force-pushed the fix/md-root-relative-images branch from dbf2ab7 to e9381ec Compare October 25, 2026 01:42
@inariku

inariku commented Oct 25, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto c4ce1efa5, which carries the bundle-size fix #23867 (range-diff: both commits unchanged). Locally on the new head e9381ec2e: the bundle-size gate passes (927 chunks within budget), plus tsc and the 14,022 dependent vitest tests. The new head re-runs Internal Content Scan, which had no verdict on the last one.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 25, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 25, 2026 04:04

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tier 1 auto-approve: fix (10 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: bug fix so a root-relative markdown image in a previewed file falls back to the directories above the file (bounded to eight), with the broken-image fallback moved onto ErrorNotice; tests, a capture page and a conventions note ride along.

@KiroCrewCaptain
KiroCrewCaptain merged commit 2719ba9 into kirodotdev:main Oct 25, 2026
103 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

File preview: root-relative markdown images (/images/…) render as missing

2 participants