@wocart/storefront 1.5.0 → 1.7.0

package/dist/endpoints/proxy.js

@@ -31,7 +31,7 @@ import { collectForwardedHeaders } from "../actions.js";
  * ```
  */
 export function createProxyEndpoint(config) {
-    const { method, client, inputSchema, queryParams = [], pathParams = {}, csrfProtection = method === "POST", forwardAttribution = false, successStatus = 200, errorStatus, successBody, noContent = false, } = config;
+    const { method, client, inputSchema, queryParams = [], pathParams = {}, csrfProtection = method !== "GET", readInput, forwardAttribution = false, successStatus = 200, errorStatus, successBody, noContent = false, } = config;
     return async (context) => {
         const { request, params } = context;
         // CSRF Protection: reject cross-origin requests
@@ -41,7 +41,10 @@ export function createProxyEndpoint(config) {
         // Parse input based on method
         let input;
         try {
-            if (method === "GET") {
+            if (readInput) {
+                input = readInput(request);
+            }
+            else if (method === "GET") {
                 input = parseGetInput(request, params, queryParams, pathParams);
             }
             else {

package/dist/endpoints/storefront-routes.d.ts

@@ -1,9 +1,10 @@
 /**
  * The storefront's same-origin API routes, ready to export.
  *
- * Every theme needs the same eight routes between the shopper's browser and
- * the platform: OTP send and verify, cart validation, abandoned-checkout
- * tracking and its conversion, communes, and reviews (list and submit). What
+ * Every theme needs the same routes between the shopper's browser and the
+ * platform: OTP send and verify, cart validation, abandoned-checkout tracking
+ * and its conversion, communes, and reviews (list, find the order, send a
+ * photo or voice note, submit). What
  * each one must get right is decided here once — the cross-origin check on
  * every POST, the shopper's address forwarded wherever the server counts or
  * attributes per shopper, the input bounds, and the response shape the
@@ -47,7 +48,15 @@ export interface StorefrontRoutes<C extends AstroAPIContext> {
     readonly communes: StorefrontApiRoute<C>;
     /** GET, path param `productId`, query `limit`/`offset` → `{ data: Review[], total }`. */
     readonly reviewsList: StorefrontApiRoute<C>;
-    /** POST a `ReviewInput` → 201 `{ success: true, data: { id } }`. */
+    /** POST `{ orderNumber, phone, turnstileToken? }` → `{ data: ReviewEligibility }`. */
+    readonly reviewEligibility: StorefrontApiRoute<C>;
+    /**
+     * PUT one file as the body, the grant in `X-Review-Grant` (and a voice
+     * note's length in `X-Media-Duration-Ms`) → 201 `{ data: ReviewUpload }`.
+     * The file streams on to the server unbuffered.
+     */
+    readonly reviewUpload: StorefrontApiRoute<C>;
+    /** POST a `ReviewInput` → 201 `{ success: true, data: { id, visibility } }`. */
     readonly reviewSubmit: StorefrontApiRoute<C>;
 }
 export declare const REVIEWS_PAGE_DEFAULT = 20;

package/dist/endpoints/storefront-routes.js

@@ -1,9 +1,10 @@
 /**
  * The storefront's same-origin API routes, ready to export.
  *
- * Every theme needs the same eight routes between the shopper's browser and
- * the platform: OTP send and verify, cart validation, abandoned-checkout
- * tracking and its conversion, communes, and reviews (list and submit). What
+ * Every theme needs the same routes between the shopper's browser and the
+ * platform: OTP send and verify, cart validation, abandoned-checkout tracking
+ * and its conversion, communes, and reviews (list, find the order, send a
+ * photo or voice note, submit). What
  * each one must get right is decided here once — the cross-origin check on
  * every POST, the shopper's address forwarded wherever the server counts or
  * attributes per shopper, the input bounds, and the response shape the
@@ -65,11 +66,40 @@ const reviewsListInput = z.object({
  */
 const reviewSubmitInput = z.object({
     orderNumber: z.string().min(1).max(64),
+    phone: z.string().min(1).max(32).optional(),
     productId: z.string().min(1).max(200),
     rating: z.number(),
     title: z.string().max(500).optional(),
     body: z.string().max(5000),
+    grant: z.string().min(1).max(2048).optional(),
+    uploads: z.array(z.string().min(1).max(64)).max(8).optional(),
 });
+const reviewEligibilityInput = z.object({
+    orderNumber: z.string().min(1).max(64),
+    phone: z.string().min(1).max(32),
+    turnstileToken: z.string().min(1).max(2048).optional(),
+});
+/** The file itself stays a stream; only the headers around it are checked here. */
+const reviewUploadInput = z.object({
+    body: z.custom((value) => value instanceof ReadableStream, "No file was sent"),
+    grant: z.string().min(1).max(2048),
+    contentLength: z.number().int().positive().optional(),
+    durationMs: z.number().int().positive().max(600_000).optional(),
+});
+function readUpload(request) {
+    const length = Number(request.headers.get("Content-Length"));
+    const duration = Number(request.headers.get("X-Media-Duration-Ms"));
+    return {
+        body: request.body,
+        grant: request.headers.get("X-Review-Grant") ?? "",
+        ...(Number.isInteger(length) && length > 0 ? { contentLength: length } : {}),
+        ...(Number.isInteger(duration) && duration > 0 ? { durationMs: duration } : {}),
+    };
+}
+/** Drops the keys a form left undefined: the client's input type is exact. */
+function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
 export function createStorefrontRoutes(options) {
     const route = (config) => async (context) => {
         const { call, ...endpoint } = config;
@@ -130,12 +160,24 @@ export function createStorefrontRoutes(options) {
                 data: await client.products.reviews.list(productId, { limit, offset }),
             }),
         }),
+        reviewEligibility: route({
+            method: "POST",
+            inputSchema: reviewEligibilityInput,
+            call: (client, input) => client.products.reviews.eligibility(defined(input)),
+        }),
+        reviewUpload: route({
+            method: "PUT",
+            readInput: readUpload,
+            inputSchema: reviewUploadInput,
+            successStatus: 201,
+            call: (client, input) => client.products.reviews.upload(defined(input)),
+        }),
         reviewSubmit: route({
             method: "POST",
             inputSchema: reviewSubmitInput,
             successStatus: 201,
             successBody: (data) => ({ success: true, data }),
-            call: (client, { title, ...review }) => client.products.reviews.submit(title === undefined ? review : { ...review, title }),
+            call: (client, review) => client.products.reviews.submit(defined(review)),
         }),
     };
 }

package/dist/index.d.ts

@@ -17,11 +17,11 @@ export { productImageSource } from "./utils/product-image.js";
 export type { ProductImageSourceInput } from "./utils/product-image.js";
 export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";
 export type { PrefillToken, ResolvePrefillParams } from "./whatsapp.js";
-export { STOREFRONT_ROUTES, showsWidgetOn } from "./routes.js";
+export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";
 export { servedLanguage } from "./locales.js";
 export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "./locale-routing.js";
 export type { LocalePath, LocaleRouting } from "./locale-routing.js";
-export type { StorefrontRoute } from "./routes.js";
+export type { StorefrontPageMatch, StorefrontPageType, StorefrontPathParams, StorefrontRoute } from "./routes.js";
 export { createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.js";
 export type { BasketStore, BasketStorageAdapter, BasketStoreOptions, BasketListener, } from "./basket.js";
 export { createOtpMachine, createOtpTransport, mapOtpResponse, otpTransportFailure, } from "./otp.js";

package/dist/index.js

@@ -13,7 +13,7 @@ export { formatMoney } from "./utils/money.js";
 export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, } 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_ROUTES, showsWidgetOn } from "./routes.js";
+export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";
 export { servedLanguage } from "./locales.js";
 export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "./locale-routing.js";
 export { createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.js";

package/dist/review-media.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `@wocart/storefront/review-media` — what a theme's review form does in the
+ * browser before a photo or a voice note is sent, so it arrives small on a
+ * slow mobile connection:
+ *
+ *   prepareReviewPhoto   shrinks a photo to 1600 px at most and re-encodes it
+ *                        (WebP, else JPEG) — a phone photo of several MB
+ *                        becomes a few hundred KB, and its EXIF (the phone's
+ *                        location) is gone before it leaves the device
+ *   createVoiceRecorder  records speech at a low bitrate in what the phone
+ *                        records (WebM/Opus, MP4/AAC on iPhone), and stops by
+ *                        itself at the store's limit
+ *
+ * Browser-only, and kept off the main entry point: a theme that takes no
+ * media pays nothing for it. Each takes its browser dependencies as an
+ * optional last argument, for tests and unusual hosts.
+ */
+export interface PhotoOptions {
+    /** Longest edge in pixels. Default 1600 (what the server keeps). */
+    maxEdge?: number;
+    /** Encoder quality, 0–1. Default 0.82. */
+    quality?: number;
+}
+/** The size a photo is drawn at: its own, or scaled so its longest edge is `maxEdge`. */
+export declare function photoTargetSize(width: number, height: number, maxEdge: number): {
+    width: number;
+    height: number;
+};
+export interface PhotoDeps {
+    createImageBitmap: (image: Blob, options?: ImageBitmapOptions) => Promise<ImageBitmap>;
+    /** A canvas of the given size that can encode itself. */
+    createCanvas: (width: number, height: number) => {
+        getContext(type: "2d"): Pick<CanvasRenderingContext2D, "drawImage"> | null;
+        toBlob(type: string, quality: number): Promise<Blob | null>;
+    };
+}
+/**
+ * A photo ready to send: drawn upright (the camera's orientation applied),
+ * no larger than `maxEdge`, re-encoded as WebP (JPEG where WebP cannot be
+ * written). When the browser cannot do it, the photo is sent as it is — the
+ * server still converts it and drops its EXIF.
+ */
+export declare function prepareReviewPhoto(photo: Blob, options?: PhotoOptions, deps?: PhotoDeps | null): Promise<Blob>;
+/** Formats in the order a recorder is tried: Opus where it can be written, AAC on iPhone. */
+export declare const VOICE_MIME_TYPES: readonly ["audio/webm;codecs=opus", "audio/ogg;codecs=opus", "audio/mp4;codecs=mp4a.40.2", "audio/mp4", "audio/webm"];
+/** The first format this browser can record, or null when it cannot record voice. */
+export declare function pickVoiceMimeType(isTypeSupported: (type: string) => boolean): string | null;
+export interface RecordedVoice {
+    blob: Blob;
+    /** As measured while recording; send it with the upload. */
+    durationMs: number;
+    mimeType: string;
+}
+export interface VoiceRecorderOptions {
+    /** Stops by itself after this many seconds (the store's limit). */
+    maxSeconds: number;
+    /** About every 250 ms while recording, with the time recorded so far. */
+    onTick?: (elapsedMs: number) => void;
+    /** When it stopped by itself at the limit. */
+    onLimit?: (voice: RecordedVoice) => void;
+}
+export interface VoiceRecorder {
+    /** Asks for the microphone and starts. Rejects when it is refused or unavailable. */
+    start(): Promise<void>;
+    /** Stops and gives the recording. */
+    stop(): Promise<RecordedVoice>;
+    /** Stops and throws the recording away. */
+    cancel(): void;
+    readonly state: "idle" | "recording" | "stopped";
+}
+export interface VoiceDeps {
+    getUserMedia: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    MediaRecorder: {
+        new (stream: MediaStream, options?: MediaRecorderOptions): MediaRecorder;
+        isTypeSupported(type: string): boolean;
+    };
+    now: () => number;
+    setInterval: (fn: () => void, ms: number) => unknown;
+    clearInterval: (id: unknown) => void;
+}
+/** Whether this browser can record a voice note at all (hide the record button when not). */
+export declare function canRecordVoice(deps?: VoiceDeps | null): boolean;
+/**
+ * A recorder for one voice note: speech at about 32 kb/s, mono, with the
+ * phone's echo cancellation and noise suppression — 60 s is about 240 KB.
+ */
+export declare function createVoiceRecorder(options: VoiceRecorderOptions, deps?: VoiceDeps | null): VoiceRecorder;

package/dist/review-media.js

@@ -0,0 +1,182 @@
+/**
+ * `@wocart/storefront/review-media` — what a theme's review form does in the
+ * browser before a photo or a voice note is sent, so it arrives small on a
+ * slow mobile connection:
+ *
+ *   prepareReviewPhoto   shrinks a photo to 1600 px at most and re-encodes it
+ *                        (WebP, else JPEG) — a phone photo of several MB
+ *                        becomes a few hundred KB, and its EXIF (the phone's
+ *                        location) is gone before it leaves the device
+ *   createVoiceRecorder  records speech at a low bitrate in what the phone
+ *                        records (WebM/Opus, MP4/AAC on iPhone), and stops by
+ *                        itself at the store's limit
+ *
+ * Browser-only, and kept off the main entry point: a theme that takes no
+ * media pays nothing for it. Each takes its browser dependencies as an
+ * optional last argument, for tests and unusual hosts.
+ */
+/** The size a photo is drawn at: its own, or scaled so its longest edge is `maxEdge`. */
+export function photoTargetSize(width, height, maxEdge) {
+    const longest = Math.max(width, height);
+    if (longest <= maxEdge || longest === 0)
+        return { width, height };
+    const scale = maxEdge / longest;
+    return { width: Math.max(1, Math.round(width * scale)), height: Math.max(1, Math.round(height * scale)) };
+}
+function browserPhotoDeps() {
+    if (typeof createImageBitmap !== "function" || typeof document === "undefined")
+        return null;
+    return {
+        createImageBitmap: (image, options) => createImageBitmap(image, options),
+        createCanvas: (width, height) => {
+            const canvas = document.createElement("canvas");
+            canvas.width = width;
+            canvas.height = height;
+            return {
+                getContext: () => canvas.getContext("2d"),
+                toBlob: (type, quality) => new Promise((resolve) => canvas.toBlob(resolve, type, quality)),
+            };
+        },
+    };
+}
+/**
+ * A photo ready to send: drawn upright (the camera's orientation applied),
+ * no larger than `maxEdge`, re-encoded as WebP (JPEG where WebP cannot be
+ * written). When the browser cannot do it, the photo is sent as it is — the
+ * server still converts it and drops its EXIF.
+ */
+export async function prepareReviewPhoto(photo, options = {}, deps = browserPhotoDeps()) {
+    if (!deps)
+        return photo;
+    const maxEdge = options.maxEdge ?? 1600;
+    const quality = options.quality ?? 0.82;
+    let bitmap;
+    try {
+        bitmap = await deps.createImageBitmap(photo, { imageOrientation: "from-image" });
+    }
+    catch {
+        return photo;
+    }
+    try {
+        const size = photoTargetSize(bitmap.width, bitmap.height, maxEdge);
+        const canvas = deps.createCanvas(size.width, size.height);
+        const context = canvas.getContext("2d");
+        if (!context)
+            return photo;
+        context.drawImage(bitmap, 0, 0, size.width, size.height);
+        for (const type of ["image/webp", "image/jpeg"]) {
+            const blob = await canvas.toBlob(type, quality);
+            if (blob && blob.type === type && blob.size > 0)
+                return blob;
+        }
+        return photo;
+    }
+    catch {
+        return photo;
+    }
+    finally {
+        bitmap.close?.();
+    }
+}
+/** Formats in the order a recorder is tried: Opus where it can be written, AAC on iPhone. */
+export const VOICE_MIME_TYPES = ["audio/webm;codecs=opus", "audio/ogg;codecs=opus", "audio/mp4;codecs=mp4a.40.2", "audio/mp4", "audio/webm"];
+/** The first format this browser can record, or null when it cannot record voice. */
+export function pickVoiceMimeType(isTypeSupported) {
+    return VOICE_MIME_TYPES.find((type) => {
+        try {
+            return isTypeSupported(type);
+        }
+        catch {
+            return false;
+        }
+    }) ?? null;
+}
+function browserVoiceDeps() {
+    if (typeof navigator === "undefined" || !navigator.mediaDevices?.getUserMedia || typeof MediaRecorder === "undefined")
+        return null;
+    return {
+        getUserMedia: (constraints) => navigator.mediaDevices.getUserMedia(constraints),
+        MediaRecorder,
+        now: () => performance.now(),
+        setInterval: (fn, ms) => setInterval(fn, ms),
+        clearInterval: (id) => clearInterval(id),
+    };
+}
+/** Whether this browser can record a voice note at all (hide the record button when not). */
+export function canRecordVoice(deps = browserVoiceDeps()) {
+    return Boolean(deps && pickVoiceMimeType((type) => deps.MediaRecorder.isTypeSupported(type)));
+}
+/**
+ * A recorder for one voice note: speech at about 32 kb/s, mono, with the
+ * phone's echo cancellation and noise suppression — 60 s is about 240 KB.
+ */
+export function createVoiceRecorder(options, deps = browserVoiceDeps()) {
+    let state = "idle";
+    let recorder = null;
+    let stream = null;
+    let chunks = [];
+    let startedAt = 0;
+    let ticker = null;
+    let finished = null;
+    const release = () => {
+        if (ticker !== null)
+            deps?.clearInterval(ticker);
+        ticker = null;
+        stream?.getTracks().forEach((track) => track.stop());
+        stream = null;
+    };
+    return {
+        get state() {
+            return state;
+        },
+        async start() {
+            if (!deps)
+                throw new Error("This browser cannot record voice notes");
+            if (state === "recording")
+                return;
+            const mimeType = pickVoiceMimeType((type) => deps.MediaRecorder.isTypeSupported(type));
+            if (!mimeType)
+                throw new Error("This browser cannot record voice notes");
+            stream = await deps.getUserMedia({ audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true } });
+            chunks = [];
+            recorder = new deps.MediaRecorder(stream, { mimeType, audioBitsPerSecond: 32_000 });
+            const active = recorder;
+            finished = new Promise((resolve) => {
+                active.ondataavailable = (event) => {
+                    if (event.data.size > 0)
+                        chunks.push(event.data);
+                };
+                active.onstop = () => {
+                    const type = (active.mimeType || mimeType).split(";")[0];
+                    resolve({ blob: new Blob(chunks, { type }), durationMs: Math.round(deps.now() - startedAt), mimeType: type });
+                };
+            });
+            startedAt = deps.now();
+            recorder.start(1000);
+            state = "recording";
+            ticker = deps.setInterval(() => {
+                const elapsed = deps.now() - startedAt;
+                options.onTick?.(elapsed);
+                if (elapsed >= options.maxSeconds * 1000 && state === "recording") {
+                    void this.stop().then((voice) => options.onLimit?.(voice));
+                }
+            }, 250);
+        },
+        async stop() {
+            if (state !== "recording" || !recorder || !finished)
+                throw new Error("Not recording");
+            state = "stopped";
+            recorder.stop();
+            const voice = await finished;
+            release();
+            return voice;
+        },
+        cancel() {
+            if (recorder && state === "recording")
+                recorder.stop();
+            state = "stopped";
+            chunks = [];
+            release();
+        },
+    };
+}

package/dist/routes.d.ts

@@ -1,20 +1,59 @@
 /**
- * The canonical storefront route contract.
+ * The storefront's page types and their public paths.
  *
- * One deployment serves one store, and three parts of the platform meet on the
- * same public URLs: the theme renders them, the server writes them into a conversion's
- * landing URL (`/lp/:slug` for an attributed sale, `/thank-you` otherwise), and
- * the dashboard shows them as the store's public links (`/pages/:slug`). These
- * patterns are what all three already assume, so they are written down here: a
- * theme may restyle everything else, but these paths are a platform contract,
- * not a theme decision.
+ * A page type is what a URL *means* — a product, a category, a store page, a
+ * landing page — and the path is where it lives. The paths are a platform
+ * contract, not a theme decision: the platform builds them without running
+ * the theme (the dashboard shows a page's public link, the server names the
+ * landing page in a conversion's source URL), so a theme renders each page
+ * type it supports at its path and builds every link to one with
+ * `storefrontPath` — never a hand-written string. Any other route is the
+ * theme's own (`/about`, `/offers/summer` …): Astro's file routing owns those,
+ * and nothing here constrains them.
  *
- * Two further paths carry no parameter and no pattern: the root (`/`, the home
- * surface) and the catalog index (`/products`, the catalog surface). The
- * surface gate below handles them alongside the six frozen patterns.
+ * Language prefixes are applied on top: `localizeHref(storefrontPath(…),
+ * locale, routing)`.
  */
 import type { WidgetSurfaces } from "./types.js";
-/** One route in the contract: the pattern and the surface that renders it. */
+/** Each page type's public path; `:handle` / `:slug` mark its one parameter. */
+export declare const STOREFRONT_PAGE_PATHS: {
+    readonly home: "/";
+    readonly catalog: "/products";
+    readonly category: "/category/:slug";
+    readonly product: "/products/:handle";
+    readonly page: "/pages/:slug";
+    readonly landing: "/lp/:slug";
+    readonly checkout: "/checkout";
+    readonly thankYou: "/thank-you";
+};
+/** What a storefront URL means. */
+export type StorefrontPageType = keyof typeof STOREFRONT_PAGE_PATHS;
+type ParamOf<P extends string> = P extends `${string}:${infer Name}` ? Name : never;
+/** The parameter a page type's path needs: `{ handle }` for a product, `{ slug }` for a category, page or landing page, nothing otherwise. */
+export type StorefrontPathParams<T extends StorefrontPageType> = ParamOf<(typeof STOREFRONT_PAGE_PATHS)[T]> extends never ? Record<string, never> : {
+    [K in ParamOf<(typeof STOREFRONT_PAGE_PATHS)[T]>]: string;
+};
+/** A pathname recognised as one of the page types, with its parameter. */
+export interface StorefrontPageMatch {
+    readonly type: StorefrontPageType;
+    readonly params: Readonly<Record<string, string>>;
+}
+/**
+ * The public path of a page type, its parameter encoded:
+ * `storefrontPath("product", { handle: "robe" })` → `/products/robe`.
+ * Throws when the parameter is missing — a link to nowhere is a bug to see,
+ * not a path to render.
+ */
+export declare function storefrontPath<T extends StorefrontPageType>(type: T, params?: StorefrontPathParams<T>): string;
+/**
+ * Which page type a pathname is, and its parameter (decoded) — or null for
+ * any other path. Exact matches only: `/products/` is the catalog,
+ * `/productsomething` and `/products/a/b` are nothing. The query, the
+ * fragment and a trailing slash are ignored. Pass a pathname without its
+ * language prefix (`resolveLocalePath` gives it).
+ */
+export declare function matchStorefrontPath(rawPathname: string): StorefrontPageMatch | null;
+/** One route with a parameter or a fixed path of its own, and the widget surface that renders it. */
 export interface StorefrontRoute {
     /** Path pattern; `:handle` and `:slug` mark the single path parameter. */
     readonly path: string;
@@ -22,24 +61,17 @@ export interface StorefrontRoute {
     readonly surface: keyof WidgetSurfaces;
 }
 /**
- * The frozen contract. Adding a route is a deliberate platform change: a path
- * that renders a surface but is missing here is a surface the merchant cannot
- * switch on with any confidence.
+ * @deprecated Use `STOREFRONT_PAGE_PATHS` (every page type, the home and the
+ * catalog index included) with `storefrontPath` and `matchStorefrontPath`.
+ * Kept equal to what it always listed.
  */
 export declare const STOREFRONT_ROUTES: readonly StorefrontRoute[];
 /**
- * Whether the widget belongs on a pathname.
- *
- * The merchant answers "which surfaces" (`surfaces[surface]`); this function
- * answers the platform half — which surface a pathname *is* — and it reads the
- * contract above:
- *
- * - `/` → the home surface;
- * - `/products` (the catalog index) and `/category/:slug` → the catalog surface;
- * - `/products/:handle` → the product surface;
- * - `/pages/:slug`, `/lp/:slug`, `/checkout`, `/thank-you` → their own surfaces;
- * - anything else — a 404, `/productsomething`, `/checkout-success` — → no
- *   surface at all, never a prefix match that leaks a widget onto a page the
- *   merchant switched off.
+ * Whether the widget belongs on a pathname: the merchant answers "which
+ * surfaces" (`surfaces[surface]`); this answers which surface a pathname *is*,
+ * from the page types above. Any other path — a 404, `/productsomething`,
+ * `/checkout-success` — is no surface at all, never a prefix match that leaks
+ * the widget onto a page the merchant switched off.
  */
 export declare function showsWidgetOn(surfaces: WidgetSurfaces | null | undefined, rawPathname: string): boolean;
+export {};