@lime-bundles/react 1.0.0 → 2.1.0

package/docs/hydrogen.md

@@ -0,0 +1,185 @@
+# Hydrogen
+
+> **Before you start:** most Hydrogen merchants don't need this guide. The [web component](./web-component.md) (`<lime-bundle>`) works inside any Hydrogen page and handles cart and checkout via Shopify's tokenless Storefront Cart API. Paste the snippet from `/app/settings/headless` into your product route and you're done. Reach for this guide only when you want React components (`<FixedBundle>`) that thread cart mutations through Hydrogen's `useCart` state.
+
+SSR-first integration: fetch the bundle server-side in a route loader, hydrate a `<FixedBundle>` (or volume / mix-match) with Hydrogen's `useCart` for the add-to-cart callback.
+
+## Install
+
+```bash
+npm install @lime-bundles/react @lime-bundles/core
+```
+
+`@lime-bundles/core` is a transitive dependency. Installing it explicitly lets you call `fetchBundleData` from a loader without pulling React.
+
+## Environment
+
+Open `/app/settings/headless` in your Lime Bundles admin, click **Generate token**, then append the value to your Hydrogen project's `.env`:
+
+```bash
+# Existing values you already had: keep these as-is
+PUBLIC_STORE_DOMAIN=my-shop.myshopify.com
+PUBLIC_STOREFRONT_API_TOKEN=<your existing Shopify Storefront token>
+
+# New: Lime Bundles' own Storefront token
+PUBLIC_LIME_BUNDLES_TOKEN=<paste the generated token>
+```
+
+The variable is intentionally namespaced so it doesn't collide with the `PUBLIC_STOREFRONT_API_TOKEN` that Shopify's Headless app issues for your primary storefront. Lime Bundles uses its own Storefront Access Token, scoped to bundle metaobjects and product listings only.
+
+Lime Bundles creates the token for you via Shopify's Admin API. No custom-app configuration needed (Shopify deprecated that flow on 2026-01-01). The token carries the read-only scopes `unauthenticated_read_metaobjects` and `unauthenticated_read_product_listings` and nothing else. To rotate, click **Regenerate** on the same page. It revokes the current token and issues a new one atomically.
+
+## Getting a bundle GID
+
+Each bundle you create in the Lime Bundles admin has a Shopify Metaobject GID (`gid://shopify/Metaobject/<numericId>`). You have two ways to use it:
+
+- **Pin one bundle**: hardcode the GID. Find it in the admin at `/app/bundles/<id>/analytics` (URL), or by inspecting a bundle's API response.
+- **Render every bundle configured against a product**: skip the explicit GID and use `fetchBundlesForProduct({ productHandle })` instead. Hand it the product handle from your loader; it returns every active bundle the merchant attached to that product. See the [React guide](./react-nextjs.md#auto-fetch-every-bundle-for-a-product) for the client-side `useBundlesForProduct` hook.
+
+Both patterns are shown below.
+
+## Fetch a specific bundle in a loader
+
+Hydrogen runs on Oxygen, where `process.env` is not available in the browser. Surface the values the route component needs through the loader. Oxygen injects environment variables as `context.env`:
+
+```tsx
+// app/routes/products.$handle.tsx
+import { fetchBundleData } from "@lime-bundles/react";
+import { useLoaderData } from "@shopify/remix-oxygen";
+import type { LoaderFunctionArgs } from "@shopify/remix-oxygen";
+
+export async function loader({ request, context }: LoaderFunctionArgs) {
+  const shopDomain = context.env.PUBLIC_STORE_DOMAIN;
+  const storefrontAccessToken = context.env.PUBLIC_LIME_BUNDLES_TOKEN;
+  const bundleGid = "gid://shopify/Metaobject/123456789";
+
+  const bundle = await fetchBundleData({
+    shopDomain,
+    storefrontAccessToken,
+    bundleGid,
+    // Required on SSR. Without it Shopify may return 430 Security Rejection
+    // for server-originated traffic on a private token. `x-forwarded-for` is
+    // set by Oxygen and most other hosts; take the first IP in the list.
+    buyerIp:
+      request.headers.get("x-forwarded-for")?.split(",")[0].trim() ?? undefined,
+  });
+
+  return { bundle, shopDomain, storefrontAccessToken, bundleGid };
+}
+```
+
+`fetchBundleData` throws `StorefrontApiError` on HTTP / GraphQL failure and `BundleParseError` when the metaobject is missing, inactive, not yet scheduled, or expired. Hydrogen surfaces thrown loader errors via its standard `ErrorBoundary`.
+
+## Fetch every bundle for a product (auto-detect)
+
+If you'd rather not pin a GID, use `fetchBundlesForProduct` in the loader. Pass it the product handle from route params and it returns every active bundle the merchant attached to that product (inactive, draft, not-yet-started, and expired bundles are filtered out):
+
+```tsx
+// app/routes/products.$handle.tsx
+import { fetchBundlesForProduct } from "@lime-bundles/react";
+import type { LoaderFunctionArgs } from "@shopify/remix-oxygen";
+
+export async function loader({ request, params, context }: LoaderFunctionArgs) {
+  const shopDomain = context.env.PUBLIC_STORE_DOMAIN;
+  const storefrontAccessToken = context.env.PUBLIC_LIME_BUNDLES_TOKEN;
+
+  const bundles = await fetchBundlesForProduct({
+    shopDomain,
+    storefrontAccessToken,
+    productHandle: params.handle!,
+    buyerIp:
+      request.headers.get("x-forwarded-for")?.split(",")[0].trim() ?? undefined,
+  });
+
+  return { bundles, shopDomain, storefrontAccessToken };
+}
+```
+
+The route component then maps the list and renders the right component per `bundleType` (see the [React guide](./react-nextjs.md#auto-fetch-every-bundle-for-a-product)). Prefer this shape when the product has more than one bundle configured or when you don't want to redeploy each time a merchant swaps bundles.
+
+For a purely client-side version (no loader), use the `useBundlesForProduct` hook in a component.
+
+## Render and wire cart
+
+```tsx
+// Same file: route component
+import { FixedBundle } from "@lime-bundles/react";
+import { useCart } from "@shopify/hydrogen-react";
+
+export default function ProductRoute() {
+  const { shopDomain, storefrontAccessToken, bundleGid } =
+    useLoaderData<typeof loader>();
+  const { linesAdd } = useCart();
+
+  return (
+    <FixedBundle
+      shopDomain={shopDomain}
+      storefrontAccessToken={storefrontAccessToken}
+      bundleGid={bundleGid}
+      onAddToCart={async (lines) => {
+        await linesAdd(lines);
+      }}
+      onError={(err) => console.error("Bundle error", err)}
+    />
+  );
+}
+```
+
+The component fetches the bundle client-side via `useBundleData` on mount. Server-side prefetching in the loader warms Shopify's CDN cache so the client-side fetch returns instantly. If you want to avoid the duplicate fetch entirely, pass the `bundle` prop from the loader into a client component that renders directly without the Lime Bundles component. See [React guide](./react-nextjs.md#ssr-without-refetch) for that pattern.
+
+## The cart contract
+
+`onAddToCart` receives a Hydrogen-compatible `CartLineInput[]`:
+
+```ts
+type CartLineInput = {
+  merchandiseId: string;       // variant GID
+  quantity: number;
+  attributes: Array<{ key: string; value: string }>;
+};
+```
+
+The `attributes` array always includes `{ key: "_lime_bundle_gid", value: <bundle GID> }`. **Do not strip this.** The `orders/create` webhook relies on it for purchase attribution. Hydrogen's `cart.linesAdd` preserves custom attributes through checkout by default.
+
+## Worked example: Volume bundle
+
+```tsx
+import { VolumeBundle } from "@lime-bundles/react";
+
+<VolumeBundle
+  shopDomain={SHOP_DOMAIN}
+  storefrontAccessToken={TOKEN}
+  bundleGid="gid://shopify/Metaobject/42"
+  onAddToCart={async (lines) => {
+    await linesAdd(lines);
+  }}
+/>
+```
+
+The component renders tier cards, auto-selects the configured default tier, and calls `onAddToCart` with the chosen tier's merchandise and quantity.
+
+## Styling and merchant widget config
+
+The React SDK does **not** automatically apply the widget styles the merchant set in the admin editor. That's deliberate. If you chose `@lime-bundles/react` on Hydrogen you likely want full control over the look so bundles match your storefront's design system.
+
+Every `ParsedBundle` that `fetchBundleData` resolves to exposes the merchant's full config as `bundle.widgetConfig`. Read any field you want from it:
+
+```tsx
+<button style={{ background: bundle.widgetConfig.cta.primaryColor }}>
+  {bundle.widgetConfig.cta.ctaText}
+</button>
+```
+
+Want drop-in parity with the admin preview instead? Swap to the [web component](./web-component.md): it honours `widgetConfig` end-to-end without any wiring on your side.
+
+Full field list in [`packages/core/src/bundle/types.ts`](../../packages/core/src/bundle/types.ts). Helpers `WIDGET_CONFIG_DEFAULTS`, `mergeWidgetConfig`, `flattenWidgetConfig`, and `applyWidgetConfigVars` are exported from `@lime-bundles/core` if you want to apply the CSS custom properties to your own DOM.
+
+## What's NOT your job
+
+- **Purchase attribution.** The Lime Bundles `orders/create` webhook scans every line item's `_lime_bundle_gid` attribute and records a `bundle_purchased` AnalyticsEvent. Don't add client-side `checkout_completed` tracking; it double-counts.
+- **Custom CSS.** If merchants configure custom CSS in `/app/settings/custom-css`, `useBundleData` auto-fetches and injects a scoped `<style>` tag. No action needed.
+
+## Next steps
+
+- [CSS variables reference](./css-variables.md): brand-match the widget to your theme.
+- [Web component guide](./web-component.md): fallback for sections of the site that aren't React-controlled.

package/docs/react-nextjs.md

@@ -0,0 +1,379 @@
+# React / Next.js / Vite
+
+> **Before you start:** you may not need this guide. The [web component](./web-component.md) (`<lime-bundle>`) works inside any React app. Paste it into your JSX like any other custom element, handle cart and checkout via Shopify's tokenless Storefront Cart API, zero configuration. Use this guide only when you want React components (`<FixedBundle>`, `<VolumeBundle>`, `<MixMatchBundle>`) with type-safe props and cart integration through your existing React state.
+
+`@lime-bundles/react` works anywhere React does. This guide covers Next.js App Router, Pages Router, and Vite / CRA. For Remix on Oxygen, see the [Hydrogen guide](./hydrogen.md). Hydrogen is Remix under the hood, and the loader pattern there applies unchanged. BYO-cart: Lime Bundles renders and tracks analytics; you wire up your own cart mutation.
+
+## Install
+
+```bash
+npm install @lime-bundles/react @lime-bundles/core
+```
+
+React ≥18 and react-dom ≥18 are peer dependencies.
+
+## Environment
+
+Open `/app/settings/headless` in your Lime Bundles admin, click **Generate token**, then append the value to your project. Don't overwrite the Shopify Storefront token your app already uses:
+
+```bash
+# .env.local (Next.js) or .env (Vite)
+NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN=my-shop.myshopify.com
+NEXT_PUBLIC_LIME_BUNDLES_TOKEN=<paste the generated token>
+
+# Vite: same name with the VITE_ prefix instead
+# VITE_LIME_BUNDLES_TOKEN=<paste the generated token>
+```
+
+The variable is intentionally namespaced to `LIME_BUNDLES_` so it doesn't collide with the Storefront API token Shopify's own Headless app issues for your primary storefront. Lime Bundles uses its own Storefront Access Token, scoped to bundle metaobjects and product listings only.
+
+The `NEXT_PUBLIC_` prefix (or `VITE_` for Vite) exposes the value to client bundles. Lime Bundles creates the token for you via Shopify's Admin API. No custom-app setup needed (Shopify deprecated that flow on 2026-01-01). The token is a read-only public Storefront Access Token with `unauthenticated_read_metaobjects` and `unauthenticated_read_product_listings` scopes, safe to ship in client code. To rotate, click **Regenerate** in the admin. It atomically revokes the old token and issues a new one.
+
+## Pick a rendering mode
+
+Before you drop a component into a route, decide which bundles you want to show.
+
+- **All bundles on this product** (the standard Shopify behaviour). Use [`useBundlesForProduct({ productHandle })`](#auto-fetch-every-bundle-for-a-product). Hand it a product handle from your router (`params.handle`, `params.slug`, etc.) and render whatever comes back.
+- **One specific bundle, pinned to this page.** Hardcode the bundle's Shopify Metaobject GID (you can copy it from the URL of the bundle's analytics page in the admin) and pass it to `<FixedBundle>` / `<VolumeBundle>` / `<MixMatchBundle>` via `bundleGid`.
+
+Most product-page integrations want the first pattern. Landing-pages / curated placements want the second.
+
+## Next.js App Router (client-only, pin one bundle)
+
+```tsx
+// app/bundles/[id]/page.tsx
+"use client";
+
+import { FixedBundle } from "@lime-bundles/react";
+
+export default function BundlePage({ params }: { params: { id: string } }) {
+  return (
+    <FixedBundle
+      shopDomain={process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!}
+      storefrontAccessToken={process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN!}
+      bundleGid={`gid://shopify/Metaobject/${params.id}`}
+      onAddToCart={async (lines) => {
+        // Wire your cart here. Storefront Cart API, a Route Handler, etc.
+        await fetch("/api/cart/add", {
+          method: "POST",
+          body: JSON.stringify(lines),
+        });
+      }}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+The component fetches the bundle on mount via `useBundleData`, manages loading / error state internally, and calls `onAddToCart` when the merchant clicks the CTA.
+
+## Next.js App Router (server-fetch + client-render)
+
+Fetch the bundle in a Server Component, render it in a Client Component. This avoids the client-side network round-trip on first paint.
+
+```tsx
+// app/bundles/[id]/page.tsx (server component, no "use client")
+import { fetchBundleData } from "@lime-bundles/react";
+import { BundleClient } from "./BundleClient";
+import { headers } from "next/headers";
+
+export default async function BundlePage({ params }: { params: { id: string } }) {
+  const h = await headers();
+  const bundle = await fetchBundleData({
+    shopDomain: process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!,
+    storefrontAccessToken: process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN!,
+    bundleGid: `gid://shopify/Metaobject/${params.id}`,
+    buyerIp: h.get("x-forwarded-for")?.split(",")[0] ?? undefined,
+  });
+
+  return <BundleClient bundle={bundle} />;
+}
+```
+
+```tsx
+// app/bundles/[id]/BundleClient.tsx
+"use client";
+import type { ParsedBundle } from "@lime-bundles/react";
+
+export function BundleClient({ bundle }: { bundle: ParsedBundle }) {
+  // Render directly from the prop. No fetch needed.
+  // Wire up your own UI here, or pass to <FixedBundle> if you still
+  // want the components to double-check liveness via useBundleData.
+  return <pre>{JSON.stringify(bundle, null, 2)}</pre>;
+}
+```
+
+### SSR without refetch
+
+If you want server-rendered HTML *and* the Lime Bundles React components, pass the server-fetched bundle through React Query / SWR / a context, and have the inner component skip its own `useBundleData` call. A lightweight pattern: fork `<FixedBundle>` into your own component and copy the rendering logic (~80 lines). The SDK exports the bundle data type so this is straightforward.
+
+## Next.js Pages Router
+
+Use `getServerSideProps`:
+
+```tsx
+import { fetchBundleData, FixedBundle, type ParsedBundle } from "@lime-bundles/react";
+import type { GetServerSideProps } from "next";
+
+export const getServerSideProps: GetServerSideProps = async ({ req, params }) => {
+  const bundle = await fetchBundleData({
+    shopDomain: process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!,
+    storefrontAccessToken: process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN!,
+    bundleGid: `gid://shopify/Metaobject/${params!.id}`,
+    buyerIp: (req.headers["x-forwarded-for"] as string)?.split(",")[0],
+  });
+  return { props: { bundle } };
+};
+
+export default function Page({ bundle }: { bundle: ParsedBundle }) {
+  return (
+    <FixedBundle
+      shopDomain={process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!}
+      storefrontAccessToken={process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN!}
+      bundleGid={bundle.id}
+      onAddToCart={async (lines) => {
+        await fetch("/api/cart/add", { method: "POST", body: JSON.stringify(lines) });
+      }}
+    />
+  );
+}
+```
+
+## Vite / CRA
+
+```tsx
+import { FixedBundle } from "@lime-bundles/react";
+
+export function App() {
+  return (
+    <FixedBundle
+      shopDomain={import.meta.env.VITE_SHOPIFY_STORE_DOMAIN}
+      storefrontAccessToken={import.meta.env.VITE_LIME_BUNDLES_TOKEN}
+      bundleGid="gid://shopify/Metaobject/123"
+      onAddToCart={async (lines) => {
+        await fetch("/cart/add", { method: "POST", body: JSON.stringify(lines) });
+      }}
+    />
+  );
+}
+```
+
+## Styling and merchant widget config
+
+The React SDK does **not** automatically apply the widget styles the merchant set in the admin editor. That's deliberate. If you chose `@lime-bundles/react`, you almost certainly want full control over the look so bundles match your storefront's design system.
+
+Every `ParsedBundle` (the object `fetchBundleData` resolves to and `useBundleData` hands you) exposes the merchant's full config as `bundle.widgetConfig`. Read any field you want:
+
+```tsx
+function BundleCTA({ bundle }: { bundle: ParsedBundle }) {
+  return (
+    <button style={{ background: bundle.widgetConfig.cta.primaryColor }}>
+      {bundle.widgetConfig.cta.ctaText}
+    </button>
+  );
+}
+```
+
+Want drop-in parity with the admin preview (same header, save badge, product list, etc.) without writing markup? Swap to the [web component](./web-component.md) instead; it honours `widgetConfig` end-to-end.
+
+The shape of `widgetConfig` is stable at v2.0.0. See [`packages/core/src/bundle/types.ts`](../../packages/core/src/bundle/types.ts) for the full field list. Helpers `WIDGET_CONFIG_DEFAULTS`, `mergeWidgetConfig`, `flattenWidgetConfig`, and `applyWidgetConfigVars` are exported from `@lime-bundles/core` if you want to apply the CSS custom properties onto your own DOM instead of reading fields one at a time.
+
+## Auto-fetch every bundle for a product
+
+The web component's default mode is "show every active bundle configured against the current product." The React SDK equivalent is `useBundlesForProduct`:
+
+```tsx
+import {
+  useBundlesForProduct,
+  FixedBundle,
+  VolumeBundle,
+  MixMatchBundle,
+  type CartLineInput,
+} from "@lime-bundles/react";
+
+const SHOP_DOMAIN = process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!;
+const TOKEN = process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN!;
+
+function ProductBundles({ handle }: { handle: string }) {
+  const result = useBundlesForProduct({
+    shopDomain: SHOP_DOMAIN,
+    storefrontAccessToken: TOKEN,
+    productHandle: handle,
+  });
+
+  if (result.status === "loading") return null;          // or your own skeleton
+  if (result.status === "error") return null;
+  if (result.bundles.length === 0) return null;
+
+  const cartProps = {
+    shopDomain: SHOP_DOMAIN,
+    storefrontAccessToken: TOKEN,
+    onAddToCart: async (lines: CartLineInput[]) => {
+      await fetch("/api/cart/add", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ lines }),
+      });
+    },
+  };
+
+  return (
+    <>
+      {result.bundles.map((bundle) => {
+        switch (bundle.bundleType) {
+          case "fixed":
+            return <FixedBundle key={bundle.id} bundleGid={bundle.id} {...cartProps} />;
+          case "volume":
+            return <VolumeBundle key={bundle.id} bundleGid={bundle.id} {...cartProps} />;
+          case "mix_match":
+            return <MixMatchBundle key={bundle.id} bundleGid={bundle.id} {...cartProps} />;
+        }
+      })}
+    </>
+  );
+}
+```
+
+Inactive, draft, not-yet-started, and expired bundles are filtered out by the hook; consumers don't need to guard.
+
+For SSR / Hydrogen loaders, use `fetchBundlesForProduct` (the async helper `useBundlesForProduct` wraps) and pass the list as a prop to a client component.
+
+## Build your own UI (DIY path)
+
+If the built-in `<FixedBundle>` / `<VolumeBundle>` / `<MixMatchBundle>` components aren't the right fit (you want a radically different layout, or you want to compose bundles into an existing design system), `@lime-bundles/react` re-exports every primitive the first-party widget uses. You never have to reverse-engineer our totals or CSS variables.
+
+**Data + parsing:**
+
+```tsx
+import {
+  createStorefrontClient,
+  fetchBundlesForProduct,
+  parseMetaobjectBundle,
+  BUNDLE_METAOBJECT_QUERY,
+  BUNDLES_FOR_PRODUCT_QUERY,
+} from "@lime-bundles/react";
+```
+
+**Pricing math (matches Shopify Discount Function per-unit floor rounding):**
+
+```tsx
+import {
+  parseCents,
+  formatCents,
+  percentageDiscountUnit,
+  computeFixedPricing,
+  computeBundleSaleCents,
+  calculateTierSavings,
+  getActiveTier,
+} from "@lime-bundles/react";
+
+const pricing = computeFixedPricing(bundle);
+// { rows, totalCents, saleCents, savingsCents, headerBadge, currency }
+```
+
+**Merchant widget config → CSS variables:**
+
+```tsx
+import {
+  WIDGET_CONFIG_DEFAULTS,
+  mergeWidgetConfig,
+  applyWidgetConfigVars,
+  CSS_VAR_MAP,
+} from "@lime-bundles/react";
+
+useEffect(() => {
+  if (wrapperRef.current) {
+    applyWidgetConfigVars(wrapperRef.current, bundle.widgetConfig);
+  }
+}, [bundle.widgetConfig]);
+```
+
+**Image URL transforms (Shopify CDN 152×152 thumbnails):**
+
+```tsx
+import { transformImageUrl } from "@lime-bundles/react";
+
+<img
+  src={transformImageUrl(product.featuredImage.url, { width: 152, height: 152, crop: "center" })}
+  width={152}
+  height={152}
+  loading="lazy"
+  alt={product.title}
+/>
+```
+
+**Countdown timer:**
+
+```tsx
+import { formatCountdown } from "@lime-bundles/react";
+
+const [msLeft, setMsLeft] = useState(Date.parse(bundle.endsAt!) - Date.now());
+useEffect(() => {
+  const id = setInterval(() => setMsLeft(Date.parse(bundle.endsAt!) - Date.now()), 1000);
+  return () => clearInterval(id);
+}, [bundle.endsAt]);
+
+return <span>{formatCountdown(msLeft)}</span>;
+```
+
+**A/B variant resolution:**
+
+```tsx
+import { getABTestAssignment, applyABVariantB } from "@lime-bundles/react";
+
+// appUrl is your Lime Bundles app URL (same value your theme app block uses).
+// shopDomain is the merchant's *.myshopify.com domain.
+const appUrl = process.env.NEXT_PUBLIC_LIME_BUNDLES_APP_URL!;
+const shopDomain = process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!;
+
+const assignment = await getABTestAssignment(
+  appUrl,
+  shopDomain,
+  bundle.abTestId!,
+  bundle.id,
+);
+const bundleForRender = assignment?.variant === "B" ? applyABVariantB(bundle) : bundle;
+```
+
+**Analytics + consent:**
+
+```tsx
+import {
+  reportImpression,
+  reportAddToCart,
+  observeImpression,
+  setConsent,
+  hasConsent,
+} from "@lime-bundles/react";
+```
+
+**Custom CSS injection:**
+
+```tsx
+import { injectCustomCss, sanitizeCustomCss } from "@lime-bundles/react";
+```
+
+**Mix-match quantity validation:**
+
+```tsx
+import { validateQuantity } from "@lime-bundles/react";
+
+const { valid, message } = validateQuantity(selectedCount, bundle.minQuantity, bundle.maxQuantity);
+```
+
+Anything the web component does, a developer importing from `@lime-bundles/react` can do too. The built-in components are one way to arrange these primitives; ship your own the moment you need a different one.
+
+## Cart mutation patterns
+
+You choose how `onAddToCart` talks to Shopify. Three common patterns:
+
+1. **Storefront Cart API directly from the client.** Call `cartLinesAdd` via `createStorefrontClient` (from `@lime-bundles/core`). Public token, safe in the browser.
+2. **Proxy via your own API route.** POST to `/api/cart/add` (Next.js Route Handler) which calls Storefront Cart API server-side. Lets you validate inventory, tack on UTM params, or enforce per-shop rate limits before forwarding.
+3. **Existing cart context.** If you already use Hydrogen-React's `CartProvider`, call `useCart().linesAdd` inside the callback. See [Hydrogen guide](./hydrogen.md).
+
+In all three, preserve the `attributes` array on each `CartLineInput` verbatim. `_lime_bundle_gid` and `_lime_bundle_type` drive purchase attribution on the Lime Bundles `orders/create` webhook.
+
+## Next steps
+
+- [CSS variables reference](./css-variables.md): brand-match the widget.
+- [Web component guide](./web-component.md): fallback for non-React sections.