#3825 Extension registry page: a supported way to include media (images) in the README

Problem

The extension page (/extensions/<name>) renders the packaged README.md as markdown, but there is no supported way to put a picture in it.

Bundled files aren't reachable over HTTP, so relative references break even though the file is in the archive:

• GET /extensions/@maphew/club-pulse/README.md → 404
• GET /extensions/@maphew/club-pulse/files/pulse-view.sh → 404 (that extension does ship binaries: files, which pull lands at <ext>/files/)

An image also can't ride along as a normal asset, because additionalFiles only accepts .ts, .json, .md, .yaml, .yml, .txt (push: "Disallowed extensions"). The only way in is binaries:, which is documented for executables, not for README media.

The practical result is that a README can only show a picture by pointing at an external host (GitHub raw content, a shields.io badge, …). That is fragile and a bit absurd for the most obvious use case: a screenshot or diagram of this extension's own output (e.g. a dashboard HTML artifact or a report table).

Evidence it simply isn't being used: I sampled 200 published extension pages and found zero <img> elements and zero relative links inside the rendered README (div.ext-readme.markdown-body). The site CSS styles images globally (img { max-width:100%; height:auto }) but has no .ext-readme img rule.

Request

A minimal, documented way to include media in the README on the registry page. Format and limits are your call; from the outside, an SVG-first policy looks cheap and safe:

• SVG preferred: text, diffable, reviewable, and small — it can go through the same safety scanner and human review as any other text asset, rather than asking anyone to trust an opaque blob. I'm not sure a vector-only restriction is practical (screenshots, terminal captures, generated charts are raster), so treat that as a preference, not a hard requirement.
• Small, explicit cap (e.g. tens of KB per file, a low per-extension media budget) so scanning/redaction stays feasible and no one can upload a novel.
• Bundled, not fetched: serving the file from the published archive keeps the page self-contained and avoids link rot on external hosts.

Any of these would close it:

1. Serve additionalFiles-adjacent media from a stable registry URL and rewrite relative image refs in the rendered README (so ![](dashboard.svg) works and push validates the file).
2. Or keep external URLs as the only path — but then say so explicitly in the publishing docs, plus what the renderer's sanitizer allows (plain markdown images? raw <svg>? data: URIs?), so authors don't burn a version push discovering it.

If images are going to be stripped regardless, a single sentence in the publishing reference ("README images are not rendered on the registry page") would be an acceptable minimum outcome — it's the silent failure that costs time.

Notes

• Not routed to an extension: this is the registry page / publish pipeline, not one package's behavior. Happy to re-route if it belongs in a specific queue.
• Happy to be listed as a co-author if this ships, and happy to test a preview or a canary build — I have a real case waiting (@maphew/club-pulse has a self-contained HTML dashboard whose screenshot would explain the extension at a glance).