@nok-integration/storefront-react 0.19.1 → 0.19.2

package/dist/index.d.ts

@@ -177,9 +177,9 @@ declare const CartItem: z.ZodObject<{
      * and tell the fan *why* instead of silently refusing. Mirrors
      * {@link ProductVariant.available}.
      *
-     * **Display only, and a hint.** The projection is a cache and the authoritative check
-     * runs at checkout (DAZN's, under ADR-0008) — a consumer must not treat this as a
-     * guarantee that N are purchasable. Absent = impose no cap client-side; the engine
+     * **Display only, and a hint.** The read model is a cache and the authoritative check
+     * runs at checkout — a consumer must not treat this as a guarantee that N are
+     * purchasable. Absent = impose no cap client-side; the engine
      * still rejects an over-quantity update with `out_of_stock`, which carries the real
      * `available` figure in its error details.
      */
@@ -321,10 +321,9 @@ export declare function CartView(props?: CartViewProps): JSX.Element;
  * 4.4 Cart. Loads the session cart, supports optimistic + idempotent qty/remove edits
  * (reverting on error), and hands off to checkout.
  *
- * There is no `withSession` wrapper here any more. Re-authentication moved down into the
- * SDK's transport, which asks the host's `getToken()` once on a `401` and retries — so
- * every component gets that behaviour without remembering to opt in, and a component
- * that forgets can no longer quietly lose it.
+ * Re-authentication lives in the SDK's transport, not here: it asks the host's
+ * `getToken()` once on a `401` and retries. Every component gets that without opting in,
+ * so none can quietly lose it.
  */
 export declare interface CartViewProps {
     /**
@@ -363,13 +362,11 @@ declare type CatalogReadQuery = z.infer<typeof CatalogReadQuery>;
  * 4.2 Category (PCP) — the composed screen, given a page that is already fetched.
  *
  * This exists for the same reason `ProductDetail` does: the presentation belongs to the
- * package, so that the fetching wrapper around it — `CategoryView` here, an RSC route in
- * our own app — is only ever fetching. It was previously written out twice, once in each,
- * and the two drifted: the SDK copy rendered a bare `div`/`section`/`ul` tree with none of
- * the page layout, so a host mounting `CategoryView` got correctly styled blocks stacked
- * with no column spacing, no page background, and a full-bleed one-column "grid". The
- * blocks looked right individually, which is what made it read as a missing stylesheet
- * rather than a missing wrapper.
+ * package, so that any fetching wrapper around it — `CategoryView` here, or a host's own
+ * route — is only ever fetching. Writing the layout out separately in the wrapper is what
+ * this prevents: the blocks then look right individually while the page has no column
+ * spacing, no background and a full-bleed one-column "grid", which reads as a missing
+ * stylesheet rather than a missing wrapper.
  *
  * Not a client component: it renders no interactivity of its own, so it stays usable
  * directly from a server component. The pieces that do need the client carry their own
@@ -2808,8 +2805,8 @@ declare function createClient(options: ClientOptions): {
         }>;
     };
     /**
-     * The fan's own orders (ADR-0015). Session-scoped: there is no way to ask for
-     * someone else's, because there is no parameter that names a customer.
+     * The fan's own orders. Session-scoped: there is no way to ask for someone else's,
+     * because there is no parameter that names a customer.
      */
     stockAlerts: {
         /** "Remind me when available" — idempotent per SKU for the session's principal. */
@@ -2924,10 +2921,10 @@ declare function createClient(options: ClientOptions): {
             can_return?: boolean | undefined;
         }>;
         /**
-         * Ask for the order to be cancelled (ADR-0024). Returns the order as it now stands.
+         * Ask for the order to be cancelled. Returns the order as it now stands.
          *
-         * A request, not a refund: DAZN are merchant of record and the money is theirs to
-         * move. This records the fan's ask and hands it on.
+         * A request, not a refund: the merchant of record moves the money. This records the
+         * fan's ask and hands it on.
          */
         requestCancellation: (orderRef: string, body: RequestCancellationRequest) => Promise<{
             status: "packing" | "on_its_way" | "out_for_delivery" | "delivered" | "cancelled";
@@ -3083,8 +3080,8 @@ declare function createClient(options: ClientOptions): {
         }>;
     };
     /**
-     * The Help Center form (ADR-0021). Session-scoped: the ticket is filed against the
-     * fan already signed in, and there is no parameter that names a different one.
+     * The Help Center form. Session-scoped: the ticket is filed against the fan already
+     * signed in, and there is no parameter that names a different one.
      */
     support: {
         /**
@@ -3207,21 +3204,21 @@ export declare interface DaznShopConfig {
      * - `'cookie'` — the engine's httpOnly session cookie is sent instead. Correct for a
      *   first-party web view that authenticates by cookie and has no token for JS to hold.
      *
-     * Getting this wrong does not fail loudly. Requests simply arrive unauthenticated, and
-     * an environment that issues anonymous sessions will hand out a **new** one per call —
-     * so an item is added to one cart and read back from another, and the basket looks
-     * empty rather than broken. That is exactly how this was found.
+     * **Getting this wrong does not fail loudly.** Requests simply arrive unauthenticated,
+     * and an environment that issues anonymous sessions hands out a **new** one per call —
+     * so an item is added to one cart and read back from another, and the basket looks empty
+     * rather than broken. Check this first if a cart will not hold its contents.
      */
     sessionTransport?: 'bearer' | 'cookie';
     /**
      * Origin (or path prefix) the SDK's own static assets are served from — the design
      * imagery the shop-entry screen renders. Default: none, i.e. paths are left as written.
      *
-     * These are **root-relative** in the source (`/figma/home/hero.jpg`), which is correct
-     * in our own app and wrong everywhere else: a browser resolves them against the page's
-     * origin, and mounted in a host's page that is the **host's** origin. The host does not
-     * serve our imagery, so every one of them 404s and the entry screen renders with broken
-     * images while the rest of the SDK works perfectly — which is exactly how it presents.
+     * These paths are **root-relative** in the bundle (`/figma/home/hero.jpg`), so a browser
+     * resolves them against the page's own origin — which, once mounted, is the host's. A
+     * host that does not serve this imagery gets a 404 for each one, and the shop-entry
+     * screen renders with broken images while every other screen behaves normally. Set this
+     * to wherever the assets are served from.
      *
      * Only root-relative paths are rebased. Absolute and protocol-relative URLs are left
      * untouched, because catalogue media arrives from the API already absolute and must not
@@ -3292,7 +3289,7 @@ export declare interface EmptyStateProps {
  * | invalid_request    | 400  | malformed body or missing field               |
  * | unauthorized       | 401  | missing/invalid session or credentials        |
  * | out_of_stock       | 409  | requested qty exceeds available stock         |
- * | cart_locked        | 409  | RETIRED (ADR-0025); defined, never raised     |
+ * | cart_locked        | 409  | RETIRED; defined, never raised                |
  * | sku_not_found      | 404  | a referenced SKU/product does not exist       |
  * | category_not_found | 404  | a referenced category code does not exist     |
  * | amount_mismatch    | 422  | totals do not match the authorised amount     |
@@ -3315,7 +3312,7 @@ declare type ErrorCode = z.infer<typeof ErrorCode>;
  * | invalid_request    | 400  | malformed body or missing field               |
  * | unauthorized       | 401  | missing/invalid session or credentials        |
  * | out_of_stock       | 409  | requested qty exceeds available stock         |
- * | cart_locked        | 409  | RETIRED (ADR-0025); defined, never raised     |
+ * | cart_locked        | 409  | RETIRED; defined, never raised                |
  * | sku_not_found      | 404  | a referenced SKU/product does not exist       |
  * | category_not_found | 404  | a referenced category code does not exist     |
  * | amount_mismatch    | 422  | totals do not match the authorised amount     |
@@ -3433,8 +3430,8 @@ export declare interface IdentityGateProps {
 }
 
 /**
- * `GET /v1/inventory/{sku}` — read-model availability. Authoritative stock is Odoo;
- * a live check is also run at checkout.
+ * `GET /v1/inventory/{sku}` — read-model availability. This is a cached projection, not
+ * the authoritative figure; a live check is also run at checkout.
  */
 declare const Inventory: z.ZodObject<{
     sku: z.ZodString;
@@ -3556,19 +3553,18 @@ export declare type OnEvent = (event: ShopEvent) => void;
 /**
  * The order confirmation (Figma `5295:74053`).
  *
- * **A different screen from `OrderTrackingView`, not a state of it**, which is the answer
- * to the question DAZN asked on 20 Aug 2026. The two frames differ in their chrome
- * (close-only against back + cart + overflow), in their headline, and in their footer
- * action, and nothing in the payload can tell them apart: `status` is a fulfilment step
- * and cannot say "has just come back from paying", and time-since-placed guesses wrong for
- * anyone who opens the email an hour later. So the two screens are two routes, and the one
- * that navigates here is the one that knows — the checkout that has just finished.
+ * **A different screen from `OrderTrackingView`, not a state of it.** The two differ in
+ * their chrome (close-only against back + cart + overflow), in their headline, and in
+ * their footer action, and nothing in the payload can tell them apart: `status` is a
+ * fulfilment step and cannot say "has just come back from paying", and time-since-placed
+ * guesses wrong for anyone opening a confirmation email an hour later. So they are two
+ * routes, and the caller that navigates here is the one that knows — the checkout that
+ * has just finished.
  *
  * Below the widget the two are the same three blocks, and they are the same components:
  * see `OrderReceipt`.
  *
- * Read-only, like tracking. The frame's footer is "Done" rather than "Cancel order"
- * precisely because cancellation is DAZN's under ADR-0008 and ADR-0017.
+ * Read-only, like tracking: the footer is "Done" rather than "Cancel order".
  */
 export declare function OrderConfirmationView(props: OrderConfirmationViewProps): JSX.Element;
 
@@ -3580,14 +3576,12 @@ export declare interface OrderConfirmationViewProps {
     /**
      * The frame's "Done". Omit it and no button renders.
      *
-     * **It leaves the shop.** DAZN settled this on 21 Aug 2026: "Done = DAZN home, X = DAZN
-     * Shop home". The two are not the same destination and wiring both to the shop home —
-     * which is what the first integration did — loses the only way out of the shop at the
-     * end of a purchase.
+     * **It leaves the shop entirely.** "Done" goes to the app's own home; the header's
+     * close control goes to the shop home. They are different destinations, and wiring both
+     * to the shop home removes the only way out of the shop at the end of a purchase.
      *
-     * We cannot make that trip ourselves: the DAZN app's own home is not a route on our
-     * `/v1` surface and not something a `navigate('/')` can reach. So this stays the host's
-     * callback, and the header's `onClose` is the one that goes to the shop home.
+     * It is a host callback because the app's home is not reachable from the `/v1` surface
+     * and not somewhere `navigate('/')` can go.
      */
     onDone?: () => void;
 }
@@ -4087,11 +4081,10 @@ declare const OrderDetail: z.ZodObject<{
 declare type OrderDetail = z.infer<typeof OrderDetail>;
 
 /**
- * The fan's orders (Figma `mobile/order/list`, ADR-0015).
+ * The fan's orders (Figma `mobile/order/list`).
  *
- * Read-only, like the detail screen it links to. Cancellation and returns are DAZN's under
- * ADR-0008, so the design's return states have no data behind them — see
- * {@link OrderStatusBadge}.
+ * Read-only, like the detail screen it links to. The design's return states have no data
+ * behind them — see {@link OrderStatusBadge}.
  *
  * Scoped to the session at the engine: `GET /v1/orders` takes no customer parameter, so
  * there is no identifier a caller could supply to read somebody else's history.
@@ -4123,9 +4116,9 @@ declare const OrderProgressStep: z.ZodEnum<["packing", "on_its_way", "out_for_de
 declare type OrderProgressStep = z.infer<typeof OrderProgressStep>;
 
 /**
- * Fulfilment order status. Lives here (not in a synchronous order contract) because the
- * engine no longer owns orders (ADR-0008) — order/fulfilment status reaches us only as
- * async events (Odoo → engine → consumers). DAZN is authoritative for completed orders.
+ * Fulfilment order status. It lives on the event contract rather than a synchronous order
+ * one because fulfilment status arrives asynchronously, as events. The merchant of record
+ * is authoritative for completed orders.
  */
 declare const OrderStatus: z.ZodEnum<["confirmed", "packed", "shipped", "delivered", "cancelled", "refunded"]>;
 
@@ -4160,20 +4153,16 @@ export declare interface OrderSummaryProps {
      * This exists because a zero is ambiguous and the ambiguity is dangerous. `Pricing`
      * requires all four values, so the engine sends `0` for shipping and tax it has not
      * computed — and rendering that gives the fan a confident "Tax £0.00" and a total that
-     * changes at checkout. DAZN owns checkout and therefore owns delivery and tax
-     * (ADR-0008), so in the cart both are genuinely unknown rather than genuinely free.
+     * changes at checkout. Delivery and tax are settled at checkout, so in the cart both are
+     * genuinely unknown rather than genuinely free.
      *
-     * **The grand total is still drawn.** It used to be withheld whenever anything here was
-     * deferred, on the reasoning that a total omitting delivery is not a total. DAZN
-     * reviewed that on 21 Aug 2026 against the frame — which draws a Total row — and chose
-     * the frame. So the row is drawn, carrying `pricing.total`, and on a cart that means the
-     * items total: delivery and tax are added at DAZN's checkout and can move it by the
-     * spread the design's own shipping note quotes (standard $5-16, express $15-23).
+     * **The grand total is still drawn**, carrying `pricing.total`. On a cart that means the
+     * items total: delivery and tax are added at checkout and can move it by the spread the
+     * design's own shipping note quotes (standard $5-16, express $15-23).
      *
-     * Deferring a row therefore now changes only that row. If the withholding is ever
-     * wanted back, it belongs behind an explicit prop rather than as a side effect of
-     * `deferred` — a prop that silently removes a different row is the kind of surprise this
-     * comment exists to prevent.
+     * **Deferring a row changes only that row.** Withholding the total as a side effect of
+     * deferring something else would be a prop that silently removes a different row; if
+     * that behaviour is ever wanted, it belongs behind an explicit prop of its own.
      */
     deferred?: DeferredLine[];
     /**
@@ -4234,11 +4223,10 @@ export declare interface OrderTimelineProps {
  * One screen with three states, and the engine's `progress` is what draws them: the widget
  * says where the parcel is, and everything under it is the same for all three.
  *
- * The frame's first state carries a "Cancel order" button and its last offers a return,
- * and **both are ours since 21 Aug** (ADR-0024). Cancelling happens in place, through the
- * reason sheet at the foot of this file; a return is three screens, so "Return items"
- * navigates to them. Neither moves money: DAZN remain merchant of record, and what the
- * engine records is a request handed on.
+ * The first state carries a "Cancel order" button and the last offers a return.
+ * Cancelling happens in place, through the reason sheet; a return is three screens, so
+ * "Return items" navigates to them. **Neither moves money** — both record a request and
+ * hand it on, and nothing here computes or settles a refund.
  *
  * Both are drawn on the ENGINE's say-so — `can_cancel` is its dispatch cut-off,
  * `can_return` its returns window. Neither is a status this screen can infer, and it does
@@ -4261,15 +4249,10 @@ export declare interface OrderTrackingViewProps {
     /**
      * Open the return flow.
      *
-     * **Optional now, and it was once required.** Returns were DAZN's under ADR-0008, so
-     * this used to be the only way the row could appear: a control that cannot complete is
-     * worse than an absent one. ADR-0024 gave us the flow — `POST /v1/orders/{ref}/returns`
-     * and the three screens behind it — so the default is no longer "nothing happens".
-     *
-     * It is still the seam, because the flow is three SCREENS and only the host knows where
-     * its routes are — the same reason `OrderListView` takes `onOpenOrder` rather than
-     * navigating itself. What changed is what the handler leads to: mount `ReturnFlowView`
-     * with this order's reference and the whole flow is there.
+     * Optional. The return flow is three SCREENS, and only the host knows where its routes
+     * are — the same reason `OrderListView` takes `onOpenOrder` rather than navigating
+     * itself. Mount `ReturnFlowView` with this order's reference and the whole flow is
+     * there.
      *
      * Without it the control is not drawn. The SDK will not offer a button whose destination
      * does not exist, and that has not changed either.
@@ -4425,7 +4408,7 @@ declare const Pricing: z.ZodObject<{
 
 declare type Pricing = z.infer<typeof Pricing>;
 
-/** A catalog product, served from the engine's cached read model (synced from Odoo). */
+/** A catalog product, served from the engine's cached read model. */
 declare const Product: z.ZodObject<{
     sku: z.ZodString;
     title: z.ZodString;
@@ -4680,10 +4663,9 @@ export declare interface ProductDetailProps {
  * three lines with a more/less toggle. Only renders when the catalogue provides a
  * description — no placeholder copy is invented.
  *
- * The toggle appears only when the clamp is actually hiding something. It used to render
- * for every description, so a two-line one offered a "more" that expanded to the same two
- * lines and a "Less" that collapsed to them again — reported from staging, where most
- * products have a short description.
+ * The toggle appears only when the clamp is actually hiding something, measured rather
+ * than assumed: a description short enough to fit gets no control, instead of a "More"
+ * that expands to the same lines and a "Less" that collapses back to them.
  */
 export declare function ProductDetails({ description }: ProductDetailsProps): JSX.Element | null;
 
@@ -4981,8 +4963,8 @@ declare type RequestCancellationRequest = z.infer<typeof RequestCancellationRequ
  * - **relative** (`./x`, `x.jpg`) — resolves against the document, which is the host's
  *   business, not ours.
  *
- * With no base configured this is the identity function, so our own app — which serves
- * these paths itself — needs no configuration and keeps working unchanged.
+ * With no base configured this is the identity function, so a host that already serves
+ * these paths needs no configuration.
  */
 export declare function resolveAssetUrl(src: string, base?: string): string;
 
@@ -5175,9 +5157,9 @@ declare type ReturnDetail = z.infer<typeof ReturnDetail>;
  * around views that own the drawing. Same reason as there — a screen that loads itself is
  * one a host can mount from a route with nothing but a reference.
  *
- * **It settles no money and it is not a refund** (ADR-0024). It records goods coming back
- * so the warehouse can expect them; DAZN remain merchant of record and tell us about the
- * refund afterwards through the inbound event.
+ * **It settles no money and it is not a refund.** It records goods coming back so the
+ * warehouse can expect them. The merchant of record makes any refund, and reports it
+ * separately.
  */
 export declare function ReturnFlowView(props: ReturnFlowViewProps): JSX.Element;
 
@@ -5301,13 +5283,12 @@ export declare interface SaleBadgeProps {
 /**
  * What a whole screen looks like while its data is in flight.
  *
- * This replaces `<Skeleton />` on its own, which was not a loading state at all: with no
- * width, height or content, a `display: block` span computes to **zero pixels tall**. The
- * views returned it, it painted nothing, and whatever the host had behind us showed
- * through — which in DAZN's dark app is a black screen between tapping a link and the
- * product arriving. It looked like a navigation bug and was a CSS one.
+ * Use this rather than a bare `<Skeleton />`, which is not a loading state on its own:
+ * with no width, height or content, a `display: block` span computes to **zero pixels
+ * tall**, paints nothing, and lets whatever the host has behind it show through — in a
+ * dark host, a black screen between tapping a link and the content arriving.
  *
- * Two things follow from that and are the whole point of this component. It has real
+ * Two things follow, and they are the whole point of this component. It has real
  * dimensions, so there is something on screen for the entire wait. And it is a
  * `ShopSurface`, so the wait is painted in the palette of the screen you are waiting for
  * — a light PDP that resolves out of a light wait, rather than out of the host's black.
@@ -5357,14 +5338,11 @@ export declare interface SheetHeaderProps {
  * no free-shipping threshold (per design). The shopper picks the delivery tier at
  * DAZN's checkout; this only signals that the options exist.
  *
- * **The returns window is 14 days, and it used to be 30.** ADR-0016 kept 30 because the
- * design contradicted itself: this card said 14 on the PDP and 30 where the very same
- * component was placed in the cart, so ours was the number the file agreed with more
- * often. The current cart frame (5304:78218) says 14 as well, so the contradiction is
- * gone and 14 is what the design now says in both places.
+ * **The returns window is 14 days**, matching the design on both the PDP and the cart
+ * (`5304:78218`).
  *
- * It is still not OUR number. Returns are DAZN's under ADR-0008 and this only reports
- * the policy — if 14 is wrong, it is wrong in the design and one word fixes it here.
+ * The card only reports the policy; it does not set it. If 14 is wrong, it is wrong in the
+ * design, and one word changes it here.
  */
 export declare function ShippingInfo(): JSX.Element;
 
@@ -5428,17 +5406,17 @@ export declare type ShopEvent = {
 /**
 * A fan asked for help with a delivered order (0.17.2).
 *
-* **The Contact Support form is DAZN's**, so this is a hand-off rather than a step in a
-* flow we own: the fan pressed the row on the order screen, and where they go next is
-* the host's to decide. Same shape as `checkout_handoff` — we know the moment and the
-* order, and nothing after it.
+* A hand-off, not a step in a flow the SDK completes: the fan pressed the row on the
+* order screen, and where they go next is the host's to decide. Same shape as
+* `checkout_handoff` — the event carries the moment and the order, and nothing after
+* it. No support form is rendered.
 */
 | {
     type: 'support_requested';
     orderRef: string;
 }
 /**
-* The fan confirmed a cancellation and the engine accepted it (ADR-0024).
+* The fan confirmed a cancellation and the engine accepted it.
 *
 * Raised after the write succeeds, never on the tap: this is a statement that an order
 * has been cancelled, and a host acting on it — refreshing a list, telling analytics —
@@ -5449,7 +5427,7 @@ export declare type ShopEvent = {
     orderRef: string;
     reason: string;
 }
-/** "Reorder" on a cancelled order. The host owns where that goes; we only announce it. */
+/** "Reorder" on a cancelled order. The host decides where that leads; this only announces it. */
 | {
     type: 'reorder_requested';
     orderRef: string;
@@ -5459,8 +5437,8 @@ export declare type ShopEvent = {
 *
 * Raised after the write, like the cancellation above, and for the same reason: a host
 * counting returns must not count one the engine refused. It is not a refund and must
-* not be treated as one; DAZN remain merchant of record and say what is paid back
-* (ADR-0024).
+* not be treated as one — the merchant of record determines what is paid back, and this
+* event says nothing about money.
 */
 | {
     type: 'return_requested';
@@ -5497,21 +5475,19 @@ export declare type ShopEvent = {
  * The 64px shop header from Figma `mobile/header` (context=shop): back chevron on the
  * left, cart and overflow on the right.
  *
- * **Optional, and off by default in every view.** In the real embed the DAZN app provides
- * this chrome — it is their back button and their menu — which is why nothing in the SDK
- * renders it for you. It is exported because DAZN's team asked for it after finding the
- * bar they see in our own storefront was not available to them: rebuilding it is a waste
- * if the design is ours, and a mismatch if only half of it is.
+ * **Optional, and off by default in every view.** In the embedded case the host app
+ * provides this chrome — its own back button and menu — which is why no view renders it
+ * for you. It is exported for hosts that would otherwise have to rebuild the same bar:
+ * duplicating it is wasted work, and matching only half of it is worse.
  *
  * The cart count is real, never fabricated: `useCartCount` returns `null` until it knows,
  * and the badge stays hidden until then — a "0" that appears while the cart is still
  * loading and then jumps to "3" is a guess wearing a number.
  *
  * **The badge is also hidden at zero**, which is a deliberate departure from the frame:
- * `.cart.icon` draws an explicit empty state carrying "0". DAZN asked for it removed on
- * 17 Aug 2026 and they are right — a filled pill is an attention mark, and one that says
- * there is nothing to look at spends the fan's attention to tell them so. The empty state
- * is the icon on its own.
+ * `.cart.icon` draws an explicit empty state carrying "0". A filled pill is an attention
+ * mark, and one saying there is nothing to look at spends attention to say so. The empty
+ * state is the icon on its own.
  *
  * `useCartCount` had said as much since it was written ("a badge must render nothing for
  * `null` and nothing for `0`"); the component followed the frame instead, and the two
@@ -5646,9 +5622,9 @@ export declare interface ShopLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnc
  *
  * A light card anchored under the bar, over a scrim, with a close control and two rows.
  *
- * **"Redeem a code" is gone**, and the design is what removed it. The menu had three rows
- * from `Settings` (636:51006) on the page ADR-0022 retired; the frame of record draws
- * exactly two, orders and help. It is the one row this package rendered knowing it could
+ * **"Redeem a code" is gone**, and the design is what removed it. An earlier `Settings`
+ * frame (636:51006) had three rows; the frame of record draws exactly two, orders and
+ * help. It is the one row this package rendered knowing it could
  * never work — promotions are DAZN's and nothing in the commerce API can redeem anything —
  * so a fan tapping it got a control that did nothing, every time, by design. Both sides
  * now agree it should not be there.
@@ -5666,8 +5642,7 @@ export declare interface ShopMenuSheetProps {
     open: boolean;
     onClose: () => void;
     /**
-     * The fan's orders. Ours since [ADR-0015]; wire it to wherever the host renders
-     * `OrderListView`.
+     * The fan's orders. Wire it to wherever the host renders `OrderListView`.
      */
     onManageOrders?: () => void;
     /** Help. DAZN's own surface, so a host that has one passes it here. */
@@ -5681,7 +5656,7 @@ export declare interface ShopMenuSheetProps {
  * The public surface DAZN programs against. Everything here is a **contract**, not an
  * implementation detail — see the versioning policy in the component SDK specification.
  */
-/** A storefront-relative identifier. NOT a URL we expect to exist on the host. */
+/** A storefront-relative identifier. NOT a URL expected to resolve on the host. */
 export declare type ShopRoute = '/' | `/category/${string}` | `/product/${string}` | '/cart';
 
 /**
@@ -5709,39 +5684,31 @@ declare type ShopSessionRequest = z.infer<typeof ShopSessionRequest>;
  * The root element of a storefront screen: base typography, element defaults, and a
  * palette.
  *
- * Both halves of this were previously the host's job by accident. The typography lived in
- * our Next app's `globals.css` on `<body>`, and the dark palette was switched on by a
- * route-watching `ThemeController` that set `data-theme` on `<html>`. Neither travelled
- * with the components into this package, so a host mounting `<CategoryView>` got a screen
- * designed dark rendered on a light palette in the host's own body font — every component
- * individually correct, the screen as a whole wrong.
- *
- * **`tone` is the only input, and the provider's `theme` no longer overrides it.**
+ * **Every screen root must render inside one.** A screen's typography and palette belong
+ * to the screen, not to the page it is mounted in — without this, a host mounting
+ * `<CategoryView>` gets a screen designed dark rendered on a light palette in the host's
+ * own body font: every component individually correct, the screen as a whole wrong.
  *
- * It used to. The reasoning was that a host wanting one palette throughout should be able
- * to say so — but the storefront has no light and dark of the same screen to choose
- * between. Each screen is drawn once, in one palette: the shop entry and category pages
- * are dark, the PDP and cart are light. There is no light version of the dark hero, so
- * `theme="light"` did not render one; it repainted the tokens underneath a screen whose
- * artwork, photography and contrast were all built for the other palette.
+ * **`tone` is the only input; the provider's `theme` does not override it.**
  *
- * DAZN set `theme="light"` and got a dark hero photograph with near-black button text on
- * it — a screen that exists in no design, produced by an option that sounded reasonable.
- * The prop is still accepted so that setting it does not break a host's build, and it
- * still reaches the context for hosts reading it, but it no longer decides what a screen
- * looks like. Black screens stay black; light screens stay light.
+ * Each screen is drawn once, in one palette: the shop entry and category pages are dark,
+ * the PDP and cart are light. There is no light version of the dark hero, so asking for
+ * one does not produce it — it repaints the tokens underneath artwork, photography and
+ * contrast that were all built for the other palette, giving a dark hero photograph with
+ * near-black text on it. `theme` is still accepted, so setting it will not break a build,
+ * and it still reaches the context for hosts that read it; it does not decide what a
+ * screen looks like.
  *
- * `data-shop-theme` is a real attribute rather than a hashed module class so the token
- * remap can live once in `theme.css` beside the values it overrides, and so a host can
- * scope our palette onto a subtree of their own if they ever need to.
+ * `data-shop-theme` is a real attribute rather than a hashed module class, so the token
+ * remap lives once in `theme.css` beside the values it overrides, and so a host can scope
+ * the palette onto a subtree of its own.
  *
- * **Anything that paints its own background must be one of these, not merely look like
+ * **Anything that paints its own background must BE one of these, not merely look like
  * one.** Setting `background: var(--color-surface-default)` on an element without also
  * setting `color` leaves the text inheriting from the host's `<body>` — so a light sheet
- * in a dark host app renders white text on white. That is what happened to the cart
- * bottom sheet, and it was invisible in our own app because our `<body>` happened to
- * carry a matching colour. Hence the forwarded props and ref: a surface has to be usable
- * **as** a dialog or a layout element, or callers will reach for the CSS shortcut again.
+ * in a dark host renders white text on white. Hence the forwarded props and ref: a
+ * surface has to be usable **as** a dialog or a layout element, or callers reach for the
+ * CSS shortcut instead.
  */
 export declare const ShopSurface: ForwardRefExoticComponent<ShopSurfaceProps & RefAttributes<HTMLDivElement>>;
 
@@ -6013,8 +5980,8 @@ declare const SupportTicketRequest: z.ZodObject<{
      * caller. It is authoritative for its own users in exactly the way order intake
      * already is when DAZN tells us whose order they have taken.
      *
-     * Added for DAZN's Contact Support form, which lives outside the shop and therefore
-     * has no shop session to read an identity from (21 Aug 2026).
+     * This is for a Contact Support form living outside the shop, which therefore has no
+     * shop session to read an identity from.
      */
     dazn_user_id: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
@@ -6038,9 +6005,9 @@ export declare function swatchColour(name: string): string;
 /**
  * One row, structurally.
  *
- * Deliberately not `OrderProgressEntry` itself. The return timeline (ADR-0024) is drawn
- * by the same Figma component with a different set of steps — reported, received,
- * completed — so its entries carry a different `step` enum and would not assign. Nothing
+ * Deliberately not `OrderProgressEntry` itself. The return timeline is drawn by the same
+ * Figma component with a different set of steps — reported, received, completed — so its
+ * entries carry a different `step` enum and would not assign. Nothing
  * here interprets `step` beyond keying on it, so the widened type costs nothing and saves
  * a second copy of the timeline that would drift from this one.
  */
@@ -6106,8 +6073,8 @@ declare type UpdateCartItemRequest = z.infer<typeof UpdateCartItemRequest>;
 
 /**
  * Resolve an SDK asset path against the host's configured base. Identity outside a
- * provider, and identity when no base is configured — so our own app, which serves these
- * paths itself, needs no configuration.
+ * provider, and identity when no base is configured — so a host that already serves these
+ * paths needs no configuration.
  */
 export declare function useAssetUrl(): (src: string) => string;
 
@@ -6186,13 +6153,10 @@ export declare function useShopOptional(): ShopContextValue | null;
 /**
  * Access the toast API. Always returns something usable.
  *
- * This used to throw outside `<ToastProvider>`, and that was wrong on the project's own
- * principle that strictness is **per capability**: `useShopApi` throws because reaching
- * the API genuinely cannot degrade, but a toast can. Worse, it made the specification's
- * opening example — one `<DaznShopProvider>` with `<CartView>` beneath it — crash the
- * entire tree on mount, because `CartView` raises toasts and nothing had mounted a
- * provider. With no error boundary above it, a host following our own documentation got
- * a blank page.
+ * **It never throws**, because strictness here is per capability: `useShopApi` throws
+ * because reaching the API cannot degrade, but a toast can. A `<DaznShopProvider>` with
+ * `<CartView>` beneath it and no `<ToastProvider>` is a supported arrangement — `CartView`
+ * raises toasts, and mounting it must not bring the tree down.
  *
  * Without a `<ToastProvider>` the message still goes somewhere useful: it is emitted to
  * the host as a `notification` event if there is a shop provider to emit through, which