@wocart/theme 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to `@wocart/theme` are recorded here. The package follows
 major version, and an export is marked `@deprecated` for at least one minor
 release before a major removes it.
 
+## 1.4.0 — 2026-10-18
+
+### Added
+
+- `@wocart/theme/image-service`: `mediaImageService(() => mediaDomain)`, an
+  Astro image service that resizes media-domain images with Cloudflare Image
+  Resizing on the media domain itself, so a storefront on Cloudflare and one
+  on Vercel get the same URLs and edge cache. Other images are served as they
+  are; the domain is read per image, so one build serves every store.
+  `mediaImageParams` maps an Astro transform to the resizing options (Astro's
+  `fit` in Cloudflare's words).
+
+### Changed
+
+- The `@wocart/storefront` peer range is now `^1.14.0` (`mediaImageUrl`).
+
 ## 1.3.0 — 2026-10-17
 
 ### Added

package/README.md

@@ -37,6 +37,7 @@ Node 22.12 or newer.
 | `@wocart/theme` | definitions, validation, page documents, resolution, the manifest, languages and messages — framework-neutral |
 | `@wocart/theme/astro` | `createReadCache` and the `RendererIssue` type |
 | `@wocart/theme/astro/InstanceView.astro` | the reference renderer component |
+| `@wocart/theme/image-service` | `mediaImageService` — an Astro image service that resizes media-domain images on the media domain (any storefront host) |
 
 ## Use
 
@@ -444,6 +445,34 @@ migration engine, by design; what follows is the whole policy:
   stick to semver so the manifest validator stays quiet and future tooling can
   reason about upgrades.
 
+## Images
+
+`@wocart/theme/image-service` resizes every `<Image>` of a media-domain image
+with Cloudflare Image Resizing, on the media domain itself
+(`https://<media>/cdn-cgi/image/…`). The media domain is a Cloudflare zone
+wherever the storefront runs, so a storefront on Cloudflare and one on Vercel
+share the same URLs and edge cache. Any other image is served as it is; with no
+media domain, every image passes through.
+
+The domain is read on each image, not at build — one build serves every store.
+Bind it once:
+
+```ts
+// src/image-service.ts
+import { MEDIA_DOMAIN } from "astro:env/server";
+import { mediaImageService } from "@wocart/theme/image-service";
+export default mediaImageService(() => MEDIA_DOMAIN);
+```
+
+```js
+// astro.config.mjs
+image: { service: { entrypoint: "./src/image-service.ts" } },
+// @astrojs/cloudflare: imageService: "custom"   ·   @astrojs/vercel: leave imageService off
+```
+
+The media domain's zone needs Image Transformations on (Images →
+Transformations; included in the Free plan).
+
 ## Testing your theme
 
 A theme proves it honors the contract with four checks in its own test suite:

package/dist/image-service.d.ts

@@ -0,0 +1,39 @@
+/**
+ * An Astro image service for Wocart storefronts: every `<Image>` and
+ * `getImage()` of a media-domain image is resized by Cloudflare Image Resizing
+ * on the media domain itself (`https://<media>/cdn-cgi/image/…/<path>`).
+ *
+ * The media domain is always a Cloudflare zone, wherever the storefront runs,
+ * so a storefront on Cloudflare and one on Vercel get the same URLs, the same
+ * edge cache and no second image bill. Any other image — another host, a file
+ * imported into the theme — is served as it is. Without a media domain (local
+ * development, a store without one) every image passes through unchanged.
+ *
+ * The domain is read per call, not at build: one theme build serves every
+ * store. Bind it once, in the theme, to wherever the store's media domain
+ * lives:
+ *
+ * ```ts
+ * // src/image-service.ts
+ * import { MEDIA_DOMAIN } from "astro:env/server";
+ * import { mediaImageService } from "@wocart/theme/image-service";
+ * export default mediaImageService(() => MEDIA_DOMAIN);
+ * ```
+ *
+ * ```js
+ * // astro.config.mjs — and the adapter keeps it:
+ * //   @astrojs/cloudflare: imageService: "custom";  @astrojs/vercel: no imageService
+ * image: { service: { entrypoint: "./src/image-service.ts" } },
+ * ```
+ */
+import type { ExternalImageService, ImageTransform } from "astro";
+import { type MediaImageParams } from "@wocart/storefront";
+/** The Cloudflare resizing options an Astro image transform asks for. */
+export declare function mediaImageParams(options: ImageTransform): MediaImageParams;
+/**
+ * The image service, bound to the store's media domain.
+ *
+ * @param mediaDomain - Read on every image (e.g. `() => MEDIA_DOMAIN`): the
+ *   store's media domain, or `undefined` to pass every image through.
+ */
+export declare function mediaImageService(mediaDomain: () => string | undefined): ExternalImageService;

package/dist/image-service.js

@@ -0,0 +1,73 @@
+/**
+ * An Astro image service for Wocart storefronts: every `<Image>` and
+ * `getImage()` of a media-domain image is resized by Cloudflare Image Resizing
+ * on the media domain itself (`https://<media>/cdn-cgi/image/…/<path>`).
+ *
+ * The media domain is always a Cloudflare zone, wherever the storefront runs,
+ * so a storefront on Cloudflare and one on Vercel get the same URLs, the same
+ * edge cache and no second image bill. Any other image — another host, a file
+ * imported into the theme — is served as it is. Without a media domain (local
+ * development, a store without one) every image passes through unchanged.
+ *
+ * The domain is read per call, not at build: one theme build serves every
+ * store. Bind it once, in the theme, to wherever the store's media domain
+ * lives:
+ *
+ * ```ts
+ * // src/image-service.ts
+ * import { MEDIA_DOMAIN } from "astro:env/server";
+ * import { mediaImageService } from "@wocart/theme/image-service";
+ * export default mediaImageService(() => MEDIA_DOMAIN);
+ * ```
+ *
+ * ```js
+ * // astro.config.mjs — and the adapter keeps it:
+ * //   @astrojs/cloudflare: imageService: "custom";  @astrojs/vercel: no imageService
+ * image: { service: { entrypoint: "./src/image-service.ts" } },
+ * ```
+ */
+import { baseService } from "astro/assets";
+import { mediaImageUrl } from "@wocart/storefront";
+/** Astro's `fit` (CSS object-fit) in Cloudflare's words; a value Cloudflare also knows passes as it is. */
+const CLOUDFLARE_FIT = {
+    cover: "cover",
+    contain: "contain",
+    fill: "squeeze",
+    "scale-down": "scale-down",
+    crop: "crop",
+    pad: "pad",
+    squeeze: "squeeze",
+};
+/** The Cloudflare resizing options an Astro image transform asks for. */
+export function mediaImageParams(options) {
+    const params = {};
+    if (options.width)
+        params.width = options.width;
+    if (options.height)
+        params.height = options.height;
+    if (options.format)
+        params.format = options.format;
+    if (typeof options.quality === "number")
+        params.quality = options.quality;
+    const fit = options.fit ? CLOUDFLARE_FIT[options.fit] : undefined;
+    if (fit)
+        params.fit = fit;
+    return params;
+}
+/**
+ * The image service, bound to the store's media domain.
+ *
+ * @param mediaDomain - Read on every image (e.g. `() => MEDIA_DOMAIN`): the
+ *   store's media domain, or `undefined` to pass every image through.
+ */
+export function mediaImageService(mediaDomain) {
+    return {
+        ...baseService,
+        getURL(options) {
+            const src = options.src;
+            if (typeof src !== "string")
+                return src.src;
+            return mediaImageUrl(src, mediaImageParams(options), mediaDomain()) ?? src;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",
@@ -38,6 +38,10 @@
       "default": "./dist/astro/index.js"
     },
     "./astro/InstanceView.astro": "./dist/astro/InstanceView.astro",
+    "./image-service": {
+      "types": "./dist/image-service.d.ts",
+      "default": "./dist/image-service.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -63,7 +67,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@wocart/storefront": "^1.0.0",
+    "@wocart/storefront": "^1.14.0",
     "astro": "^7.0.0"
   },
   "peerDependenciesMeta": {