@usequeek/theme-kit 0.1.23 → 0.1.24

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to `@usequeek/theme-kit`. See the README for the versioning
+policy. Versions before this file started are in the git tags.
+
+## 0.1.24 - 2026-10-12
+
+### Added
+
+- `ApiRequestError` and `ApiTimeoutError` carry a stable `code` (`unauthenticated`,
+  `forbidden`, `not_found`, `rate_limited`, `client_error`, `server_error`,
+  `timeout`) and a `retryable` flag. `ApiRequestError` also carries `requestId`,
+  `retryAfterSeconds` and `detail`. Their messages say what happened and what to do
+  next, and never include the query string.
+- The fetching hooks (`useProducts`, `useProductBySlug`, `useShop`, `usePosts`,
+  `useReviews`, `useProductQuestions`, `useCategories`, `useRelatedProducts`,
+  `useProductDetail`) return an `error` field (`Error | null`).
+- One warning, in production builds only, when `QUEEK_API_URL` is not set.
+- JSDoc with examples on the hooks, providers, clients, stores and the main
+  components.
+
+### Fixed
+
+- `useProducts` and `useShop` no longer leave an unhandled promise rejection when
+  the request fails.
+- Slugs and ids are URL-encoded when they are placed in a request path
+  (products, collections, related products, questions, orders).
+- Google sign-in no longer logs the sign-in URL or the response body.
+- Hook errors raised outside a provider name the missing provider and the fix.
+
+### Packaging
+
+- The published package no longer contains `tests/` or `scripts/`.
+- Peer dependency `@queekai/client-sdk` is `^0.3.1 || ^0.4.0` (was `*`); `engines.node` is
+  `>=22`; `bugs`, `homepage`, `author` and `keywords` are set; releases publish
+  with npm provenance.
+- The licence names the legal entity, Queekx Technology LTD.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Queek
+Copyright (c) 2026 Queekx Technology LTD
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,9 +1,21 @@
 # @usequeek/theme-kit
 
-The framework a Queek storefront theme is built against: hooks, stores, headless
-flows (auth, cart, checkout), types and the block renderer. See the
-[theme documentation](https://docs.usequeek.com/docs/themes) for how themes
-work end to end.
+The runtime a Queek storefront theme is built on: hooks for products, cart, auth
+and search, state stores, the page and block renderer, navigation, shared blocks,
+and locale strings. A theme is React components and CSS; this kit supplies
+everything that talks to Queek. See the
+[theme documentation](https://docs.usequeek.com/docs/themes) for how themes work
+end to end.
+
+## Requirements
+
+- **Next.js 15 or later (App Router)**, `react` and `react-dom` 19 or later. The
+  kit imports `next` itself (links, navigation, server request headers), so it
+  runs inside a Next.js app, not in a bare React app.
+- `@queekai/client-sdk` `^0.3.1 || ^0.4.0`, the Queek customer SDK the auth and checkout
+  hooks call.
+- Node.js 22 or later (the version CI tests on).
+- TypeScript with `moduleResolution: bundler` and `jsx: react-jsx`.
 
 ## Install
 
@@ -11,9 +23,6 @@ work end to end.
 npm install @usequeek/theme-kit
 ```
 
-Peer dependencies: `next` (>=15), `react` and `react-dom` (>=19) and
-`@queekai/client-sdk`.
-
 The package ships TypeScript source, not a build. Most modules carry a
 `'use client'` directive, and that directive is the whole contract with the
 React Server Components boundary; bundlers routinely strip or hoist it when a
@@ -26,10 +35,57 @@ bundler that enforces them:
 export default { transpilePackages: ['@usequeek/theme-kit'] };
 ```
 
-Compiling a theme against it needs `moduleResolution: bundler` and
-`jsx: react-jsx`. A vitest setup that renders kit components needs the package
-inlined (`server.deps.inline: ['@usequeek/theme-kit']`) so the shipped `.tsx`
-source is transformed like first-party code.
+A vitest setup that renders kit components needs the package inlined
+(`server.deps.inline: ['@usequeek/theme-kit']`) so the shipped `.tsx` source is
+transformed like first-party code.
+
+## Quickstart
+
+A product list that loads, handles a failed request, links to each product and
+adds to the cart:
+
+```tsx
+'use client';
+
+import { useCart } from '@usequeek/theme-kit/hooks/use-cart';
+import { useHref } from '@usequeek/theme-kit/hooks/use-href';
+import { useProducts } from '@usequeek/theme-kit/hooks/use-products';
+import { Link } from '@usequeek/theme-kit/navigation';
+import { formatMoney } from '@usequeek/theme-kit/utils/format';
+
+export function PopularProducts() {
+  const { products, isLoading, error } = useProducts({ limit: 4, sort: 'popular' });
+  const { addProduct } = useCart();
+  const href = useHref();
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>We could not load products. Please try again.</p>;
+
+  return (
+    <ul>
+      {products.map((product) => (
+        <li key={product.id}>
+          <Link href={href(`/products/${product.slug}`)}>{product.title}</Link>
+          <span>{formatMoney(product.pricing.sale_amount, product.currency)}</span>
+          <button type="button" onClick={() => addProduct(product)}>
+            Add to cart
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+The storefront mounts `StorefrontProvider` for every theme, so a theme never
+renders it. Hooks called outside it throw an error that says so. In a test or a
+script, wrap the component yourself:
+
+```tsx
+<StorefrontProvider vendor={vendor} config={config} menus={[]}>
+  <PopularProducts />
+</StorefrontProvider>
+```
 
 ## Use
 
@@ -53,6 +109,71 @@ Theme CSS ships with the package: `@usequeek/theme-kit/shared-blocks/core-blocks
 (framework-owned blocks), plus per-component CSS next to its component
 (`components/variant-picker.css`, `apps/apps.css`).
 
+### Hooks
+
+The hooks that fetch (products, shop, categories, posts, reviews, questions,
+related products, product detail) report failure through an `error` field (an
+`Error`, or `null`). They never throw and never leave an unhandled rejection, and
+they keep the data already on screen. They return `isLoading`, except
+`useProductDetail`, which returns `loadingDetail`. In preview, hooks read
+`previewData` from the provider and make no request.
+
+| Hook | Module | Returns |
+| --- | --- | --- |
+| `useProducts(options?)` | `hooks/use-products` | A product list: `{ products, isLoading, error }` |
+| `useProductBySlug(slug)` | `hooks/use-products` | One product by slug: `{ product, isLoading, error }` |
+| `useProductDetail(listProduct, isOpen, vendorSlug?, locale?)` | `hooks/use-product-detail` | A list product completed with variants and add-ons |
+| `useRelatedProducts(slug, limit?)` | `hooks/use-related-products` | Related products |
+| `useShop(options?)` + `useShopParams()` | `hooks/use-shop`, `hooks/use-shop-params` | The shop catalogue page and its URL state |
+| `useCollectionParams()` | `hooks/use-collection-params` | Search, sort and page state for a collection page |
+| `useCategories(options?)` | `hooks/use-categories` | Categories, flattened |
+| `usePosts(options?)` | `hooks/use-posts` | Blog posts |
+| `useReviews(block)` | `hooks/use-reviews` | Reviews and the rating summary |
+| `useProductQuestions(block)` | `hooks/use-product-questions` | Product questions and answers |
+| `useCart()` / `useShopCart(shopId)` | `hooks/use-cart`, `hooks/use-shop-cart` | The cart and its actions; one shop's lines and totals |
+| `useAuth()` | `hooks/use-auth` | The signed-in customer and sign-in modal controls |
+| `useVariantSelection(product)` | `hooks/use-variant-selection` | Option selection state and the add-to-cart gate |
+| `useSearch(query, products, collections)` | `hooks/use-search` | Instant search over data you hold |
+| `useAddressAutocomplete(text)` / `useResolveCoordinates()` | `hooks/use-address-autocomplete`, `hooks/use-resolve-coordinates` | Delivery address lookup |
+| `useHref()` | `hooks/use-href` | Builds a store-relative link |
+| `useLocales()` | `hooks/use-locales` | The store's languages and the active one |
+| `useStorefront()` / `useStorefrontLocale()` / `useThemeStrings()` | `provider` | The store, the request locale, the bound `t` |
+
+## Errors
+
+Requests go through one place (`sdk/client.ts`). A non-2xx answer throws
+`ApiRequestError`, a request that outlives its budget throws `ApiTimeoutError`.
+Branch on `code`, never on the message:
+
+| Field | Meaning |
+| --- | --- |
+| `code` | `unauthenticated` (401), `forbidden` (403), `not_found` (404), `rate_limited` (429), `client_error` (other 4xx), `server_error` (5xx), `timeout` |
+| `status`, `url` | The HTTP status and the full request URL (`ApiRequestError` only) |
+| `retryable` | `true` for 429, 5xx and timeouts. The kit never retries a write on its own: a timed-out POST may already have reached the API. |
+| `requestId` | The API's `x-request-id`, for a support ticket |
+| `retryAfterSeconds` | The API's `Retry-After`, when it sent one |
+| `detail` | The API's own error message, when its body carried one |
+| `cause` | The original `DOMException` (`ApiTimeoutError` only) |
+
+Messages never include the query string, so search terms stay out of logs.
+Server-side fetchers that must render "not found" for a missing resource use
+`swallowNotFound`, which returns `null` for a 404 and rethrows everything else,
+so an API outage never shows as a missing page.
+
+## Configuration (storefront host)
+
+Themes set none of these; the storefront host does.
+
+| Variable | Used for |
+| --- | --- |
+| `QUEEK_API_URL` (or `NEXT_PUBLIC_QUEEK_API_URL`) | Origin of the Queek API for server-side reads. Without it the kit falls back to `http://127.0.0.1:8000/api/v1` and warns once in production builds. |
+| `NEXT_PUBLIC_QUEEK_AUTH_URL` | Origin of the sign-in service (default `https://auth.usequeek.com`). |
+| `STOREFRONT_DOMAIN` | Domain whose subdomains are store slugs (default `queek.com.ng`). |
+| `CUSTOM_DOMAIN_VENDOR_MAP` | JSON object mapping a custom domain to a store slug. |
+
+Browser requests are always same-origin (`/api/v1/client/*`), so the host needs
+a rewrite from that path to the API. The browser never learns the API origin.
+
 ## Theme strings
 
 The kit's UI-string mechanism (`strings/theme-strings.ts`; pure, with no
@@ -292,7 +413,7 @@ export default function Footer() {
 - MUST: place `<PoweredByQueek />` on every footer variant (`footers/*.tsx`,
   or `footer.tsx` where a theme has no `footers/` dir). The placement and
   spacing are the theme's — the component is the content, the footer owns
-  where it sits. The theme check rule `theme/footer-shows-powered-by`
+  where it sits. The `theme/footer-shows-powered-by` rule of `npm run check`
   ([checks reference](https://docs.usequeek.com/docs/themes/checks)) enforces
   this, so a theme cannot ship without it.
 - Style only: the link emits `core-powered-by` with a
@@ -538,8 +659,8 @@ the kit is the one place that knows it, and a framework change is a kit
 release, not an update to every theme. `Link` is an `<a>` that moves inside the
 store without a full page load (`href`, `prefetch`, `replace`, plus any anchor
 attribute); `useRouter()` gives `push`, `replace`, `back` and `refresh`;
-`usePathname()` returns the current path. The theme check rejects a theme that
-imports `next`.
+`usePathname()` returns the current path. `npm run check` in the theme starter rejects a
+theme that imports `next`.
 
 ## Boundary
 
@@ -549,7 +670,7 @@ framework: the kit may import `next`, a theme may not.
 ## Develop
 
 ```bash
-npm install
+npm ci
 npm run typecheck       # tsc --noEmit
 npm test                # public-text check, then vitest run
 npm run verify-package  # pack current source, typecheck a real theme against it
@@ -560,19 +681,41 @@ it from a sandbox, so a break that only external consumers would see (for
 example a module relying on the global `JSX` namespace, which React 19 removed)
 fails here instead of after publishing.
 
+## Versioning
+
+The kit is pre-1.0 (`0.x`). A change to the surface the barrels declare that can
+break a theme ships in a minor version and is listed in
+[CHANGELOG.md](./CHANGELOG.md); patch versions are fixes and additions. Pin a
+minor version (`~0.1.23`) if a theme must not move on its own.
+
 ## Release
 
-Publishing runs on tags via `.github/workflows/publish.yml`, which needs the
-`NPM_TOKEN` repository secret:
+Publishing runs on tags via `.github/workflows/publish.yml`, through npm
+trusted publishing (no stored token), with provenance:
 
 ```bash
-# 1. Bump version in package.json and commit
-# 2. Tag and push the tag — the workflow typechecks, tests, runs verify-package,
-#    then `npm publish --access public`:
+# 1. Bump version in package.json, add the CHANGELOG entry, commit
+# 2. Tag and push the tag. The workflow typechecks, tests, runs verify-package,
+#    then `npm publish --provenance --access public`:
 git tag vX.Y.Z
 git push origin main --tags
 ```
 
+## Contributing
+
+Open an issue or a pull request at
+[usequeek/theme-kit](https://github.com/usequeek/theme-kit). Run `npm run typecheck`
+and `npm test` before you push; CI runs both plus `verify-package`. Keep a change
+to the public surface small, documented with a JSDoc `@example`, and recorded in
+the CHANGELOG.
+
+## Security
+
+The kit holds no secrets and only calls the Queek API's `/client/*` routes (a
+guard in `sdk/client.ts` refuses anything else). Customer tokens live in the
+browser's `localStorage`. To report a vulnerability, use GitHub's private
+vulnerability reporting on this repository rather than a public issue.
+
 ## License
 
-MIT
+MIT, copyright Queekx Technology LTD. See [LICENSE](./LICENSE).

package/api/collections.ts

@@ -8,6 +8,7 @@ import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
  *  gets a 422 from the API. */
 export type CollectionSort = 'newest' | 'popular' | 'price_low' | 'price_high';
 
+/** Options for `fetchCollectionProducts`. */
 export interface FetchCollectionProductsOptions {
   page?: number;
   perPage?: number;
@@ -20,6 +21,10 @@ export interface FetchCollectionProductsOptions {
 // SSR collection reads go through `/client/store/*`, which resolves the store and
 // forces X-Platform=storefront (base prices, no marketplace commission) — never
 // the legacy v1 routes shared with the marketplace.
+/**
+ * The store's collections, for server components. Returns `[]` when the store
+ * has none. A 404 becomes `[]`; any other failure (timeout, 5xx) throws.
+ */
 export async function fetchCollections(vendorSlug: string, storefrontOnly = true, locale?: string): Promise<Collection[]> {
   const client = createServerStoreClient(vendorSlug, await getRequestOrigin());
 
@@ -36,12 +41,20 @@ export async function fetchCollections(vendorSlug: string, storefrontOnly = true
   }
 }
 
+/** One collection by slug, or `null` when it is not in the store's list. */
 export async function fetchCollection(vendorSlug: string, slug: string, locale?: string): Promise<Collection | null> {
   const collections = await fetchCollections(vendorSlug, true, locale);
 
   return collections.find((collection) => collection.slug === slug) ?? null;
 }
 
+/**
+ * A collection and one page of its products, for server components.
+ *
+ * A missing collection gives `{ collection: null, products: [] }`.
+ *
+ * @throws {ApiRequestError} on any other API failure (timeout, 5xx).
+ */
 export async function fetchCollectionProducts(
   vendorSlug: string,
   slug: string,
@@ -63,7 +76,7 @@ export async function fetchCollectionProducts(
   try {
     const [collection, response] = await Promise.all([
       fetchCollection(vendorSlug, slug, options?.locale),
-      client.get<ApiResponse<unknown, Record<string, unknown>>>(`/collections/${slug}/products`, query, options?.locale),
+      client.get<ApiResponse<unknown, Record<string, unknown>>>(`/collections/${encodeURIComponent(slug)}/products`, query, options?.locale),
     ]);
 
     return {

package/api/orders.ts

@@ -1,6 +1,15 @@
 import { createBrowserClient } from '../sdk/client';
 import type { OrderListResponse, OrderDetail } from '../types/order';
 
+/**
+ * One page of the current customer's orders (`GET /client/store/orders`). Pass
+ * a `status` to filter; `'all'` or omitted means no filter.
+ *
+ * @throws {ApiRequestError} when the API refuses; `code: 'unauthenticated'` means the customer must sign in.
+ *
+ * @example
+ * const { data } = await fetchOrders(vendor.slug, 1, 'completed');
+ */
 export async function fetchOrders(
   vendorSlug: string,
   page = 1,
@@ -13,11 +22,16 @@ export async function fetchOrders(
   });
 }
 
+/**
+ * One of the current customer's orders, by id.
+ *
+ * @throws {ApiRequestError} with `code: 'not_found'` when the order does not exist for this customer.
+ */
 export async function fetchOrderDetail(
   vendorSlug: string,
   id: string,
 ): Promise<OrderDetail> {
   const client = createBrowserClient(vendorSlug);
-  const res = await client.get<{ data: OrderDetail }>(`/orders/${id}`);
+  const res = await client.get<{ data: OrderDetail }>(`/orders/${encodeURIComponent(id)}`);
   return res.data;
 }

package/apps/follow-card.tsx

@@ -41,6 +41,11 @@ const POSITION_CLASS: Record<string, string> = {
   'center-left': 'core-follow-card--center-left',
 };
 
+/**
+ * The store's follow card, shown when the merchant has turned it on. It is
+ * floating by default; `display="inline"` places it in the page flow. Renders
+ * nothing when the app is off.
+ */
 export function FollowCard({ display }: { display?: 'floating' | 'inline' } = {}): JSX.Element | null {
   const { config, vendor } = useStorefront();
   const followConfig = config.apps?.follow_card;

package/apps/subscribe-form.tsx

@@ -22,8 +22,8 @@ type Status = 'idle' | 'saving' | 'done' | 'error';
  * The `subscribe` app's `inline` variant (the theme-declared default) — a
  * theme's own `getSubscribeForm` dispatch renders this directly, passing
  * heading/tagline/cta straight through with no gate of its own; gating on
- * `config.apps?.subscribe?.enabled` happens once, centrally, in whichever
- * variant dispatch mounts it (see vendor-shell.tsx / a theme's footer).
+ * `config.apps?.subscribe?.enabled` happens once, centrally, by whatever
+ * mounts it (the storefront host, or a theme's footer).
  */
 export function SubscribeForm({
   heading = 'Stay in the loop',

package/components/auth/auth-flow.tsx

@@ -18,6 +18,18 @@ function AuthFlowInner(): JSX.Element | null {
   return null;
 }
 
+/**
+ * The kit's customer sign-in and sign-up flow (email code, email and password,
+ * and Google), rendered step by step. A theme that wants its own sign-in
+ * layout provides `AuthRenderer` in its module and renders this inside it. Its
+ * markup carries `core-auth*` classes for your CSS, and every string goes
+ * through the theme strings (`auth.*`).
+ *
+ * @example
+ * export function AuthRenderer() {
+ *   return <div className="my-auth-card"><AuthFlow /></div>;
+ * }
+ */
 export function AuthFlow(): JSX.Element {
   return (
     <AuthFlowProvider>

package/components/cart/cart-panel-controller.tsx

@@ -10,6 +10,7 @@ import { useShopCart } from '../../hooks/use-shop-cart';
 import { useCartPanelStore } from '../../stores/cart-panel-store';
 import { normalizeCurrencyCode } from '../../utils/format';
 
+/** What {@link CartPanelController} hands to your render function: the panel state, this shop's lines, and the actions that change them. */
 export interface CartPanelControllerRenderProps {
   isOpen: boolean;
   items: CartItem[];
@@ -23,6 +24,18 @@ export interface CartPanelControllerRenderProps {
   onRemove: (id: string, shopId: string) => void;
 }
 
+/**
+ * Headless controller for a cart panel (drawer). It owns open and close state,
+ * the Escape key, scroll locking and navigation to checkout; you own the markup.
+ * Open it from anywhere with `useCartPanelStore.getState().open()`.
+ *
+ * @example
+ * <CartPanelController>
+ *   {({ isOpen, items, total, onClose, onCheckout }) =>
+ *     isOpen ? <MyDrawer items={items} total={total} onClose={onClose} onCheckout={onCheckout} /> : <></>
+ *   }
+ * </CartPanelController>
+ */
 export function CartPanelController({
   children,
 }: {

package/components/checkout/default-checkout-shell.tsx

@@ -8,6 +8,11 @@ import { CheckoutContactSection } from './checkout-contact';
 import { useThemeStrings } from '../../provider';
 import { PolicyLinks } from './policy-links';
 
+/**
+ * The kit's default checkout layout. The storefront fills its slots (address,
+ * payment, promo, fees, submit) and passes them in; a theme can replace the
+ * whole shell by providing its own checkout component.
+ */
 export function DefaultCheckoutShell({
   cartItems,
   deliveryModes,

package/components/checkout/policy-links.tsx

@@ -23,6 +23,10 @@ function subscribeNoop(): () => void {
   return () => {};
 }
 
+/**
+ * Links to the store's published policies (returns, shipping, privacy, terms).
+ * Each opens in the kit's policy modal. Renders nothing when `policies` is empty.
+ */
 export function PolicyLinks({ policies }: { policies: Page[] }): JSX.Element | null {
   const t = useThemeStrings();
   const activeSlug = usePolicyModalStore((s) => s.activeSlug);

package/components/image.tsx

@@ -23,6 +23,7 @@ const PLACEHOLDER_SVG = `data:image/svg+xml,${encodeURIComponent(
   </svg>`,
 )}`;
 
+/** A labelled placeholder drawn in place of an image that is missing or failed to load. Size it to the space the image will fill. */
 export interface PlaceholderProp {
   label?: string;
   sublabel?: string;
@@ -59,6 +60,15 @@ type ImageProps = ImgHTMLAttributes<HTMLImageElement> & {
  */
 type LoadStage = 'primary' | 'original' | 'failed';
 
+/**
+ * The kit's image element. Use it instead of a raw `<img>`: it picks a
+ * responsive `srcset` from the API's image variants, retries the original file
+ * when a resized one fails, and falls back to `fallback` or a branded
+ * placeholder. It accepts every `<img>` attribute.
+ *
+ * @example
+ * <Image src={product.media.image ?? ''} variants={product.media.image_variants} intent="card" alt={product.title} />
+ */
 export function Image({ fallback, placeholder, variants, intent = 'raw', onError, ...props }: ImageProps) {
   const [stage, setStage] = useState<LoadStage>('primary');
   // Read context directly — returns null outside a StorefrontProvider

package/components/language-switcher.tsx

@@ -9,6 +9,7 @@ import type { MenuAlign, MenuSide } from '../utils/menu-placement';
 import { LanguageMenu } from './language-menu';
 import './language-switcher.css';
 
+/** Props for `LanguageSwitcher`. The README lists each prop with its default. */
 export interface LanguageSwitcherProps {
   /** Extra class on the root, to position or restyle the control. */
   className?: string;

package/components/powered-by-queek.tsx

@@ -4,6 +4,7 @@ import { useContext, type JSX } from 'react';
 import { StorefrontContext } from '../provider';
 import { poweredByQueekUrl } from '../utils/powered-by';
 
+/** Props for {@link PoweredByQueek}. */
 export interface PoweredByQueekProps {
   /** Extra class so a footer can position the link — styling stays theme-owned. */
   className?: string;
@@ -15,11 +16,11 @@ export interface PoweredByQueekProps {
 }
 
 /**
- * Core-owned storefront attribution — the `ProductMetafields` pattern: themes
- * import-and-place it, never re-implement it.
+ * The storefront attribution link, owned by the kit: themes import and place
+ * it, and never re-implement it.
  *
  * Required on every footer variant of every theme (enforced by the
- * `theme/footer-shows-powered-by` rule of the theme check). The link
+ * `theme/footer-shows-powered-by` rule of `npm run check`). The link
  * target (`https://usequeek.com/business`) and `rel` are the contract —
  * do not change them. The href is tagged `utm_source=powered_by`,
  * `utm_medium=storefront`, `utm_campaign=<store slug>` via `poweredByQueekUrl`

package/components/product-media-frame.tsx

@@ -19,6 +19,11 @@ interface ProductMediaFrameProps {
   intent?: ImageIntent;
 }
 
+/**
+ * One frame of a product's media gallery: an image through `Image`, or a video.
+ * Pass a frame from `buildMediaFrames(product)`. `variant="thumbnail"` renders a
+ * muted video with no controls, so the browser shows its first frame.
+ */
 export function ProductMediaFrame({
   frame,
   className,

package/components/product-metafields.tsx

@@ -7,10 +7,12 @@ import type {
 } from '../types/product';
 import { formatDisplayDate } from '../utils/format';
 
+/** Merchant-set labels and types for custom fields, keyed by field key. Passed as `metafieldDefinitions` on the product page. */
 export interface ProductMetafieldDefinitionLabels {
   [key: string]: { name: string; type: string };
 }
 
+/** Props for {@link ProductMetafields}. */
 export interface ProductMetafieldsProps {
   product: Product;
   definitions?: ProductMetafieldDefinitionLabels;
@@ -205,6 +207,13 @@ export function renderValue(value: MetafieldValue, fieldKey: string, label: stri
   return renderScalar(value as MetafieldScalar, fieldKey, label, type);
 }
 
+/**
+ * Place this on the product page to show the product's custom fields.
+ * Renders nothing when there are none to show.
+ *
+ * @example
+ * <ProductMetafields product={product} definitions={metafieldDefinitions} />
+ */
 export function ProductMetafields({ product, definitions }: ProductMetafieldsProps): JSX.Element | null {
   const metafields = product.metafields && typeof product.metafields === 'object' ? product.metafields : {};
   const visible = Object.entries(metafields).filter(([, value]) => isVisibleValue(value as MetafieldValue));

package/components/variant-picker.css

@@ -1,11 +1,8 @@
 /* ============================================================
-   VariantPicker — shared option-selection UI (QR ordering sheet,
-   default theme's quick-view modal). Prefix: qk-variant-.
-   Reads --brand-* directly (not a context-scoped token set like
-   --qr- or --qka-) so it renders correctly regardless of which
-   surface mounts it. Mirrors quick-add-page.css's qka-option/qka-swatch
-   rules — same visual language, kept as a separate small file since
-   this component is reused outside that page's scope.
+   VariantPicker: shared option-selection UI (in-store ordering sheet,
+   quick-view modal). Class prefix: qk-variant-.
+   Reads --brand-* directly, not a surface-scoped token set, so it renders
+   correctly whichever surface mounts it.
    ============================================================ */
 
 .qk-variant-option {

package/edit-mode.tsx

@@ -6,9 +6,10 @@ import dynamic from 'next/dynamic';
 
 const QK_EDIT_FLAG = 'edit';
 
-// Lightweight: reads `?edit=1` once on mount. Always shipped to the
-// storefront bundle, but cheap (one URLSearchParams parse) and adds no
-// runtime overhead for public visitors.
+/**
+ * True when the page was opened by the merchant editor (`?edit=1`). Read once
+ * on mount. Cheap enough to ship to every visitor: one query-string parse.
+ */
 export function useEditMode(): boolean {
   const [isEdit, setIsEdit] = useState(false);
 

package/hooks/use-address-autocomplete.ts

@@ -4,6 +4,7 @@ import { useEffect, useState } from 'react';
 import { useStorefront } from '../provider';
 import { getQueekClient } from '../sdk/queek-client';
 
+/** One address suggestion. Pass `place_id` to `useResolveCoordinates` to get its position. */
 export interface AddressSuggestion {
   description: string;
   place_id: string;
@@ -11,6 +12,14 @@ export interface AddressSuggestion {
 
 const DEBOUNCE_MS = 300;
 
+/**
+ * Address suggestions for what the shopper has typed, after a 300 ms pause.
+ * Nothing is requested for fewer than two characters. A failed request clears
+ * the suggestions rather than throwing, so the field stays usable.
+ *
+ * @example
+ * const { suggestions, loading } = useAddressAutocomplete(text);
+ */
 export function useAddressAutocomplete(query: string): {
   suggestions: AddressSuggestion[];
   loading: boolean;