Skip to content
SHC Docs

Marketplace screenshots (2026-08-16)

Archived, shipped. Now described in App definition.

Vocabulary note: presets and vpresets have since been abolished and replaced by add-ons: one apps/<bucket>/<app>/addons/<name>.addon.yaml per add-on, typed by the presence or absence of a vapp: key. This document is left as written; the current shape is docs/app-development/addons.md.

Status: PROPOSAL, nothing implemented, no field added, no bytes captured. Owner-reported symptom: “missing all the icons and screenshots.” Icons are a sibling lane, and they are a pipeline defect: the data exists in the repo (82 of 90 packages carry icon:; 52 icon files are committed, 348,662 B total) and the storefront drops it on the floor. Screenshots are not that. There is no data to drop.

This document is measurement first, recommendation second, and it ends with the questions only the owner can answer. It deliberately does not propose a schema change or a capture script, because the load-bearing decisions here are legal and editorial, not technical, and every technical option below is cheap once those are ruled.


All figures below were taken on 2026-08-16 against this checkout (main) and against the live storefront. Reads only; nothing was written anywhere.

0.1 The data does not exist, confirmed, and narrowed

Section titled “0.1 The data does not exist, confirmed, and narrowed”
QuestionMeasured
First-party app.yaml under apps/, excluding tests/ fixtures90 (git ls-files filtered; 99 including the 9 test-fixture consumers)
Of those, carrying screenshots:0
Of those, carrying gallery:0
Repo-wide matches for “screenshot” in shipped YAML3, all prose in comments: apps/standalone/agent-canvas/compose.yaml:130, apps/flagship/openreplay/compose.yaml:675, apps/integrated/journiv/app.yaml:144

So the owner’s framing is exactly right: nobody has ever captured one.

Count reconciliation: the brief cited 109 app.yaml files. Repo-wide find returns 254, but that sweeps installed-state copies under .shc/data/apps/, staged built-ins under .make/staged/, cloud-campaign fixtures under tests/clouds/, and deployment snapshots under .shc/state/. The tracked, first-party catalogue is 90 packages, which is also the number the live storefront renders. Every figure in this document uses 90.

0.2 But the vocabulary is already ruled, and the ingest already exists

Section titled “0.2 But the vocabulary is already ruled, and the ingest already exists”

This is the single most useful thing this lane found, and it changes the shape of the answer.

docs/proposals/2026-07-17-app-metadata-schema.md:51 already names the canonical field:

SHC canonicalConceptRemaps from
galleryscreenshot URLsumbrel gallery, casaos screenshot_link, cloudron mediaLinks

And three foreign-catalog adapters already emit it today, proven by tests in this repo:

  • tests/unit/modules/adapter/adapters/casaos/casaos_test.go:134: “screenshot_link → gallery”, asserting the generated app.yaml contains - https://cdn.example.com/casaos/nextcloud/screenshot-1.png
  • tests/unit/modules/adapter/adapters/cloudron/cloudron_test.go:112: “mediaLinks → gallery”
  • tests/unit/modules/adapter/adapters/umbrel/umbrel_test.go:133: - 1.jpg, annotated // gallery

Consequence: an app imported from CasaOS gets screenshots and an app we package ourselves does not. The asymmetry is the defect, not the absence of a field. Any proposal that invents a new screenshots: key forks the dialect against a schema decision already taken and already implemented on the foreign side. If this lane ships anything, the key is gallery:.

0.3 Adding the field is free at the wire-compat level

Section titled “0.3 Adding the field is free at the wire-compat level”

KnownFields(true) appears 0 times in the vendored ce module (grepped; also asserted independently by tests/unit/ci/apps_index_images_test.go:160 and tests/unit/catalog/plug_key_readers_test.go:18). app.yaml decoding is lenient everywhere. An added gallery: key is therefore silently ignored by every older daemon, the same additive-field precedent scripts/gen-apps-registry-index.go:129 records for Flagship. No version break, no migration. The cost of this lane is entirely in producing and maintaining the bytes, not in carrying them.

0.4 The storefront has no image pipeline at all

Section titled “0.4 The storefront has no image pipeline at all”
  • <img> tags in the served storefront home document: 0.
  • apps/marketplace/public/ contains exactly two files, both fonts (inter-400.woff2, inter-700.woff2).
  • Icons on the storefront are synthesized, not fetched: features/marketplace/src/catalog/AppGlyph.tsx: “the bench ships no artwork, so every app gets a deterministic Flathub-grade glyph tile.”
  • The catalog bench’s App Listing DocType has 8 fields and no image field (image_field: None in frappe/apps/marketplace/.../app_listing/app_listing.json): app_name, title, description, category, bucket, latest_version, license_posture, published.

So screenshots require inventing an image origin from zero. That is a real cost and it is separate from capture.

0.5 The 8.36 MB page is a red herring, measured

Section titled “0.5 The 8.36 MB page is a red herring, measured”

This matters enough to state plainly, because the brief’s framing (“adding screenshot payload naively would make a mobile page load genuinely painful”) is correct in conclusion but wrong in mechanism, and the wrong mechanism would lead to the wrong fix.

GET https://marketplace.selfhostedcloud.org/
uncompressed document 8,329,369 B (7.94 MiB)
actual transfer (gzip) 178,252 B ← what a phone downloads today
brotli -q11 (not currently served) 53,594 B
decomposition of the uncompressed document:
inlined tamagui.css style block 8,284,381 B = 99.46% of the document
…which gzips to 140,159 B
everything else (HTML, 23 inline scripts totalling 890 B)
40,432 B → gzip 4,225 B

The 8.36 MB is parse and memory cost, not network cost. Atomic CSS is pathologically repetitive, so it compresses 46.7×. The storefront currently costs a phone 178 KB.

Screenshots behave the opposite way. They are already-compressed binary and gzip does essentially nothing, measured on a real capture: a 13,640 B WebP gzips to 13,594 B, a 0.3% saving. Every screenshot byte is a byte on the wire.

That is the whole sizing argument. Against a 178 KB page, a single 46 KB hero shot is +26%. A naive four-shot gallery loaded eagerly is +184 KB; it more than doubles the page. Not because the page is 8 MB, but because the page is really 178 KB.

(Side finding, free money, belongs to whoever owns the storefront build: serving brotli instead of gzip cuts the current page from 178 KB to 54 KB, a 124 KB saving, i.e. it pays for two hero screenshots and change. Worth raising separately regardless of what is ruled here.)

0.6 What a screenshot actually weighs: measured, not estimated

Section titled “0.6 What a screenshot actually weighs: measured, not estimated”

Four real 1440×900 viewport captures, re-encoded with ImageMagick at WebP q82 and JPEG q80:

Subject1440px webp1200px webp960px webp640px webp1200px jpeg
Storefront home (sparse UI)35,09227,35020,16811,47657,111
Immich login (very sparse)17,06413,64010,2105,70430,360
Grafana (mid-density chrome)24,71619,49814,6908,23835,615
Gitea explore (dense text UI)57,58846,07633,39018,15281,430

Working budget: 1200px WebP q82, 14–46 KB, plan on 45 KB p90. WebP beats JPEG by ~1.8× at equal perceptual quality on this content. AVIF was not measurable here (magick on this box has no AVIF encode delegate); AVIF would typically land another 20–30% below WebP but adds an encoder dependency to the build; see the questions.

0.7 The capture problem, measured by accident, and this is the finding

Section titled “0.7 The capture problem, measured by accident, and this is the finding”

I pointed a headless browser at two real, public, running instances of apps in our catalog’s own categories, the way an unattended CI screenshotter would. Two attempts, two unshippable images:

  1. https://demo.immich.app/ → a login form. Not the photo grid. Just “Login”, two empty fields, and a red banner reading “Due to abuse, uploads to this instance are disabled.”
  2. https://play.grafana.org/d/000000012/grafana-play-home → a “Dashboard not found” error page with a red toast, because the dashboard behind that hardcoded deep link had moved.

I was not trying to demonstrate this. It is simply what naive capture produces.

The expensive part of auto-capture is not the browser. It is the authenticated, seeded, deterministic application state, per app, maintained forever. Anyone costing this lane as “we already have Playwright” has costed the cheap half.

AssetWhereReusable for this?
Playwright + chromium-headless-shell in CI, cached on the runner bind mount at PLAYWRIGHT_BROWSERS_PATH=/ci-cache/ms-playwright.gitlab-ci.yml:3572-3589 (the pages job, for rehype-mermaid)Yes, the browser is already free. ~100 MB download happens once per browser rev, not per job.
Per-app live boot: shc test run ./apps/<app> against an isolated shcd, bats cwd is apps/<app>/testsMakefile:200-235Yes, and this is the real hook. 89 of 90 packages ship tests/tests.bats; 75 make HTTP calls; 84 reference login/password/admin. The app is already up and in many cases already authenticated.
Freshness verifier doctrinecmd/verify-preset-freshness, make catalog/freshness (Makefile:581)Yes, as a template; see §4.
Live cloud deployment campaignstests/clouds/*, tests/hetzner/*No, not per-release. These are manually driven and cost real cloud spend. The main pipeline has 4 top-level jobs (lint, images, pages, plus the deployfile include) and no per-app live-deploy job.
  • 68 of 90 packages carry license: {id: unverified}. We do not know the code license for 76% of the catalog.
  • A code license does not grant screenshot or trademark rights in any case. AGPL/Apache cover source, not marketing assets or marks.
  • This exact concern is already on the record in this repo: docs/proposals/2026-07-17-manifest-adapters.md:151: “Licensing generally is a legal decision, not engineering: the Umbrel platform is PolyForm Noncommercial; catalog + gallery screenshots need diligence before any verbatim ingest, given SHC is commercially deployed.”

Three options were posed. Measured verdicts:

Viable at 21, not at 90. The work is not the capture, it is that a hand-captured shot has no mechanism forcing it to be re-taken, so it silently becomes the stale-screenshot problem of §4 the moment an app updates. Cost per release: zero automated, unbounded human. Realistic only against a small, explicitly enumerated set someone is willing to own by name.

Option B: auto-captured by driving the app in CI

Section titled “Option B: auto-captured by driving the app in CI”

Viable, but the cost is 90 seeded-scenario recipes, not 90 screenshots. §0.7 is the evidence: unattended navigation yields login screens and error pages. To get a shippable frame you must, per app, know the URL, the credential, the seed data, and the “is it done painting yet” condition, and keep all four true as upstream changes.

The honest good news is that we have already paid most of that bill: shc test run ./apps/<app> boots the app for real, and 84 of 89 bats suites already handle login. The incremental ask is a browser step plus a per-app recipe naming which screen. That is a much smaller ask than “drive each app in CI” sounds.

The honest bad news is that the recipe is per-app hand work with ongoing maintenance, i.e. it carries Option A’s maintenance burden plus a build system. Its advantage is that the burden becomes enforceable (a broken recipe is a red job) rather than invisible (a stale JPEG is green forever). That advantage is the entire case for Option B, and it is a good one.

Also unmeasured and material: nobody has timed a full app-suite boot. Ninety of them serially on release-tag CI may be an hour or may be six. A pilot must measure this before anyone commits to catalog-wide auto-capture.

Refuse as a default path; permit as a per-app, evidenced exception. 76% unverified code licensing (§0.9), code licenses that do not cover artwork anyway, an existing in-repo ruling that this is a legal question, and SHC is commercially deployed. Blanket ingest of vendor screenshots is not ours to make.

Where a vendor does grant it (many publish press kits with explicit terms), that is a fine source, but the grant must be recorded next to the asset with the URL and the date it was read, exactly the way the vpreset catalogues record what they consulted and when. An unattributed vendor screenshot in our storefront is a liability with no paper trail.

Not one source, a source discriminator per asset, so the catalog can always answer “where did this come from and who may we show it to”:

gallery:
- path: gallery/dashboard.webp
source: captured # captured | vendor | none
caption: Project dashboard
captured_from: "1.24.3" # app version the frame was taken at

vendor entries additionally carry the grant URL and the date it was read. This costs nothing now and is the difference between a catalog that can be audited and one that cannot.


2.1 Not in the Frappe bench’s sites: volume

Section titled “2.1 Not in the Frappe bench’s sites: volume”

Frappe’s /files store is the obvious-looking answer; bench-web already serves /files via application_with_statics(), and it is a trap. The marketplace compose file states the invariant and plants its own tripwire:

“All of it is DERIVED today; scripts/import_catalog.py re-seeds the catalog from any release tag, which is why there is still no backup.yaml; the day reviews or vendor submissions land, that stops being true and this comment is the tripwire.” deploy/shc/marketplace/compose.yaml, volumes: block

Uploading screenshots into the bench makes bench state non-derived and buys a backup.yaml plus a restore path plus a disaster story, for a catalog whose whole current virtue is that losing it costs one re-seed. Do not put screenshot bytes in the bench. Put the reference there (a path or URL string on App Listing) and the bytes elsewhere.

The storefront container is already declared stateless and image-baked:

“Stateless: one serve reads the dist baked into the image and writes nothing, no volumes, and replicas scale freely. Every byte this service serves is redeployed by rebuilding the image, which is what makes the deployfile’s per-commit image tag the whole state of the frontend.”

Screenshots committed under apps/<app>/gallery/ and copied into the storefront’s public/ at build time preserve that invariant exactly, need no CDN, no new service, no new volume, and no new failure mode. A screenshot then ships and rolls back atomically with the release that describes it, which is also, conveniently, the freshness property §4 wants.

Repo-weight cost of this choice, measured against what apps/ already carries (52 icons, 348,662 B, avg 6,456 B):

SliceAssetsAt 45 KB p90Multiple of today’s icon payload
1 hero × 21 flagship21~0.9 MB2.7×
1 hero × 90 apps90~4.0 MB12×
4-shot gallery × 90 apps360~16 MB46×

The first row is a rounding error in a repo this size. The third row is a real git-weight decision that deserves an explicit ruling (see §5), and if it is ever taken, the answer is probably a release-artifact bucket, not git.

Derived from §0.5 and §0.6, not from taste:

  • Format: WebP q82. ~1.8× better than JPEG on this content, universally supported. AVIF is a further 20–30% but adds a build dependency; not worth it for a first slice; revisit if a full gallery is ever ruled.
  • Intrinsic width 1200px, one 2400px variant only if a lightbox is built. 1440px buys ~25% more bytes for pixels a card never shows.
  • Never inline. No data: URIs. A separate cacheable file per asset means the document stays 178 KB, the image is a second request the browser can defer, and a repeat visit pays zero.
  • loading="lazy" + explicit width/height on every image. Explicit dimensions are not optional; without them a lazy image reflows the card grid on arrival, which is a worse experience than no screenshot.
  • Below the fold by construction. The catalog grid keeps the synthesized AppGlyph (§0.4); glyphs are free and already good. Screenshots appear only on ListingDetailScreen, i.e. one page, one app, at most a handful of assets. This alone bounds the payload regardless of how large the gallery grows.
  • Budget to enforce in CI: a listing detail page must stay under +150 KB of image bytes above the fold. At 45 KB p90 that is three assets, and it is a number a test can assert rather than a principle someone remembers.

Recommended first slice: one hero shot for the 21 flagship apps. 21 assets, ~0.9 MB, no new service, no schema fork, no legal exposure.

Rationale, all of it measured:

  • Flagship is already a first-class distinction in the catalog (docs/decisions/2026-08-06-flagship-tier.md). The slice is the apps/flagship/ bucket, 21 packages (not the separate flagship: league key, which only 3 packages carry). It is a set that exists for exactly this reason: the apps we want to be judged on.
  • 21 assets is hand-capturable and hand-maintainable by one person, which makes it a slice that can ship this month instead of a program that ships next quarter.
  • It is enough to answer the owner’s actual complaint. A storefront where the 21 apps you would show someone all have a picture does not read as “missing all the screenshots.”
  • One hero is ~26% of current page weight on the one page that shows it, versus a four-shot gallery that would double it (§0.5).
  • Critically, it does not foreclose anything. The gallery: list is a list. Shipping one entry per flagship app is the honest first element of the same structure a full gallery would use.

Explicitly out of the first slice: the 69 non-flagship apps, multi-shot galleries, lightboxes, video, AVIF, any CDN, any bench upload path, and any vendor-sourced asset.

A defensible fallback for the other 69: keep the synthesized glyph. It already looks deliberate rather than broken, which is the only thing a missing screenshot must not do.


A stale screenshot is worse than none, agreed, and it is the reason a hand-captured-only program is a slow-motion defect. The repo already contains the right answer’s shape.

4.1 Copy cmd/verify-preset-freshness’s doctrine, not its code

Section titled “4.1 Copy cmd/verify-preset-freshness’s doctrine, not its code”

That command exists for a structurally identical problem, stated in its own header: “Upstream was consulted once, at authoring time, and the answers were frozen … So the catalogue rots on UPSTREAM’s clock, not the repo’s, and nothing notices.” Replace “catalogue” with “screenshot” and the sentence is unchanged.

What to carry over verbatim:

  • Its verdict vocabulary: OK / WARNING / UNVERIFIED / BROKEN (main.go:172-188). The four-value split matters: “I could not check this” is not “this is fine”, and conflating them is how guards die.
  • Its acknowledgement file pattern: apps/FRESHNESS_UNVERIFIABLE, which is “self-stale-ing in both directions”: the guard fails if a line names a subject it could now measure. That is what stops an exemption list rotting into a blanket exemption. A screenshot guard needs the same file for the apps whose UI genuinely cannot be reached by a credential-free probe.
  • Its lane placement: network-dependent, therefore outside make lint and outside make test (the unit suite stays hermetic), driven by its own make target and its own CI job, on release tags plus a daily schedule, “because a catalogue rots while nobody is pushing.”
  • Its refusal to pass over what it cannot see: every unmeasured subject itemised with a reason, and an acknowledgement suppresses the failure, never the report.

The cheapest true signal is already in the data model and needs no probe: the app version the frame was captured at, recorded as captured_from: on the asset, compared against app.yaml’s version:.

ConditionVerdict
captured_from == current versionOK
captured_from trails by a patchOK (UIs rarely move on patches)
captured_from trails by a minorWARNING
captured_from trails by a majorBROKEN; a major is exactly when the UI is redrawn
asset present, captured_from absentUNVERIFIED

This is hermetic, costs no network, runs in milliseconds, and would have caught every stale asset in a hand-captured program. It is strictly better than nothing and it is available on day one of the first slice.

A perceptual-diff tier (re-capture and compare against the committed frame, flagging on a pixel-delta threshold) is the right long-term answer and should be explicitly deferred: it presupposes the reliable capture harness §1 Option B has not built yet, and it is meaningless without it.

4.3 The property that makes this tractable

Section titled “4.3 The property that makes this tractable”

Because §2.2 bakes assets into the release image, a screenshot and the version it depicts ship together and roll back together. Freshness stops being a background-drift problem and becomes a per-release assertion. That is worth more than any verifier, and it is a free consequence of the storage choice.


Ordered so that a “no” high up saves the work below it.

  1. Do we ship screenshots at all in this cycle, or is the flagship-tier glyph good enough for now? The synthesized AppGlyph currently reads as deliberate design, not as breakage. If the answer is “glyphs are fine, fix icons first,” this lane closes today and the icons lane gets the attention; which is defensible, because icons are a pipeline bug with existing data and screenshots are a new content program.

  2. gallery: or screenshots:? Recommendation: gallery:. The metadata-schema proposal already ruled it, and the CasaOS/Cloudron/Umbrel adapters already emit it; a new key forks the dialect and leaves imported apps and first-party apps describing the same concept two ways. Confirming this costs nothing and settles it permanently.

  3. Hand-capture the 21 flagship heroes now, or wait for the CI harness? Recommendation: hand-capture now. The freshness rule of §4.2 is available immediately and makes hand-captured assets governed rather than rotting. Waiting means shipping nothing for a quarter.

  4. Is vendor-sourced material permitted at all, and who signs off? 68 of 90 packages have unverified licensing and there is already an on-record position that this is a legal question. Recommendation: no vendor assets in the first slice, and if ever permitted, only per-app with the grant URL and read date recorded next to the asset. This needs a named owner, not a policy.

  5. Do screenshot bytes live in git, or in a release artifact bucket? ~0.9 MB for the flagship slice is a rounding error and git is clearly right. ~16 MB for a full 4-shot gallery across 90 apps is a genuine repo-weight decision. Recommendation: git for the first slice, and treat “we want a full gallery” as the trigger to revisit; do not design the bucket now.

  6. Is a per-app auto-capture harness worth funding, given the measured failure mode? §0.7 says naive capture yields login screens and error pages; §0.8 says shc test run ./apps/<app> has already paid most of the bill. Recommendation: fund a 3-app pilot, not a program, and require the pilot to report a measured wall-clock cost per app before anything catalog-wide is discussed. Nobody has timed a full suite boot, and 90 of them on release-tag CI is either fine or unacceptable and we do not currently know which.

  7. Unrelated but free, and it belongs to someone: serve brotli. Measured, the storefront transfers 178,252 B gzip where brotli -q11 gives 53,594 B; a 124 KB saving on every cold load, which is more than the entire flagship screenshot budget for that page. Should this be split out as its own lane?


Terminal window
# §0.1 the data does not exist
git ls-files | grep '^apps/.*/app\.yaml$' | grep -v '/tests/' | wc -l # 90
git grep -n 'screenshots:\|gallery:' -- 'apps/**/app.yaml' # no output
# §0.3 lenient decode
grep -rn 'KnownFields(true)' vendor/gitlab.com/bitspur/selfhosted-cloud/ce/ | wc -l # 0
# §0.5 page weight
curl -s -o /tmp/h.html -w '%{size_download}\n' https://marketplace.selfhostedcloud.org/ # 8329369
curl -s -H 'Accept-Encoding: gzip' -o /dev/null -w '%{size_download}\n' \
https://marketplace.selfhostedcloud.org/ # 178252
brotli -q 11 -c /tmp/h.html | wc -c # 53594
# §0.6 screenshot weight (any 1440x900 PNG capture)
magick shot.png -resize 1200x -strip -quality 82 out.webp && stat -c%s out.webp
# §0.9 licensing
# 68 of 90 app.yaml carry license.id == "unverified"