App
 └─ ThemeSettingsProvider        // merged theme settings
     └─ ThemeStyleApplier        // applies settings as CSS variables
     └─ InitialDataProvider      // pre-rendered / injected data
         └─ ToastProvider
             └─ BrowserRouter
                 └─ AppShell
                     ├─ Header
                     ├─ Routes
                     │   ├─ Home       (/)
                     │   ├─ Product    (/product/:slug)
                     │   ├─ Cart       (/cart)
                     │   ├─ Checkout   (/checkout)
                     │   ├─ Page       (/page/:slug)
                     │   └─ Terms      (/terms)
                     └─ Footer

// In your theme, implement a `useStore()` hook that returns storefront data
// (use `window.__SHOPPEX_INITIAL__` for fast first paint, then revalidate via `shoppex.getStorefront()`).
declare function useStore(): {
  store: { name: string } | null;
  products: Array<{ uniqid: string; title: string }>;
  groups: any[];
  isLoading: boolean;
  error: string | null;
};

function ProductList() {
  const { store, products, groups, isLoading, error } = useStore();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div>
      <h1>{store?.name}</h1>
      {products.map((p) => (
        <div key={p.uniqid}>{p.title}</div>
      ))}
    </div>
  );
}

export function emitCartChanged(): void {
  window.dispatchEvent(new CustomEvent('shoppex:cart-changed'));
}

export function useCartSync(): CartSnapshot {
  const [snapshot, setSnapshot] = useState<CartSnapshot>(getSnapshot());

  useEffect(() => {
    const update = () => setSnapshot(getSnapshot());
    window.addEventListener('shoppex:cart-changed', update);
    window.addEventListener('storage', update);
    return () => {
      window.removeEventListener('shoppex:cart-changed', update);
      window.removeEventListener('storage', update);
    };
  }, []);

  return snapshot;
}

// assumes: useCartSync and emitCartChanged from your theme's hooks (see above)
declare function useCartSync(): { items: any[]; totalQuantity: number; subtotal: number };
declare function emitCartChanged(): void;

function AddToCartButton({ productId, variantId }: { productId: string; variantId: string }) {
  const handleClick = () => {
    shoppex.addToCart(productId, variantId);
    emitCartChanged(); // notify all listeners
  };
  return <button onClick={handleClick}>Add to Cart</button>;
}

function CartBadge() {
  const { totalQuantity } = useCartSync();
  return <span>{totalQuantity > 0 ? totalQuantity : null}</span>;
}

import { useThemeSettings } from '@/context/ThemeSettingsContext';

function BrandedSection() {
  const settings = useThemeSettings();
  const primaryColor = (settings.colors as Record<string, string>)?.primary;

  return (
    <section style={{ borderColor: primaryColor }}>
      Branded content
    </section>
  );
}

body {
  font-family: var(--font-family-body);
  color: rgb(var(--text));
  background: rgb(var(--surface));
}

.btn-primary {
  background: rgb(var(--brand-600));
  border-radius: var(--button-radius);
}