@usequeek/theme-kit 0.1.23 → 0.1.25

package/sdk/client.ts

@@ -1,20 +1,38 @@
 import { getActivePlatform } from './platform';
 
-// SERVER-side only (SSR data fetching, server-to-server — never reaches the
-// browser, so the real absolute host is correct and required here).
-export const API_BASE_URL = process.env.QUEEK_API_URL ?? process.env.NEXT_PUBLIC_QUEEK_API_URL ?? 'http://127.0.0.1:8000/api/v1';
-// BROWSER-side only (createBrowserClient below, "for client components/hooks").
-// Hardcoded relative on purpose, same reasoning as queek-client.ts's
-// API_BASE_URL: the host app's `next.config` rewrite already proxies
-// /api/v1/client/:path* to the API server-side, so the browser never needs the
-// real host. This
-// used to read NEXT_PUBLIC_QUEEK_API_URL directly — when that's set to the
-// same absolute value as the server-side QUEEK_API_URL, every hook built on
-// createBrowserClient (products, shop, categories, reviews, related products,
-// product questions, QR collections) leaked api.usequeek.com straight into
-// the browser Network tab, bypassing the proxy entirely.
+const LOCAL_API_URL = 'http://127.0.0.1:8000/api/v1';
+const API_URL_FROM_ENV = process.env.QUEEK_API_URL ?? process.env.NEXT_PUBLIC_QUEEK_API_URL;
+
+/**
+ * Origin of the Queek API for SERVER-side reads (server rendering and
+ * server-to-server calls; this value never reaches the browser).
+ *
+ * Set `QUEEK_API_URL` (or `NEXT_PUBLIC_QUEEK_API_URL`) in the storefront host's
+ * environment. When neither is set the kit falls back to a local development
+ * address and warns once in production builds.
+ */
+export const API_BASE_URL = API_URL_FROM_ENV ?? LOCAL_API_URL;
+
+// BROWSER-side only (createBrowserClient below, for client components and hooks).
+// Always same-origin relative: the host app's `next.config` rewrite proxies
+// /api/v1/client/:path* to the API, so the browser never needs the API's real
+// host. Reading NEXT_PUBLIC_QUEEK_API_URL here would leak that host into every
+// browser request whenever the variable holds the same absolute value as the
+// server-side QUEEK_API_URL.
 const PUBLIC_API_BASE_URL = '/api/v1';
 
+let warnedAboutLocalApiUrl = false;
+
+function warnIfApiUrlUnset(baseUrl: string): void {
+  if (warnedAboutLocalApiUrl || baseUrl !== LOCAL_API_URL || API_URL_FROM_ENV !== undefined) return;
+  if (process.env.NODE_ENV !== 'production') return;
+  warnedAboutLocalApiUrl = true;
+  console.warn(
+    `[theme-kit] QUEEK_API_URL is not set, so server-side reads go to ${LOCAL_API_URL}. ` +
+      'Set QUEEK_API_URL to your Queek API origin in the storefront host environment.',
+  );
+}
+
 export interface RequestOptions extends RequestInit {
   query?: Record<string, string | number | boolean | string[] | null | undefined>;
   /** Abort budget. Omit to leave the request unbounded (browser default). */
@@ -42,41 +60,123 @@ export interface RequestCachePolicy {
 const BROWSER_GET_TIMEOUT_MS = 15_000;
 const BROWSER_POST_TIMEOUT_MS = 25_000;
 
+/** Stable machine-readable code for a failed request. Branch on this, not on the message. */
+export type ApiErrorCode =
+  | 'unauthenticated'
+  | 'forbidden'
+  | 'not_found'
+  | 'rate_limited'
+  | 'client_error'
+  | 'server_error'
+  | 'timeout';
+
+function codeForStatus(status: number): ApiErrorCode {
+  if (status === 401) return 'unauthenticated';
+  if (status === 403) return 'forbidden';
+  if (status === 404) return 'not_found';
+  if (status === 429) return 'rate_limited';
+  return status >= 500 ? 'server_error' : 'client_error';
+}
+
+function nextStepForStatus(status: number, retryAfterSeconds: number | null): string {
+  if (status === 401) return 'The customer session is missing or has expired. Ask the customer to sign in again.';
+  if (status === 403) return 'This session is not allowed to do that on this store.';
+  if (status === 404) return 'The resource does not exist, or it is not visible on this store. Check the slug or id.';
+  if (status === 429) {
+    return retryAfterSeconds === null
+      ? 'Too many requests. Wait a moment, then retry.'
+      : `Too many requests. Retry after ${retryAfterSeconds} seconds.`;
+  }
+  if (status >= 500) return 'The Queek API could not complete the request. Retry shortly; if it keeps failing, quote the request id to Queek support.';
+  return 'The API rejected the request. Check the inputs; `detail` carries the API message when it sent one.';
+}
+
+/** The request path without its query string, so messages and logs never carry search terms or tokens. */
+function pathOnly(url: string): string {
+  const end = url.search(/[?#]/);
+  return end === -1 ? url : url.slice(0, end);
+}
+
+/** Extra context an API failure can carry. All fields are optional. */
+export interface ApiRequestErrorDetails {
+  /** The API's request id (`x-request-id`), for support tickets. */
+  requestId?: string | null;
+  /** Seconds the API asked the caller to wait (`Retry-After`), when it sent one. */
+  retryAfterSeconds?: number | null;
+  /** The API's own error message, when its body carried one. */
+  detail?: string | null;
+}
+
 /**
+ * The API answered with a non-2xx status.
+ *
  * Carries the HTTP status so callers can tell a genuine "this does not exist"
  * (404) apart from an infrastructure failure (5xx, timeout, network). That
  * distinction is load-bearing in a host's vendor layout: 404 must render
- * not-found, while an API blip must NOT — a 404 on every URL of a live store
- * is how storefronts get deindexed.
+ * not-found, while an API blip must NOT, because a 404 on every URL of a live
+ * store is how storefronts get deindexed.
+ *
+ * @example
+ * try {
+ *   await client.get('/products/oak-chair');
+ * } catch (error) {
+ *   if (error instanceof ApiRequestError && error.code === 'not_found') return null;
+ *   throw error;
+ * }
  */
 export class ApiRequestError extends Error {
+  /** Stable machine code derived from the status. */
+  readonly code: ApiErrorCode;
+  /** True when repeating the same request later can succeed (429 and 5xx). */
+  readonly retryable: boolean;
+  readonly requestId: string | null;
+  readonly retryAfterSeconds: number | null;
+  readonly detail: string | null;
+
   constructor(
     public readonly status: number,
     public readonly url: string,
+    { requestId = null, retryAfterSeconds = null, detail = null }: ApiRequestErrorDetails = {},
   ) {
-    super(`Request failed with status ${status}`);
+    super(
+      `Request to ${pathOnly(url)} failed with status ${status}. ${nextStepForStatus(status, retryAfterSeconds)}` +
+        (requestId ? ` (request id ${requestId})` : ''),
+    );
     this.name = 'ApiRequestError';
+    this.code = codeForStatus(status);
+    this.retryable = status === 429 || status >= 500;
+    this.requestId = requestId;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.detail = detail;
   }
 }
 
 /**
+ * The request did not finish inside its time budget and was aborted.
+ *
  * Thrown in place of the raw `DOMException` that `AbortSignal.timeout()`
  * produces. `DOMException` passes `instanceof Error` but its `message` is a
- * getter with no setter — Next's dev bundler (`setup-dev-bundler.js`,
- * `logErrorWithOriginalStack`) unconditionally does `err.message = ...` on
- * anything `instanceof Error` when rendering the dev overlay, which crashes
- * with "Cannot set property message of ... which has only a getter" and
- * cascades into unhandledRejection noise. Rewrapping into a plain, settable
- * Error here — the one place every SSR/browser fetch funnels through — stops
- * that crash without touching the abort/timeout semantics themselves.
+ * getter with no setter, and Next's dev bundler unconditionally assigns
+ * `err.message` on anything `instanceof Error` when rendering its overlay,
+ * which crashes with "Cannot set property message of ... which has only a
+ * getter". Rewrapping into a plain, settable Error here, the one place every
+ * server and browser fetch funnels through, avoids that without changing the
+ * abort semantics. The original `DOMException` stays on `cause`.
  */
 export class ApiTimeoutError extends Error {
+  readonly code: ApiErrorCode = 'timeout';
+  /** A timed-out read can be repeated. A timed-out write may already have reached the API: do not repeat it blindly. */
+  readonly retryable = true;
+
   constructor(
     public readonly url: string,
     public readonly timeoutMs: number,
     { cause }: { cause?: unknown } = {},
   ) {
-    super(`Request to ${url} timed out after ${timeoutMs}ms`);
+    super(
+      `Request to ${pathOnly(url)} timed out after ${timeoutMs}ms. ` +
+        'Retry a read. For a write, check whether it was applied before sending it again.',
+    );
     this.name = 'ApiTimeoutError';
     this.cause = cause;
   }
@@ -94,6 +194,10 @@ export class ApiTimeoutError extends Error {
  * `status` is read structurally rather than via `instanceof`: the class is
  * emitted once per bundler layer, so an `instanceof` check across the RSC/SSR
  * boundary can be silently false.
+ *
+ * @example
+ * const product = await client.get<Product>(`/products/${slug}`).catch(swallowNotFound);
+ * if (!product) notFound();
  */
 export function swallowNotFound(error: unknown): null {
   if ((error as { status?: number } | null)?.status === 404) {
@@ -134,16 +238,48 @@ function withQuery(path: string, query?: RequestOptions['query']): string {
   return queryString === '' ? path : `${path}?${queryString}`;
 }
 
+function readRetryAfterSeconds(response: Response): number | null {
+  const raw = response.headers.get('retry-after');
+  if (raw === null) return null;
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) && seconds >= 0 ? Math.ceil(seconds) : null;
+}
+
+async function readErrorDetail(response: Response): Promise<string | null> {
+  try {
+    const body = (await response.json()) as { message?: unknown } | null;
+    return typeof body?.message === 'string' ? body.message.slice(0, 300) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One JSON request to the Queek API. Everything the kit fetches goes through here.
+ *
+ * Only `/client/*` paths are accepted: that scope resolves the store and forces
+ * the sales channel, so prices are always the storefront's. A write is never
+ * retried: an aborted POST may already have reached the API, and sending it
+ * again could duplicate an order or a payment.
+ *
+ * @throws {ApiRequestError} on a non-2xx response (read `code`, `status`, `requestId`).
+ * @throws {ApiTimeoutError} when `timeoutMs` elapses first.
+ *
+ * @example
+ * const info = await request<{ data: { name: string } }>(API_BASE_URL, '/client/store/info', {
+ *   timeoutMs: 8000,
+ * });
+ */
 export async function request<T>(baseUrl: string, path: string, options: RequestOptions & { credentials?: RequestCredentials } = {}, extraHeaders?: Record<string, string>): Promise<T> {
-  // HARD RULE: the storefront only ever calls the `/v1/client/*` scope. That scope
-  // resolves the vendor AND forces the platform (storefront/instore_qr), so prices
-  // are always the storefront's (no marketplace commission). Legacy v1 routes
-  // (/products, /vendors/*, /categories) skip that resolution → wrong platform →
-  // wrong price. Never call them from here.
   if (!path.startsWith('/client/')) {
-    throw new Error(`Storefront may only call /v1/client/* routes — got "${path}". Use createServerStoreClient / createBrowserClient (which prefix /client/store).`);
+    throw new Error(
+      `Refused to call "${path}": storefront code may only call /client/* routes, which resolve the store and force the storefront sales channel. ` +
+        'Use createServerStoreClient (server) or createBrowserClient (browser); both add the /client/store prefix.',
+    );
   }
 
+  warnIfApiUrlUnset(baseUrl);
+
   const { query, timeoutMs, cachePolicy, ...init } = options;
   const url = `${baseUrl}${withQuery(path, query)}`;
 
@@ -155,9 +291,9 @@ export async function request<T>(baseUrl: string, path: string, options: Request
   };
 
   // Only idempotent, unauthenticated reads may be cached. A POST must always
-  // reach the origin, and a bearer token means the response is per-user — the
-  // data cache is shared across every visitor, so caching either would serve one
-  // customer's data to another.
+  // reach the origin, and a bearer token means the response is per-user: the
+  // data cache is shared across every visitor, so caching either would serve
+  // one customer's data to another.
   const method = (init.method ?? 'GET').toUpperCase();
   const cacheable = method === 'GET' && headers.Authorization === undefined && !!cachePolicy;
 
@@ -182,7 +318,11 @@ export async function request<T>(baseUrl: string, path: string, options: Request
   }
 
   if (!response.ok) {
-    throw new ApiRequestError(response.status, url);
+    throw new ApiRequestError(response.status, url, {
+      requestId: response.headers.get('x-request-id'),
+      retryAfterSeconds: readRetryAfterSeconds(response),
+      detail: await readErrorDetail(response),
+    });
   }
 
   return response.json() as Promise<T>;
@@ -193,8 +333,15 @@ export async function request<T>(baseUrl: string, path: string, options: Request
 // is always forced server-side. Do NOT reintroduce a raw-v1 client here.
 
 /**
- * Browser-side client for client components/hooks.
- * Uses client-store routes (/client/store/*) with Origin + X-Vendor-Slug vendor resolution.
+ * Browser-side client for client components and hooks.
+ *
+ * Calls the same-origin `/api/v1/client/store/*` routes, resolving the store from
+ * the page origin plus the `X-Vendor-Slug` header. Reads time out after 15 s and
+ * writes after 25 s. Failures throw `ApiRequestError` or `ApiTimeoutError`.
+ *
+ * @example
+ * const client = createBrowserClient(vendor.slug);
+ * const { data } = await client.get<{ data: Product[] }>('/products', { per_page: 8 });
  */
 export function createBrowserClient(vendorSlug?: string, token?: string): {
   get: <T>(path: string, query?: RequestOptions['query']) => Promise<T>;

package/sdk/error-handler.ts

@@ -1,13 +1,20 @@
 'use client';
 
-import { QueekSdkError } from '@queekai/client-sdk';
+import { QueekSdkError } from '@usequeek/client-sdk';
 import { useAuthModalStore } from '../stores/auth-modal-store';
 import { useUserStore } from '../stores/user-store';
 import { isReauthSuppressed } from './reauth-guard';
 
 /**
- * Returns true if the caught error is an unauthenticated (401) error
- * from the API or SDK token layer.
+ * True when the error is an unauthenticated (401) failure from the API or the
+ * SDK token layer: the customer session is missing, expired or revoked.
+ *
+ * @example
+ * try {
+ *   await client.get('/client/orders');
+ * } catch (error) {
+ *   if (isUnauthenticatedError(error)) triggerReauth('orders');
+ * }
  */
 export function isUnauthenticatedError(err: unknown): boolean {
   if (err instanceof QueekSdkError) {
@@ -18,19 +25,20 @@ export function isUnauthenticatedError(err: unknown): boolean {
 }
 
 /**
- * Reset local user state and open the auth modal. Safe to call
- * repeatedly (idempotent). Called by the SDK's onUnauthenticated
- * callback (configured in queek-client.ts).
+ * Clear the local customer session and open the sign-in modal. Safe to call
+ * repeatedly. The SDK's `onUnauthenticated` callback (configured in
+ * `queek-client.ts`) calls it, so most code never needs to.
+ *
+ * `reason` (usually the request path) is logged to help trace which call
+ * lost the session. It must not contain tokens.
  */
 export function triggerReauth(reason?: string): void {
   if (isReauthSuppressed()) {
-     
-    console.warn(`[queek-sdk] unauthenticated (${reason ?? 'unknown'}) — suppressed, an auth exchange is in flight`);
+    console.warn(`[theme-kit] a request lost its session (${reason ?? 'unknown request'}), but sign-in is in progress, so the customer was not signed out.`);
     return;
   }
   if (reason) {
-     
-    console.warn(`[queek-sdk] unauthenticated → reauth (${reason})`);
+    console.warn(`[theme-kit] session expired on ${reason}: signing the customer out and opening sign-in.`);
   }
   useUserStore.getState().logout();
   useAuthModalStore.getState().open('login');

package/sdk/queek-client.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { createQueekClient, type QueekClientInstance, type StorageAdapter } from '@queekai/client-sdk';
+import { createQueekClient, type QueekClientInstance, type StorageAdapter } from '@usequeek/client-sdk';
 import { triggerReauth } from './error-handler';
 import { getActivePlatform } from './platform';
 
@@ -75,6 +75,16 @@ export function getLastRequestId(): string | null {
 let cachedClient: QueekClientInstance | null = null;
 let cachedSlug: string | null = null;
 
+/**
+ * The Queek customer SDK client for this store, created once and reused.
+ * Browser only: it keeps the customer's tokens in `localStorage` and sends
+ * every request to the same-origin `/api/v1`. A 401 signs the customer out and
+ * opens the sign-in modal (see `triggerReauth`).
+ *
+ * @example
+ * const client = getQueekClient(vendor.slug);
+ * const orders = await client.get('/client/store/orders');
+ */
 export function getQueekClient(vendorSlug?: string): QueekClientInstance {
   const slug = vendorSlug ?? null;
 
@@ -99,7 +109,7 @@ export function getQueekClient(vendorSlug?: string): QueekClientInstance {
   return cachedClient;
 }
 
-/** Read the current access token for one-off requests outside the SDK (e.g. inbox pairing-code mint). */
+/** The customer's current access token, or null when signed out or on the server. For one-off requests outside the SDK; never log it. */
 export function getAccessToken(): string | null {
   return typeof window !== 'undefined' ? localStorage.getItem(ACCESS_KEY) : null;
 }

package/sdk/server-store-client.ts

@@ -120,8 +120,8 @@ function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolic
 
 /**
  * True when this render is the merchant editor's preview iframe, which loads the
- * storefront with `?preview=true&id=<vendorId>`. Set by `proxy.ts`, which is the only
- * place that can see query params before the fetch layer runs.
+ * storefront with `?preview=true&id=<vendorId>`. Set by the host's request proxy, the
+ * only place that sees query params before the fetch layer runs.
  *
  * A preview render MUST bypass the cache outright rather than rely on the API's
  * invalidation call. Invalidation is a distributed handshake — it needs two env vars

package/shared-blocks/embed.tsx

@@ -2,12 +2,16 @@
 
 import type { JSX } from 'react';
 import type { EmbedBlockData } from '../types/block';
+import { useThemeStrings } from '../provider';
 
 /**
  * Framework-owned embed block. Renders an iframe for any external URL
- * (Instagram, Spotify, Twitter, custom). Themes style via `.core-block-embed`.
+ * (a social post, an audio player, any page that allows embedding). Its words come
+ * from the theme strings (`embed.*`). Themes style via `.core-block-embed`.
  */
 export function CoreEmbedBlock({ url }: EmbedBlockData): JSX.Element {
+  const t = useThemeStrings();
+
   if (!url) {
     return (
       <section className="core-block core-block-embed">
@@ -17,7 +21,7 @@ export function CoreEmbedBlock({ url }: EmbedBlockData): JSX.Element {
               <polyline points="16 18 22 12 16 6" />
               <polyline points="8 6 2 12 8 18" />
             </svg>
-            <span>Paste an Instagram, Spotify, or iframe URL</span>
+            <span>{t('embed.placeholder')}</span>
           </div>
         </div>
       </section>
@@ -30,7 +34,7 @@ export function CoreEmbedBlock({ url }: EmbedBlockData): JSX.Element {
         <iframe
           className="core-block-embed__frame"
           src={url}
-          title="Embedded content"
+          title={t('embed.title')}
           allowFullScreen
           loading="lazy"
           referrerPolicy="no-referrer-when-downgrade"

package/shared-blocks/manifest.ts

@@ -20,7 +20,7 @@ export const FRAMEWORK_BLOCK_MANIFEST: Record<string, ThemeManifestVariant[]> =
     { id: 'default', label: 'Quote', default: true, purpose: 'Pull-quote with optional attribution' },
   ],
   embed: [
-    { id: 'default', label: 'Embed', default: true, purpose: 'Instagram, Spotify, Twitter, or any iframe URL' },
+    { id: 'default', label: 'Embed', default: true, purpose: 'Any page that allows embedding, from its URL' },
   ],
   video: [
     { id: 'default', label: 'Video', default: true, purpose: 'Embed a YouTube, Vimeo, or self-hosted video' },

package/shared-blocks/product-qa.tsx

@@ -80,7 +80,7 @@ function AskQuestionPanel({ productSlug }: { productSlug: string }): JSX.Element
     setError(null);
     try {
       const client = getQueekClient(vendor.slug ?? undefined);
-      await client.post(`/client/store/products/${productSlug}/questions`, { question: trimmed });
+      await client.post(`/client/store/products/${encodeURIComponent(productSlug)}/questions`, { question: trimmed });
       setOpen(false);
       setQuestion('');
       setSubmitted(true);

package/stores/address-modal-store.ts

@@ -8,6 +8,7 @@ interface AddressModalState {
   close: () => void;
 }
 
+/** Open and close state for the delivery address modal. Call `useAddressModalStore.getState().open()` from anywhere, or select from it in a component. */
 export const useAddressModalStore = create<AddressModalState>()((set) => ({
   isOpen: false,
   open: () => set({ isOpen: true }),

package/stores/auth-modal-store.ts

@@ -9,6 +9,7 @@ interface AuthModalState {
   close: () => void;
 }
 
+/** Open and close state for the sign-in modal. `open('signup')` starts on the sign-up step. Most code uses `useAuth()` instead. */
 export const useAuthModalStore = create<AuthModalState>()((set) => ({
   isOpen: false,
   mode: 'login',

package/stores/cart-panel-store.ts

@@ -9,6 +9,7 @@ interface CartPanelState {
   toggle: () => void;
 }
 
+/** Open and close state for the cart panel (drawer). Call `useCartPanelStore.getState().open()` from anywhere, or select from it in a component. */
 export const useCartPanelStore = create<CartPanelState>()((set) => ({
   isOpen: false,
   open: () => set({ isOpen: true }),

package/stores/cart-store.ts

@@ -12,11 +12,11 @@ import { productRequiresVariant } from '../utils/match-variant';
 
 interface CartState {
   items: CartItem[];
-  /** Set once per vendor mount (see vendor-shell.tsx) — the store has no
+  /** Set once per vendor mount by the storefront host. The store has no
    *  React context, so this is how it learns the active vendor's currency
-   *  for GA4 event values. The initial value is the platform default as a
-   *  last resort only; vendor-shell overwrites it with the vendor's currency
-   *  on mount. List-level `meta.currency` is never a source. */
+   *  for analytics event values. The initial value is the platform default as
+   *  a last resort only; the host overwrites it with the vendor's currency on
+   *  mount. List-level `meta.currency` is never a source. */
   currency: string;
   setCurrency: (currency: string) => void;
   addProduct: (product: Product, quantity?: number, variant?: ProductVariant | null) => void;
@@ -25,7 +25,7 @@ interface CartState {
   setQuantity: (id: string, shopId: string, quantity: number) => void;
   clearShopCart: (shopId: string) => void;
   /** Replaces a shop's items with the server-persisted cart — only called when
-   *  the local cart for that shop is empty (see use-cart-sync.ts), so this
+   *  the local cart for that shop is empty (by the storefront host), so this
    *  never clobbers what the customer is actively looking at. */
   adoptServerItems: (shopId: string, items: CartItem[]) => void;
 }
@@ -48,6 +48,11 @@ export function makeItemId(productId: string, addons: CartAddon[], variantId?: s
   return `${base}-${addons.map((addon) => addon.item_id).sort().join(',')}`;
 }
 
+/**
+ * The cart store. Prefer the `useCart()` and `useShopCart()` hooks; read this
+ * directly only from non-React code (`useCartStore.getState()`). Lines persist
+ * in `localStorage` under a per-channel key.
+ */
 export const useCartStore = create<CartState>()(
   persist(
     (set, get) => ({
@@ -62,7 +67,7 @@ export const useCartStore = create<CartState>()(
         // save fails server-side, so persisting one only moves the failure to
         // checkout. Themes gate
         // their add button too, but a theme is presentation — correctness
-        // cannot depend on all seven, or on the next one, getting it right.
+        // cannot depend on every theme getting it right.
         if (!variant && productRequiresVariant(product)) {
           toast({
             title: 'Select options',
@@ -75,7 +80,7 @@ export const useCartStore = create<CartState>()(
         const itemId = makeItemId(product.id, addons, variant?.id);
         const addonTotal = addons.reduce((sum, addon) => sum + addon.price, 0);
         // A variant's own price/stock override the base product's — the same
-        // precedence quick-add-page.tsx's matchedVariant already uses.
+        // precedence the quick-add flow uses.
         const unitPrice = (variant?.pricing.sale_amount ?? product.pricing.sale_amount) + addonTotal;
         const itemImage = variant?.media.thumbnail ?? variant?.media.image ?? product.media.thumbnail ?? product.media.image ?? null;
 

package/stores/checkout-store.ts

@@ -15,7 +15,7 @@ export interface ScheduleSlot {
 export type CheckoutTab = 'summary' | 'checkout';
 export type DeliveryType = 'instant' | 'schedule';
 
-/** The Shipbubble courier the customer picked. Its price is re-derived from the
+/** The courier option the customer picked for automated shipping. Its price is re-derived from the
  *  server-cached quote (via request_token + service_code) at fee/order time —
  *  never trusted from the client — so display == charge. */
 export interface ShipbubbleSelection {
@@ -42,7 +42,7 @@ interface CheckoutState {
   paymentMethodName: string | null;
   selectedBankAccount: SelectedBankAccount | null;
   /** instore_qr dine-in only — which of the vendor's tables the customer is
-   *  sitting at (App\Models\VendorTable id). Null for every other flow. */
+   *  sitting at (the table's id). Null for every other flow. */
   selectedTableId: string | null;
   promoCode: string;
   vendorNote: string;
@@ -53,7 +53,7 @@ interface CheckoutState {
   /** Shipping zone UUID — required for a MANUAL shipping order */
   shippingZoneId: string | null;
   shippingZoneName: string | null;
-  /** The picked Shipbubble courier for an AUTOMATED shipping order (transient) */
+  /** The courier option picked for an AUTOMATED shipping order (transient) */
   shipbubbleSelection: ShipbubbleSelection | null;
   /** Total order weight in kg — needed when selected zone has has_weight_pricing: true */
   weightKg: number | null;
@@ -64,7 +64,7 @@ interface CheckoutState {
   /** Transient. True while the customer is searching/changing their delivery
    *  address — the resolved fee is stale then, so surfaces hide it. */
   isEditingAddress: boolean;
-  /** The customer's saved address (CustomerAddress uuid) currently selected for
+  /** The customer's saved address (its uuid) currently selected for
    *  delivery, when they picked one from their address book instead of
    *  searching a fresh address. Lets the API reuse the cached courier
    *  geocode. Null whenever the address came from a fresh Google search. */

package/stores/location-store.ts

@@ -16,6 +16,11 @@ interface LocationState {
   clearLocation: () => void;
 }
 
+/**
+ * The shopper's chosen delivery location (coordinates and address), persisted
+ * per sales channel. Before one is chosen it holds the platform's default map
+ * centre and an empty address.
+ */
 export const useLocationStore = create<LocationState>()(
   persist(
     (set) => ({

package/stores/orders-sheet-store.ts

@@ -11,6 +11,7 @@ interface OrdersSheetState {
   closeDetail: () => void;
 }
 
+/** Open and close state for the customer's orders sheet. Call `useOrdersSheetStore.getState().open()` from anywhere, or select from it in a component. */
 export const useOrdersSheetStore = create<OrdersSheetState>()((set) => ({
   isOpen: false,
   activeOrderId: null,

package/stores/product-modal-store.ts

@@ -10,6 +10,7 @@ interface ProductModalState {
   close: () => void;
 }
 
+/** Open and close state for the quick-view product modal. Call `useProductModalStore.getState().open()` from anywhere, or select from it in a component. */
 export const useProductModalStore = create<ProductModalState>()((set) => ({
   isOpen: false,
   product: null,

package/stores/search-modal-store.ts

@@ -9,6 +9,7 @@ interface SearchModalState {
   close: () => void;
 }
 
+/** Open and close state for the search modal. Call `useSearchModalStore.getState().open()` from anywhere, or select from it in a component. */
 export const useSearchModalStore = create<SearchModalState>()((set) => ({
   isOpen: false,
   initialQuery: '',

package/stores/user-store.ts

@@ -32,7 +32,7 @@ export interface StorefrontUser {
  * the vendor already has the customer physically present, so a phone is not
  * needed to fulfil the order (matches POS, which never requires it either).
  *
- * `requiresEmail` — pass true for an automated-shipping vendor: Shipbubble's
+ * `requiresEmail` — pass true for an automated-shipping vendor: the
  * courier lookup needs a real email, which a phone-OTP-only signup never has.
  * Defaults false everywhere else so this stays a no-op for every other caller.
  */

package/strings/pseudo-locale.ts

@@ -2,7 +2,7 @@
  * Pseudo-locale QA helper.
  *
  * PURE AND SERVER-SAFE: this module imports nothing from `next/*` and nothing
- * from React, so server components, Node tooling (such as the theme check), tests and the
+ * from React, so server components, Node tooling (such as `npm run check` in a theme starter), tests and the
  * browser all share it (precedent: `utils/locale.ts`, `strings/theme-strings.ts`).
  * Keep it that way.
  *