Headless Try-On Architecture: Hydrogen, Next.js & Framer with Style Swap AI

HMAC-Verified App Proxy & Zero-CLS Floating Pill

Style Swap AI exposes a signed App Proxy at /apps/try-on/* on your shop's domain. Every request is HMAC-SHA256-verified against your app proxy secret, so only your storefront can invoke the Seedream 5.0 Pro inference engine. On the client you ship only a lightweight launcher: a fixed-position floating pill with reserved dimensions (zero CLS) that lazy-loads the try-on module on first interaction—your LCP and INP budgets stay intact.

• Hydrogen: render the pill from a client component in root.tsx. Next.js App Router: load the launcher via next/script with the afterInteractive strategy in app/layout.tsx and keep listeners inside 'use client' components.
• Framer: paste the same snippet into a custom code block or fire seed-try-on:open from a code override—the proxy is domain-agnostic, so there is no per-framework build.
• Pass productHandle, variantId, and optional pair_with context in the event detail to pre-stage a 3-piece outfit before the modal opens.
• privacyZeroPhotoStorage is true by default: EXIF is stripped and the selfie compressed to maxDim 1400px in the browser before anything leaves the device.

// Hydrogen / Next.js client component: open the try-on modal
const handleTryOn = (productHandle, variantId) => {
  window.dispatchEvent(new CustomEvent('seed-try-on:open', {
    detail: { productHandle, variantId, mode: 'quick' }
  }));
};

// Framer: same event from a code override — the proxy is domain-agnostic
const openTryOn = () => {
  window.dispatchEvent(new CustomEvent('seed-try-on:open', {
    detail: { productHandle: '{{product.handle}}' }
  }));
};

React & Framer Integration with seed-try-on DOM Events

All communication between the try-on engine and your UI runs over three typed CustomEvents on window—seed-try-on:open, seed-try-on:add-to-cart, and seed-try-on:complete-look-add. Because the contract is event-based, it works identically in Hydrogen client components, Next.js 'use client' components, and Framer code overrides: no SDK, no prop drilling, no hydration mismatch. Listen for the two cart events to update state, fire analytics, and post the bundle.

• Register listeners once in a useEffect with a cleanup function; seed-try-on:add-to-cart delivers variant ID and quantity payloads ready for your existing cart mutation.
• seed-try-on:complete-look-add carries up to 3 variant IDs—map it to a single cartLinesAdd (Storefront Cart API) so the whole outfit lands in one checkout and one AOV data point.
• Reposition or relabel the pill with data attributes; it is position: fixed with reserved dimensions, so tuning it never touches layout.
• Full embed controls and dev events unlock on the Runway Plan ($49.99/mo); every plan starts with a 7-day free trial including up to 50 try-on credits.

// Any 'use client' component (Next.js) or Hydrogen client component
useEffect(() => {
  const onAddToCart = (e) => cartLinesAdd(e.detail); // { variantId, quantity }
  const onCompleteLook = (e) => cartLinesAdd({ lines: e.detail.items }); // up to 3 SKUs
  window.addEventListener('seed-try-on:add-to-cart', onAddToCart);
  window.addEventListener('seed-try-on:complete-look-add', onCompleteLook);
  return () => {
    window.removeEventListener('seed-try-on:add-to-cart', onAddToCart);
    window.removeEventListener('seed-try-on:complete-look-add', onCompleteLook);
  };
}, []);

Multi-Garment Outfit Try-On with Storefront Cart API Bundles

Complete the Look is the highest-leverage merchandising surface on a headless build. Style Swap AI reads custom.pair_with metafields (a JSON list of variant IDs) on each product, falls back to DOM cross-sell detection or the Shopify Product Recommendations API, and layers top + bottom + outerwear in a single inference pass. When the shopper accepts, seed-try-on:complete-look-add hands your cart mutation every SKU at once.

• Merchandising: set custom.pair_with on hero SKUs to steer shoppers toward high-margin layers—blazer over slip dress, abaya over loungewear—and the AI renders exactly the combinations you curate.
• Long-tail catalog? Skip metafields and let the Product Recommendations API fallback rank visually compatible pieces automatically.
• Checkout: map the event payload to one cartLinesAdd mutation with multiple merchandise lines so the bundle posts a single checkout—no sequential adds, no dropped items.
• Measure: segment the Klaviyo 'Tried On Product' event by look_type = complete_look to compare bundle AOV against single-garment try-ons.

Zero-Photo Storage, 2K Inference & Klaviyo Attribution

Headless shoppers expect app-grade privacy and speed. privacyZeroPhotoStorage (on by default) compresses and strips EXIF in the browser (maxDim 1400px), transmits over TLS 1.3, and processes the selfie in volatile RAM only—nothing is written to disk, your database, or Shopify Admin. Quick Mode returns 1K previews in ~8–10 seconds; Studio Mode renders 2K high-definition output, with Priority 2K generation on the Unlimited Fashion Plan ($199.99/mo).

• Compliance-ready for GDPR, UAE PDPL, and Saudi PDPL: no selfie is ever persisted or merchant-visible. Say so on the PDP—it converts privacy-sensitive and modest-fashion shoppers.
• Protect Core Web Vitals: the launcher is a few KB and the inference module lazy-loads on the first seed-try-on:open, so LCP and INP are untouched until a shopper opts in.
• Klaviyo sync (Runway Plan, $49.99/mo and above) fires a server-side 'Tried On Product' event—build abandoned-try-on flows and segment by look_type or atmosphere remix.
• The orders/paid webhook attributes revenue and AOV to each try-on session, so you can reconcile ROI against your plan's included credits and overage rate ($0.10–$0.16 per try-on by tier).

// Server-side Klaviyo event fired by Style Swap AI (Runway Plan and above)
{
  "event": "Tried On Product",
  "customer_properties": { "$email": "shopper@example.com" },
  "properties": {
    "product_id": 123456789,
    "variant_id": 987654321,
    "look_type": "complete_look",
    "try_on_mode": "quick",
    "storefront": "hydrogen"
  }
}