@wocart/storefront 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ follows [semantic versioning](https://semver.org/): breaking changes ship only
 in a new major version, and an export is marked `@deprecated` for at least one
 minor release before a major removes it.
 
+## 1.16.0 — 2026-10-18
+
+### Changed
+
+- `pageData.get(surface)` reads the document the store composed for the
+  client's theme: a client created with `theme` sends it
+  (`/store/page-documents/{surface}?theme=`), so a store keeps one document
+  per theme and switching themes never shows another theme's page. Without
+  `theme`, the server answers the most recently saved document for the
+  surface, as before.
+
+## 1.15.0 — 2026-10-18
+
+### Added
+
+- `mediaUrl(key, mediaDomain)`: the public URL of a stored media key — what a
+  theme's `image` field holds (`{ key: "products/…" }`) — on the store's media
+  domain; `null` with no media domain or a key that cannot name an object. The
+  key is the image's identity; the URL is derived at render, never stored.
+- **Preview** (`@wocart/storefront/server`): `readPreviewRequest`,
+  `verifyPreviewToken`, `previewResponseHeaders` and `previewConfig`, with
+  `PreviewClaims` and `PreviewDraft`. A storefront opens a preview (`GET`
+  with the token in the query) and renders a draft (`POST` JSON from its own
+  origin) only for an Ed25519-signed token (`alg: "EdDSA"`) made for its
+  origin and theme, living at most an hour; the answer can be framed by the
+  token's editor only and is never stored or indexed. Without a public key,
+  preview is off.
+
 ## 1.14.0 — 2026-10-18
 
 ### Added

package/README.md

@@ -68,7 +68,7 @@ if (result.success) {
 | Import | Runs in | What it holds |
 | --- | --- | --- |
 | `@wocart/storefront` | browser and server | read-model types and schemas, reference data (58 wilayas, 1,551 communes), money and image helpers, the basket and OTP state machines, language routing, Meta pixel payloads |
-| `@wocart/storefront/server` | server only | `createStoreClient`, `StoreClient`, `ClientResult`, `StorefrontError` — the API key lives here |
+| `@wocart/storefront/server` | server only | `createStoreClient`, `StoreClient`, `ClientResult`, `StorefrontError` — the API key lives here — and the preview checks (`readPreviewRequest`, `verifyPreviewToken`, `previewResponseHeaders`, `previewConfig`) |
 | `@wocart/storefront/astro` | server only | `createStorefrontRoutes`, `createProxyEndpoint`, `placeOrderInput`, `executePlaceOrder`, `collectForwardedHeaders`, `runFormAction` |
 
 Browser code never receives the key. It calls your own same-origin routes

package/USAGE.md

@@ -215,6 +215,7 @@ server directly.
 | --- | --- |
 | `formatMoney`, `optimizeImage`, `generateSrcSet` | Money text and image URLs |
 | `mediaImageUrl` | The Cloudflare resizing URL of a media-domain image, served by the media domain itself (any storefront host); `null` for any other image — the builder behind every image helper and `@wocart/theme/image-service` |
+| `mediaUrl(key, mediaDomain)` | The public URL of a stored media key — what a theme's `image` field holds (`{ key: "products/…" }`): `mediaUrl(image.key, MEDIA_DOMAIN)`; `null` with no media domain or a key that cannot name an object. The key is the identity; the URL is derived at render |
 | `createImageHelpers(mediaDomain)`, `getCardImage`, `getGalleryImage`, `getThumbnailImage`, `getHeroImage`, `getCategoryImage`, `getLogoImage` | The bound image toolkit (`IMAGE_SIZES` holds the presets) |
 | `WILAYAS`, `ALGERIA_COMMUNES`, `communesForWilaya` | Reference data: 58 wilayas, 1,551 communes, one wilaya's rows |
 | `normalizeAlgerianPhone`, `toLocalAlgerianMobile` | The one Algerian phone rule (accept/format) |
@@ -883,8 +884,9 @@ Do not invent tracking events from a landing-page slug.
 const saved = await store.pageData.get("home");   // null = never saved / failed
 ~~~
 
-One document per surface ("home" today), owned by the store and written by
-the platform's page editor — a storefront never writes it. `null` means the store has never saved one (or the read
+One document per theme and surface ("home" today), owned by the store and
+written by the platform's page editor — a storefront never writes it. A
+client created with `theme` reads the document composed for that theme. `null` means the store has never saved one (or the read
 failed): render the theme's shipped default document. The payload is
 **transport-checked only** (`version`, `surface`, `sections`) and fetched
 fresh on every call, so a save reaches the next render.
@@ -1606,6 +1608,37 @@ Three rules come with it, and a theme must not re-implement them:
 visible rather than silently swallowed. The cap and the token list are the
 same ones the dashboard enforces.
 
+## Previewing a draft for an editor
+
+A visual editor shows a merchant's unsaved changes on the store's own
+storefront. It frames the theme's preview route with a short-lived token its
+server signed — `GET /wocart-preview?token=…&surface=home&locale=fr` — and the
+framed page then re-renders each draft the editor sends it by posting the
+draft back to the same route as JSON. The storefront checks the token with a
+public key it was deployed with, renders what it was sent, and stores nothing.
+A draft is never a form post: Astro's `checkOrigin` (on by default) refuses
+cross-site forms, and the preview needs no exception to it. Everything lives in
+`@wocart/storefront/server`:
+
+| Export | Use it for |
+| --- | --- |
+| `readPreviewRequest(request, { publicKey, theme })` | Read a preview request: the `GET` that opens it (`token`, `surface`, optional `locale` and `path` in the query; the draft names the page and nothing else, so it renders as saved) or the `POST` of a draft (JSON `{ token, draft }`, from this storefront's own origin only, 1 MB at most). `{ ok: true, claims, draft, token }` only when the token verifies for this storefront (its origin is the token's `aud`) and this theme; otherwise a status to answer — 404 without a key, 405, 403, 413, 415, 400 |
+| `verifyPreviewToken(token, { publicKey, audience, theme })` | The token check alone: a compact JWS signed with Ed25519 (`alg: "EdDSA"`), claims `aud`, `theme`, `editor` (an origin), `iat`/`exp` at most an hour apart |
+| `previewResponseHeaders(claims)` | The headers a preview answers with: `frame-ancestors` the token's editor only, `Cache-Control: private, no-store`, `noindex`, and a referrer kept on the storefront (the address holds the token) |
+| `previewConfig(config, draft)` | The store config the preview renders: the draft's theme settings and text edits over the saved ones, and no Meta pixel — a preview is not a visit |
+
+```ts
+// src/middleware.ts — the one place a request's store context is built
+const preview = await readPreviewRequest(context.request, { publicKey: WOCART_PREVIEW_KEY, theme: THEME_KEY });
+if (!preview.ok) return new Response(null, { status: preview.status });
+context.locals.store = buildStoreContext(previewConfig(await client.config.get(), preview.draft), preview.draft.locale);
+```
+
+The public key is a deployment setting (a JWK); without it preview is off.
+A storefront can verify tokens but never make one: the private key stays with
+the editor's server. The page side — marking sections and talking to the
+editor — is `@wocart/theme`'s (its README, "Preview").
+
 ## A recommended theme structure
 
 Keep the theme visually expressive while making the platform boundary obvious:

package/dist/client/page-data.d.ts

@@ -2,8 +2,10 @@
  * Page Data Namespace — the store's saved composition document.
  *
  * Deep module: hides URL construction and transport behind one call. The
- * document belongs to the store (one per surface — "home" today) and is
- * written by the platform's editor; this namespace is the theme's read side.
+ * document belongs to the store (one per theme and surface — "home" today)
+ * and is written by the platform's editor; this namespace is the theme's
+ * read side. A client created with `theme` reads that theme's document;
+ * without it, the server answers the most recently saved one for the surface.
  *
  * Transport semantics (NOT the document contract): the payload is validated
  * as `{ version, surface, sections }` and returns `null` for "no saved

package/dist/client/page-data.js

@@ -2,8 +2,10 @@
  * Page Data Namespace — the store's saved composition document.
  *
  * Deep module: hides URL construction and transport behind one call. The
- * document belongs to the store (one per surface — "home" today) and is
- * written by the platform's editor; this namespace is the theme's read side.
+ * document belongs to the store (one per theme and surface — "home" today)
+ * and is written by the platform's editor; this namespace is the theme's
+ * read side. A client created with `theme` reads that theme's document;
+ * without it, the server answers the most recently saved one for the surface.
  *
  * Transport semantics (NOT the document contract): the payload is validated
  * as `{ version, surface, sections }` and returns `null` for "no saved
@@ -24,7 +26,9 @@ export function createPageDataNamespace(core) {
     return {
         async get(surface) {
             try {
-                const document = await core.get(`/store/page-documents/${encodeURIComponent(surface)}`, PageDocumentPayloadSchema.nullable(), { operation: STOREFRONT_OPERATIONS.pageDataGet });
+                const path = `/store/page-documents/${encodeURIComponent(surface)}`;
+                const theme = core.config.theme;
+                const document = await core.get(theme === undefined ? path : `${path}?${new URLSearchParams({ theme })}`, PageDocumentPayloadSchema.nullable(), { operation: STOREFRONT_OPERATIONS.pageDataGet });
                 return document ?? null;
             }
             catch (error) {

package/dist/domain.d.ts

@@ -12,7 +12,8 @@ export interface StoreScope {
      * The key of the theme this client renders (`defineTheme({ key })` in
      * `@wocart/theme`). The store's edits to that theme's text arrive as
      * `StoreConfig.contentOverrides`; without it there are none, because edits
-     * belong to the theme that declares their keys. The server owns the key
+     * belong to the theme that declares their keys. `pageData.get` reads the
+     * documents the store composed for that theme. The server owns the key
      * format and refuses a malformed one.
      */
     readonly theme?: string;

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  */
 export { formatMoney } from "./utils/money.js";
 export type { MoneyFormatOptions } from "./utils/money.js";
-export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, mediaImageUrl, } from "./utils/image.js";
+export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, mediaImageUrl, mediaUrl, } from "./utils/image.js";
 export type { ImageHelpers, ImageResizeOptions, MediaImageParams } from "./utils/image.js";
 export { productImageSource } from "./utils/product-image.js";
 export type { ProductImageSourceInput } from "./utils/product-image.js";

package/dist/index.js

@@ -10,7 +10,7 @@
  * Internal modules stay reachable only through their intentional entry points.
  */
 export { formatMoney } from "./utils/money.js";
-export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, mediaImageUrl, } from "./utils/image.js";
+export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, mediaImageUrl, mediaUrl, } from "./utils/image.js";
 export { productImageSource } from "./utils/product-image.js";
 export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";
 export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";

package/dist/preview.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Preview: rendering a draft on the store's own storefront, for an editor.
+ *
+ * An editor (a page on another origin) frames the storefront's preview route
+ * with a short-lived token its server signed; the framed page then re-renders
+ * each draft the editor sends it by posting the draft to the same route. The
+ * storefront verifies the token with a public key it was deployed with — it
+ * can check tokens, never make them — renders what it was sent, and answers so
+ * the response is framed only by that editor and never cached or indexed. The
+ * draft is never stored by the storefront.
+ *
+ * The token is a compact JWS signed with Ed25519 (`alg: "EdDSA"`), claims:
+ * `aud` the storefront origin, `theme` the previewed theme's key, `editor` the
+ * editor's origin, `iat`/`exp` (at most an hour apart), optional `sub`/`jti`.
+ */
+import type { StoreConfig } from "./types.js";
+/** What a verified token says. */
+export interface PreviewClaims {
+    /** The storefront origin the token was made for. */
+    aud: string;
+    /** The key of the theme it previews. */
+    theme: string;
+    /** The editor's origin: the only page that may frame the preview and send it drafts. */
+    editor: string;
+    iat: number;
+    exp: number;
+    sub?: string;
+    jti?: string;
+}
+export type PreviewTokenRefusal = "malformed" | "unsupported-algorithm" | "invalid-key" | "bad-signature" | "invalid-claims" | "expired" | "not-yet-valid" | "too-long-lived" | "wrong-audience" | "wrong-theme";
+export type PreviewTokenCheck = {
+    ok: true;
+    claims: PreviewClaims;
+} | {
+    ok: false;
+    reason: PreviewTokenRefusal;
+};
+export interface PreviewTokenOptions {
+    /** The Ed25519 public key, as a JWK (`{"kty":"OKP","crv":"Ed25519","x":"…"}`, a JSON string or object). */
+    publicKey: string | JsonWebKey;
+    /** This storefront's origin (`https://store.example`). */
+    audience: string;
+    /** This theme's key. */
+    theme: string;
+    /** Seconds since the epoch; defaults to now. */
+    now?: number;
+}
+/** Check a preview token's signature and claims against this storefront and theme. */
+export declare function verifyPreviewToken(token: string, options: PreviewTokenOptions): Promise<PreviewTokenCheck>;
+/**
+ * What an editor sends to be previewed. The storefront renders it as if it
+ * were saved — `document` for `surface`, `settings` for the theme settings,
+ * `content` for the text edits of the languages it names — and stores none of
+ * it. Each part is optional: what is absent renders as saved.
+ */
+export interface PreviewDraft {
+    /** The surface to render (`home`, `product`). */
+    surface: string;
+    /** The language to render in; absent: the store's primary. */
+    locale?: string;
+    /** For a template, the resource route it is previewed for (`/products/robe-kabyle`). */
+    path?: string;
+    /** The draft page document; the theme reads it with `@wocart/theme`'s `parsePageData`. */
+    document?: Record<string, unknown>;
+    /** The draft theme settings, replacing the saved ones. */
+    settings?: Record<string, unknown>;
+    /** The draft text edits, per language, replacing the saved edits of those languages. */
+    content?: Record<string, Record<string, string>>;
+}
+export type PreviewRequest = {
+    ok: true;
+    claims: PreviewClaims;
+    draft: PreviewDraft;
+    token: string;
+} | {
+    ok: false;
+    status: 400 | 403 | 404 | 405 | 413 | 415;
+    reason: string;
+};
+export interface PreviewRequestOptions {
+    /** The deployment's preview public key (a JWK); absent: preview is off and every request answers 404. */
+    publicKey?: string | JsonWebKey | undefined;
+    /** This theme's key. */
+    theme: string;
+    /** The largest body accepted, in bytes; 1 MB by default. */
+    maxBytes?: number;
+    /** Seconds since the epoch; defaults to now. */
+    now?: number;
+}
+/**
+ * Read a preview request. Two kinds, both refused — and nothing rendered —
+ * unless the token verifies for this storefront and theme:
+ *
+ * - `GET ?token=…&surface=…[&locale=…][&path=…]`: the editor frames the
+ *   preview. The draft names what to show and carries nothing else, so the
+ *   page renders as saved until the editor sends a draft.
+ * - `POST` JSON `{ token, draft }` from this storefront's own origin: the
+ *   framed page re-rendering a draft. A cross-site form can never post one.
+ */
+export declare function readPreviewRequest(request: Request, options: PreviewRequestOptions): Promise<PreviewRequest>;
+/**
+ * The headers every preview response carries: framed only by the token's
+ * editor, never stored by a browser or a CDN, never indexed, and its address
+ * — which holds the token — never sent to another origin.
+ */
+export declare function previewResponseHeaders(claims: PreviewClaims): Record<string, string>;
+/**
+ * The store config as the preview renders it: the draft's settings and text
+ * edits over the saved ones, and no tracking — a preview is not a visit.
+ */
+export declare function previewConfig(config: StoreConfig, draft: PreviewDraft): StoreConfig;

package/dist/preview.js

@@ -0,0 +1,249 @@
+/** Clock skew tolerated between the editor's server and the storefront. */
+const CLOCK_SKEW_SECONDS = 30;
+/** The longest a preview token may live. */
+const MAX_LIFETIME_SECONDS = 60 * 60;
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+function base64UrlBytes(value) {
+    if (!/^[A-Za-z0-9_-]*$/.test(value))
+        return null;
+    try {
+        const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (value.length % 4)) % 4));
+        return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    }
+    catch {
+        return null;
+    }
+}
+function base64UrlJson(value) {
+    const bytes = base64UrlBytes(value);
+    if (bytes === null)
+        return null;
+    try {
+        const parsed = JSON.parse(decoder.decode(bytes));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+const isOrigin = (value) => {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const url = new URL(value);
+        return (url.protocol === "https:" || url.hostname === "localhost" || url.hostname === "127.0.0.1") && url.origin === value;
+    }
+    catch {
+        return false;
+    }
+};
+async function importKey(publicKey) {
+    try {
+        const jwk = typeof publicKey === "string" ? JSON.parse(publicKey) : publicKey;
+        if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.x !== "string" || jwk.d !== undefined)
+            return null;
+        return await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, { name: "Ed25519" }, false, ["verify"]);
+    }
+    catch {
+        return null;
+    }
+}
+/** Check a preview token's signature and claims against this storefront and theme. */
+export async function verifyPreviewToken(token, options) {
+    const parts = typeof token === "string" ? token.split(".") : [];
+    if (parts.length !== 3)
+        return { ok: false, reason: "malformed" };
+    const [headerPart, payloadPart, signaturePart] = parts;
+    const header = base64UrlJson(headerPart);
+    const payload = base64UrlJson(payloadPart);
+    const signature = base64UrlBytes(signaturePart);
+    if (header === null || payload === null || signature === null)
+        return { ok: false, reason: "malformed" };
+    if (header.alg !== "EdDSA" || header.crit !== undefined)
+        return { ok: false, reason: "unsupported-algorithm" };
+    const key = await importKey(options.publicKey);
+    if (key === null)
+        return { ok: false, reason: "invalid-key" };
+    const signed = encoder.encode(`${headerPart}.${payloadPart}`);
+    let valid = false;
+    try {
+        valid = await crypto.subtle.verify({ name: "Ed25519" }, key, signature, signed);
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid)
+        return { ok: false, reason: "bad-signature" };
+    const { aud, theme, editor, iat, exp, sub, jti } = payload;
+    if (typeof aud !== "string" ||
+        typeof theme !== "string" ||
+        !isOrigin(editor) ||
+        typeof iat !== "number" ||
+        typeof exp !== "number" ||
+        !Number.isFinite(iat) ||
+        !Number.isFinite(exp) ||
+        (sub !== undefined && typeof sub !== "string") ||
+        (jti !== undefined && typeof jti !== "string")) {
+        return { ok: false, reason: "invalid-claims" };
+    }
+    const now = options.now ?? Math.floor(Date.now() / 1000);
+    if (exp <= now - CLOCK_SKEW_SECONDS)
+        return { ok: false, reason: "expired" };
+    if (iat > now + CLOCK_SKEW_SECONDS)
+        return { ok: false, reason: "not-yet-valid" };
+    if (exp - iat > MAX_LIFETIME_SECONDS)
+        return { ok: false, reason: "too-long-lived" };
+    if (aud !== options.audience)
+        return { ok: false, reason: "wrong-audience" };
+    if (theme !== options.theme)
+        return { ok: false, reason: "wrong-theme" };
+    const claims = { aud, theme, editor, iat, exp };
+    if (sub !== undefined)
+        claims.sub = sub;
+    if (jti !== undefined)
+        claims.jti = jti;
+    return { ok: true, claims };
+}
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+const SURFACE_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,63}$/;
+const LOCALE_PATTERN = /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|\d{3}))?$/;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function parseDraft(value) {
+    if (!isRecord(value) || typeof value.surface !== "string" || !SURFACE_PATTERN.test(value.surface))
+        return null;
+    const draft = { surface: value.surface };
+    if (value.locale !== undefined) {
+        if (typeof value.locale !== "string" || !LOCALE_PATTERN.test(value.locale))
+            return null;
+        draft.locale = value.locale;
+    }
+    if (value.path !== undefined) {
+        if (typeof value.path !== "string" || !value.path.startsWith("/") || value.path.startsWith("//") || value.path.length > 2048 || /[\s\\]/.test(value.path))
+            return null;
+        draft.path = value.path;
+    }
+    if (value.document !== undefined) {
+        if (!isRecord(value.document))
+            return null;
+        draft.document = value.document;
+    }
+    if (value.settings !== undefined) {
+        if (!isRecord(value.settings))
+            return null;
+        draft.settings = value.settings;
+    }
+    if (value.content !== undefined) {
+        if (!isRecord(value.content))
+            return null;
+        const content = {};
+        for (const [locale, pack] of Object.entries(value.content)) {
+            if (!LOCALE_PATTERN.test(locale) || !isRecord(pack))
+                return null;
+            const texts = {};
+            for (const [key, text] of Object.entries(pack)) {
+                if (typeof text !== "string" || key === "__proto__")
+                    return null;
+                texts[key] = text;
+            }
+            content[locale] = texts;
+        }
+        draft.content = content;
+    }
+    return draft;
+}
+const refuse = (status, reason) => ({ ok: false, status, reason });
+/**
+ * Read a preview request. Two kinds, both refused — and nothing rendered —
+ * unless the token verifies for this storefront and theme:
+ *
+ * - `GET ?token=…&surface=…[&locale=…][&path=…]`: the editor frames the
+ *   preview. The draft names what to show and carries nothing else, so the
+ *   page renders as saved until the editor sends a draft.
+ * - `POST` JSON `{ token, draft }` from this storefront's own origin: the
+ *   framed page re-rendering a draft. A cross-site form can never post one.
+ */
+export async function readPreviewRequest(request, options) {
+    if (options.publicKey === undefined || options.publicKey === "")
+        return refuse(404, "preview is not enabled on this storefront");
+    const url = new URL(request.url);
+    const audience = url.origin;
+    let token;
+    let draftValue;
+    if (request.method === "GET") {
+        token = url.searchParams.get("token");
+        const named = {};
+        for (const key of ["surface", "locale", "path"]) {
+            const value = url.searchParams.get(key);
+            if (value !== null)
+                named[key] = value;
+        }
+        draftValue = named;
+    }
+    else if (request.method === "POST") {
+        if (request.headers.get("Origin") !== audience)
+            return refuse(403, "a draft is posted by the preview page itself");
+        if (!(request.headers.get("Content-Type") ?? "").startsWith("application/json"))
+            return refuse(415, "a draft is posted as JSON");
+        const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+        const declared = Number(request.headers.get("Content-Length") ?? "0");
+        if (Number.isFinite(declared) && declared > maxBytes)
+            return refuse(413, "the draft is too large");
+        const body = await request.text();
+        if (encoder.encode(body).length > maxBytes)
+            return refuse(413, "the draft is too large");
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            return refuse(400, "the body is not JSON");
+        }
+        if (!isRecord(parsed))
+            return refuse(400, "the body is not an object");
+        token = parsed.token;
+        draftValue = parsed.draft;
+    }
+    else {
+        return refuse(405, "a preview is opened with GET and re-rendered with POST");
+    }
+    if (typeof token !== "string")
+        return refuse(403, "a preview carries its token");
+    const verified = await verifyPreviewToken(token, {
+        publicKey: options.publicKey,
+        audience,
+        theme: options.theme,
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    if (!verified.ok)
+        return refuse(403, `the token is refused: ${verified.reason}`);
+    const draft = parseDraft(draftValue);
+    if (draft === null)
+        return refuse(400, "the draft is not a preview draft");
+    return { ok: true, claims: verified.claims, draft, token };
+}
+/**
+ * The headers every preview response carries: framed only by the token's
+ * editor, never stored by a browser or a CDN, never indexed, and its address
+ * — which holds the token — never sent to another origin.
+ */
+export function previewResponseHeaders(claims) {
+    return {
+        "Cache-Control": "private, no-store",
+        "Content-Security-Policy": `frame-ancestors ${claims.editor}`,
+        "X-Robots-Tag": "noindex, nofollow",
+        "Referrer-Policy": "same-origin",
+    };
+}
+/**
+ * The store config as the preview renders it: the draft's settings and text
+ * edits over the saved ones, and no tracking — a preview is not a visit.
+ */
+export function previewConfig(config, draft) {
+    return {
+        ...config,
+        ...(draft.settings === undefined ? {} : { themeSettings: draft.settings }),
+        contentOverrides: { ...config.contentOverrides, ...(draft.content ?? {}) },
+        pixelId: null,
+    };
+}

package/dist/server.d.ts

@@ -2,3 +2,5 @@ export { createStoreClient } from "./client/index.js";
 export type { StoreClient } from "./client/index.js";
 export type { ClientResult } from "./client/core.js";
 export { StorefrontError, isStorefrontError } from "./client/errors.js";
+export { previewConfig, previewResponseHeaders, readPreviewRequest, verifyPreviewToken } from "./preview.js";
+export type { PreviewClaims, PreviewDraft, PreviewRequest, PreviewRequestOptions, PreviewTokenCheck, PreviewTokenOptions, PreviewTokenRefusal, } from "./preview.js";

package/dist/server.js

@@ -1,2 +1,3 @@
 export { createStoreClient } from "./client/index.js";
 export { StorefrontError, isStorefrontError } from "./client/errors.js";
+export { previewConfig, previewResponseHeaders, readPreviewRequest, verifyPreviewToken } from "./preview.js";

package/dist/utils/image.d.ts

@@ -53,6 +53,18 @@ export interface MediaImageParams {
  * @returns `null` when there is no media domain, or the URL is not on it.
  */
 export declare function mediaImageUrl(originalUrl: string, params: MediaImageParams, mediaDomain?: string): string | null;
+/**
+ * The public URL of an object in the store's media bucket, from its key —
+ * what a theme's `image` field stores (`products/3f2a9c.webp`). The key is
+ * the image's identity; the URL depends on where the store serves its media,
+ * so it is derived here, at render, never stored. Pass the result to
+ * `mediaImageUrl` or Astro's `<Image>` to resize it.
+ *
+ * @returns `null` when there is no media domain, or the key cannot name an
+ * object: empty, too long, an empty, `.` or `..` segment (a leading slash
+ * makes an empty one), whitespace, control characters, a backslash, `?` or `#`.
+ */
+export declare function mediaUrl(key: string, mediaDomain?: string): string | null;
 /**
  * Predefined image sizes for common use cases
  */

package/dist/utils/image.js

@@ -43,16 +43,15 @@ export function optimizeImage(originalUrl, options, mediaDomain) {
 export function mediaImageUrl(originalUrl, params, mediaDomain) {
     if (!mediaDomain || !originalUrl)
         return null;
-    let mediaOrigin;
+    const mediaOrigin = mediaOriginOf(mediaDomain);
     let original;
     try {
-        mediaOrigin = new URL(`https://${mediaDomain.replace(/^https?:\/\//, "")}`).origin;
         original = new URL(originalUrl);
     }
     catch {
         return null;
     }
-    if (original.origin !== mediaOrigin)
+    if (mediaOrigin === null || original.origin !== mediaOrigin)
         return null;
     const options = ["onerror=redirect"];
     for (const key of ["width", "height", "format", "quality", "fit"]) {
@@ -63,6 +62,37 @@ export function mediaImageUrl(originalUrl, params, mediaDomain) {
     const imagePath = `${original.pathname.replace(/^\/+/, "")}${original.search}${original.hash}`;
     return `${mediaOrigin}/cdn-cgi/image/${options.join(",")}/${imagePath}`;
 }
+/** The media domain (`media.example.com`, with or without a scheme) as an HTTPS origin, or `null`. */
+function mediaOriginOf(mediaDomain) {
+    try {
+        return new URL(`https://${mediaDomain.replace(/^https?:\/\//, "")}`).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The public URL of an object in the store's media bucket, from its key —
+ * what a theme's `image` field stores (`products/3f2a9c.webp`). The key is
+ * the image's identity; the URL depends on where the store serves its media,
+ * so it is derived here, at render, never stored. Pass the result to
+ * `mediaImageUrl` or Astro's `<Image>` to resize it.
+ *
+ * @returns `null` when there is no media domain, or the key cannot name an
+ * object: empty, too long, an empty, `.` or `..` segment (a leading slash
+ * makes an empty one), whitespace, control characters, a backslash, `?` or `#`.
+ */
+export function mediaUrl(key, mediaDomain) {
+    if (!mediaDomain || typeof key !== "string" || key.length === 0 || key.length > 512)
+        return null;
+    if (/[\s\\?#\u0000-\u001f\u007f]/.test(key))
+        return null;
+    const segments = key.split("/");
+    if (segments.some((segment) => segment === "" || segment === "." || segment === ".."))
+        return null;
+    const origin = mediaOriginOf(mediaDomain);
+    return origin === null ? null : `${origin}/${segments.map(encodeURIComponent).join("/")}`;
+}
 /**
  * Predefined image sizes for common use cases
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/storefront",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",