Media / foldkit-media
Variant spaces and revisions
A server makes only what its Variant.space({ widths?, formats?, qualities?, revision? })
allows: the width ladder, a set of formats (AVIF and WebP by default), and a set
of qualities (omitted by default, leaving encoding quality to the encoder).
Requests outside the space return 404 before any transform runs, bounding an
original to at most space.size variants (16 for Variant.standard). Share one
provider across pages and server so both agree: define
const media = Provider.hosted({ space }) once and pass it to serveFetch's
images.provider (or layer({ provider })).
A variant's URL names its parameters (hash, width, format, quality), and its
response is cached for a year as immutable. Because encoder upgrades can change
output bytes, changes to how variants are built belong in a new revision on
the space rather than behind existing URLs. Variant.space({ revision: 1 })
writes w640.r1.avif; revision 0 (the default) omits the revision segment so
existing URLs keep their spelling. A server at revision 2 still answers earlier
revisions: serving stored earlier variants while present, or redirecting (302)
to the current revision with a short cache header for rolling deploys. Requests
for a future revision return 404 with the same short cache header.