@siteswarm/cms-media

Optional pluggable media capability for SiteSwarm Headless CMS.

Strategic Purpose

Because Cloudflare Images transformations incur usage costs ($0.50 per 1,000 unique transforms) and R2 has storage allocations, image optimization and media management is decoupled as an optional, pluggable commercial add-on capability rather than mandatory overhead in @siteswarm/cms.

Standard client sites run with near-$0 compute and D1 storage, while high-touch clients (e.g. bakeries with pastry photo catalogs or agencies with design portfolios) opt into the media capability retainer ($29–$99/month).

Architecture & Features

R2D1MediaAdapter: Standard CMSMediaAdapter implementation combining Cloudflare R2 object storage with D1 metadata persistence.
Content-Addressed SHA-256 Keys: Cryptographic master asset keys prevent cache corruption and guarantee idempotency.
Edge Transformations: Direct integration with @siteswarm/media for automatic AVIF/WebP conversion, responsive srcset, and /cdn-cgi/image/... routing.
Web API Handler: Route factory createCMSMediaHandler() for production-gated GET and POST /api/cms/media endpoints with administrative auth validation.
EmDash Media Collection: Declarative schema definition (cmsMediaCollection) for EmDash CMS Studio.
Headless Invariant: Pure headless TypeScript logic with zero DOM markup or CSS injection.