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.