@wocart/storefront 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -5,6 +5,102 @@ 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.20.0 — 2026-10-24
+
+What every theme used to write itself is now the package's: the order form's
+quote, abandoned-checkout tracking, the review form, the request's store and
+language, the sitemap, search-engine metadata and images sized for the
+screen. Search, sorting, listing totals, a shopper's order status and product
+SEO fields arrive with the server that answers them; on an older server each
+degrades safely.
+
+### Added
+
+- **The order form, from the browser.** `createQuoter({ endpoint })` asks the
+  theme's cart-validate route and answers `fresh` (the quote), `stale` (a newer
+  question was asked meanwhile) or `failed`. `readCartQuote(value)` reads a
+  quote exactly as `CartValidationSchema` does, without Zod.
+- **Coupons.** `couponRefusalTone(reason)` says whether a refusal is a `hint`
+  (the basket does not meet the code yet) or `refused` (the code cannot be
+  used); `COUPON_HINT_REASONS` and `COUPON_REFUSAL_REASONS` list them.
+- **Abandoned checkouts.** `createBrowserAbandonedCheckoutTracker({ endpoint })`
+  wires the tracker to the page — session storage, timers, Meta cookies, a
+  keepalive POST and a beacon on exit. `convertAbandonedCheckout(...)` marks the
+  tab's checkout converted from the thank-you page;
+  `ABANDONED_CHECKOUT_SESSION_KEY` names where its id lives.
+- **Reviews.** `createReviewSession({ routes })` in `@wocart/storefront/review-media`
+  proves the purchase, sends each photo (shrunk) or voice note with its
+  progress and retries, and submits; every refusal comes back as a code from
+  `REVIEW_REFUSAL_CODES`. `REVIEW_TEXT_LIMITS` gives the lengths the server
+  accepts; `isOrderNumber(value)` and `ORDER_NUMBER_PATTERN` the shape of an
+  order number.
+- **The basket.** `basket.addSelections(line, selections)` adds an offer chosen
+  piece by piece — one line per variant, as one change, all or nothing.
+- **Request and preview.** `resolveStoreRequest` and `resolvePreviewStore` in
+  `@wocart/storefront/astro` decide the request's store and language (path
+  prefixes, the asking page's language for endpoints and server islands, the
+  redirects) and the draft's store. `notFound(Astro)` answers a missing
+  resource with the not-found page, never cached.
+- **Sitemap.** `sitemapXml(paths, routing, origin)` and `catalogPaths(client,
+  config)` in `@wocart/storefront/server`.
+- **Images.** `mediaImageSrcset(src, widths, options)` gives width descriptors
+  for `sizes`; `pictureOf(image, mediaDomain)` turns a picked image into its
+  URL, alt, size and focal point.
+- **Search engines.** `productMeta(product)`, `productStructuredData(product,
+  options)` and `jsonLd(value)`; `SEO_TEXT_LIMITS`. Products carry the
+  merchant's `metaTitle` and `metaDescription`, in the client's language.
+- **Catalog.** `products.search(text, filters)`; `sort` on listings
+  (`PRODUCT_SORTS`); `ProductPage.total`; a collection's `productCount` and
+  `image`; `DEFAULT_COLLECTION_HANDLES`; `productTags(product)` reads tags as a
+  list from a listing or a product page.
+- **Order status.** `orders.status({ orderNumber, phone })` and the
+  `orderStatus` storefront route: where a shopper's order is
+  (`SHOPPER_ORDER_STAGES`), its lines, total and tracking number — never its
+  address.
+
+### Changed
+
+- `getProductView(product)` reads the default variant's stock for
+  `isOutOfStock` and `isLowStock` on a product with variants, not the
+  product's total.
+
+### Deprecated
+
+- `ProductSchema.costPrice` and `ProductListSchema.costPrice`: always null —
+  what the merchant paid is never served to a storefront. A later major drops
+  them.
+
+## 1.19.0 — 2026-10-21
+
+What a theme's browser code takes from the package brings no Zod. Validation
+stays where data enters — a shopper's request at a route, the platform's answer
+in the client — on the server; the browser reads what those checked.
+
+### Added
+
+- `isWilayaId(value)`: whether a value is a wilaya id, the range
+  `WilayaIdSchema` checks on the server, read from the same `WILAYAS` — for the
+  browser, which checks a selected wilaya without a schema.
+- `readShippingRates(value)` and `readCouponOutcome(value)`: the delivery rates
+  a page carries and a quote's coupon outcome, read in the browser. Each accepts
+  exactly what `ShippingRatesSchema` / `CouponOutcomeSchema` accept and returns
+  what they would, without Zod — a page cached apart from its scripts can still
+  hold another version's shape. A property test holds each to its schema.
+- `mapOtpResponse` takes no `schema` for an answer of the SDK's own
+  `otpSend` / `otpVerify` routes, whose client already checked it on the
+  server. An answer with no `data` object is still a `MALFORMED_RESPONSE`
+  failure. Passing a schema works as before.
+
+### Changed
+
+- The basket's limits and line identity (`MAX_BASKET_LINES`,
+  `MAX_BASKET_LINE_QUANTITY`, `basketLineKey`) and the operation tables
+  (`STOREFRONT_OPERATIONS`, `STOREFRONT_RETRY_POLICIES`) moved out of the
+  module that builds the schemas. The exports are the same; a browser bundle
+  that uses the basket or names an operation no longer carries Zod.
+- A test bundles every browser-facing export through the package entry the
+  way a theme's Vite build does and fails, naming the export, if Zod appears.
+
 ## 1.18.0 — 2026-10-21
 
 The basket carries the offer a shopper chose for a line, so a quantity tier

package/USAGE.md

@@ -218,6 +218,8 @@ server directly.
 | `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 |
+| `isWilayaId` | Whether a value is a wilaya id — the range `WilayaIdSchema` checks on the server, without a schema in the browser |
+| `readShippingRates`, `readCouponOutcome` | Read in the browser what the server handed it — the rates a page carries, a quote's coupon outcome — accepting exactly what `ShippingRatesSchema` / `CouponOutcomeSchema` accept, without Zod |
 | `normalizeAlgerianPhone`, `toLocalAlgerianMobile` | The one Algerian phone rule (accept/format) |
 | `resolvePrefillText`, `buildWhatsAppHref`, `stripTrackingParams`, `truncateAtWordBoundary`, `PREFILL_TOKENS`, `MAX_RESOLVED_PREFILL_LENGTH` | WhatsApp prefill text and the `wa.me` link |
 | `storefrontPath`, `matchStorefrontPath`, `STOREFRONT_PAGE_PATHS` | The page types and their public paths: build a link, recognise a page |
@@ -314,6 +316,20 @@ Browser code reaches the platform only through same-origin routes you own
 browser-safe by construction: it exports no client factory and no function that
 carries the key, which the package's own contract test asserts.
 
+**Validation runs where data enters, on the server.** The SDK checks a
+shopper's request at its routes and the platform's answer in its client, with
+the schemas this package exports. What its routes and server islands hand the
+browser has passed those checks, so browser code reads it by its type and never
+imports a schema: a schema in a browser script ships Zod — about 27 KB
+compressed — to every shopper's page. The browser-facing values (the basket,
+the variant picker, the OTP machine, tracking, routes, phones, wilayas) are
+free of schemas, and a test bundles them the way a theme's build does to keep
+them so. A page can be cached apart from its scripts, so where the browser
+reads a value another version may have shaped, it uses a reader —
+`readShippingRates`, `readCouponOutcome` — that accepts exactly what the
+schema accepts, held to it by a property test, and Zod stays on the server. A theme with an endpoint of its own still validates it — on the
+server, where the request arrives.
+
 ### The namespaces
 
 | Namespace | Use it for | Important result shapes |
@@ -677,6 +693,36 @@ The picker reads only `variations`, `active`, `inventory`, `position` and
 `isDefault` of each variant (`PickerVariant`), so a page may hand it a
 lighter copy.
 
+`getProductView(product)` opens on the default variant: its price, and its
+stock for `isOutOfStock` and `isLowStock`, so a product whose first size is
+nearly gone says so even when another size has plenty.
+
+### Search engines and shared links
+
+A product carries the title and description its merchant wrote for search
+engines (`metaTitle`, `metaDescription`, in the client's language; null when
+none was written). `productMeta(product)` gives what a page puts in its
+`<title>` and `<meta name="description">`: what the merchant wrote, else the
+product's name and the start of its description as plain text — never markup
+— within `SEO_TEXT_LIMITS` (60 and 160 characters). Add the store's name to
+the title as the theme's design wants.
+
+`productStructuredData(product, { url, storeName })` gives its schema.org
+`Product` for rich results: photos, SKU, its price and stock as an `Offer`, or
+an `AggregateOffer` when its variants cost different amounts, and its rating
+once reviewed. Write it with `jsonLd(value)`, which escapes what could end the
+script:
+
+~~~astro
+---
+import { jsonLd, productMeta, productStructuredData } from "@wocart/storefront";
+const meta = productMeta(product);
+---
+<title>{meta.title} | {store.config.name}</title>
+{meta.description && <meta name="description" content={meta.description} />}
+<script type="application/ld+json" set:html={jsonLd(productStructuredData(product, { url: Astro.url.href, storeName: store.config.name }))} />
+~~~
+
 ### Product lists
 
 ~~~ts
@@ -709,10 +755,46 @@ const onSale = await store.products.list({ onSale: true, limit: 8 });
 - `featured: true` and `ProductList.storeFeatured` are deprecated: they mean
   the `featured` collection.
 
+A collection's page also has its size and a photo: `collections.get(handle)`
+answers `productCount` (what a shopper sees in it) and `image` (its first
+listed product's first photo, a `ProductImage`), both absent from a server
+that predates them.
+
+**Pages, totals and order.** `products.page(filters)` answers one page,
+whether another follows, and how many products the whole listing holds
+(`total`, null from a server that predates counts) — enough for "page 2 of 5"
+or "36 products":
+
+~~~ts
+const page = await store.products.page({ collection: "best-sellers", sort: "price-ascending", limit: 24, offset: 24 });
+// page.items, page.hasNext, page.total
+~~~
+
+`sort` is one of `PRODUCT_SORTS` — `newest`, `price-ascending`,
+`price-descending` — for a theme's sort control.
+
+`DEFAULT_COLLECTION_HANDLES` names the collections every store starts with,
+the likeliest to hold products first, for a page that needs one and was named
+none. Without one a listing keeps
+its own order: a collection's, a search's best match first, else newest. A
+server that predates sorting ignores it.
+
+**Search.** `products.search(text, filters)` answers a page of the products
+whose name — in the client's language or the catalog's — or tags hold every
+word, with the same filters, sort and paging; names that hold every word come
+first. Blank text finds nothing without asking. Search has its own path, so a
+server that predates it answers an empty page (reported through `onError`),
+never the whole catalog:
+
+~~~ts
+const results = await store.products.search(Astro.url.searchParams.get("q") ?? "", { limit: 24 });
+~~~
+
 Product lists return ProductList objects. ProductList and Product are
 different shapes: a list item is not a detail object and must not be cast to
 Product. ProductList carries list-oriented fields such as coverImage and
 reviewStats, while variantOptions and tags remain their raw serialized form.
+Read tags with `productTags(product)`, which gives a list from either shape.
 
 The limit is optional. An explicit limit of 0 is preserved, so do not replace
 it with a truthiness fallback.
@@ -795,6 +877,41 @@ const { blob, durationMs } = await recorder.stop();
 `canRecordVoice()` says whether to show a record button at all; a shopper can
 also attach an audio file. Send a recording with its `durationMs`.
 
+**The whole flow, from the browser.** `createReviewSession` runs the three
+steps through the theme's own review routes (see the storefront routes
+below): it keeps the proof and the upload grant between them, shrinks a
+photo before sending it, reports an upload's progress, tries again after a
+dropped connection or a server failure (twice, after 2 s then 4 s), and
+answers every refusal as a code for the form to word. It never throws.
+
+~~~ts
+import { createReviewSession } from "@wocart/storefront/review-media";
+import { REVIEW_REFUSAL_CODES, REVIEW_TEXT_LIMITS, isOrderNumber } from "@wocart/storefront";
+
+const session = createReviewSession({
+  routes: { eligibility: "/api/reviews/eligibility", upload: "/api/reviews/upload", submit: "/api/reviews/submit" },
+});
+
+const found = await session.find({ orderNumber, phone });
+if (found.status === "refused") return say(found.code); // null: no answer came
+
+const upload = session.upload(file, { kind: "image", onProgress: (share) => bar.style.inlineSize = `${share * 100}%` });
+remove.onclick = () => upload.cancel();
+const sent = await upload.result; // { status: "sent", uploadId } | refused | cancelled
+
+const submitted = await session.submit({ productId, rating, body, title, uploads: [uploadId] });
+// submitted.status === "submitted": submitted.result.visibility
+~~~
+
+`REVIEW_REFUSAL_CODES` lists every code a step can be refused with — word
+each one, and keep a general sentence for a code a newer server adds. A
+malformed order number is refused before any request, with the server's own
+`VALIDATION_FAILED`; `isOrderNumber(value)` and `ORDER_NUMBER_PATTERN` let a
+form say so as the shopper types. `REVIEW_TEXT_LIMITS` holds the lengths the
+server accepts (`bodyMin`, `bodyMax`, `titleMax`) for the form's hints and
+`maxlength`. `session.reset()` forgets the order and cancels what is still
+sending, when the shopper changes order.
+
 ## Categories, legal pages, and landing pages
 
 ### Categories
@@ -964,6 +1081,10 @@ const communes = await store.geo.communes(wilayaId); // server rows, cached
 // zero-network rows for the checkout's locality field:
 import { communesForWilaya } from "@wocart/storefront";
 const rows = communesForWilaya(wilayaId); // Commune[] — [] if unknown
+
+// a selected wilaya, checked in the browser before its communes are asked for:
+import { isWilayaId } from "@wocart/storefront";
+if (isWilayaId(Number(select.value))) loadCommunes(Number(select.value));
 ~~~
 
 Wilayas are local and do not use the network. `geo.communes()` reads the
@@ -1054,6 +1175,20 @@ The basket persists under `DEFAULT_BASKET_STORAGE_KEY` and holds at most
 `MAX_BASKET_LINES` lines of at most `MAX_BASKET_LINE_QUANTITY` units each —
 the same caps the server re-checks.
 
+An offer chosen piece by piece — three pyjamas in two sizes — goes in with
+`addSelections`: the product's line, then the per-piece choice exactly as an
+order's `variantSelections` carries it. Each variant becomes one line holding
+its pieces, all carrying the offer, in one change (listeners hear once). It
+is all or nothing: when the basket has no room for every new line, nothing is
+added, so an offer is never half in the basket.
+
+~~~ts
+basket.addSelections(
+  { productId, productName, unitPrice, offerId: "three-for-two", href, image },
+  [{ variantId: "6m", variantLabel: "6 mois" }, { variantId: "12m", variantLabel: "12 mois" }, { variantId: "6m", variantLabel: "6 mois" }],
+);
+~~~
+
 ### Single-product order versus basket order
 
 An order is either:
@@ -1137,6 +1272,31 @@ the code's field.
 A shareable link carries a code in the query (`COUPON_URL_PARAM`, `?coupon=RAMADAN10`);
 `couponFromUrl(url)` reads it so the theme can fill the code box.
 
+How a refusal reads is the platform's too: `couponRefusalTone(reason)` is
+`"hint"` when the code is good but this basket does not meet it yet — a phone
+to type, a product under an offer, a minimum not reached, delivery already
+free (`COUPON_HINT_REASONS`) — and `"refused"` when the code itself cannot be
+used, including a reason this release does not know. `COUPON_REFUSAL_REASONS`
+lists every reason the platform names, for a theme to word each one.
+
+**Asking from the browser.** An order form asks again whenever the shopper
+changes something, and only the latest question counts. `createQuoter` posts
+to the theme's cart-validate route and says which answer to show:
+
+~~~ts
+import { createQuoter } from "@wocart/storefront";
+
+const quoter = createQuoter({ endpoint: "/api/cart/validate" });
+const answer = await quoter.quote({ items: basket.toOrderItems() }, { destination, couponCode, phone });
+if (answer.status === "fresh") render(answer.quote); // a CartValidation
+else if (answer.status === "failed") showError();    // the latest question got no usable answer
+// "stale": a newer question was asked meanwhile — keep what is shown
+~~~
+
+`readCartQuote(value)` reads a quote the way the quoter does, for a quote a
+page carries: exactly what `CartValidationSchema` accepts, without a
+validator in the shopper's page.
+
 ### OTP
 
 Use OTP only when config.otpEnabled says the store requires or offers it.
@@ -1182,12 +1342,12 @@ The SDK exports `createOtpMachine` to manage the complete interactive WhatsApp
 verification lifecycle without managing timers and attempts manually. It talks
 to your own same-origin OTP routes through a transport; `mapOtpResponse` turns
 each route's response into the SDK's typed result, and `otpTransportFailure`
-covers a request that never completed:
+covers a request that never completed. The routes are the SDK's own
+(`createStorefrontRoutes`), whose client checked the answer on the server, so
+`mapOtpResponse` takes no schema here; pass one only for an endpoint of your own:
 
 ~~~ts
 import {
-  OtpSendResultSchema,
-  OtpVerifyResultSchema,
   STOREFRONT_OPERATIONS,
   createOtpMachine,
   createOtpTransport,
@@ -1195,14 +1355,14 @@ import {
   otpTransportFailure,
 } from "@wocart/storefront";
 
-async function post(path, body, schema, operation) {
+async function post(path, body, operation) {
   try {
     const response = await fetch(path, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(body),
     });
-    return await mapOtpResponse(response, { schema, operation, fallbackError: "Please try again" });
+    return await mapOtpResponse(response, { operation, fallbackError: "Please try again" });
   } catch (error) {
     return otpTransportFailure(error, operation, "Please try again");
   }
@@ -1211,9 +1371,9 @@ async function post(path, body, schema, operation) {
 const otp = createOtpMachine({
   transport: createOtpTransport({
     send: (phone) =>
-      post("/api/otp/send", { phone }, OtpSendResultSchema, STOREFRONT_OPERATIONS.ordersOtpSend),
+      post("/api/otp/send", { phone }, STOREFRONT_OPERATIONS.ordersOtpSend),
     verify: (phone, requestId, code) =>
-      post("/api/otp/verify", { phone, requestId, code }, OtpVerifyResultSchema, STOREFRONT_OPERATIONS.ordersOtpVerify),
+      post("/api/otp/verify", { phone, requestId, code }, STOREFRONT_OPERATIONS.ordersOtpVerify),
   }),
   initialPhone: "0551234567",
 });
@@ -1243,6 +1403,24 @@ tracking returns pixelId and an event of Purchase or Lead, or null. If it is
 null, fire no conversion event. Do not infer an event from a successful HTTP
 response alone.
 
+**Where an order is, for the shopper.** A shopper has no account: the order's
+number and the phone it was placed with prove it is theirs, as for a review.
+
+~~~ts
+const found = await store.orders.status({ orderNumber, phone }, forwardedHeaders);
+if (found.success) {
+  // found.data.stage: placed, confirmed, preparing, shipped, out_for_delivery,
+  //   delivered, returned (refused at the door) or cancelled — SHOPPER_ORDER_STAGES
+  // found.data.lines, found.data.total, found.data.placedAt
+  // found.data.tracking: { number, carrier } once the carrier has the parcel
+}
+// ORDER_NOT_FOUND: a wrong number or a wrong phone, answered the same.
+// ORDER_LOOKUP_RATE_LIMITED: too many tries for the order or the shopper.
+~~~
+
+It never answers the address, the notes or the merchant's own statuses.
+From the browser, use the storefront routes' `orderStatus`.
+
 ### Meta browser primitives
 
 The payload builders are pure and browser-safe. Use the server-validated value
@@ -1268,6 +1446,26 @@ Use these only when the theme has a real abandoned-checkout flow. Keep the
 normal mutation result handling and never block order creation on optional
 analytics.
 
+In the browser, `createBrowserAbandonedCheckoutTracker` does the capturing:
+the checkout's id for the tab in `sessionStorage`
+(`ABANDONED_CHECKOUT_SESSION_KEY`), a capture after the shopper pauses, the
+Meta cookies, a `keepalive` POST to the theme's route, and a beacon when the
+shopper leaves. Blocked storage or a failed send never touches the order.
+
+~~~ts
+import { convertAbandonedCheckout, createBrowserAbandonedCheckoutTracker } from "@wocart/storefront";
+
+const tracker = createBrowserAbandonedCheckoutTracker({ endpoint: "/api/abandoned" });
+nameInput.addEventListener("input", () => tracker.schedule(snapshot()));
+addEventListener("pagehide", () => tracker.captureOnExit(snapshot()));
+
+// On the thank-you page: the checkout became this order.
+convertAbandonedCheckout({ endpoint: "/api/abandoned/convert", orderId, orderNumber });
+~~~
+
+`createAbandonedCheckoutTracker` is the same policy with every browser
+dependency passed in, for an unusual host.
+
 ## Astro actions and form handling
 
 The SDK cannot import Astro virtual modules, so a theme owns the thin Astro
@@ -1375,6 +1573,60 @@ the next page with no result: the thank-you redirect never fires, and a
 refused order shows no message. resolveActionRedirectDecision, the earlier
 name, is deprecated and now always answers next.
 
+### The request's store and language
+
+`resolveStoreRequest` decides which store a request renders and in which
+language, with the rules every storefront needs: a page takes its language
+from its path (`/fr/products/robe`); the primary's own prefix redirects for
+good to its one address, and a language the store stopped publishing
+redirects for now to the primary page; an endpoint (`/api/…`) or a server
+island takes the language of the page that asked, from its same-origin
+`Referer`, and is never redirected or rewritten. It answers data — the
+request's client, config, language, routing and unprefixed path — and the
+theme builds its own context from it:
+
+~~~ts
+// src/middleware.ts
+import { resolvePreviewStore, resolveStoreRequest, runFormAction } from "@wocart/storefront/astro";
+
+const options = { client: createStore, fallback: FALLBACK_CONFIG }; // the theme's one client factory, and its shell config
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  if (context.url.pathname === THEME_PREVIEW_PATH) {
+    const preview = await readThemePreview(context.request);
+    if (!preview.ok) return new Response(null, { status: preview.status, headers: { "Cache-Control": "no-store" } });
+    context.locals.store = buildContext(await resolvePreviewStore(preview.draft, options));
+    return next();
+  }
+  const request = await resolveStoreRequest({ url: context.url, referer: context.request.headers.get("Referer") }, options);
+  if (request.kind === "redirect") return context.redirect(request.location, request.status);
+  context.locals.store = buildContext(request);
+  // … runFormAction as above …
+  return request.rewrite ? next(request.rewrite) : next();
+});
+~~~
+
+`client(locale?)` makes the request's client, in a language or the
+store's primary; `fallback` is the config rendered when the store cannot be
+read — a shell with the checkout off. `embedded(pathname)` overrides which
+paths serve part of a page. `resolvePreviewStore(draft, options)` is the
+editor's preview: the draft's language when the store serves it, the draft's
+settings and text over the saved ones, tracking off.
+
+### A page whose resource does not exist
+
+A product, category, collection or page that is not there answers the
+theme's not-found page with 404 — and is never cached, or a product published
+a minute later keeps answering "not found":
+
+~~~astro
+---
+import { notFound } from "@wocart/storefront/astro";
+const product = await Astro.locals.store.client.products.get(Astro.params.handle ?? "");
+if (!product) return notFound(Astro);
+---
+~~~
+
 ## Browser-facing proxy routes
 
 Browser code calls same-origin theme routes, which call the platform with the
@@ -1382,8 +1634,8 @@ server-only API key. The key never reaches the browser.
 
 ### The storefront routes, ready to export
 
-createStorefrontRoutes returns the eight routes every storefront needs. Bind
-them once to the request's own client:
+createStorefrontRoutes returns the routes every storefront needs. Bind them
+once to the request's own client:
 
 ~~~ts
 // src/theme/api-routes.ts
@@ -1415,12 +1667,14 @@ export const POST = routes.otpSend;
 | `reviewEligibility` | POST | `{ orderNumber, phone, turnstileToken? }` | `{ data: ReviewEligibility }` |
 | `reviewUpload` | PUT | the file as the body; headers `X-Review-Grant`, `X-Media-Duration-Ms` | 201 `{ data: ReviewUpload }` (streamed on, never buffered) |
 | `reviewSubmit` | POST | `ReviewInput` | 201 `{ success: true, data: { id, visibility } }` |
+| `orderStatus` | POST | `{ orderNumber, phone }` | `{ data: ShopperOrderStatus }` |
 
 What every route gets right:
 
 - every POST and PUT refuses a cross-origin request with 403;
-- the OTP routes and abandoned tracking forward the shopper's address and
-  user agent, so the server limits and attributes per shopper;
+- the OTP routes, abandoned tracking and the order status forward the
+  shopper's address and user agent, so the server limits and attributes per
+  shopper;
 - input is bounded before it is sent, and a malformed body is a 400 that never
   reaches the server;
 - a refusal answers with the status the server's category implies — 400 for
@@ -1517,6 +1771,33 @@ The image utility accepts the original media URL and can target a media
 domain. Use it to produce appropriately sized URLs rather than downloading
 original assets into every card.
 
+For an image whose width changes with the screen, give the browser widths and
+let `sizes` choose — a phone then downloads a phone-sized file.
+`mediaImageSrcset(src, widths, { mediaDomain, ratio, quality })` gives one
+size per width with width descriptors, cropped to `ratio` (height ÷ width)
+when given; null off the media domain:
+
+~~~astro
+<img
+  src={mediaImageUrl(src, { width: 720, format: "auto" }, mediaDomain) ?? src}
+  srcset={mediaImageSrcset(src, [360, 540, 720, 1080], { mediaDomain, ratio: 1.25 }) ?? undefined}
+  sizes="(min-width: 1024px) 25vw, 50vw"
+  alt="" loading="lazy" />
+~~~
+
+A photo a merchant picks for a section is stored as a media key with its alt
+text, size and focal point. `pictureOf(image, mediaDomain)` turns it into what
+an `<img>` needs — `src`, `alt` (empty when none was written), `width`,
+`height` and `position`, the focal point as CSS `object-position` — or null
+when none is picked:
+
+~~~astro
+---
+const picture = pictureOf(props.image, mediaDomain);
+---
+{picture && <img src={picture.src} alt={picture.alt} width={picture.width} height={picture.height} style={{ objectPosition: picture.position }} />}
+~~~
+
 ### Which photo a product is
 
 `coverImage` is nullable and a merchant who uploads a gallery may never pick
@@ -1608,6 +1889,27 @@ 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.
 
+## The sitemap
+
+`sitemapXml(paths, routing, origin)` writes a multilingual sitemap: one
+`<url>` per page per published language, each naming every language version
+and `x-default`. `catalogPaths(client, config)` lists what it holds — home,
+the catalog, each category, every product (read page by page) and each
+published text page; landing pages stay out, as ad destinations. Both are in
+`@wocart/storefront/server`:
+
+~~~ts
+// src/pages/sitemap.xml.ts
+import { catalogPaths, sitemapXml } from "@wocart/storefront/server";
+
+export const GET: APIRoute = async ({ locals, url }) => {
+  const { client, config, routing } = locals.store;
+  return new Response(sitemapXml(await catalogPaths(client, config), routing, url.origin), {
+    headers: { "Content-Type": "application/xml; charset=utf-8", "Cache-Control": "public, max-age=3600" },
+  });
+};
+~~~
+
 ## Previewing a draft for an editor
 
 A visual editor shows a merchant's unsaved changes on the store's own

package/dist/abandoned-checkout.d.ts

@@ -19,4 +19,49 @@ export interface AbandonedCheckoutTracker {
     captureOnExit(snapshot: AbandonedCheckoutSnapshot): void;
     isCapturable(snapshot: AbandonedCheckoutSnapshot): boolean;
 }
+/**
+ * Where the browser keeps the checkout's id for the tab (`sessionStorage`):
+ * every capture of one checkout updates one record, and the thank-you page
+ * marks that record converted.
+ */
+export declare const ABANDONED_CHECKOUT_SESSION_KEY = "cod_session_id";
 export declare function createAbandonedCheckoutTracker(ports: AbandonedCheckoutPorts): AbandonedCheckoutTracker;
+/** What the browser wiring uses of the page; the page's own globals by default. */
+export interface AbandonedCheckoutHost {
+    readonly sessionStorage?: Pick<Storage, "getItem" | "setItem" | "removeItem">;
+    readonly crypto?: Pick<Crypto, "getRandomValues"> & {
+        randomUUID?: () => string;
+    };
+    readonly document?: {
+        readonly cookie: string;
+    };
+    readonly navigator?: {
+        sendBeacon?: (url: string, data: Blob) => boolean;
+    };
+    readonly fetch?: typeof fetch;
+    readonly setTimeout: (callback: () => void, delayMs: number) => unknown;
+    readonly clearTimeout: (handle: never) => void;
+}
+export interface BrowserAbandonedCheckoutOptions {
+    /** The theme's abandoned-checkout route (`createStorefrontRoutes().abandonedUpsert`), e.g. `/api/abandoned`. */
+    endpoint: string;
+}
+/**
+ * `createAbandonedCheckoutTracker` wired to the page: the checkout's id in
+ * `sessionStorage`, timers, the Meta cookies, a `keepalive` POST to the
+ * theme's route, and `sendBeacon` when the shopper leaves. A page that blocks
+ * storage still captures; nothing it does can fail the order.
+ */
+export declare function createBrowserAbandonedCheckoutTracker(options: BrowserAbandonedCheckoutOptions, host?: AbandonedCheckoutHost): AbandonedCheckoutTracker;
+export interface AbandonedCheckoutConversion {
+    /** The theme's conversion route (`createStorefrontRoutes().abandonedConvert`), e.g. `/api/abandoned/convert`. */
+    endpoint: string;
+    orderId: string;
+    orderNumber: string;
+}
+/**
+ * Marks the tab's checkout converted, from the thank-you page: the merchant
+ * no longer sees the order it became as abandoned. The id is used once and
+ * forgotten. Best-effort — it never throws and never holds the page.
+ */
+export declare function convertAbandonedCheckout(conversion: AbandonedCheckoutConversion, host?: Pick<AbandonedCheckoutHost, "sessionStorage" | "fetch">): void;