From ca308367b232a87bc476387295b5596de84f583f Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 3 Jul 2026 09:30:02 +0200
Subject: [PATCH 1/2] feat(publisher): optimize media background images

---
 docs/features/publisher.md                    |  25 +++-
 server/handlers/cms/data/preview.ts           |   2 +-
 server/publish/mediaPrefetch.ts               |   5 +
 server/publish/publicRenderer.ts              |   2 +-
 server/publish/publishSite.ts                 |   4 +-
 server/publish/siteCssBundle.ts               |  35 ++++-
 server/router.ts                              |  15 +-
 .../canvas/classStyleInjector.test.ts         |  63 +++++++++
 .../editor/readOnlyNodeTree.test.tsx          |  37 ++++-
 .../publisher/classStyleInjector.test.ts      |  59 +++++++-
 .../server/mediaBatchResolution.test.ts       |  62 ++++++++
 .../media/hooks/useCmsMediaAssetByPath.ts     |  31 ++++
 .../hooks/useResponsiveBackgroundStyle.ts     |  88 ++++++++++++
 .../pages/site/canvas/ClassStyleInjector.tsx  |  51 ++++++-
 .../pages/site/canvas/ModuleSandboxFrame.tsx  |  25 +++-
 src/admin/pages/site/canvas/NodeRenderer.tsx  |   8 +-
 src/admin/pages/site/canvas/canvasClassCss.ts |  17 ++-
 src/core/publisher/classCss.ts                |  37 +++--
 src/core/publisher/classInjection.ts          |   4 +-
 src/core/publisher/cssCollector.ts            |   5 +-
 src/core/publisher/index.ts                   |  10 ++
 src/core/publisher/render.ts                  |  14 +-
 src/core/publisher/renderLoop.ts              |   2 +-
 src/core/publisher/renderNode.ts              |   2 +-
 .../publisher/renderVisualComponentRef.ts     |   2 +-
 src/core/publisher/responsiveBackground.ts    | 132 ++++++++++++++++++
 src/modules/base/utils/ReadOnlyNodeTree.tsx   |   4 +-
 27 files changed, 682 insertions(+), 59 deletions(-)
 create mode 100644 src/admin/pages/media/hooks/useResponsiveBackgroundStyle.ts
 create mode 100644 src/core/publisher/responsiveBackground.ts

diff --git a/docs/features/publisher.md b/docs/features/publisher.md
index 3f130b28d..6013bfd14 100644
--- a/docs/features/publisher.md
+++ b/docs/features/publisher.md
@@ -33,6 +33,7 @@ src/core/publisher/
 ├── escapeProps.ts                  — escape string props at the render boundary, dispatched per-prop on the schema control `type`
 ├── classInjection.ts               — inject author classIds into rendered HTML
 ├── classCss.ts                     — compile user StyleRule entries → CSS, including supported raw @keyframes
+├── responsiveBackground.ts         — rewrite media-library background-image url(...) values to optimized image-set(...) ladders
 ├── cssCollector.ts                 — CssCollector + collectClassCSS + sanitizeModuleCSS
 ├── reset.ts                        — PUBLISHER_RESET_CSS (cross-browser baseline)
 ├── frameworkCss.ts                 — site framework CSS (spacing scale, typography)
@@ -52,7 +53,7 @@ server/publish/
 ├── publishedHtmlPipeline.ts        — post-process (sanitize + plugin filters + injections)
 ├── siteCssBundle.ts                — server-side hashing + file emission
 ├── frontendInjections.ts           — splice plugin <script>/<link>/<meta> into HTML
-├── mediaPresentation.ts            — <picture>/<srcset> materialization at publish time
+├── mediaPresentation.ts            — media URL materialization for originals + responsive variants
 ├── renderTreeWalk.ts               — walkRenderTree: visits every node that contributes to a rendered page (page nodes + VC definition trees, cycle-guarded); single source of truth for loop-prefetch and media-prefetch
 ├── mediaPrefetch.ts, loopPrefetch.ts — pre-warm caches needed by the renderer
 ├── republish.ts                    — bulk re-publish on site-level changes
@@ -93,7 +94,7 @@ For each node, bottom-up:
   2. resolvedProps  = resolveProps(node, breakpoint)     ← merge breakpoint overrides
   3. dynamicProps   = resolveDynamicProps(...)           ← apply data bindings
   4. safeProps      = escapeProps(dynamicProps, schema)  ← escape per schema TYPE
-  5. attachResolvedMediaByKey(safeProps, def, ...)       ← attach <picture>/<srcset>
+  5. attachResolvedMediaByKey(safeProps, def, ...)       ← attach srcset-capable media payloads
   6. attachAutoSizes(safeProps, def, ...)                ← auto <img sizes>
   7. { html, css } = def.render(safeProps, children)                  ← MODULE BOUNDARY
   8. acc.cssMap.set(moduleId, sanitizeModuleCSS(css))    ← neutralise </style (Constraint #228), dedup by moduleId
@@ -205,6 +206,21 @@ style-<hash>.css       = collectClassCSS(site)                     ← user-defi
 userStyles-<hash>.css  = collectUserStylesheetCss(site, page)      ← author stylesheets, scoped to this page
 ```
 
+Media-library background images are optimized in the same publish pass as
+`<img srcset>`. `mediaPrefetch.ts` collects `/uploads/...` URLs from
+image/media module props, node `inlineStyles.backgroundImage`, and StyleRule
+`backgroundImage` values (including breakpoint/context overrides), then
+batch-fetches their media rows. During CSS emission,
+`responsiveBackground.ts` rewrites each matched `url('/uploads/original.png')`
+to two `background-image` declarations: an optimized variant URL fallback and
+an `image-set(...)` ladder built only from `media_assets.variants_json`. The
+uploaded original is excluded whenever variants exist, so a 20 MB PNG used as
+a background does not become the selectable source for modern browsers. CSS
+`image-set()` supports density descriptors (`1x`, `2x`, etc.), not HTML
+`srcset` width descriptors (`640w` + `sizes`), so the background ladder is a
+DPR-oriented mirror of the same variant policy rather than a literal copy of
+the `<img sizes>` algorithm.
+
 `reset` / `framework` / `style` are page-invariant — every page on the site
 shares the same hash. `userStyles` is **page-scoped**: each author stylesheet
 (`site.files[type === 'style']`) carries a `SiteStyleRuntimeConfig` (in
@@ -349,8 +365,9 @@ Because `serializeCsp` sorts, the same plugins + adapters always emit a **byte-i
 | `server/publish/republish.ts`                   | Bulk re-publish on settings change (touches every page).            |
 | `server/publish/publishScheduler.ts`            | Scheduled publish jobs (cron-style).                                |
 | `server/publish/frontendInjections.ts`          | Compute plugin `<script>`/`<link>`/`<meta>` tags + CSP entries.     |
-| `server/publish/mediaPresentation.ts`           | At publish time, build `<picture>` / `<img srcset>` markup from `media_assets.variants_json`. |
-| `server/publish/mediaPrefetch.ts`               | Collect every image/media-typed prop from the full render tree — including VC definition trees — via `walkRenderTree`, then batch-fetch matching `media_assets` rows into a `Map<publicPath, MediaAsset>` before render. Uses `MEDIA_ASSET_COLUMNS` and `mapMediaAssetRow` from `server/repositories/mediaAssetMapping.ts` (shared with the admin repository) so the published page and the admin panel always see one identical asset shape. |
+| `server/publish/mediaPresentation.ts`           | Materialize media paths (originals + responsive variants) for publisher consumers. |
+| `src/core/publisher/responsiveBackground.ts`    | Convert media-library `background-image: url(...)` values into optimized variant fallback + `image-set(...)` declarations. |
+| `server/publish/mediaPrefetch.ts`               | Collect every image/media-typed prop and every media-library background-image URL from the full render tree — including VC definition trees — via `walkRenderTree`, then batch-fetch matching `media_assets` rows into a `Map<publicPath, MediaAsset>` before render. Uses `MEDIA_ASSET_COLUMNS` and `mapMediaAssetRow` from `server/repositories/mediaAssetMapping.ts` (shared with the admin repository) so the published page and the admin panel always see one identical asset shape. |
 | `server/publish/loopPrefetch.ts`                | Collect every `base.loop` node from the full render tree — including VC definition trees — via `walkRenderTree`, fetch each source's items, and return a `Map<nodeId, ResolvedLoopData>` before render so the walker is purely synchronous. Also exports `canonicalRenderQuery(searchParams)` — strips all non-loop-pagination params from a URL's query, returning only `loop_<nodeId>_page` keys in sorted order (or `''` when none remain). Used by `publicRouter.ts` to normalise the Layer B cache key and Layer A fast-path eligibility. |
 | `server/publish/renderTreeWalk.ts`              | `walkRenderTree(nodes, rootNodeId, site, onNode)` — visits every node that contributes to a rendered page: all page-tree nodes reachable from `rootNodeId`, plus all nodes inside each referenced VC's definition tree (recursively, cycle-guarded by a `Set<vcId>`). Used by both `mediaPrefetch.ts` and `loopPrefetch.ts` so their traversal logic can't drift apart. |
 | `server/publish/runtime/packageServer.ts`       | Serve per-site `bun install` workspace under `/_instatic/runtime/cache/`. |
diff --git a/server/handlers/cms/data/preview.ts b/server/handlers/cms/data/preview.ts
index 32128f818..7e2821b41 100644
--- a/server/handlers/cms/data/preview.ts
+++ b/server/handlers/cms/data/preview.ts
@@ -100,11 +100,11 @@ export async function handleRowPreview(
   // resolution, etc.) operate against this seed.
   const draftPublishedRow: PublishedDataRow = synthesisePublishedRow(row, table, draftCells)
 
-  const cssBundle = buildSiteCssBundle(snapshot.site, registry, merged)
   const [loopData, mediaAssets] = await Promise.all([
     prefetchLoopData(merged, snapshot.site, db),
     prefetchMediaAssets(merged, snapshot.site, registry, db),
   ])
+  const cssBundle = buildSiteCssBundle(snapshot.site, registry, merged, { mediaAssets })
 
   const publicPath = buildEntryPublicPath(table.routeBase, draftPublishedRow.slug)
   const syntheticUrl = new URL(`http://localhost${publicPath}`)
diff --git a/server/publish/mediaPrefetch.ts b/server/publish/mediaPrefetch.ts
index cfacf49c5..accc79412 100644
--- a/server/publish/mediaPrefetch.ts
+++ b/server/publish/mediaPrefetch.ts
@@ -19,6 +19,7 @@
 
 import type { Page, SiteDocument } from '@core/page-tree'
 import type { IModuleRegistry } from '@core/module-engine'
+import { collectNodeBackgroundImagePaths, collectSiteStyleBackgroundImagePaths } from '@core/publisher'
 import { walkRenderTree } from './renderTreeWalk'
 import type { DbClient } from '../db/client'
 import type { MediaAsset } from '../repositories/media'
@@ -43,6 +44,7 @@ function collectMediaPaths(page: Page, site: SiteDocument, registry: IModuleRegi
   walkRenderTree(page.nodes, page.rootNodeId, site, (node) => {
     const def = registry.get(node.moduleId)
     if (!def) return
+    collectNodeBackgroundImagePaths(node, paths)
     for (const [propKey, control] of Object.entries(def.schema)) {
       // Only `image` / `media` controls participate in the responsive
       // pipeline. Plain `text` URL fields (rare) aren't auto-upgraded.
@@ -52,6 +54,9 @@ function collectMediaPaths(page: Page, site: SiteDocument, registry: IModuleRegi
       paths.add(value)
     }
   })
+  for (const path of collectSiteStyleBackgroundImagePaths(site)) {
+    paths.add(path)
+  }
   return paths
 }
 
diff --git a/server/publish/publicRenderer.ts b/server/publish/publicRenderer.ts
index e798504f4..19792a7b3 100644
--- a/server/publish/publicRenderer.ts
+++ b/server/publish/publicRenderer.ts
@@ -92,12 +92,12 @@ async function renderMergedTemplate(
   ctx: RenderPublishedSnapshotContext,
 ): Promise<{ html: string; jsModuleIds: string[]; publishVersion: number; cssBundle: SiteCssBundle }> {
   const publishVersion = ctx.publishVersion ?? getPublishVersion()
-  const cssBundle = buildPublishedSiteCssBundle(snapshot.site, registry, merged, publishVersion)
   const moduleJsMap = buildPublishedSiteModuleJsMap(snapshot.site, registry)
   const [loopData, mediaAssets] = await Promise.all([
     prefetchLoopData(merged, snapshot.site, ctx.db, ctx.url),
     prefetchMediaAssets(merged, snapshot.site, registry, ctx.db),
   ])
+  const cssBundle = buildPublishedSiteCssBundle(snapshot.site, registry, merged, publishVersion, { mediaAssets })
   const published = publishPage(merged, snapshot.site, registry, {
     templateContext,
     runtimeAssets: snapshot.runtimeAssets,
diff --git a/server/publish/publishSite.ts b/server/publish/publishSite.ts
index 47672e8ac..925249bc9 100644
--- a/server/publish/publishSite.ts
+++ b/server/publish/publishSite.ts
@@ -38,6 +38,7 @@ import {
   serializeImportmapForCsp,
 } from './runtime/packageImportmap'
 import { renderPublishedNotFound, renderPublishedSnapshot } from './publicRenderer'
+import { prefetchMediaAssets } from './mediaPrefetch'
 import { applyPublishedHtmlPipeline } from './publishedHtmlPipeline'
 import {
   NOT_FOUND_ARTEFACT_URL_PATH,
@@ -222,7 +223,8 @@ async function publishDraftSiteLocked(
       for (const snapshot of snapshots) {
         const page = snapshot.site.pages.find((p) => p.id === snapshot.pageRowId)
         if (!page || isTemplatePage(page)) continue // template pages only ever wrap; never baked at their own slug
-        collectCssFiles(buildPublishedSiteCssBundle(snapshot.site, registry, page, nextPublishVersion))
+        const mediaAssets = await prefetchMediaAssets(page, snapshot.site, registry, db)
+        collectCssFiles(buildPublishedSiteCssBundle(snapshot.site, registry, page, nextPublishVersion, { mediaAssets }))
       }
       for (const asset of runtimeAssetFiles) {
         if (!assetsByPath.has(asset.publicPath)) assetsByPath.set(asset.publicPath, asset.bytes)
diff --git a/server/publish/siteCssBundle.ts b/server/publish/siteCssBundle.ts
index ba71f02e9..daa7346dc 100644
--- a/server/publish/siteCssBundle.ts
+++ b/server/publish/siteCssBundle.ts
@@ -34,11 +34,13 @@ import type { IModuleRegistry } from '@core/module-engine'
 import {
   PUBLISHER_RESET_CSS,
   collectClassCSS,
+  collectSiteStyleBackgroundImagePaths,
   buildSiteFrameworkCss,
   collectUserStylesheetCss,
 } from '@core/publisher'
 import type {
   CssBundleFile,
+  ResponsiveCssOptions,
   SiteCssBundle,
   SiteCssBundleId,
 } from '@core/publisher'
@@ -70,9 +72,10 @@ export function buildSiteCssBundle(
   site: SiteDocument,
   registry: IModuleRegistry,
   page?: Page,
+  options: ResponsiveCssOptions = {},
 ): SiteCssBundle {
   return {
-    ...computePageInvariantBundles(site, registry),
+    ...computePageInvariantBundles(site, registry, options),
     userStyles: makeBundleFile('userStyles', collectUserStylesheetCss(site, page)),
   }
 }
@@ -100,9 +103,10 @@ export function buildPublishedSiteCssBundle(
   registry: IModuleRegistry,
   page?: Page,
   publishVersion: number = getPublishVersion(),
+  options: ResponsiveCssOptions = {},
 ): SiteCssBundle {
   return {
-    ...memoizedPageInvariantBundles(site, registry, publishVersion),
+    ...memoizedPageInvariantBundles(site, registry, publishVersion, options),
     userStyles: makeBundleFile('userStyles', collectUserStylesheetCss(site, page)),
   }
 }
@@ -111,11 +115,12 @@ export function buildPublishedSiteCssBundle(
 function computePageInvariantBundles(
   site: SiteDocument,
   registry: IModuleRegistry,
+  options: ResponsiveCssOptions,
 ): PageInvariantBundles {
   return {
     reset: makeBundleFile('reset', PUBLISHER_RESET_CSS),
     framework: makeBundleFile('framework', buildFrameworkCss(site, registry)),
-    style: makeBundleFile('style', collectClassCSS(site)),
+    style: makeBundleFile('style', collectClassCSS(site, options)),
   }
 }
 
@@ -126,7 +131,7 @@ function computePageInvariantBundles(
 // Deliberately NOT keyed on the site object: every consumer loads the snapshot
 // fresh (DB JSON parse per query), so an identity key would never hit — that
 // was exactly the bug that made every Layer B miss re-walk the whole site.
-let pageInvariantCache: { version: number; bundles: PageInvariantBundles } | null = null
+let pageInvariantCache: { version: number; mediaSignature: string; bundles: PageInvariantBundles } | null = null
 registerVersionedCacheReset(() => {
   pageInvariantCache = null
 })
@@ -139,15 +144,31 @@ function memoizedPageInvariantBundles(
   site: SiteDocument,
   registry: IModuleRegistry,
   version: number,
+  options: ResponsiveCssOptions,
 ): PageInvariantBundles {
-  if (pageInvariantCache && pageInvariantCache.version === version) {
+  const mediaSignature = styleMediaSignature(site, options)
+  if (pageInvariantCache && pageInvariantCache.version === version && pageInvariantCache.mediaSignature === mediaSignature) {
     return pageInvariantCache.bundles
   }
-  const bundles = computePageInvariantBundles(site, registry)
-  pageInvariantCache = { version, bundles }
+  const bundles = computePageInvariantBundles(site, registry, options)
+  pageInvariantCache = { version, mediaSignature, bundles }
   return bundles
 }
 
+function styleMediaSignature(site: SiteDocument, options: ResponsiveCssOptions): string {
+  if (!options.mediaAssets || options.mediaAssets.size === 0) return ''
+  const paths = collectSiteStyleBackgroundImagePaths(site)
+  if (paths.size === 0) return ''
+
+  const parts: string[] = []
+  for (const path of [...paths].sort()) {
+    const media = options.mediaAssets.get(path)
+    if (!media || media.variants.length === 0) continue
+    parts.push(`${path}=${media.variants.map((v) => `${v.width}:${v.path}`).join('|')}`)
+  }
+  return parts.join(';')
+}
+
 /**
  * Build the `framework.css` body: site-wide platform CSS plus any plugin
  * module CSS used anywhere on the site.
diff --git a/server/router.ts b/server/router.ts
index ef778e617..618f1ee9a 100644
--- a/server/router.ts
+++ b/server/router.ts
@@ -6,6 +6,7 @@ import { renderNotFoundResponse, renderPublicResolution } from './publish/public
 import { readStaticAsset } from './publish/staticArtefact'
 import { getLatestSnapshotForVersion } from './publish/publishedSnapshotCache'
 import { getPublishVersion, registerVersionedCacheReset } from './publish/publishState'
+import { prefetchMediaAssets } from './publish/mediaPrefetch'
 import { getSetupStatusCached } from './repositories/setup'
 import { getPublishedRuntimeAsset } from './repositories/runtimeAsset'
 import { handleLoopRequest, isLoopRuntimeAssetPath, serveLoopRuntimeAsset } from './handlers/cms/loop'
@@ -605,12 +606,22 @@ async function rebuildSiteCssFromSnapshot(
 
   const pages = bundleId === 'userStyles' ? snapshot.site.pages : snapshot.site.pages.slice(0, 1)
   for (const page of pages) {
-    const file: CssBundleFile = buildPublishedSiteCssBundle(snapshot.site, registry, page, version)[bundleId]
+    const mediaAssets = await prefetchMediaAssets(page, snapshot.site, registry, db)
+    const file: CssBundleFile = buildPublishedSiteCssBundle(snapshot.site, registry, page, version, { mediaAssets })[bundleId]
     if (file.hash === requestedHash) return file.content
   }
   // Page-agnostic view (every enabled stylesheet) — covers a hash that
   // predates a scope change but is still referenced somewhere.
-  const fallback: CssBundleFile = buildPublishedSiteCssBundle(snapshot.site, registry, undefined, version)[bundleId]
+  const fallbackMediaAssets = snapshot.site.pages[0]
+    ? await prefetchMediaAssets(snapshot.site.pages[0], snapshot.site, registry, db)
+    : undefined
+  const fallback: CssBundleFile = buildPublishedSiteCssBundle(
+    snapshot.site,
+    registry,
+    undefined,
+    version,
+    { mediaAssets: fallbackMediaAssets },
+  )[bundleId]
   if (fallback.hash === requestedHash) return fallback.content
 
   return null
diff --git a/src/__tests__/canvas/classStyleInjector.test.ts b/src/__tests__/canvas/classStyleInjector.test.ts
index a9c2da537..461896bf6 100644
--- a/src/__tests__/canvas/classStyleInjector.test.ts
+++ b/src/__tests__/canvas/classStyleInjector.test.ts
@@ -6,6 +6,7 @@ import {
 } from '@site/canvas/canvasClassCss'
 import { generateFrameworkColorUtilityClasses } from '@core/framework'
 import { classKindSelector, type StyleRule } from '@core/page-tree'
+import type { RenderResolvedMedia } from '@core/publisher'
 
 function makeClass(
   id: string,
@@ -25,6 +26,23 @@ function makeClass(
   }
 }
 
+function resolvedMedia(path = '/uploads/hero.png'): RenderResolvedMedia {
+  return {
+    publicPath: path,
+    mimeType: 'image/png',
+    width: 2400,
+    height: 1200,
+    altText: '',
+    blurHash: null,
+    variants: [
+      { width: 320, height: 160, format: 'webp', path: '/uploads/hero-w320.webp', sizeBytes: 12_000 },
+      { width: 1024, height: 512, format: 'webp', path: '/uploads/hero-w1024.webp', sizeBytes: 82_000 },
+      { width: 2048, height: 1024, format: 'webp', path: '/uploads/hero-w2048.webp', sizeBytes: 190_000 },
+    ],
+    posterPath: null,
+  }
+}
+
 describe('generateCanvasClassCSS', () => {
   it('prepends the unscoped publisher reset so the iframe cascade matches the published page', () => {
     const css = generateCanvasClassCSS({}, [])
@@ -70,6 +88,30 @@ describe('generateCanvasClassCSS', () => {
     expect(css).not.toContain('[data-breakpoint-id="mobile"] .title')
   })
 
+  it('rewrites class background images to optimized image-set candidates in the canvas CSS', () => {
+    const css = generateCanvasClassCSS(
+      {
+        hero: makeClass('hero', { backgroundImage: "url('/uploads/hero.png')" }),
+      },
+      [],
+      [],
+      null,
+      null,
+      null,
+      null,
+      null,
+      {
+        mediaAssets: new Map([['/uploads/hero.png', resolvedMedia()]]),
+        mediaSignature: 'hero',
+      },
+    )
+
+    expect(css).toContain('background-image: url("/uploads/hero-w2048.webp");')
+    expect(css).toContain('background-image: image-set(')
+    expect(css).toContain('url("/uploads/hero-w1024.webp") 1x')
+    expect(css).not.toContain('/uploads/hero.png')
+  })
+
   it('emits sanitized raw @keyframes rules, matching the published output', () => {
     // Regression: the canvas used to skip `rawCss` rules entirely, so
     // imported keyframe animations published fine but never played in the
@@ -190,6 +232,27 @@ describe('createCanvasClassCssMemo', () => {
     expect(calls()).toBe(3)
   })
 
+  it('regenerates when the responsive background media signature changes', () => {
+    const { memo, calls } = countingMemo()
+    const mediaAssets = new Map([['/uploads/hero.png', resolvedMedia()]])
+
+    memo(classes, breakpoints, conditions, null, null, null, null, null, {
+      mediaAssets,
+      mediaSignature: 'a',
+    })
+    memo(classes, breakpoints, conditions, null, null, null, null, null, {
+      mediaAssets,
+      mediaSignature: 'a',
+    })
+    expect(calls()).toBe(1)
+
+    memo(classes, breakpoints, conditions, null, null, null, null, null, {
+      mediaAssets,
+      mediaSignature: 'b',
+    })
+    expect(calls()).toBe(2)
+  })
+
   it('the exported generator produces identical CSS for cached and fresh inputs', () => {
     const cached = generateCanvasClassCSS(classes, breakpoints)
     expect(generateCanvasClassCSS(classes, breakpoints)).toBe(cached)
diff --git a/src/__tests__/editor/readOnlyNodeTree.test.tsx b/src/__tests__/editor/readOnlyNodeTree.test.tsx
index 7f83a78e0..be8d48b03 100644
--- a/src/__tests__/editor/readOnlyNodeTree.test.tsx
+++ b/src/__tests__/editor/readOnlyNodeTree.test.tsx
@@ -16,7 +16,8 @@ import { afterEach, describe, expect, it } from 'bun:test'
 import React from 'react'
 import { cleanup, render } from '@testing-library/react'
 import type { BaseNode } from '@core/page-tree'
-import { bagToReactStyle } from '@core/publisher'
+import { bagToReactStyle, type RenderResolvedMedia } from '@core/publisher'
+import { responsiveBackgroundReactStyle } from '@admin/pages/media/hooks/useResponsiveBackgroundStyle'
 import { ReadOnlyNodeTree } from '@modules/base/utils/ReadOnlyNodeTree'
 // Self-registering module imports — ReadOnlyNodeTree resolves components via
 // the global registry.
@@ -36,6 +37,23 @@ function textNode(id: string, overrides: Partial<BaseNode> = {}): BaseNode {
   }
 }
 
+function resolvedMedia(path = '/uploads/hero.png'): RenderResolvedMedia {
+  return {
+    publicPath: path,
+    mimeType: 'image/png',
+    width: 2400,
+    height: 1200,
+    altText: '',
+    blurHash: null,
+    variants: [
+      { width: 320, height: 160, format: 'webp', path: '/uploads/hero-w320.webp', sizeBytes: 12_000 },
+      { width: 1024, height: 512, format: 'webp', path: '/uploads/hero-w1024.webp', sizeBytes: 82_000 },
+      { width: 2048, height: 1024, format: 'webp', path: '/uploads/hero-w2048.webp', sizeBytes: 190_000 },
+    ],
+    posterPath: null,
+  }
+}
+
 describe('ReadOnlyNodeTree — inline styles', () => {
   it('applies node.inlineStyles to the rendered element, matching the publisher', () => {
     // happy-dom cannot parse `clamp(…)` in a React style object (the value the
@@ -135,3 +153,20 @@ describe('bagToReactStyle', () => {
     expect(bagToReactStyle({})).toBeUndefined()
   })
 })
+
+describe('responsiveBackgroundReactStyle', () => {
+  it('uses optimized image-set candidates for editor inline background styles', () => {
+    const style = responsiveBackgroundReactStyle(
+      {
+        backgroundImage: 'linear-gradient(red, blue), url("/uploads/hero.png")',
+        color: 'red',
+      },
+      new Map([['/uploads/hero.png', resolvedMedia()]]),
+    )
+
+    expect(style?.color).toBe('red')
+    expect(style?.backgroundImage).toContain('linear-gradient(red, blue), image-set(')
+    expect(style?.backgroundImage).toContain('url("/uploads/hero-w1024.webp") 1x')
+    expect(style?.backgroundImage).not.toContain('/uploads/hero.png')
+  })
+})
diff --git a/src/__tests__/publisher/classStyleInjector.test.ts b/src/__tests__/publisher/classStyleInjector.test.ts
index 35e163987..5adb0899c 100644
--- a/src/__tests__/publisher/classStyleInjector.test.ts
+++ b/src/__tests__/publisher/classStyleInjector.test.ts
@@ -13,9 +13,10 @@
  */
 
 import { describe, it, expect } from 'bun:test'
-import { bagToCSS, collectClassCSS, generateClassCSS } from '@core/publisher'
+import { bagToCSS, bagToInlineStyle, collectClassCSS, generateClassCSS } from '@core/publisher'
 import { classKindSelector, makeConditionDef } from '@core/page-tree'
 import type { StyleRule, Page, PageNode, SiteDocument } from '@core/page-tree'
+import type { RenderResolvedMedia } from '@core/publisher'
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -45,6 +46,23 @@ const BREAKPOINTS = [
   { id: 'tablet', width: 768 },
 ]
 
+function resolvedMedia(path = '/uploads/hero.png'): RenderResolvedMedia {
+  return {
+    publicPath: path,
+    mimeType: 'image/png',
+    width: 2400,
+    height: 1200,
+    altText: '',
+    blurHash: null,
+    variants: [
+      { width: 320, height: 160, format: 'webp', path: '/uploads/hero-w320.webp', sizeBytes: 12_000 },
+      { width: 1024, height: 512, format: 'webp', path: '/uploads/hero-w1024.webp', sizeBytes: 82_000 },
+      { width: 2048, height: 1024, format: 'webp', path: '/uploads/hero-w2048.webp', sizeBytes: 190_000 },
+    ],
+    posterPath: null,
+  }
+}
+
 // ---------------------------------------------------------------------------
 // bagToCSS
 // ---------------------------------------------------------------------------
@@ -141,6 +159,31 @@ describe('bagToCSS', () => {
     expect(css).toContain('border-radius: 4px;')
   })
 
+  it('rewrites media background images to optimized fallback plus image-set declarations', () => {
+    const css = bagToCSS(
+      { backgroundImage: "url('/uploads/hero.png')" },
+      { mediaAssets: new Map([['/uploads/hero.png', resolvedMedia()]]) },
+    )
+
+    expect(css).toContain('background-image: url("/uploads/hero-w2048.webp");')
+    expect(css).toContain('background-image: image-set(')
+    expect(css).toContain('url("/uploads/hero-w320.webp") 0.31x')
+    expect(css).toContain('url("/uploads/hero-w1024.webp") 1x')
+    expect(css).toContain('url("/uploads/hero-w2048.webp") 2x')
+    expect(css).not.toContain('/uploads/hero.png')
+  })
+
+  it('rewrites media background images inside inline style strings without selecting the original', () => {
+    const inline = bagToInlineStyle(
+      { backgroundImage: 'linear-gradient(red, blue), url("/uploads/hero.png")' },
+      { mediaAssets: new Map([['/uploads/hero.png', resolvedMedia()]]) },
+    )
+
+    expect(inline).toContain('linear-gradient(red, blue), url("/uploads/hero-w2048.webp")')
+    expect(inline).toContain('linear-gradient(red, blue), image-set(')
+    expect(inline).not.toContain('/uploads/hero.png')
+  })
+
   it('outputs multiple properties as separate lines', () => {
     const css = bagToCSS({ fontSize: '14px', color: '#eee', fontWeight: '600' })
     const lines = css.split('\n')
@@ -556,6 +599,20 @@ describe('generateClassCSS', () => {
     expect(tabletIdx).toBeGreaterThan(mobileIdx)
     expect(desktopIdx).toBeGreaterThan(tabletIdx)
   })
+
+  it('rewrites class background images with responsive image-set candidates', () => {
+    const classes = {
+      hero: makeClass('hero', { backgroundImage: "url('/uploads/hero.png')" }),
+    }
+    const css = generateClassCSS(classes, BREAKPOINTS, [], {
+      mediaAssets: new Map([['/uploads/hero.png', resolvedMedia()]]),
+    })
+
+    expect(css).toContain('.hero {')
+    expect(css).toContain('background-image: url("/uploads/hero-w2048.webp");')
+    expect(css).toContain('background-image: image-set(')
+    expect(css).not.toContain('/uploads/hero.png')
+  })
 })
 
 // ---------------------------------------------------------------------------
diff --git a/src/__tests__/server/mediaBatchResolution.test.ts b/src/__tests__/server/mediaBatchResolution.test.ts
index 0d88c9a03..2713eff8e 100644
--- a/src/__tests__/server/mediaBatchResolution.test.ts
+++ b/src/__tests__/server/mediaBatchResolution.test.ts
@@ -171,6 +171,68 @@ describe('prefetchMediaAssets (Finding 2)', () => {
     expect(map.size).toBe(0) // both paths not in DB → hits absent from map
   })
 
+  it('collects media paths from inline and class background images in the same batched query', async () => {
+    let queryCount = 0
+    let queriedPaths: unknown[] = []
+    const db = createFakeDb(async (_sql, params) => {
+      queryCount++
+      queriedPaths = params
+      return { rows: [], rowCount: 0 }
+    })
+    const page = {
+      id: 'p',
+      nodes: {
+        root: {
+          id: 'root',
+          moduleId: 'base.body',
+          props: {},
+          children: ['n1'],
+          breakpointOverrides: {},
+          classIds: ['hero-class'],
+        },
+        n1: {
+          id: 'n1',
+          moduleId: 'base.container',
+          props: {},
+          children: [],
+          breakpointOverrides: {},
+          classIds: [],
+          inlineStyles: { backgroundImage: "url('/uploads/inline-bg.png')" },
+        },
+      },
+      rootNodeId: 'root',
+    }
+    const site = {
+      visualComponents: [],
+      styleRules: {
+        'hero-class': {
+          id: 'hero-class',
+          name: 'hero',
+          kind: 'class',
+          selector: { kind: 'class', name: 'hero' },
+          order: 0,
+          styles: { backgroundImage: "url('/uploads/class-bg.png')" },
+          contextStyles: {
+            mobile: { backgroundImage: "url('/uploads/mobile-bg.png')" },
+          },
+          createdAt: 0,
+          updatedAt: 0,
+        },
+      },
+    }
+    const registry = { get: () => ({ id: 'base.container', schema: {} }) } as unknown as IModuleRegistry
+
+    const map = await prefetchMediaAssets(page as never, site as never, registry, db)
+
+    expect(queryCount).toBe(1)
+    expect(queriedPaths.toSorted()).toEqual([
+      '/uploads/class-bg.png',
+      '/uploads/inline-bg.png',
+      '/uploads/mobile-bg.png',
+    ])
+    expect(map.size).toBe(0)
+  })
+
   it('paths absent from the DB are absent from the returned map (real SQLite)', async () => {
     const { db, cleanup } = await createTestDb()
     try {
diff --git a/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts b/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts
index c93356d05..2bda881ff 100644
--- a/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts
+++ b/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts
@@ -76,3 +76,34 @@ export function useCmsMediaAssetByPath(publicPath: string | null | undefined): C
 
   return publicPath ? cache.get(publicPath) ?? null : null
 }
+
+export function useCmsMediaAssetsByPath(publicPaths: readonly string[]): ReadonlyMap<string, CmsMediaAsset> {
+  const [, setTick] = useState(0)
+  const hasPaths = publicPaths.length > 0
+
+  useEffect(() => {
+    if (!hasPaths) return
+    if (publicPaths.every((path) => cache.has(path))) return
+    let canceled = false
+    void ensureList()
+      .then(() => { if (!canceled) setTick((n) => n + 1) })
+      .catch(() => { /* swallow — editor still renders raw urls */ })
+    return () => { canceled = true }
+  }, [hasPaths, publicPaths])
+
+  // Subscribe to cache invalidation only when this consumer actually depends on
+  // media rows; most canvas nodes have no background image.
+  useEffect(() => {
+    if (!hasPaths) return
+    const sub = () => setTick((n) => n + 1)
+    subscribers.add(sub)
+    return () => { subscribers.delete(sub) }
+  }, [hasPaths])
+
+  const assets = new Map<string, CmsMediaAsset>()
+  for (const path of publicPaths) {
+    const asset = cache.get(path)
+    if (asset) assets.set(path, asset)
+  }
+  return assets
+}
diff --git a/src/admin/pages/media/hooks/useResponsiveBackgroundStyle.ts b/src/admin/pages/media/hooks/useResponsiveBackgroundStyle.ts
new file mode 100644
index 000000000..e5e488e86
--- /dev/null
+++ b/src/admin/pages/media/hooks/useResponsiveBackgroundStyle.ts
@@ -0,0 +1,88 @@
+import {
+  bagToReactStyle,
+  collectBackgroundImagePaths,
+  responsiveBackgroundImage,
+  type RenderResolvedMedia,
+} from '@core/publisher'
+import type { CmsMediaAsset } from '@core/persistence/cmsMedia'
+import { useCmsMediaAssetsByPath } from './useCmsMediaAssetByPath'
+
+export interface ResponsiveEditorMediaAssets {
+  mediaAssets: ReadonlyMap<string, RenderResolvedMedia>
+  signature: string
+}
+
+function renderResolvedMediaFromCms(asset: CmsMediaAsset): RenderResolvedMedia {
+  return {
+    publicPath: asset.publicPath,
+    mimeType: asset.mimeType,
+    width: asset.width,
+    height: asset.height,
+    altText: asset.altText,
+    blurHash: asset.blurHash,
+    variants: asset.variants,
+    posterPath: asset.posterPath,
+  }
+}
+
+function uniqueBackgroundPathsFromBag(bag: Record<string, unknown> | undefined): string[] {
+  return [...new Set(collectBackgroundImagePaths(bag?.backgroundImage))]
+}
+
+let lastResponsiveAssetsKey = ''
+let lastResponsiveAssets: ResponsiveEditorMediaAssets | null = null
+
+function responsiveMediaAssetsFromCms(
+  paths: readonly string[],
+  assets: ReadonlyMap<string, CmsMediaAsset>,
+): ResponsiveEditorMediaAssets {
+  const mediaAssets = new Map<string, RenderResolvedMedia>()
+  const pathKey = [...paths].sort().join('\0')
+  const signatureParts: string[] = []
+
+  for (const path of [...paths].sort()) {
+    const asset = assets.get(path)
+    if (!asset) continue
+    mediaAssets.set(path, renderResolvedMediaFromCms(asset))
+    if (asset.variants.length === 0) continue
+    signatureParts.push(`${path}=${asset.variants.map((v) => `${v.width}:${v.path}`).join('|')}`)
+  }
+
+  const signature = signatureParts.join(';')
+  const key = `${pathKey}\n${signature}`
+  if (lastResponsiveAssets && lastResponsiveAssetsKey === key) return lastResponsiveAssets
+
+  lastResponsiveAssetsKey = key
+  lastResponsiveAssets = { mediaAssets, signature }
+  return lastResponsiveAssets
+}
+
+export function responsiveBackgroundReactStyle(
+  bag: Record<string, unknown> | undefined,
+  mediaAssets: ReadonlyMap<string, RenderResolvedMedia>,
+): Record<string, string | number> | undefined {
+  if (!bag) return undefined
+  if (typeof bag.backgroundImage !== 'string' || mediaAssets.size === 0) {
+    return bagToReactStyle(bag)
+  }
+
+  const responsive = responsiveBackgroundImage(bag.backgroundImage, mediaAssets)
+  return bagToReactStyle({
+    ...bag,
+    backgroundImage: responsive.imageSet ?? responsive.fallback,
+  })
+}
+
+export function useResponsiveEditorMediaAssets(paths: readonly string[]): ResponsiveEditorMediaAssets {
+  const uniquePaths = [...new Set(paths)]
+  const assets = useCmsMediaAssetsByPath(uniquePaths)
+  return responsiveMediaAssetsFromCms(uniquePaths, assets)
+}
+
+export function useResponsiveBackgroundStyle(
+  bag: Record<string, unknown> | undefined,
+): Record<string, string | number> | undefined {
+  const paths = uniqueBackgroundPathsFromBag(bag)
+  const { mediaAssets } = useResponsiveEditorMediaAssets(paths)
+  return responsiveBackgroundReactStyle(bag, mediaAssets)
+}
diff --git a/src/admin/pages/site/canvas/ClassStyleInjector.tsx b/src/admin/pages/site/canvas/ClassStyleInjector.tsx
index 99b979456..b92b5a100 100644
--- a/src/admin/pages/site/canvas/ClassStyleInjector.tsx
+++ b/src/admin/pages/site/canvas/ClassStyleInjector.tsx
@@ -41,6 +41,8 @@
 import { useEffect } from 'react'
 import { useEditorStore } from '@site/store/store'
 import { styleRuleSelector, type ConditionDef, type StyleRule } from '@core/page-tree'
+import { collectBackgroundImagePaths, collectSiteStyleBackgroundImagePaths } from '@core/publisher'
+import { useResponsiveEditorMediaAssets } from '@admin/pages/media/hooks/useResponsiveBackgroundStyle'
 import { selectorStatePseudo } from '@site/cssStatePseudo'
 import { generateCanvasClassCSS, generateForcedStateCSS, generatePreviewClassCSS } from './canvasClassCss'
 import { resolveViewportUnitsForCanvas, type CanvasViewport } from './resolveViewportUnits'
@@ -101,6 +103,14 @@ export function ClassStyleInjector({ targetDocument, viewport }: ClassStyleInjec
   const previewClassStyles = useEditorStore((s) => s.previewClassStyles)
   const activeClassId = useEditorStore((s) => s.activeClassId)
   const selectedNodeId = useEditorStore((s) => s.selectedNodeId)
+  const backgroundPaths = [
+    ...collectSiteStyleBackgroundImagePaths({ styleRules: classes ?? EMPTY_STYLE_RULES }),
+    ...collectBackgroundImagePaths(previewClassStyles?.styles.backgroundImage),
+  ]
+  const {
+    mediaAssets: responsiveMediaAssets,
+    signature: responsiveMediaSignature,
+  } = useResponsiveEditorMediaAssets(backgroundPaths)
 
   useEffect(() => {
     const targetDoc = targetDocument ?? document
@@ -126,6 +136,7 @@ export function ClassStyleInjector({ targetDocument, viewport }: ClassStyleInjec
       frameworkSpacing,
       frameworkPreferences,
       fonts,
+      { mediaAssets: responsiveMediaAssets, mediaSignature: responsiveMediaSignature },
     )
     // Wrap in a named cascade layer so editor-chrome CSS (unlayered, from
     // EditorChromeInjector) always wins over author CSS regardless of specificity.
@@ -137,7 +148,20 @@ export function ClassStyleInjector({ targetDocument, viewport }: ClassStyleInjec
     styleEl.textContent = css
       ? `@layer user-authored {\n${css}\n}`
       : '/* no classes */'
-  }, [targetDocument, viewport, classes, breakpoints, conditions, frameworkColors, frameworkTypography, frameworkSpacing, frameworkPreferences, fonts])
+  }, [
+    targetDocument,
+    viewport,
+    classes,
+    breakpoints,
+    conditions,
+    frameworkColors,
+    frameworkTypography,
+    frameworkSpacing,
+    frameworkPreferences,
+    fonts,
+    responsiveMediaAssets,
+    responsiveMediaSignature,
+  ])
 
   // Preview overlay — a higher-specificity rule emitted while a user is
   // hovering a suggestion in a property control (e.g. spacing token
@@ -166,14 +190,14 @@ export function ClassStyleInjector({ targetDocument, viewport }: ClassStyleInjec
     const previewCss = generatePreviewClassCSS(cls, {
       breakpointId: previewClassStyles.breakpointId ?? null,
       styles: previewClassStyles.styles,
-    })
+    }, { mediaAssets: responsiveMediaAssets })
     const resolvedPreviewCss = viewport ? resolveViewportUnitsForCanvas(previewCss, viewport) : previewCss
     // Keep in the same @layer so the doubled-selector preview rule still wins
     // over the regular class rule within the layer (higher specificity).
     previewEl.textContent = resolvedPreviewCss
       ? `@layer user-authored {\n${resolvedPreviewCss}\n}`
       : ''
-  }, [targetDocument, viewport, classes, previewClassStyles])
+  }, [targetDocument, viewport, classes, previewClassStyles, responsiveMediaAssets])
 
   // Forced state preview — when a state-pseudo selector (`.btn:hover`, …) is the
   // active selector, paint its declarations onto the selected node so the state
@@ -203,10 +227,27 @@ export function ClassStyleInjector({ targetDocument, viewport }: ClassStyleInjec
     const inflight = previewClassStyles?.classId === activeClassId
       ? { contextId: previewClassStyles.breakpointId ?? null, styles: previewClassStyles.styles }
       : null
-    const forcedCss = generateForcedStateCSS(selectedNodeId, rule, breakpoints, conditions, inflight)
+    const forcedCss = generateForcedStateCSS(
+      selectedNodeId,
+      rule,
+      breakpoints,
+      conditions,
+      inflight,
+      { mediaAssets: responsiveMediaAssets },
+    )
     const resolved = viewport ? resolveViewportUnitsForCanvas(forcedCss, viewport) : forcedCss
     forceEl.textContent = resolved ? `@layer user-authored {\n${resolved}\n}` : ''
-  }, [targetDocument, viewport, classes, breakpoints, conditions, activeClassId, selectedNodeId, previewClassStyles])
+  }, [
+    targetDocument,
+    viewport,
+    classes,
+    breakpoints,
+    conditions,
+    activeClassId,
+    selectedNodeId,
+    previewClassStyles,
+    responsiveMediaAssets,
+  ])
 
   // Cleanup: remove the style elements when the component unmounts. We
   // capture `targetDocument` into the effect so cleanup targets the same
diff --git a/src/admin/pages/site/canvas/ModuleSandboxFrame.tsx b/src/admin/pages/site/canvas/ModuleSandboxFrame.tsx
index 8506f1cbc..a4b3041fc 100644
--- a/src/admin/pages/site/canvas/ModuleSandboxFrame.tsx
+++ b/src/admin/pages/site/canvas/ModuleSandboxFrame.tsx
@@ -12,7 +12,8 @@ import { Button } from '@ui/components/Button'
 import { CanvasModulePlaceholder } from '@ui/components/CanvasModulePlaceholder'
 import { PackageSolidIcon } from 'pixel-art-icons/icons/package-solid'
 import { cn } from '@ui/cn'
-import { generateClassCSS } from '@core/publisher'
+import { collectSiteStyleBackgroundImagePaths, generateClassCSS, type ResponsiveCssOptions } from '@core/publisher'
+import { useResponsiveEditorMediaAssets } from '@admin/pages/media/hooks/useResponsiveBackgroundStyle'
 import {
   createSandboxSrcDoc,
   HOST_MESSAGE_SOURCE,
@@ -30,17 +31,26 @@ interface ModuleSandboxFrameProps {
   classIds?: readonly string[]
 }
 
-function getNodeClassCSS(site: SiteDocument | null, classIds: readonly string[] | undefined): string {
-  if (!site || !classIds?.length) return ''
-
+function collectNodeClassRules(site: SiteDocument | null, classIds: readonly string[] | undefined): SiteDocument['styleRules'] {
   const classes: SiteDocument['styleRules'] = {}
+  if (!site || !classIds?.length) return classes
+
   for (const id of classIds) {
     const cls = site.styleRules[id]
     if (cls) classes[id] = cls
   }
+  return classes
+}
 
+function getNodeClassCSS(
+  site: SiteDocument | null,
+  classIds: readonly string[] | undefined,
+  responsiveOptions: ResponsiveCssOptions = {},
+): string {
+  if (!site) return ''
+  const classes = collectNodeClassRules(site, classIds)
   if (Object.keys(classes).length === 0) return ''
-  return generateClassCSS(classes, site.breakpoints, site.conditions ?? [])
+  return generateClassCSS(classes, site.breakpoints, site.conditions ?? [], responsiveOptions)
 }
 
 export function ModuleSandboxFrame({
@@ -66,7 +76,10 @@ export function ModuleSandboxFrame({
   // (with a one-click "add" affordance) before mounting the iframe at all.
   const missingDependencies = getMissingModuleDependencies(moduleDefinition, packageJson)
 
-  const classCSS = getNodeClassCSS(site, classIds)
+  const nodeClassRules = collectNodeClassRules(site, classIds)
+  const classBackgroundPaths = [...collectSiteStyleBackgroundImagePaths({ styleRules: nodeClassRules })]
+  const { mediaAssets: responsiveMediaAssets } = useResponsiveEditorMediaAssets(classBackgroundPaths)
+  const classCSS = getNodeClassCSS(site, classIds, { mediaAssets: responsiveMediaAssets })
 
   // The iframe's import map is filtered from the site's precomputed
   // `runtime.packageImportmap` — the server built it from the actual
diff --git a/src/admin/pages/site/canvas/NodeRenderer.tsx b/src/admin/pages/site/canvas/NodeRenderer.tsx
index 818fdda68..27c8928b4 100644
--- a/src/admin/pages/site/canvas/NodeRenderer.tsx
+++ b/src/admin/pages/site/canvas/NodeRenderer.tsx
@@ -37,7 +37,7 @@ import {
   resolveEditorFormPreviewState,
   resolveEditorFormPreviewSuccessMessage,
 } from './canvasFormPreview'
-import { bagToReactStyle } from '@core/publisher'
+import { useResponsiveBackgroundStyle } from '@admin/pages/media/hooks/useResponsiveBackgroundStyle'
 import { getCanvasNodeClassIds, getCanvasNodeClassName } from './canvasNodeClassName'
 import { findEnclosingComponentRef, type AnnotatedPageNode } from './canvasSelectionUtils'
 import { useLoopPreviewItems } from './useLoopPreviewItems'
@@ -194,6 +194,8 @@ export const NodeRenderer = memo(function NodeRenderer({ nodeId }: NodeRendererP
     sel.addRange(range)
   }, [isInlineEditing, inlineEditInitialValue])
 
+  const inlineStyle = useResponsiveBackgroundStyle(node?.inlineStyles)
+
   if (!node) return null
   if (node.hidden) return null
 
@@ -249,10 +251,6 @@ export const NodeRenderer = memo(function NodeRenderer({ nodeId }: NodeRendererP
   // `:nth-child()`, etc.) because it sat between every authored element.
   // Moving the bag onto the module's own root removes the wrapper entirely
   // and the canvas DOM matches the published DOM exactly.
-  // Per-node inline styles → React style object on the root element, matching
-  // the published `style="…"` attribute (sanitised to the same gate).
-  const inlineStyle = bagToReactStyle(node.inlineStyles)
-
   const nodeWrapperProps: NodeWrapperPropsType = {
     'data-node-id': nodeId,
     'data-module-id': node.moduleId,
diff --git a/src/admin/pages/site/canvas/canvasClassCss.ts b/src/admin/pages/site/canvas/canvasClassCss.ts
index 749040858..546bae592 100644
--- a/src/admin/pages/site/canvas/canvasClassCss.ts
+++ b/src/admin/pages/site/canvas/canvasClassCss.ts
@@ -4,6 +4,7 @@ import {
   generateClassCSS,
   PUBLISHER_RESET_CSS,
   type ViewportContext,
+  type ResponsiveCssOptions,
 } from '@core/publisher'
 import { generateFrameworkRootCss } from '@core/framework'
 import { generateFontsCss } from '@core/fonts'
@@ -17,6 +18,10 @@ import type {
   FrameworkTypographySettings,
 } from '@core/framework-schema'
 
+interface CanvasResponsiveCssOptions extends ResponsiveCssOptions {
+  mediaSignature?: string
+}
+
 function buildCanvasClassCSS(
   classes: Record<string, StyleRule>,
   breakpoints: ViewportContext[],
@@ -26,6 +31,7 @@ function buildCanvasClassCSS(
   frameworkSpacing?: FrameworkSpacingSettings | null,
   frameworkPreferences?: FrameworkPreferencesSettings | null,
   fonts?: SiteFontsSettings | null,
+  responsiveOptions: CanvasResponsiveCssOptions = {},
 ): string {
   const blocks: string[] = []
 
@@ -56,7 +62,7 @@ function buildCanvasClassCSS(
   // exact bytes a publish would (rule order, condition/viewport cascade, and
   // sanitized raw @keyframes rules included), so the preview cannot drift
   // from the published output.
-  const classCss = generateClassCSS(classes, breakpoints, conditions)
+  const classCss = generateClassCSS(classes, breakpoints, conditions, responsiveOptions)
   if (classCss) blocks.push(classCss)
 
   return blocks.join('\n\n')
@@ -90,6 +96,7 @@ export function createCanvasClassCssMemo(
     frameworkSpacing,
     frameworkPreferences,
     fonts,
+    responsiveOptions = {},
   ) => {
     const inputs = [
       classes,
@@ -100,6 +107,7 @@ export function createCanvasClassCssMemo(
       frameworkSpacing,
       frameworkPreferences,
       fonts,
+      responsiveOptions.mediaSignature,
     ]
     const prev = lastInputs
     if (prev && inputs.every((value, i) => Object.is(value, prev[i]))) {
@@ -114,6 +122,7 @@ export function createCanvasClassCssMemo(
       frameworkSpacing,
       frameworkPreferences,
       fonts,
+      responsiveOptions,
     )
     lastInputs = inputs
     return lastCss
@@ -137,8 +146,9 @@ export const generateCanvasClassCSS: CanvasClassCssGenerator = createCanvasClass
 export function generatePreviewClassCSS(
   cls: StyleRule,
   preview: { breakpointId?: string | null; styles: Record<string, unknown> },
+  responsiveOptions: ResponsiveCssOptions = {},
 ): string {
-  const decls = bagToCSS(preview.styles)
+  const decls = bagToCSS(preview.styles, responsiveOptions)
   if (!decls) return ''
   const selector = styleRuleSelector(cls)
   const doubled = `${selector}${selector}`
@@ -182,6 +192,7 @@ export function generateForcedStateCSS(
   breakpoints: ViewportContext[],
   conditions: ReadonlyArray<ConditionDef> = [],
   inflight?: ForcedStateInflight | null,
+  responsiveOptions: ResponsiveCssOptions = {},
 ): string {
   const rawSelector = `[data-node-id="${escapeCssAttribute(nodeId)}"]`
   const selector = `${rawSelector}${rawSelector}`
@@ -197,7 +208,7 @@ export function generateForcedStateCSS(
     contextStyles[inflight.contextId] = { ...(contextStyles[inflight.contextId] ?? {}), ...inflight.styles }
   }
 
-  const emitRule = createStyleRuleCssEmitter(breakpoints, conditions)
+  const emitRule = createStyleRuleCssEmitter(breakpoints, conditions, responsiveOptions)
   return emitRule(selector, baseStyles, contextStyles).join('\n\n')
 }
 
diff --git a/src/core/publisher/classCss.ts b/src/core/publisher/classCss.ts
index 38f6b8e00..ffc466c94 100644
--- a/src/core/publisher/classCss.ts
+++ b/src/core/publisher/classCss.ts
@@ -1,6 +1,7 @@
 import type { StyleRule, Condition, ConditionDef } from '@core/page-tree'
 import { breakpointMediaQuery, styleRuleSelector } from '@core/page-tree'
 import { sanitiseCssValue } from './utils'
+import { responsiveBackgroundImage, type ResponsiveCssOptions } from './responsiveBackground'
 
 /**
  * Convert a camelCase CSS property name to kebab-case.
@@ -137,7 +138,10 @@ function tryCollapseSides(
  * collapse, the property denylist, and value sanitisation all live here so the
  * two formatters can never drift.
  */
-function bagToDeclarations(bag: Record<string, unknown>): Array<[string, string]> {
+function bagToDeclarations(
+  bag: Record<string, unknown>,
+  options: ResponsiveCssOptions = {},
+): Array<[string, string]> {
   const decls: Array<[string, string]> = []
   // Track which prefixes have already been emitted as a collapsed shorthand
   // so we skip the remaining three side properties for that prefix.
@@ -161,7 +165,18 @@ function bagToDeclarations(bag: Record<string, unknown>): Array<[string, string]
 
     const sanitised = sanitiseCssValue(value as string | number)
     if (sanitised === null) continue
-    decls.push([toKebab(prop), sanitised])
+    const kebab = toKebab(prop)
+    if (prop === 'backgroundImage') {
+      const responsive = responsiveBackgroundImage(sanitised, options.mediaAssets)
+      const fallback = sanitiseCssValue(responsive.fallback)
+      if (fallback !== null) decls.push([kebab, fallback])
+      if (responsive.imageSet) {
+        const imageSet = sanitiseCssValue(responsive.imageSet)
+        if (imageSet !== null) decls.push([kebab, imageSet])
+      }
+      continue
+    }
+    decls.push([kebab, sanitised])
   }
   return decls
 }
@@ -171,8 +186,8 @@ function bagToDeclarations(bag: Record<string, unknown>): Array<[string, string]
  * for use inside a `{ … }` rule body). See `bagToDeclarations` for the shared
  * extraction rules.
  */
-export function bagToCSS(bag: Record<string, unknown>): string {
-  return bagToDeclarations(bag)
+export function bagToCSS(bag: Record<string, unknown>, options: ResponsiveCssOptions = {}): string {
+  return bagToDeclarations(bag, options)
     .map(([prop, value]) => `  ${prop}: ${value};`)
     .join('\n')
 }
@@ -186,8 +201,8 @@ export function bagToCSS(bag: Record<string, unknown>): string {
  * Returns `''` when no declaration survives the gate (the caller then emits no
  * `style` attribute at all).
  */
-export function bagToInlineStyle(bag: Record<string, unknown>): string {
-  return bagToDeclarations(bag)
+export function bagToInlineStyle(bag: Record<string, unknown>, options: ResponsiveCssOptions = {}): string {
+  return bagToDeclarations(bag, options)
     .map(([prop, value]) => `${prop}: ${value}`)
     .join('; ')
 }
@@ -290,6 +305,7 @@ export type StyleRuleCssEmitter = (
 export function createStyleRuleCssEmitter(
   breakpoints: ViewportContext[],
   conditions: ReadonlyArray<ConditionDef> = [],
+  options: ResponsiveCssOptions = {},
 ): StyleRuleCssEmitter {
   const breakpointById = new Map<string, { breakpoint: ViewportContext; index: number }>(
     breakpoints.map((bp, index) => [bp.id, { breakpoint: bp, index }]),
@@ -303,7 +319,7 @@ export function createStyleRuleCssEmitter(
   return (selector, styles, contextStyles) => {
     const blocks: string[] = []
 
-    const baseDecls = bagToCSS(styles)
+    const baseDecls = bagToCSS(styles, options)
     if (baseDecls) {
       blocks.push(`${selector} {\n${baseDecls}\n}`)
     }
@@ -326,7 +342,7 @@ export function createStyleRuleCssEmitter(
     // viewport-specific overrides keep winning when both contexts match.
     conditionEntries.sort((a, b) => a.index - b.index)
     for (const { bag, condition } of conditionEntries) {
-      const decls = bagToCSS(bag)
+      const decls = bagToCSS(bag, options)
       if (!decls) continue
       const prelude = conditionPrelude(condition)
       if (!prelude) continue
@@ -335,7 +351,7 @@ export function createStyleRuleCssEmitter(
 
     bpEntries.sort(compareViewportContextCascade)
     for (const { bag, breakpoint } of bpEntries) {
-      const decls = bagToCSS(bag)
+      const decls = bagToCSS(bag, options)
       if (!decls) continue
       const prelude = conditionPrelude({ kind: 'media', query: breakpointMediaQuery(breakpoint) })
       if (!prelude) continue
@@ -350,9 +366,10 @@ export function generateClassCSS(
   classes: Record<string, StyleRule>,
   breakpoints: ViewportContext[],
   conditions: ReadonlyArray<ConditionDef> = [],
+  options: ResponsiveCssOptions = {},
 ): string {
   const blocks: string[] = []
-  const emitRule = createStyleRuleCssEmitter(breakpoints, conditions)
+  const emitRule = createStyleRuleCssEmitter(breakpoints, conditions, options)
 
   // Cascade order: rules with a smaller `order` are emitted first so a later,
   // more-specific override appears later in source and wins on equal
diff --git a/src/core/publisher/classInjection.ts b/src/core/publisher/classInjection.ts
index faf61a7f1..af5699c68 100644
--- a/src/core/publisher/classInjection.ts
+++ b/src/core/publisher/classInjection.ts
@@ -20,6 +20,7 @@ import type { SiteDocument } from '@core/page-tree'
 import { classNamesForClassIds } from '@core/page-tree'
 import { bagToInlineStyle } from './classCss'
 import { escapeHtml } from './utils'
+import type { RenderResolvedMedia } from './renderConfig'
 
 /**
  * Inject a class attribute into the ROOT element of an HTML string.
@@ -132,9 +133,10 @@ function injectStyleIntoRootElement(html: string, styleAttr: string): string {
 export function injectNodeInlineStyles(
   html: string,
   inlineStyles: Record<string, unknown> | undefined,
+  mediaAssets?: ReadonlyMap<string, RenderResolvedMedia>,
 ): string {
   if (!inlineStyles || Object.keys(inlineStyles).length === 0) return html
-  const styleAttr = bagToInlineStyle(inlineStyles)
+  const styleAttr = bagToInlineStyle(inlineStyles, { mediaAssets })
   if (!styleAttr) return html
   return injectStyleIntoRootElement(html, styleAttr)
 }
diff --git a/src/core/publisher/cssCollector.ts b/src/core/publisher/cssCollector.ts
index 4a949f6af..c9ac8d4ce 100644
--- a/src/core/publisher/cssCollector.ts
+++ b/src/core/publisher/cssCollector.ts
@@ -21,6 +21,7 @@
 import type { SiteDocument } from '@core/page-tree'
 import { isGeneratedClass } from '@core/page-tree'
 import { generateClassCSS } from './classCss'
+import type { ResponsiveCssOptions } from './responsiveBackground'
 
 /**
  * Collect all user-authored CSS class declarations for the classes referenced
@@ -35,7 +36,7 @@ import { generateClassCSS } from './classCss'
  * @param site The site containing the class registry, page nodes, and VCs.
  * @returns A CSS string of all used class-name rules, or empty string if none.
  */
-export function collectClassCSS(site: SiteDocument): string {
+export function collectClassCSS(site: SiteDocument, options: ResponsiveCssOptions = {}): string {
   // Defensive guard: corrupted/partial snapshots may have classes undefined
   if (!site.styleRules) return ''
 
@@ -95,7 +96,7 @@ export function collectClassCSS(site: SiteDocument): string {
 
   if (Object.keys(usedClasses).length === 0) return ''
 
-  const css = generateClassCSS(usedClasses, site.breakpoints, site.conditions ?? [])
+  const css = generateClassCSS(usedClasses, site.breakpoints, site.conditions ?? [], options)
   return sanitizeModuleCSS(css)
 }
 
diff --git a/src/core/publisher/index.ts b/src/core/publisher/index.ts
index 276f0909d..b5d498f55 100644
--- a/src/core/publisher/index.ts
+++ b/src/core/publisher/index.ts
@@ -36,6 +36,7 @@ export { escapeHtml, isSafeUrl, safeUrl, sanitiseCssValue } from './utils'
 
 export {
   bagToCSS,
+  bagToInlineStyle,
   bagToReactStyle,
   createStyleRuleCssEmitter,
   generateClassCSS,
@@ -43,6 +44,15 @@ export {
 } from './classCss'
 export type { StyleRuleCssEmitter, ViewportContext } from './classCss'
 
+export {
+  collectBackgroundImagePaths,
+  collectBackgroundImagePathsFromStyleBag,
+  collectNodeBackgroundImagePaths,
+  collectSiteStyleBackgroundImagePaths,
+  responsiveBackgroundImage,
+} from './responsiveBackground'
+export type { ResponsiveCssOptions } from './responsiveBackground'
+
 export { collectClassCSS, CssCollector, sanitizeModuleCSS } from './cssCollector'
 
 export { buildSiteFrameworkCss, generateFrameworkCss } from './frameworkCss'
diff --git a/src/core/publisher/render.ts b/src/core/publisher/render.ts
index 81cc6b0e2..f2e3a30ef 100644
--- a/src/core/publisher/render.ts
+++ b/src/core/publisher/render.ts
@@ -204,7 +204,7 @@ function buildStyleHead(
 
   const frameworkCss = buildSiteFrameworkCss(site)
   const moduleCss = Array.from(cssMap.values()).join('\n')
-  const classCss = collectClassCSS(site)
+  const classCss = collectClassCSS(site, { mediaAssets: options.mediaAssets })
   const userCss = collectUserStylesheetCss(site, page)
   // Same cascade order as the external-link path: user CSS comes last so it
   // wins specificity ties against the class registry. Neutralise `</style>` in
@@ -258,7 +258,11 @@ function composeTemplateContext(
  * element, so root-level classIds belong on `<body>` itself — clean HTML
  * with no freeloader `<div>`.
  */
-function computeBodyOpenTag(page: Page, site: SiteDocument): string {
+function computeBodyOpenTag(
+  page: Page,
+  site: SiteDocument,
+  mediaAssets?: Map<string, RenderResolvedMedia>,
+): string {
   const rootNode = page.nodes[page.rootNodeId]
   if (!rootNode) return '<body>'
 
@@ -267,7 +271,9 @@ function computeBodyOpenTag(page: Page, site: SiteDocument): string {
     : ''
   // base.body emits no wrapper, so the root node's inline styles also belong
   // on <body> itself (same reasoning as classIds above).
-  const styleAttr = rootNode.inlineStyles ? escapeHtml(bagToInlineStyle(rootNode.inlineStyles)) : ''
+  const styleAttr = rootNode.inlineStyles
+    ? escapeHtml(bagToInlineStyle(rootNode.inlineStyles, { mediaAssets }))
+    : ''
   const htmlAttrs = bodyHtmlAttributes(rootNode.props.htmlAttributes)
 
   const attrs =
@@ -561,7 +567,7 @@ export function publishPage(
     importmapTag: runtime.importmapTag,
     headRuntimeScripts: runtime.headRuntimeScripts,
     holeRuntimeScript: runtime.holeRuntimeScript,
-    bodyOpenTag: computeBodyOpenTag(page, site),
+    bodyOpenTag: computeBodyOpenTag(page, site, options.mediaAssets),
     bodyHtml,
     bodyEndRuntimeScripts: runtime.bodyEndRuntimeScripts,
     loopRuntimeScript: runtime.loopRuntimeScript,
diff --git a/src/core/publisher/renderLoop.ts b/src/core/publisher/renderLoop.ts
index 321ad21c5..c90688a03 100644
--- a/src/core/publisher/renderLoop.ts
+++ b/src/core/publisher/renderLoop.ts
@@ -119,6 +119,6 @@ export function renderLoop(
 
   // Inject the loop's own classIds + inline styles onto the wrapper element.
   const withClasses = injectNodeClassIds(html, node.classIds, config.site)
-  const withStyles = injectNodeInlineStyles(withClasses, node.inlineStyles)
+  const withStyles = injectNodeInlineStyles(withClasses, node.inlineStyles, config.mediaAssets)
   return config.annotateNodeIds ? injectNodeId(withStyles, node.id) : withStyles
 }
diff --git a/src/core/publisher/renderNode.ts b/src/core/publisher/renderNode.ts
index 54df8595b..e54aec67e 100644
--- a/src/core/publisher/renderNode.ts
+++ b/src/core/publisher/renderNode.ts
@@ -194,7 +194,7 @@ function renderStandardNode(
   // <body> in publishPage.
   if (node.moduleId === 'base.body') return output.html
   const withClasses = injectNodeClassIds(output.html, node.classIds, config.site)
-  const withStyles = injectNodeInlineStyles(withClasses, node.inlineStyles)
+  const withStyles = injectNodeInlineStyles(withClasses, node.inlineStyles, config.mediaAssets)
   return config.annotateNodeIds ? injectNodeId(withStyles, node.id) : withStyles
 }
 
diff --git a/src/core/publisher/renderVisualComponentRef.ts b/src/core/publisher/renderVisualComponentRef.ts
index 211944e4c..61ca85e88 100644
--- a/src/core/publisher/renderVisualComponentRef.ts
+++ b/src/core/publisher/renderVisualComponentRef.ts
@@ -148,7 +148,7 @@ export function renderVisualComponentRef(
     node.classIds,
     config.site,
   )
-  const withStyles = injectNodeInlineStyles(rendered, node.inlineStyles)
+  const withStyles = injectNodeInlineStyles(rendered, node.inlineStyles, config.mediaAssets)
   // Annotate the VC root with the ref node id (the page-tree node the agent can
   // target) — outermost element only, exactly one uid per element.
   return config.annotateNodeIds ? injectNodeId(withStyles, node.id) : withStyles
diff --git a/src/core/publisher/responsiveBackground.ts b/src/core/publisher/responsiveBackground.ts
new file mode 100644
index 000000000..bb62d1a8f
--- /dev/null
+++ b/src/core/publisher/responsiveBackground.ts
@@ -0,0 +1,132 @@
+import type { BaseNode, SiteDocument, StyleRule } from '@core/page-tree'
+import type { RenderResolvedMedia } from './renderConfig'
+
+export interface ResponsiveCssOptions {
+  mediaAssets?: ReadonlyMap<string, RenderResolvedMedia>
+}
+
+const LOCAL_UPLOAD_PREFIX = '/uploads/'
+const BACKGROUND_IMAGE_SET_REFERENCE_WIDTH = 1024
+const CSS_URL_RE = /url\(\s*(?:(["'])(.*?)\1|([^"')\s][^)]*?))\s*\)/gi
+const IMAGE_SET_RE = /\bimage-set\s*\(/i
+
+interface ResponsiveBackgroundImage {
+  fallback: string
+  imageSet: string | null
+}
+
+function cssUrl(url: string): string {
+  return `url(${JSON.stringify(url)})`
+}
+
+function formatResolution(width: number): string {
+  return `${parseFloat((width / BACKGROUND_IMAGE_SET_REFERENCE_WIDTH).toFixed(2))}x`
+}
+
+function sortedVariants(media: RenderResolvedMedia): RenderResolvedMedia['variants'] {
+  return media.variants.slice().sort((a, b) => a.width - b.width)
+}
+
+function largestVariantUrl(media: RenderResolvedMedia): string | null {
+  const variants = sortedVariants(media)
+  return variants.length > 0 ? variants[variants.length - 1].path : null
+}
+
+function buildImageSet(media: RenderResolvedMedia): string | null {
+  const variants = sortedVariants(media)
+  if (variants.length === 0) return null
+
+  const seenDescriptors = new Set<string>()
+  const options: string[] = []
+  for (const variant of variants) {
+    const descriptor = formatResolution(variant.width)
+    if (seenDescriptors.has(descriptor)) continue
+    seenDescriptors.add(descriptor)
+    options.push(`${cssUrl(variant.path)} ${descriptor}`)
+  }
+
+  return options.length > 0 ? `image-set(${options.join(', ')})` : null
+}
+
+function rewriteCssUrls(
+  value: string,
+  replacementFor: (path: string) => string | null,
+): { value: string; replaced: boolean } {
+  let replaced = false
+  CSS_URL_RE.lastIndex = 0
+  const next = value.replace(CSS_URL_RE, (full, _quote: string, quoted: string, bare: string) => {
+    const path = (quoted ?? bare ?? '').trim()
+    const replacement = replacementFor(path)
+    if (!replacement) return full
+    replaced = true
+    return replacement
+  })
+  return { value: next, replaced }
+}
+
+export function collectBackgroundImagePaths(value: unknown): string[] {
+  if (typeof value !== 'string' || IMAGE_SET_RE.test(value)) return []
+  const paths: string[] = []
+  CSS_URL_RE.lastIndex = 0
+  let match: RegExpExecArray | null
+  while ((match = CSS_URL_RE.exec(value)) !== null) {
+    const path = (match[2] ?? match[3] ?? '').trim()
+    if (path.startsWith(LOCAL_UPLOAD_PREFIX)) paths.push(path)
+  }
+  return paths
+}
+
+export function collectBackgroundImagePathsFromStyleBag(
+  bag: Record<string, unknown> | undefined,
+  paths: Set<string>,
+): void {
+  if (!bag) return
+  for (const path of collectBackgroundImagePaths(bag.backgroundImage)) {
+    paths.add(path)
+  }
+}
+
+function collectBackgroundImagePathsFromStyleRule(rule: StyleRule, paths: Set<string>): void {
+  collectBackgroundImagePathsFromStyleBag(rule.styles, paths)
+  for (const bag of Object.values(rule.contextStyles ?? {})) {
+    collectBackgroundImagePathsFromStyleBag(bag, paths)
+  }
+}
+
+export function collectSiteStyleBackgroundImagePaths(site: Pick<SiteDocument, 'styleRules'>): Set<string> {
+  const paths = new Set<string>()
+  for (const rule of Object.values(site.styleRules ?? {})) {
+    collectBackgroundImagePathsFromStyleRule(rule, paths)
+  }
+  return paths
+}
+
+export function collectNodeBackgroundImagePaths(node: Pick<BaseNode, 'inlineStyles'>, paths: Set<string>): void {
+  collectBackgroundImagePathsFromStyleBag(node.inlineStyles, paths)
+}
+
+export function responsiveBackgroundImage(
+  value: string,
+  mediaAssets: ReadonlyMap<string, RenderResolvedMedia> | undefined,
+): ResponsiveBackgroundImage {
+  if (!mediaAssets || mediaAssets.size === 0 || IMAGE_SET_RE.test(value)) {
+    return { fallback: value, imageSet: null }
+  }
+
+  const fallback = rewriteCssUrls(value, (path) => {
+    const media = mediaAssets.get(path)
+    const replacement = media ? largestVariantUrl(media) : null
+    return replacement ? cssUrl(replacement) : null
+  })
+  if (!fallback.replaced) return { fallback: value, imageSet: null }
+
+  const imageSet = rewriteCssUrls(value, (path) => {
+    const media = mediaAssets.get(path)
+    return media ? buildImageSet(media) : null
+  })
+
+  return {
+    fallback: fallback.value,
+    imageSet: imageSet.replaced ? imageSet.value : null,
+  }
+}
diff --git a/src/modules/base/utils/ReadOnlyNodeTree.tsx b/src/modules/base/utils/ReadOnlyNodeTree.tsx
index 78daeff6b..df37dee50 100644
--- a/src/modules/base/utils/ReadOnlyNodeTree.tsx
+++ b/src/modules/base/utils/ReadOnlyNodeTree.tsx
@@ -33,7 +33,7 @@ import { registry } from '@core/module-engine'
 import type { NodeWrapperProps as NodeWrapperPropsType } from '@core/module-engine'
 import type { BaseNode, PageNode } from '@core/page-tree'
 import { classNamesForClassIds, resolveProps, type StyleRuleRegistry } from '@core/page-tree'
-import { bagToReactStyle } from '@core/publisher'
+import { useResponsiveBackgroundStyle } from '@admin/pages/media/hooks/useResponsiveBackgroundStyle'
 import {
   effectiveNodeBindings,
   resolveDynamicProps,
@@ -171,6 +171,7 @@ function ReadOnlyNodeRenderer({
   templateContext,
 }: ReadOnlyNodeRendererProps) {
   const node = nodes[nodeId]
+  const ownStyle = useResponsiveBackgroundStyle(node?.inlineStyles)
   if (!node) return null
   if (node.hidden) return null
 
@@ -253,7 +254,6 @@ function ReadOnlyNodeRenderer({
   // A forwarded root bag's style is appended AFTER the node's own declarations
   // (so the owning node wins per property), mirroring the publisher's
   // append-order in `renderVisualComponentRef`.
-  const ownStyle = bagToReactStyle(node.inlineStyles)
   const style = ownStyle || baseWrapperProps?.style
     ? { ...ownStyle, ...baseWrapperProps?.style }
     : undefined

From 71ea1aa58c7057512e7e97d276e1d811ed072df2 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 3 Jul 2026 17:06:54 +0200
Subject: [PATCH 2/2] fix(editor): keep optimized background media after reload

---
 .../canvas/classStyleInjectorMedia.test.tsx   | 114 +++++++
 .../media/hooks/useCmsMediaAssetByPath.ts     | 120 +++++---
 .../pages/media/hooks/useMediaWorkspace.ts    |   9 +-
 .../property-controls/MediaLibraryControl.tsx |   2 +
 tests/e2e/background-image-smoke.e2e.ts       | 279 ++++++++++++++++++
 5 files changed, 471 insertions(+), 53 deletions(-)
 create mode 100644 src/__tests__/canvas/classStyleInjectorMedia.test.tsx
 create mode 100644 tests/e2e/background-image-smoke.e2e.ts

diff --git a/src/__tests__/canvas/classStyleInjectorMedia.test.tsx b/src/__tests__/canvas/classStyleInjectorMedia.test.tsx
new file mode 100644
index 000000000..f905dfd54
--- /dev/null
+++ b/src/__tests__/canvas/classStyleInjectorMedia.test.tsx
@@ -0,0 +1,114 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import React from 'react'
+import { act, cleanup, render, waitFor } from '@testing-library/react'
+import { ClassStyleInjector } from '@site/canvas/ClassStyleInjector'
+import { useEditorStore } from '@site/store/store'
+import { classKindSelector, DEFAULT_BREAKPOINTS, type StyleRule } from '@core/page-tree'
+import { refreshCmsMediaAssetCache } from '@admin/pages/media/hooks/useCmsMediaAssetByPath'
+import { makeSite } from '../fixtures'
+
+const originalFetch = globalThis.fetch
+
+const backgroundPath = '/uploads/background.png'
+const variantPath = '/uploads/background-w1024.webp'
+
+function makeBackgroundClass(): StyleRule {
+  return {
+    id: 'hero-bg',
+    name: 'hero-bg',
+    kind: 'class',
+    selector: classKindSelector('hero-bg'),
+    order: 0,
+    styles: {
+      backgroundImage: `url('${backgroundPath}')`,
+      backgroundSize: 'cover',
+    },
+    contextStyles: {},
+    createdAt: 0,
+    updatedAt: 0,
+  }
+}
+
+function mediaResponse(): Response {
+  return new Response(JSON.stringify({
+    assets: [{
+      id: 'asset-1',
+      filename: 'background.png',
+      mimeType: 'image/png',
+      sizeBytes: 100,
+      publicPath: backgroundPath,
+      uploadedByUserId: null,
+      createdAt: '2026-07-03T00:00:00.000Z',
+      width: 1024,
+      height: 512,
+      variants: [{
+        width: 1024,
+        height: 512,
+        format: 'webp',
+        path: variantPath,
+        sizeBytes: 80,
+      }],
+    }],
+  }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+function resetEditorStore() {
+  useEditorStore.setState({
+    site: null,
+    activePageId: null,
+    activeDocument: null,
+    previewClassStyles: null,
+    activeClassId: null,
+    selectedNodeId: null,
+  } as Parameters<typeof useEditorStore.setState>[0])
+}
+
+describe('ClassStyleInjector media backgrounds', () => {
+  beforeEach(() => {
+    cleanup()
+    document.head.replaceChildren()
+    document.body.replaceChildren()
+    refreshCmsMediaAssetCache()
+    resetEditorStore()
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = typeof input === 'string' ? input : input.toString()
+      if (url.endsWith('/admin/api/cms/media')) return mediaResponse()
+      return new Response('', { status: 404 })
+    }) as typeof globalThis.fetch
+  })
+
+  afterEach(() => {
+    cleanup()
+    document.head.replaceChildren()
+    document.body.replaceChildren()
+    refreshCmsMediaAssetCache()
+    resetEditorStore()
+    globalThis.fetch = originalFetch
+  })
+
+  it('rewrites persisted class background images after the site loads during editor reload', async () => {
+    render(<ClassStyleInjector targetDocument={document} />)
+
+    await act(async () => {
+      useEditorStore.setState({
+        site: {
+          ...makeSite({ pages: [] }),
+          breakpoints: DEFAULT_BREAKPOINTS,
+          styleRules: {
+            'hero-bg': makeBackgroundClass(),
+          },
+        },
+      } as Parameters<typeof useEditorStore.setState>[0])
+    })
+
+    await waitFor(() => {
+      const css = document.head.querySelector<HTMLStyleElement>('style#mc-classes')?.textContent ?? ''
+      expect(css).toContain(`background-image: url("${variantPath}");`)
+      expect(css).toContain('background-image: image-set(')
+      expect(css).not.toContain(backgroundPath)
+    })
+  })
+})
diff --git a/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts b/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts
index 2bda881ff..be09f7144 100644
--- a/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts
+++ b/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts
@@ -25,12 +25,47 @@ const cache = new Map<string, CmsMediaAsset>()
 let listPromise: Promise<CmsMediaAsset[]> | null = null
 const subscribers = new Set<() => void>()
 
+interface CachedAssetSnapshot {
+  key: string
+  assets: ReadonlyMap<string, CmsMediaAsset>
+}
+
+const EMPTY_PATHS: string[] = []
+const EMPTY_ASSETS = new Map<string, CmsMediaAsset>()
+
+function notifySubscribers(): void {
+  for (const sub of subscribers) sub()
+}
+
+function publicPathsKey(publicPaths: readonly string[]): string {
+  return [...new Set(publicPaths)].sort().join('\0')
+}
+
+function pathsFromKey(key: string): string[] {
+  return key ? key.split('\0') : EMPTY_PATHS
+}
+
+function cachedAssetsForKey(key: string): ReadonlyMap<string, CmsMediaAsset> {
+  if (!key) return EMPTY_ASSETS
+
+  const assets = new Map<string, CmsMediaAsset>()
+  for (const path of pathsFromKey(key)) {
+    const asset = cache.get(path)
+    if (asset) assets.set(path, asset)
+  }
+  return assets
+}
+
+function cacheAssetList(assets: readonly CmsMediaAsset[]): void {
+  for (const asset of assets) cache.set(asset.publicPath, asset)
+  notifySubscribers()
+}
+
 function ensureList(): Promise<CmsMediaAsset[]> {
   if (listPromise) return listPromise
   listPromise = listCmsMediaAssets()
     .then((assets) => {
-      for (const asset of assets) cache.set(asset.publicPath, asset)
-      for (const sub of subscribers) sub()
+      cacheAssetList(assets)
       return assets
     })
     .catch((err) => {
@@ -49,61 +84,50 @@ function ensureList(): Promise<CmsMediaAsset[]> {
 export function refreshCmsMediaAssetCache(): void {
   cache.clear()
   listPromise = null
-  for (const sub of subscribers) sub()
+  notifySubscribers()
+}
+
+export function primeCmsMediaAssetCache(asset: CmsMediaAsset): void {
+  cacheAssetList([asset])
 }
 
 export function useCmsMediaAssetByPath(publicPath: string | null | undefined): CmsMediaAsset | null {
-  // Tiny state so the component re-renders when the cache populates. The
-  // value itself comes from the module-level Map.
-  const [, setTick] = useState(0)
+  const assets = useCmsMediaAssetsByPath(publicPath ? [publicPath] : EMPTY_PATHS)
+  return publicPath ? assets.get(publicPath) ?? null : null
+}
+
+export function useCmsMediaAssetsByPath(publicPaths: readonly string[]): ReadonlyMap<string, CmsMediaAsset> {
+  const key = publicPathsKey(publicPaths)
+  const [snapshot, setSnapshot] = useState<CachedAssetSnapshot>(() => ({
+    key,
+    assets: cachedAssetsForKey(key),
+  }))
+  const currentAssets = snapshot.key === key ? snapshot.assets : cachedAssetsForKey(key)
 
   useEffect(() => {
-    if (!publicPath) return
-    if (cache.has(publicPath)) return
+    const paths = pathsFromKey(key)
+    if (paths.length === 0) return
+
     let canceled = false
-    void ensureList()
-      .then(() => { if (!canceled) setTick((n) => n + 1) })
-      .catch(() => { /* swallow — editor still renders raw src */ })
-    return () => { canceled = true }
-  }, [publicPath])
 
-  // Subscribe to cache invalidation so refresh() bumps every consumer.
-  useEffect(() => {
-    const sub = () => setTick((n) => n + 1)
-    subscribers.add(sub)
-    return () => { subscribers.delete(sub) }
-  }, [])
+    const updateSnapshot = () => {
+      if (!canceled) setSnapshot({ key, assets: cachedAssetsForKey(key) })
+    }
 
-  return publicPath ? cache.get(publicPath) ?? null : null
-}
+    updateSnapshot()
+    subscribers.add(updateSnapshot)
 
-export function useCmsMediaAssetsByPath(publicPaths: readonly string[]): ReadonlyMap<string, CmsMediaAsset> {
-  const [, setTick] = useState(0)
-  const hasPaths = publicPaths.length > 0
+    if (!paths.every((path) => cache.has(path))) {
+      void ensureList()
+        .then(updateSnapshot)
+        .catch(() => { /* swallow — editor still renders raw urls */ })
+    }
 
-  useEffect(() => {
-    if (!hasPaths) return
-    if (publicPaths.every((path) => cache.has(path))) return
-    let canceled = false
-    void ensureList()
-      .then(() => { if (!canceled) setTick((n) => n + 1) })
-      .catch(() => { /* swallow — editor still renders raw urls */ })
-    return () => { canceled = true }
-  }, [hasPaths, publicPaths])
-
-  // Subscribe to cache invalidation only when this consumer actually depends on
-  // media rows; most canvas nodes have no background image.
-  useEffect(() => {
-    if (!hasPaths) return
-    const sub = () => setTick((n) => n + 1)
-    subscribers.add(sub)
-    return () => { subscribers.delete(sub) }
-  }, [hasPaths])
+    return () => {
+      canceled = true
+      subscribers.delete(updateSnapshot)
+    }
+  }, [key])
 
-  const assets = new Map<string, CmsMediaAsset>()
-  for (const path of publicPaths) {
-    const asset = cache.get(path)
-    if (asset) assets.set(path, asset)
-  }
-  return assets
+  return currentAssets
 }
diff --git a/src/admin/pages/media/hooks/useMediaWorkspace.ts b/src/admin/pages/media/hooks/useMediaWorkspace.ts
index 35e0d66b4..634753abc 100644
--- a/src/admin/pages/media/hooks/useMediaWorkspace.ts
+++ b/src/admin/pages/media/hooks/useMediaWorkspace.ts
@@ -38,7 +38,7 @@ import {
 import { buildFolderTree, type MediaFolderNode } from '../utils/folderTree'
 import { collectMediaTags, filterMediaAssets, type MediaFilters, type MediaSort, type MediaType } from '../utils/filters'
 import { useUploadQueue, type UseUploadQueueResult } from './useUploadQueue'
-import { refreshCmsMediaAssetCache } from './useCmsMediaAssetByPath'
+import { primeCmsMediaAssetCache, refreshCmsMediaAssetCache } from './useCmsMediaAssetByPath'
 import type { WorkspaceLoadState } from '@admin/lib/workspaceLoadState'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import {
@@ -318,13 +318,12 @@ export function useMediaWorkspace(): UseMediaWorkspaceResult {
 
   // Splice an uploaded asset into the workspace cache when the queue
   // reports success. Folder assignment (if any) happens inside the queue.
-  // Also invalidate the shared by-path cache so the editor canvas
+  // Also seed the shared by-path cache so the editor canvas
   // (`ImageEditor` / `useCmsMediaAssetByPath`) picks up the new asset
-  // immediately — otherwise an open Site editor would keep rendering a
-  // raw `<img src>` until manual reload.
+  // immediately without racing a follow-up list request.
   const onUploaded = (asset: CmsMediaAsset) => {
     setAssets((current) => [asset, ...current.filter((existing) => existing.id !== asset.id)])
-    refreshCmsMediaAssetCache()
+    primeCmsMediaAssetCache(asset)
   }
 
   const uploadQueue = useUploadQueue({
diff --git a/src/admin/pages/site/property-controls/MediaLibraryControl.tsx b/src/admin/pages/site/property-controls/MediaLibraryControl.tsx
index 482416a3b..63cf71dc2 100644
--- a/src/admin/pages/site/property-controls/MediaLibraryControl.tsx
+++ b/src/admin/pages/site/property-controls/MediaLibraryControl.tsx
@@ -32,6 +32,7 @@ import { VideoSolidIcon } from 'pixel-art-icons/icons/video-solid'
 import { MediaPickerField } from '@admin/pages/media/components/MediaPickerField'
 import { MediaViewerWindow } from '@admin/pages/media/components/MediaViewerWindow/MediaViewerWindow'
 import { useStandaloneMediaEditor } from '@admin/pages/media/hooks/useStandaloneMediaEditor'
+import { primeCmsMediaAssetCache } from '@admin/pages/media/hooks/useCmsMediaAssetByPath'
 import styles from './controls.module.css'
 import { getErrorMessage } from '@core/utils/errorMessage'
 
@@ -172,6 +173,7 @@ export function MediaLibraryControl({
   function handlePickFromModal(asset: CmsMediaAsset) {
     // Keep the local asset cache up to date so the "currently picked"
     // preview can render the right thumb without re-fetching.
+    primeCmsMediaAssetCache(asset)
     setCmsAssets((current) => {
       if (current.some((a) => a.id === asset.id)) return current
       return [asset, ...current]
diff --git a/tests/e2e/background-image-smoke.e2e.ts b/tests/e2e/background-image-smoke.e2e.ts
new file mode 100644
index 000000000..dc53efcd6
--- /dev/null
+++ b/tests/e2e/background-image-smoke.e2e.ts
@@ -0,0 +1,279 @@
+import { expect, test, type Locator, type Page } from '@playwright/test'
+import { mkdir } from 'node:fs/promises'
+import sharp from 'sharp'
+import {
+  ANONYMOUS_STATE,
+  PUBLIC_BASE_URL,
+  canvasFrame,
+  createPage,
+  insertModuleViaPicker,
+  login,
+  openSiteEditor,
+  openSitePanel,
+  publishDraft,
+  saveDraft,
+  setPropValue,
+} from './helpers'
+
+test.describe('background image smoke', () => {
+  test.use({ storageState: ANONYMOUS_STATE })
+
+  test('uses optimized media variants for authored background images in editor and public CSS', async ({
+    page,
+    browser,
+  }) => {
+    const suffix = Date.now().toString(36)
+    const pageName = `Background smoke ${suffix}`
+    const slug = `background-smoke-${suffix}`
+    const className = `e2e-bg-${suffix}`
+    const label = `Background image smoke ${suffix}`
+    const filename = `background-smoke-${suffix}.png`
+    const proofDir = `.tmp/e2e-background-image-smoke/${suffix}`
+    await mkdir(proofDir, { recursive: true })
+
+    await login(page)
+    await openSiteEditor(page)
+    await page.screenshot({ path: `${proofDir}/01-editor-start.png`, fullPage: true })
+
+    await createPage(page, pageName, slug)
+    await page.getByRole('treeitem', { name: `Open page ${pageName}` }).click()
+
+    await insertModuleViaPicker(page, 'base.button')
+    await setPropValue(page, 'label', label)
+    const canvasButton = canvasFrame(page).getByRole('button', { name: label })
+    await expect(canvasButton).toBeVisible()
+
+    await page.getByTestId('class-picker-input').fill(className)
+    await page.getByTestId('class-picker-submit').click()
+    await expect(page.getByTestId(`class-chip-${className}`)).toBeVisible()
+
+    const styleSearch = page.getByLabel('Search class style properties to add')
+    await styleSearch.fill('background image')
+    await page.getByRole('button', { name: 'Background image from media library' }).click()
+    await page.getByRole('button', { name: 'Browse image library' }).click()
+
+    const picker = page.getByTestId('media-picker-modal')
+    await expect(picker).toBeVisible()
+    await picker
+      .locator('input[type="file"]')
+      .setInputFiles({
+        name: filename,
+        mimeType: 'image/png',
+        buffer: await largePng(),
+      })
+    await picker.getByRole('button', { name: `Open ${filename}` }).click()
+    await picker.getByRole('button', { name: 'Use selected' }).click()
+    await expect(picker).toBeHidden()
+
+    await setClassTextProperty(page, styleSearch, 'backgroundSize', 'background size', 'cover')
+    await setClassTextProperty(page, styleSearch, 'backgroundPosition', 'background position', 'center')
+
+    const editorCss = await expectOptimizedCanvasClassCss(page, className)
+    expect(editorCss).not.toMatch(/background-image:\s*url\("[^"]+\.png"\)/)
+    const editorBackground = await expectOptimizedBackground(canvasButton)
+    expect(editorBackground).not.toContain('.png')
+    await page.screenshot({ path: `${proofDir}/02-editor-background.png`, fullPage: true })
+
+    await saveDraft(page)
+    await page.reload()
+    await openSiteEditor(page)
+    await openSitePanel(page)
+    const pageItem = page.getByRole('treeitem', { name: `Open page ${pageName}` })
+    await pageItem.click()
+    await expect(pageItem).toHaveAttribute('aria-selected', 'true')
+    const reloadedButton = canvasFrame(page).getByRole('button', { name: label })
+    await expect(reloadedButton).toBeVisible()
+    const mediaSummary = await mediaVariantSummary(page)
+    expect(mediaSummary).toContainEqual(
+      expect.objectContaining({
+        filename,
+        publicPath: expect.stringMatching(/^\/uploads\/.*\.png$/),
+        variantCount: expect.any(Number),
+      }),
+    )
+    expect(mediaSummary.find((asset) => asset.filename === filename)?.variantCount).toBeGreaterThan(0)
+    const reloadedCss = await observedOptimizedCanvasClassCss(page, className)
+    expect.soft(
+      reloadedCss,
+      'persisted canvas class CSS should use image-set candidates after reload',
+    ).toMatch(/background-image:\s*image-set\(.*\.webp/i)
+    expect.soft(
+      reloadedCss,
+      'persisted canvas class CSS should not keep the original PNG declaration',
+    ).not.toMatch(/background-image:\s*url\(["'][^"']+\.png["']\)/)
+    const reloadedBackground = await observedOptimizedBackground(reloadedButton)
+    expect.soft(
+      reloadedBackground,
+      'persisted canvas computed background should use optimized image-set candidates after reload',
+    ).toMatch(/image-set\(.*\.webp/i)
+    await page.screenshot({ path: `${proofDir}/03-editor-reload.png`, fullPage: true })
+
+    await publishDraft(page)
+    await page.screenshot({ path: `${proofDir}/04-publish-feedback.png`, fullPage: true })
+
+    const context = await browser.newContext()
+    const visitor = await context.newPage()
+    const uploadResponses: string[] = []
+    visitor.on('response', (response) => {
+      const url = new URL(response.url())
+      if (url.pathname.startsWith('/uploads/')) uploadResponses.push(url.pathname)
+    })
+
+    try {
+      await visitor.goto(`${PUBLIC_BASE_URL}/${slug}`)
+
+      const publishedButton = visitor.getByRole('button', { name: label })
+      await expect(publishedButton).toBeVisible()
+      await expect(publishedButton).toHaveClass(new RegExp(`\\b${className}\\b`))
+      await expectOptimizedBackground(publishedButton)
+      await visitor.screenshot({ path: `${proofDir}/05-public-background.png`, fullPage: true })
+
+      const css = await publicStylesheetText(visitor)
+      expect(css).toContain(`.${className}`)
+      expect(css).toContain('background-image: image-set(')
+      expect(css).toContain('.webp')
+      expect(css).not.toMatch(/background-image:\s*url\("[^"]+\.png"\)/)
+      expect(uploadResponses.some((path) => path.endsWith('.webp'))).toBe(true)
+      expect(uploadResponses.some((path) => path.endsWith('.png'))).toBe(false)
+      await expect(visitor.locator('[data-testid="canvas-root"]')).toHaveCount(0)
+    } finally {
+      await context.close()
+    }
+  })
+})
+
+async function largePng(): Promise<Buffer> {
+  return sharp({
+    create: {
+      width: 1800,
+      height: 1000,
+      channels: 3,
+      background: { r: 36, g: 114, b: 184 },
+    },
+  })
+    .composite([
+      {
+        input: await sharp({
+          create: {
+            width: 720,
+            height: 420,
+            channels: 4,
+            background: { r: 236, g: 196, b: 74, alpha: 0.92 },
+          },
+        }).png().toBuffer(),
+        left: 120,
+        top: 140,
+      },
+    ])
+    .png()
+    .toBuffer()
+}
+
+async function setClassTextProperty(
+  page: Page,
+  styleSearch: Locator,
+  prop: string,
+  query: string,
+  value: string,
+): Promise<void> {
+  await styleSearch.fill(query)
+  const row = page.getByTestId(`css-property-row-${prop}`)
+  await expect(row).toBeVisible()
+  const input = row.locator(`#ctrl-${prop}`)
+  await input.fill(value)
+  await input.blur()
+}
+
+async function expectOptimizedBackground(locator: Locator): Promise<string> {
+  await expect
+    .poll(
+      async () => locator.evaluate((el) => getComputedStyle(el).backgroundImage),
+      { timeout: 20_000 },
+    )
+    .toMatch(/image-set\(.*\.webp/i)
+  return locator.evaluate((el) => getComputedStyle(el).backgroundImage)
+}
+
+async function expectOptimizedCanvasClassCss(page: Page, className: string): Promise<string> {
+  await expect
+    .poll(
+      async () => classCssSnippet(await canvasClassCss(page), className),
+      { timeout: 20_000 },
+    )
+    .toMatch(/background-image:\s*image-set\(.*\.webp/i)
+  return classCssSnippet(await canvasClassCss(page), className)
+}
+
+async function observedOptimizedCanvasClassCss(page: Page, className: string): Promise<string> {
+  try {
+    return await expectOptimizedCanvasClassCss(page, className)
+  } catch {
+    return classCssSnippet(await canvasClassCss(page), className)
+  }
+}
+
+async function observedOptimizedBackground(locator: Locator): Promise<string> {
+  try {
+    return await expectOptimizedBackground(locator)
+  } catch {
+    return locator.evaluate((el) => getComputedStyle(el).backgroundImage)
+  }
+}
+
+async function canvasClassCss(page: Page): Promise<string> {
+  return await canvasFrame(page).locator('style#mc-classes').textContent() ?? ''
+}
+
+function classCssSnippet(css: string, className: string): string {
+  const index = css.indexOf(`.${className}`)
+  if (index === -1) return css.slice(0, 2_000)
+  return css.slice(index, index + 2_000)
+}
+
+async function mediaVariantSummary(page: Page): Promise<Array<{
+  filename: string
+  publicPath: string
+  variantCount: number
+}>> {
+  return page.evaluate(async () => {
+    const response = await fetch('/admin/api/cms/media', { credentials: 'include' })
+    if (!response.ok) throw new Error(`Media list failed: ${response.status}`)
+    const json: unknown = await response.json()
+    const assets = getField(json, 'assets')
+    if (!Array.isArray(assets)) return []
+    return assets.map((asset) => {
+      const variants = getField(asset, 'variants')
+      return {
+        filename: stringField(asset, 'filename'),
+        publicPath: stringField(asset, 'publicPath'),
+        variantCount: Array.isArray(variants) ? variants.length : 0,
+      }
+    })
+
+    function getField(value: unknown, key: string): unknown {
+      if (typeof value !== 'object' || value === null) return undefined
+      return Object.getOwnPropertyDescriptor(value, key)?.value
+    }
+
+    function stringField(value: unknown, key: string): string {
+      const field = getField(value, key)
+      return typeof field === 'string' ? field : ''
+    }
+  })
+}
+
+async function publicStylesheetText(page: Page): Promise<string> {
+  const hrefs = await page.locator('link[rel="stylesheet"]').evaluateAll((nodes) =>
+    nodes
+      .map((node) => node instanceof HTMLLinkElement ? node.href : '')
+      .filter((href) => href.includes('/_instatic/css/')),
+  )
+  const bodies = await page.evaluate(async (urls) => {
+    return Promise.all(urls.map(async (url) => {
+      const response = await fetch(url)
+      if (!response.ok) throw new Error(`CSS fetch failed: ${response.status} ${url}`)
+      return response.text()
+    }))
+  }, hrefs)
+  return bodies.join('\n')
+}