The art and dates listing fields the UI needs

[Maximilian-Nesslauer]

The UI work in Borea#8 has reached the point where the mockups ask the metadata format for things spec_version = 1 does not carry.

RFC 0031's own evolution rule says an added optional field is not a break and does not bump the version, and RFC 0035 already took that path: it replaced RFC 0031's [install] table with a superset and stayed at spec_version = 1.
The only thing in here that would be a real break is making an image required, and nobody is proposing that.

Please reference the numbers so the thread stays followable.

1. What images

Every mockup in Borea#8 shows an image per listing, on three surfaces: a small thumbnail in the Discover rows, a larger one in the detail header, and a 1:1 tile with the title laid over it on Home.

The format has no image field at all. I just forgot it when I proposed RFC 0031.

The options as I see them, each having a bigger cost due to more files:

1. just a square icon
2. Just A square icon plus a wide banner.
3. A square icon plus a wide banner plus an ordered gallery of multiple screenshots, each with an optional caption.

Two things regardles of whichever shape wins:

• The icon is a listing fact, not a release fact. It must stay live and must not freeze into the listing block RFC 0031 stamps into each release file, the same carve-out status and superseded_by already have. Otherwise changing your icon leaves every past release showing the old one.
• Dimensions, format, and a size cap have to be stated

2. Where the image actually live

RFC 0025 states as a non-goal that we host no content files.

A. The author names a URL in the authored file.
Cheapest to specify and cheapest to author.
Costs: links rot, and a dead icon is a broken listing page forever; the client fetches from an arbitrary host, so a list view is N requests to N hosts and every one of them learns the user's IP; nothing guarantees dimensions or size unless the checks fetch the image anyway; and the snapshot stops being enough on its own, which breaks the offline-first property RFC 0033 and RFC 0017 both lean on.

B. The image is committed into content-index and the index serves it.
One host, one CDN, one cache. The bytes are moderatable, and shippable offline with the snapshot, and dimensions can be enforced at publish time.
Costs: binary blobs enter git history and cannot be pruned later; changing your icon is a pull request; the checks need real image validation; the index Repos would get very big.

[Maximilian-Nesslauer]

I would restart this with a complete optional image model for the current Borea designs and Markdown descriptions, plus listing dates that every client can calculate the same way.

1. Let authors define each image that a listing can show

I propose optional authored image records for an icon, a banner, an ordered gallery, and images that the Markdown description can use:

description = """
Configure the guidance mode in the settings window.

![The guidance settings window](ksa-image:settings-window)
"""

[images.icon]
url = "https://example.invalid/my-mod-icon.png"
sha256 = "0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF"
license = "CC-BY-4.0"
attribution = "Artwork by Example Artist"
source = "https://example.invalid/original-artwork"

[images.banner]
url = "https://example.invalid/my-mod-banner.webp"
sha256 = "1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF"
license = "CC-BY-4.0"
attribution = "Artwork by Example Artist"

[[images.gallery]]
url = "https://example.invalid/flight-view.png"
sha256 = "2345678901ABCDEF2345678901ABCDEF2345678901ABCDEF2345678901ABCDEF"
license = "CC-BY-4.0"
alt = "The flight guidance display during a lunar descent"
caption = "Powered descent guidance in flight"

[[images.description]]
id = "settings-window"
url = "https://example.invalid/settings-window.png"
sha256 = "3456789012ABCDEF3456789012ABCDEF3456789012ABCDEF3456789012ABCDEF"
license = "CC-BY-4.0"

url, sha256, and license are required for every image record.
attribution and source are optional unless the image's terms require them.
license is an SPDX expression or a LicenseRef with a public license URL.
alt is required for gallery images, and caption is optional.
The order of the [[images.gallery]] records is the display order.
Each [[images.description]] record has a unique, case-sensitive id.
The CommonMark description references it with ksa-image:<id> instead of a direct remote URL.
A client that renders Markdown resolves only declared ksa-image: references and uses the Markdown alternative text.
This keeps the image URL, digest, license, and attribution in structured metadata while the author controls where the image appears in the description.
An unknown or missing image id renders as missing image content and does not prevent the rest of the description from rendering.

For a mod or mod loader, all images are live listing facts.
They appear in the authored document and the snapshot, but they are not copied into a release file's frozen listing block.
Changing an image must update every listing view at once, like status and superseded_by.

A mod pack has no separate live listing document because every pack version is one complete immutable authored document.
For a pack, the full [images] content is a pack-version fact.
The pack listing view uses the images from the newest non-retracted pack version, and a version view uses that version's images.
Publishing a new pack version is the only way to change them.

2. Keep the image on the author's host

The index does not copy or serve the image.
That keeps RFC 0025's no-hosting boundary and avoids binary files in the index repositories.

The listing checks fetch the image and require:

• HTTPS after redirects.
• A public network target, with loopback, private, link-local, and metadata-service addresses rejected before each connection and after each DNS resolution.
• PNG, JPEG, or WebP raster data, checked from the bytes and not only from the file extension or response header.
• An icon that is square and from 256 by 256 through 1024 by 1024 pixels.
• A banner, gallery image, or description image whose width and height are each from 256 through 4096 pixels.
• At most 256 KiB for an icon and at most 1 MiB for each other image.
• No animation.
• A short timeout, at most three redirects, the same checks on every redirect target, and a streamed byte limit that stops the response before it exceeds the cap.
• Bytes whose SHA-256 matches the authored sha256 value.

The 256 KiB icon limit follows the current Modrinth icon limit and should be enough for a square listing image.
The larger limit for other images supports screenshots and banners while it still gives clients a firm download bound.
The dimension ranges let authors provide useful source images while clients render the size their layout needs.
SVG stays out of the first proposal because raster-only validation and rendering have a smaller security and compatibility surface.

A client must repeat the applicable byte limit, type, dimensions, animation, and digest checks because the host can change after publication.
It must treat an unavailable or invalid image as missing metadata, show its content-type placeholder, and keep the listing usable.
Clients should fetch without credentials or cookies and cache by digest.
Changing the image bytes requires an authored metadata change with a new digest, while a mirror move can change only the URL when the bytes stay identical.
An author-hosted URL still tells that host the user's IP address and can stop working later.
That is the main cost of keeping the index out of image hosting, and the placeholder is the required offline and failure behavior.

The index needs a new submission rule for images.
By submitting an image URL, the listing owner states that they have the right to publish the image and let clients display and cache it under the stated per-image license.
When third-party work or the license requires credit, a license notice, a source link, or a modification statement, the authored table must carry that information through attribution and source.
The KSA Mod Release Rules provide the community precedent for compatible rights and credit for other people's assets, but they do not grant these rights for a separately hosted index image.
The listing's existing content license does not automatically cover separate artwork, which is why the image has its own required license field.

3. Derive listing dates instead of asking authors to write them

RFC 0031 already carries the source timestamps:

• release_date on each watched release.
• released_at on each authored pack version.

Authors should not add a second listing date that can disagree with those values.
Git commit dates should not be the source either because a repository move or history rewrite can change them.

I propose two optional fields generated into each listing entry in the snapshot:

• published_at is the earliest indexed release_date or released_at, including a version that was later yanked or retracted because it still records when the content first appeared.
• updated_at is the latest indexed release_date or released_at whose version is not yanked or retracted.

Both are ISO 8601 UTC timestamps.
updated_at includes stable, testing, and dev releases and is independent of game compatibility and operating-system support.
A listing with no indexed version has neither field, and a listing whose every version is yanked or retracted has published_at but no updated_at.
The underlying per-version timestamps remain the source of truth, and the snapshot builder only provides the common aggregation so clients do not invent different rules.

Modrinth also separates a project's published and updated timestamps from its version dates.
This proposal uses the same user-facing distinction, but derives both values from indexed versions because our index has no separate account or project-creation event.

4. Compatibility with current clients

All image records and derived date fields are optional.
RFC 0031 says that optional metadata fields do not change spec_version, and the living snapshot specification says that optional snapshot fields do not change snapshot_version.
Both values stay at 1.
No production client or production metadata exists yet, so this proposal needs no migration path or new version.
The RFC and living specification only need to define the fields before production starts.
A listing without an icon or dates remains valid.
An image fetch failure never changes installability, dependency resolution, or compatibility.

5. I especially consider these decisions to be still open

• The recommended banner aspect ratio and whether the index enforces one.
• Whether the proposed 1 MiB and 4096-pixel limits for banner, gallery, and description images are the correct starting limits.
• Whether gallery records require author-written alternative text, or whether the user interface treats a gallery as decorative and uses captions only.
• Whether ksa-image:<id> is the correct Markdown reference syntax or a different index-local syntax is clearer.
• Whether clients can fetch author-hosted images with the privacy, network-safety, integrity, cache, and failure rules above.
• Whether a separate image license is always required or can fall back to the listing license when the author explicitly says that it covers the image.
• Whether a pack listing uses all images from its newest non-retracted version or uses a smaller stable image identity across versions.
• Whether updated_at includes every non-yanked development and testing release, or only stable releases.

If this scope is acceptable, the RFC can specify the exact TOML and snapshot schemas, the validation errors, the rights statement in the listing guidance, and fixtures for each image role, a Markdown image reference, no images, a changed image behind the same URL, unsafe network targets, no releases, all versions unavailable, stable plus dev releases, a yanked newest release, a retracted newest pack version, and a backfilled older release.

References:

• RFC 0025, scope and the no-hosting boundary
• RFC 0031, current release dates and format evolution
• RFC 0033, snapshot and offline behavior
• KSA Mod Release Rules
• Modrinth project metadata
• Modrinth icon upload limit

[averageksp]

Some thoughts from building the Borea screens that would use this. Numbered to match.

1. Images
I'd start with just the icon (plus [[images.description]]). The current Figma has no place for a banner or a gallery. Discover rows, the detail header and the Home tiles are all square. Since an added optional field isn't a break under RFC 0031, banner and gallery can come later when a design actually needs them. That also takes the banner ratio question off the table for now.

Please also cap the count, not just the size. A 4096x4096 image decodes to about 64 MB, so a big gallery can eat a lot of client memory. Something like max 8 gallery and 8 description images would give clients a real bound.

2. Hosting
The checks already download every image, so they could write width, height and byte size into the snapshot. Clients could then lay out lists and show placeholders without fetching anything first, and only load what's on screen instead of hitting N hosts at startup.

It would also help if the checker re-fetched images now and then and put a digest mismatch into index_status. Otherwise a changed or dead image just turns into a placeholder forever and the author never hears about it.

Clients should probably offer a setting to not load images from author hosts at all, given the IP exposure. That's a client call, but the spec could recommend it.

3. ksa-image:<id>
Works for us. Normal CommonMark parsers treat it as a regular image link, so nothing special is needed on the parsing side.

4. Dates
Fine as proposed. One small thing: with dev and testing releases counted, "Updated 2d ago" can show up for someone who only uses stable. Clients have the release statuses anyway, so I'd keep the field and just say clients may show a per-channel date.

Open questions

• Gallery alt text: keep it required, it maps straight to screen reader names.
• Image license: keep it required too. Copying the listing license is one line for the author and avoids guessing.

Not covered yet
The designs also show download counts and a "Trending" section on Home, and nothing here covers those. Might be worth linking the static aggregation idea from #33 so this doesn't look like the full list of what the UI needs.

[Maximilian-Nesslauer]

I agree with most of.

1. Images

Agreed on only the icon plus [[images.description]] for now.

Agreed on a count cap. At most 8 [[images.description]] records per listing should be fine? I would also lower the description image limit from 4096 to 2048 pixels per side. A 2048 image decodes to about 16 MiB, so 8 images stay near 128 MiB in the worst case, and 2048 is still wider than the description column at 2x display scale. The icon stays square, 256 to 1024 pixels, at most 256 KiB.

2. Hosting

agreed on the goal, but I would not let the checks write the Width, height and byte size in the snapshot. The checks run unprivileged on the pull request and only leave a verdict, and the snapshot builder copies documents verbatim and computes nothing into them. The simpler way is the one sha256 already uses: the author, the listing tool or the ksamods.gg form writes width, height and size into the image record, and the checks verify them against the fetched bytes. Because the digest pins the bytes, these three values cannot become wrong later, since any bytes that match the digest also have the stated size. A client can then lay out lists and show placeholders from the snapshot alone.

Re-fetching: agreed, but not into index_status.

3. ksa-image:<id>

Good.

4. Dates

Agreed. The RFC will say that updated_at counts every channel, and that a client may show a date per release channel, which it can compute from release_status and release_date in the snapshot.

Not covered yet

Download counts are RFC 0052 in #52, which you already approved, and it needs one more steward approval. "Trending this week" is not covered by it on purpose since RFC 0052 keeps totals without timestamps and defines no ranking, and a weekly trend needs counts over time. Until then Home shows "recently updated", which Borea#8 agreed on and KSAModding/Borea#139 implements. I will link both from the RFC so it does not read as the full list of what the UI needs.

If nobody objects in the next few days, I will open the RFC with this scope: icon and description images, the authored url, sha256, width, height, size and license per image, the count and size caps, the fetch rules, the per-listing issue for a dead image, the client opt-out, and published_at and updated_at.

@SafeShows @renancamm @MrJeranimo please say so if something here does not work for your side.

[averageksp]

Thanks, looks good to me 👍

[renancamm]

What I had in my mind is to only have a 1:1 thumbnail. We need it in 3 sizes (small/medium/large), for list, tile and detail page. The idea behind it was to simplify the spec requirements and focus the art to help scanning the list and identification of the content.

All the rest, like banner or gallery I was expecting to delegate for the content description field, like a markdown and fetch it on demand, so each modder can decide if they want a wall of text os many many images. Optionally we can add a tab inside the mod detail page that is called "gallery", but I still prefer the flexibility of a rich description box.

The reason to try to "keep it simple" is mainly that it is painful for people without art skill to generate quality art assets, and we end up with ugly art in the app.

[averageksp]

I agree

[Maximilian-Nesslauer]

Decided by RFC 0058, which gives an authored document an optional [images] table with one icon and the description images, each verified by digest, plus the derived published_at and updated_at fields in the snapshot.
RFC 0065 later allowed an icon that is not square, within a ratio of two to one.
Closing as resolved.