fix(plugins): rewrite relative README image URLs to source-host raw URLs

[momothemage]

fix(plugins): rewrite relative README image URLs to source-host raw URLs

Summary

Plugin detail pages currently render package READMEs verbatim, so a
normal Markdown reference like

![Overall architecture](./images/openclaw-plugin-engine-overview.png)

emits the relative path as-is. On a page like
https://clawhub.ai/plugins/@openviking/openclaw-plugin the browser
resolves it to https://clawhub.ai/plugins/@openviking/openclaw-plugin/images/openclaw-plugin-engine-overview.png,
which 404s — even though the same image is reachable in the source
repo on raw.githubusercontent.com and inside the npm tarball.

Reference: original report observed against @openviking/openclaw-plugin@2026.5.21.

fix: #2357

Why we don't proxy

The straightforward "fix" — serving package binary assets through
ClawHub itself — would push us into being a general image CDN, with
new storage, bandwidth, abuse and rewrite-route surfaces. We don't
need any of that for the actual problem: every release that has
this issue already carries a source.repo + source.commit,
because that pair is required to publish a code-plugin. The
images we want to render are already addressable on
raw.githubusercontent.com at a stable, content-addressed URL.

So the fix is rendering-side and stateless: rewrite the relative
URL when we know the source host. No new endpoints. No new
storage. No new allow-list beyond the
raw.githubusercontent.com entry already in vercel.json.

What changes

Rendering: rewrite at MarkdownPreview time

• New src/lib/readmeAssetBaseUrl.ts:
  buildReadmeAssetBaseUrl(release) returns
  https://raw.githubusercontent.com/<owner>/<repo>/<sha>/ when
  the release has a source.repo (or full source.url for older
  publishes) and a 40-hex source.commit. Anything else
  returns undefined.
  • 40-hex SHA is required on purpose. A moving ref like main
    would make a published page silently change images later;
    pinning to commit SHA keeps each release stable, which matches
    the rest of our package-page model.
  • Non-GitHub hosts are rejected. The raw URL pattern is
    GitHub-specific, and any other host would also need a separate
    vercel.json allow-list entry, which we deliberately don't
    add here.
• MarkdownPreview now accepts an optional assetBaseUrl prop and
  threads it through a new lightweight rehype pass
  rehypeRewriteRelativeImages (in src/lib/rehypeProxyImages.ts).
  The pass only touches <img src> whose value is relative
  (Markdown image refs become <img> after rehype, so this
  covers both syntaxes). Absolute URLs, protocol-relative URLs,
  data: URIs, fragment refs, and empty src are left untouched.
• src/routes/plugins/$name.tsx derives the base URL from the
  latest release and passes it into MarkdownPreview. Releases
  without a usable (repo, sha) pair fall back to the legacy
  behavior (leave the URL alone) — i.e. nothing regresses for
  releases this fix doesn't apply to.

Publish: warn when authors will hit this

Even with the rewrite in place, releases without source metadata
(e.g. bundle-plugin, or a code-plugin uploaded as a zip/tgz
without filling Source repo / Source commit) still can't be fixed
at render time. For those, we surface a non-blocking warning at
publish time:

• New src/lib/detectRelativeReadmeAssets.ts scans README text for
  relative image references — both Markdown ![](./x) and raw
  HTML <img src="./x"> — and returns up to 5 sample paths plus a
  total count. Absolute http(s), protocol-relative, data:,
  mailto:, tel:, and fragment refs are excluded; root-absolute
  paths like /foo.png are flagged because they break on the
  detail page just like ./foo.png.
• The publish form runs the scan after upload (using the same
  normalizePackageUploadFiles lookup the server uses, so the
  shallowest README is picked consistently) and renders a
  Badge variant="accent" warning under the Source repo / commit
  inputs only when relative images were detected and at
  least one of sourceRepo / sourceCommit is empty. Filling in
  those fields immediately hides the warning. Publish is never
  blocked.

What this does NOT change

• No new HTTP endpoint, route handler, or asset-proxy.
• No new storage, no DB schema change, no Convex action.
• No silent default to main / HEAD or any moving ref.
• No host-side allow-list change beyond what vercel.json already
  permits for raw.githubusercontent.com.
• No behavior change for releases that already render correctly
  (i.e. those with absolute README image URLs, or releases that
  happen to have no images at all).

Tests

File	Coverage
src/lib/readmeAssetBaseUrl.test.ts	6 cases: SHA validation, owner/repo and full-URL sourceRepo normalization, non-GitHub rejection, missing-metadata fallback.
src/lib/detectRelativeReadmeAssets.test.ts	9 cases: Markdown + raw-HTML detection, absolute / data: / protocol-relative / fragment exclusions, root-absolute path inclusion, dedup with total, 5-sample cap, markdown title segment.
src/components/MarkdownPreview.test.tsx (+3)	Relative <img> rewritten, absolute / data: left alone, assetBaseUrl omitted is a no-op.
src/__tests__/package-detail-route.test.tsx	Existing render assertions unchanged; resolved-URL paths covered indirectly via the MarkdownPreview tests above.
src/__tests__/plugins-publish-route.test.tsx (+3)	Warning fires for relative refs + no source, disappears once Source repo + commit are filled, never appears for absolute-only READMEs.

bunx vitest run \
  src/lib/readmeAssetBaseUrl.test.ts \
  src/lib/detectRelativeReadmeAssets.test.ts \
  src/components/MarkdownPreview.test.tsx \
  src/__tests__/package-detail-route.test.tsx \
  src/__tests__/plugins-publish-route.test.tsx
# 5 files, 72 tests, all passing

bunx oxfmt is clean across all touched files.

Manual verification path

For the issue's reference package:

1. @openviking/openclaw-plugin@2026.5.21 already has
   source.repo = "volcengine/OpenViking" and a 40-hex
   source.commit.
2. With this PR, the detail page resolves
   ./images/openclaw-plugin-engine-overview.png to
   https://raw.githubusercontent.com/volcengine/OpenViking/<sha>/images/openclaw-plugin-engine-overview.png,
   which is the same URL the report verified is reachable.
3. Subsequent releases pin to their own commit SHA, so the diagram
   set on the 2026.5.21 page stays exactly what was shipped at
   that release even if the source branch moves later.

For releases without source metadata (bundle plugins, zip uploads
that skipped the Source fields), the publish form now surfaces the
relative-image warning at the moment of publish so the author can
either fill in source metadata or rewrite the README to absolute
URLs before shipping. They can still publish — the warning is
informational.

Risk

Low.

• The rewrite path is gated behind a strict 40-hex SHA + GitHub
  host check, so the only way to produce a base URL is the same
  combination authors already use to refer to a stable source.
• When the gate fails, behavior is identical to today (relative
  src untouched), so any release that doesn't qualify simply
  inherits the pre-PR behavior.
• The publish warning is informational and never disables the
  Publish button.

Related

• Original issue: relative README image URLs 404 on plugin detail
  pages (e.g. @openviking/openclaw-plugin).
• Out of scope (intentionally): rewriting non-image relative
  resources (e.g. <a href="./CONTRIBUTING.md">), supporting
  non-GitHub source hosts, mirroring binary assets on ClawHub.

I confirmed in DevTools that rendered tags now have src="/_vercel/image?url=https%3A%2F%2Fraw.githubusercontent.com%2F...%2Fimages%2Ffoo.png&w=1024&q=75" instead of the original relative ./images/foo.png. This proves the README rewrite pipeline (buildReadmeAssetBaseUrl → rehypeProxyImages) is working end-to-end.

The images still 404 in my local environment, but that's unrelated to this fix: /_vercel/image is Vercel's built-in image-optimization endpoint and is only served by Vercel's edge runtime. A plain bun dev (or vite dev) doesn't provide it, so any request to /_vercel/image?... returns 404 locally. On a real Vercel deployment (or under vercel dev) the endpoint is available and the images load correctly.

[vercel]

@momothemage is attempting to deploy a commit to the Amantus Machina Team on Vercel.

A member of the Team first needs to authorize it.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 2, 2026, 7:56 AM ET / 11:56 UTC.

Summary
The PR rewrites package README relative img src values from GitHub source metadata, adds verification.sourcePath plumbing and fallbacks, publish-form warnings, tests, and small e2e/proof helper changes.

Reproducibility: yes. Source inspection shows current main passes relative README images through, and the PR gap is reproducible from source with a supported <picture><source srcset="./dark.png"><img src="./light.png"></picture> README where only the fallback img is rewritten.

Review metrics: 2 noteworthy metrics.

• Changed files: 23 files, +1289/-19. The patch spans renderer, publish UI, Convex schema/API plumbing, schema package output, tests, e2e helpers, and proof tooling.
• Public verification fields: 1 optional field added. verification.sourcePath affects persisted package metadata and API consumers, so upgrade behavior and generated schema output matter before merge.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦐 gold shrimp
Patch quality: 🦐 gold shrimp
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Rewrite and test supported picture source srcset image candidates.
• [P1] Add redacted Vercel preview, production, network, or terminal proof showing the affected README image loads successfully.

Proof guidance:

• [P1] Needs stronger real behavior proof before merge: The inspected screenshot shows after-fix DOM img src rewriting, but it does not show the _vercel/image request succeeding or the affected image visibly loading on Vercel/production; add redacted screenshot, video, network output, terminal output, or logs and update the PR body for re-review.

Mantis proof suggestion
A browser proof would materially verify the visible plugin README image load on a Vercel-style runtime. A maintainer can ask Mantis to capture proof by posting a new PR comment that starts with the OpenClaw Mantis account mention, followed by:

visual task: verify the OpenViking plugin detail page renders README images from raw GitHub URLs on a Vercel preview, including picture/source srcset behavior if added.

Risk before merge

• [P1] Supported picture source srcset entries can still resolve under the ClawHub route and 404 because the new rewrite pass ignores non-img nodes.
• [P1] The screenshot proves rewritten DOM src values, but the final /_vercel/image request for the affected OpenViking page is not proven on a Vercel or production-like runtime.

Maintainer options:

1. Fix image carriers and proof before merge (recommended)
   Update the rewrite logic and tests for supported source srcset image candidates, then add Vercel/browser proof that the affected README image visibly loads or returns 200.
2. Accept img-only scope intentionally
   Maintainers could merge this as an img src-only improvement, but the linked issue should remain open or the PR body should document unsupported picture/source cases and missing runtime proof.

Next step before merge

• [P1] Human follow-up is needed because the patch has a supported srcset gap and the contributor still needs real runtime proof that Vercel-optimized images load.

Security
Cleared: No concrete security or supply-chain regression was found; the diff adds no dependencies or endpoints and keeps rewritten images behind the existing sanitizer and Vercel image allow-list.

Review findings

• [P2] Rewrite picture source srcset values too — src/lib/rehypeProxyImages.ts:88-89

Review details

Best possible solution:

Cover all supported README image carriers, including img src and source srcset, then land after real Vercel/browser proof shows the reported image loads successfully.

Do we have a high-confidence way to reproduce the issue?

Yes. Source inspection shows current main passes relative README images through, and the PR gap is reproducible from source with a supported <picture><source srcset="./dark.png"><img src="./light.png"></picture> README where only the fallback img is rewritten.

Is this the best way to solve the issue?

No, not yet. The source-metadata rewrite is a maintainable strategy and the new sourcePath fallback fixes the earlier stored-release blocker, but the renderer should also cover supported srcset image candidates and show final image-load proof.

Full review comments:

• [P2] Rewrite picture source srcset values too — src/lib/rehypeProxyImages.ts:88-89
MarkdownPreview deliberately allows <picture><source srcset> through sanitization, but this new pass only rewrites img[src]. In a supported README banner, the browser can select the relative source[srcset] candidate and still request it under the ClawHub route, so the image 404 remains even though the fallback img was rewritten. Please rewrite source[srcset] candidates against assetBaseUrl as well, with a focused regression test.
  Confidence: 0.86

Overall correctness: patch is incorrect
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against ce62df9d0886.

Label changes

Label changes:

• add merge-risk: 🚨 other: Green CI can pass while supported README picture/source image URLs and Vercel optimizer loading remain unproven, leaving part of the linked image-404 problem unresolved.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🦐 gold shrimp.
• remove proof: sufficient: Current real behavior proof status is insufficient, not sufficient.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.

Label justifications:

• P2: This is a normal-priority plugin detail rendering bug fix with limited blast radius, but the PR still has a concrete edge-case gap before merge.
• merge-risk: 🚨 other: Green CI can pass while supported README picture/source image URLs and Vercel optimizer loading remain unproven, leaving part of the linked image-404 problem unresolved.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🦐 gold shrimp.
• status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Needs stronger real behavior proof before merge: The inspected screenshot shows after-fix DOM img src rewriting, but it does not show the _vercel/image request succeeding or the affected image visibly loading on Vercel/production; add redacted screenshot, video, network output, terminal output, or logs and update the PR body for re-review.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The inspected screenshot shows after-fix DOM img src rewriting, but it does not show the _vercel/image request succeeding or the affected image visibly loading on Vercel/production; add redacted screenshot, video, network output, terminal output, or logs and update the PR body for re-review.

Evidence reviewed

What I checked:

• PR head derives README asset base from verification metadata: PluginDetailPage builds readmeAssetBaseUrl from verification.sourceRepo, verification.sourceCommit, and verification.sourcePath, then passes it into MarkdownPreview. (src/routes/plugins/$name.tsx:420, 5a68167107b6)
• PR head only rewrites img src nodes: rehypeProxyImages returns unless the element tag is img and then reads properties.src, so allowed source srcset values inside picture are not rewritten. (src/lib/rehypeProxyImages.ts:88, 5a68167107b6)
• MarkdownPreview explicitly allows picture/source markup: The sanitizer schema keeps picture and source with srcSet/srcset, so these are supported README image carriers that can still contain relative URLs after this PR. (src/components/MarkdownPreview.tsx:30, 5a68167107b6)
• Existing-release sourcePath fallback was added: The latest head derives missing public verification.sourcePath from packageReleases.source.path for package and release responses, which addresses the prior stored-release metadata gap in the review thread. (convex/packages.ts:767, 5a68167107b6)
• Contributor proof is DOM-only for the network-sensitive path: The PR comment says DevTools showed rewritten /_vercel/image?...raw.githubusercontent.com... src values, but also says the images still 404 locally and relies on a real Vercel deployment for successful loading. (5a68167107b6)
• Vercel runtime proof is not available on this head: The current head status includes Vercel – clawhub failure with Authorization required to deploy, so the PR has no preview-deployment proof of the optimizer URL returning a loaded image. (5a68167107b6)

Likely related people:

• Jesse Merhi: Blame shows the current MarkdownPreview/image proxy and public package verification baseline came from 90de729, and recent package publish/schema history includes dcbc389. (role: introduced renderer and package baseline; recent package registry contributor; confidence: high; commits: 90de729fe135, dcbc38999f1a; files: src/components/MarkdownPreview.tsx, src/lib/rehypeProxyImages.ts, convex/packages.ts)
• Patrick-Erichsen: Recent history shows ff48b2c changed convex/packages.ts around public package release shaping adjacent to this PR's toPublicPackageRelease path. (role: recent adjacent package release contributor; confidence: medium; commits: ff48b2cc7020; files: convex/packages.ts, src/routes/plugins/$name.tsx)
• Vyctor H. Brzezowski: git log --follow shows 321df22 recently changed the plugin publish form surface touched by the new README asset warning UI. (role: recent publish UI contributor; confidence: medium; commits: 321df223b2ef; files: src/routes/plugins/publish.tsx)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[momothemage]

I confirmed in DevTools that rendered tags now have src="/_vercel/image?url=https%3A%2F%2Fraw.githubusercontent.com%2F...%2Fimages%2Ffoo.png&w=1024&q=75" instead of the original relative ./images/foo.png. This proves the README rewrite pipeline (buildReadmeAssetBaseUrl → rehypeProxyImages) is working end-to-end.

The images still 404 in my local environment, but that's unrelated to this fix: /_vercel/image is Vercel's built-in image-optimization endpoint and is only served by Vercel's edge runtime. A plain bun dev (or vite dev) doesn't provide it, so any request to /_vercel/image?... returns 404 locally. On a real Vercel deployment (or under vercel dev) the endpoint is available and the images load correctly.

[momothemage]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[momothemage]

@clawsweeper re-review

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

Re-review progress:

• State: Superseded
• Detail: A newer re-review for this item started before this run finished, so GitHub cancelled this older run. Check the latest ClawSweeper run for the current result.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26757846038
• Updated: 2026-06-01T13:31:43.957Z

[momothemage]

@clawsweeper automerge

[clawsweeper]

🦞🔧
ClawSweeper picked up the repair feedback.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper needs-human verdict with repairable P-severity findings (sha=5a68167107b696d74e586ee346e66cf3d596ca5d)
Action: repair worker queued. Run: https://github.com/openclaw/clawsweeper/actions/runs/26817320474
Model: gpt-5.5

I will update this PR branch, or open a safe credited replacement, if the repair worker finds a narrow fix.

Automerge progress:

• 2026-06-02 11:28:03 UTC repair completed 26120737b172 (branch updated) in 5m 18s Run: https://github.com/openclaw/clawsweeper/actions/runs/26816398690 initial automerge rebase is delegated to Codex repair

• 2026-06-02 11:28:03 UTC review queued 26120737b172 (after repair)

• 2026-06-02 11:38:06 UTC automerge wait 26120737b172 (waiting) in 15m 20s Run: https://github.com/openclaw/clawsweeper/actions/runs/26816398690 waiting for exact-head ClawSweeper review pass

• 2026-06-02 11:38:07 UTC repair finished 26120737b172 (pushed) in 15m 22s Run: https://github.com/openclaw/clawsweeper/actions/runs/26816398690 repair_contributor_branch

• 2026-06-02 11:39:58 UTC review requested repair 26120737b172 (structured ClawSweeper marker: fix-required (finding=review-feedback sha=261207...)

• 2026-06-02 11:40:18 UTC repair queued 26120737b172 (autonomous) Run: https://github.com/openclaw/clawsweeper/actions/runs/26817320474

• 2026-06-02 11:41:37 UTC repair started (running) in 0s Run: https://github.com/openclaw/clawsweeper/actions/runs/26817320474 automerge-openclaw-clawhub-2412

• 2026-06-02 11:41:41 UTC validation plan (passed) in 5s Run: https://github.com/openclaw/clawsweeper/actions/runs/26817320474 bun run check

• 2026-06-02 11:41:53 UTC Codex write preflight (passed) in 17s Run: https://github.com/openclaw/clawsweeper/actions/runs/26817320474 danger-full-access

• 2026-06-02 11:46:56 UTC Codex edit 1 26120737b172 (complete) in 5m 20s Run: https://github.com/openclaw/clawsweeper/actions/runs/26817320474 exit 0

• 2026-06-02 11:49:57 UTC validation and review 1 5a68167107b6 (complete) in 8m 20s Run: https://github.com/openclaw/clawsweeper/actions/runs/26817320474 already-current

• 2026-06-02 11:50:01 UTC repair completed 5a68167107b6 (branch updated) in 8m 25s Run: https://github.com/openclaw/clawsweeper/actions/runs/26817320474 initial automerge rebase is delegated to Codex repair

• 2026-06-02 11:50:01 UTC review queued 5a68167107b6 (after repair)

• 2026-06-02 12:00:04 UTC automerge wait 5a68167107b6 (waiting) in 18m 28s Run: https://github.com/openclaw/clawsweeper/actions/runs/26817320474 waiting for exact-head ClawSweeper review pass

• 2026-06-02 11:56:39 UTC review requested repair 5a68167107b6 (structured ClawSweeper needs-human verdict with repairable P-severity findings...)

• 2026-06-02 12:00:05 UTC repair finished 5a68167107b6 (pushed) in 18m 29s Run: https://github.com/openclaw/clawsweeper/actions/runs/26817320474 repair_contributor_branch

[momothemage]

@clawsweeper automerge

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

[momothemage]

@clawsweeper automerge

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

[momothemage]

@clawsweeper automerge

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26813237953
• Updated: 2026-06-02T10:20:34.293Z

[momothemage]

@clawsweeper automerge

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.