@vitrine-kit/vitrine 0.3.1 → 0.4.0

package/kit/registry/checkout-paddle/feature.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "checkout-paddle",
+  "title": "Payment — Paddle",
+  "kitVersion": "0.4.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "checkout"
+  ],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [
+    "@paddle/paddle-node-sdk@^2.0.0"
+  ],
+  "files": [
+    {
+      "from": "files/lib/checkout-paddle/",
+      "to": "lib/checkout-paddle/"
+    },
+    {
+      "from": "files/app/",
+      "to": "app/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.checkout-paddle": true
+    }
+  },
+  "payment": {
+    "provider": "paddle"
+  },
+  "env": [
+    {
+      "key": "PADDLE_API_KEY",
+      "required": true
+    },
+    {
+      "key": "PADDLE_WEBHOOK_SECRET",
+      "required": true
+    },
+    {
+      "key": "PADDLE_ENVIRONMENT",
+      "required": false
+    },
+    {
+      "key": "PADDLE_CHECKOUT_URL",
+      "required": false
+    }
+  ],
+  "claudeDoc": "docs/checkout-paddle.md",
+  "conflicts": [
+    "checkout-stripe",
+    "checkout-yookassa"
+  ],
+  "removable": true
+}

package/kit/registry/checkout-paddle/files/app/api/webhooks/paddle/route.ts

@@ -0,0 +1,22 @@
+// Paddle webhook: paddleProvider.verifyWebhook (Paddle-Signature) →
+// normalized event → handlePaymentWebhook → the shared fulfillOrderFromEvent.
+import { NextResponse } from 'next/server';
+import { handlePaymentWebhook } from '@vitrine-kit/core';
+import { paddleProvider } from '@/lib/checkout-paddle/provider';
+import { fulfillOrderFromEvent } from '@/lib/checkout/fulfill';
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+  const headers = { 'paddle-signature': req.headers.get('paddle-signature') };
+
+  try {
+    const result = await handlePaymentWebhook({
+      provider: paddleProvider,
+      req: { rawBody, headers },
+      handlers: { onCheckoutCompleted: (event) => fulfillOrderFromEvent(event, 'paddle') },
+    });
+    return NextResponse.json(result);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 400 });
+  }
+}

package/kit/registry/checkout-paddle/files/lib/checkout-paddle/provider.ts

@@ -0,0 +1,59 @@
+// PaymentProvider over Paddle Billing. The SDK lives here (in the feature), not in the core.
+// createCheckout creates a transaction with non-catalog line items (prices set on the fly
+// from the cart) and custom_data.cartId → returns the hosted checkout URL. verifyWebhook
+// verifies the Paddle-Signature (HMAC) and normalizes the event.
+//
+// Paddle expects amounts as a string in the currency's minor units (like our Money), so
+// we pass String(unitPrice) as-is. For hosted checkout, the Paddle dashboard needs a
+// default payment link OR set PADDLE_CHECKOUT_URL (override).
+import { Environment, Paddle, type EventEntity } from '@paddle/paddle-node-sdk';
+import type { CreateCheckoutArgs, NormalizedPaymentEvent, PaymentProvider, PaymentWebhookRequest } from '@vitrine-kit/core';
+
+function client(): Paddle {
+  return new Paddle(process.env.PADDLE_API_KEY ?? '', {
+    environment:
+      process.env.PADDLE_ENVIRONMENT === 'production' ? Environment.production : Environment.sandbox,
+  });
+}
+
+export const paddleProvider: PaymentProvider = {
+  name: 'paddle',
+
+  async createCheckout(args: CreateCheckoutArgs): Promise<{ redirectUrl: string }> {
+    const { cart, baseUrl, cancelPath = '/cart' } = args;
+    const paddle = client();
+    const txn = await paddle.transactions.create({
+      items: cart.lines.map((l) => ({
+        quantity: l.quantity,
+        price: {
+          description: l.title,
+          name: l.title,
+          unitPrice: { amount: String(l.unitPrice), currencyCode: cart.currency },
+          product: { name: l.title, taxCategory: 'standard' },
+        },
+      })),
+      customData: { cartId: cart.id },
+      ...(process.env.PADDLE_CHECKOUT_URL ? { checkout: { url: process.env.PADDLE_CHECKOUT_URL } } : {}),
+    });
+    return { redirectUrl: txn.checkout?.url ?? `${baseUrl}${cancelPath}` };
+  },
+
+  async verifyWebhook(req: PaymentWebhookRequest): Promise<NormalizedPaymentEvent> {
+    const paddle = client();
+    const secret = process.env.PADDLE_WEBHOOK_SECRET ?? '';
+    const signature = req.headers['paddle-signature'] ?? '';
+    // Throws on an invalid signature — handlePaymentWebhook returns a 400.
+    const event = (await paddle.webhooks.unmarshal(req.rawBody, secret, signature)) as EventEntity | null;
+    if (!event) return { kind: 'unknown', raw: req.rawBody };
+
+    if (event.eventType === 'transaction.completed' || event.eventType === 'transaction.paid') {
+      const data = event.data as { id?: string; customData?: { cartId?: string } | null };
+      const cartId = (data.customData ?? undefined)?.cartId;
+      return { kind: 'checkout_completed', cartId, providerRef: data.id, raw: event };
+    }
+    if (event.eventType === 'transaction.payment_failed') {
+      return { kind: 'payment_failed', raw: event };
+    }
+    return { kind: 'unknown', raw: event };
+  },
+};

package/kit/registry/checkout-paddle/files/lib/checkout-paddle/register.ts

@@ -0,0 +1,7 @@
+// Registers the Paddle payment provider. The CLI calls this from lib/payments.ts.
+import { payments } from '@vitrine-kit/core';
+import { paddleProvider } from './provider.js';
+
+export function registerCheckoutPaddleProvider(): void {
+  payments.register(paddleProvider);
+}

package/kit/registry/checkout-stripe/docs/checkout-stripe.md

@@ -0,0 +1,17 @@
+# Feature: checkout-stripe (Stripe payment provider)
+
+A Stripe Hosted Checkout provider for the `checkout` scaffold (which it depends on). Installed
+instead of `checkout-paddle` / `checkout-yookassa` (mutually exclusive). The critical
+logic (webhook dispatcher, order from cart) lives in `@vitrine-kit/core`.
+
+- **Provider:** `lib/checkout-stripe/provider.ts` → `stripeProvider`
+  (`PaymentProvider`): `createCheckout` creates a Stripe session; `verifyWebhook`
+  verifies the signature via the Stripe SDK and normalizes the event.
+- **Registration:** `registerCheckoutStripeProvider()` (called from `lib/payments.ts`),
+  sets `integrations.payments: "stripe"` in `site.config`.
+- **API (Next glue):** `POST /api/webhooks/stripe` → `handlePaymentWebhook` →
+  `fulfillOrderFromEvent` (the `checkout` feature's shared code).
+- **env:** `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET` (required).
+
+Flow: cart → `Checkout` → redirect to Stripe → webhook
+`checkout.session.completed` → order in the admin, cart `converted`.

package/kit/registry/checkout-stripe/feature.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "checkout-stripe",
+  "title": "Payment — Stripe",
+  "kitVersion": "0.4.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "checkout"
+  ],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [
+    "stripe@^17.0.0"
+  ],
+  "files": [
+    {
+      "from": "files/lib/checkout-stripe/",
+      "to": "lib/checkout-stripe/"
+    },
+    {
+      "from": "files/app/",
+      "to": "app/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.checkout-stripe": true
+    }
+  },
+  "payment": {
+    "provider": "stripe"
+  },
+  "env": [
+    {
+      "key": "STRIPE_SECRET_KEY",
+      "required": true
+    },
+    {
+      "key": "STRIPE_WEBHOOK_SECRET",
+      "required": true
+    }
+  ],
+  "claudeDoc": "docs/checkout-stripe.md",
+  "conflicts": [
+    "checkout-paddle",
+    "checkout-yookassa"
+  ],
+  "removable": true
+}

package/kit/registry/checkout-stripe/files/app/api/webhooks/stripe/route.ts

@@ -0,0 +1,23 @@
+// Stripe webhook: stripeProvider.verifyWebhook (Stripe SDK signature) → normalized
+// event → handlePaymentWebhook → the shared fulfillOrderFromEvent creates an order from
+// the cart and marks it converted. No provider-specific code here — just glue.
+import { NextResponse } from 'next/server';
+import { handlePaymentWebhook } from '@vitrine-kit/core';
+import { stripeProvider } from '@/lib/checkout-stripe/provider';
+import { fulfillOrderFromEvent } from '@/lib/checkout/fulfill';
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+  const headers = { 'stripe-signature': req.headers.get('stripe-signature') };
+
+  try {
+    const result = await handlePaymentWebhook({
+      provider: stripeProvider,
+      req: { rawBody, headers },
+      handlers: { onCheckoutCompleted: (event) => fulfillOrderFromEvent(event, 'stripe') },
+    });
+    return NextResponse.json(result);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 400 });
+  }
+}

package/kit/registry/checkout-stripe/files/lib/checkout-stripe/provider.ts

@@ -0,0 +1,73 @@
+// PaymentProvider over Stripe Hosted Checkout. The Stripe SDK lives here (in the feature),
+// not in the core: createCheckout creates a session, verifyWebhook verifies the signature and
+// normalizes the event into a NormalizedPaymentEvent. Mapping the cart into Stripe line items
+// (price_data — dynamic prices, unit_amount in minor units) also lives here.
+import type { Cart } from '@vitrine-kit/contracts';
+import type {
+  CreateCheckoutArgs,
+  NormalizedPaymentEvent,
+  PaymentProvider,
+  PaymentWebhookRequest,
+} from '@vitrine-kit/core';
+
+interface StripeLineItem {
+  quantity: number;
+  price_data: { currency: string; unit_amount: number; product_data: { name: string } };
+}
+
+function cartToStripeLineItems(cart: Cart): StripeLineItem[] {
+  return cart.lines.map((l) => ({
+    quantity: l.quantity,
+    price_data: {
+      currency: cart.currency.toLowerCase(),
+      unit_amount: l.unitPrice,
+      product_data: { name: l.title },
+    },
+  }));
+}
+
+export const stripeProvider: PaymentProvider = {
+  name: 'stripe',
+
+  async createCheckout(args: CreateCheckoutArgs): Promise<{ redirectUrl: string }> {
+    const { cart, baseUrl, successPath = '/order/success', cancelPath = '/cart' } = args;
+    const { default: Stripe } = await import('stripe');
+    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY ?? '');
+    const session = await stripe.checkout.sessions.create({
+      mode: 'payment',
+      line_items: cartToStripeLineItems(cart),
+      success_url: `${baseUrl}${successPath}?session_id={CHECKOUT_SESSION_ID}`,
+      cancel_url: `${baseUrl}${cancelPath}`,
+      metadata: { cartId: cart.id },
+    });
+    return { redirectUrl: session.url ?? `${baseUrl}${cancelPath}` };
+  },
+
+  async verifyWebhook(req: PaymentWebhookRequest): Promise<NormalizedPaymentEvent> {
+    const { default: Stripe } = await import('stripe');
+    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY ?? '');
+    const secret = process.env.STRIPE_WEBHOOK_SECRET ?? '';
+    const signature = req.headers['stripe-signature'] ?? '';
+    // Throws on an invalid signature — handlePaymentWebhook surfaces it as a 400.
+    const event = stripe.webhooks.constructEvent(req.rawBody, signature, secret);
+
+    if (event.type === 'checkout.session.completed') {
+      const session = event.data.object as {
+        id?: string;
+        metadata?: { cartId?: string };
+        customer_details?: { email?: string };
+      };
+      return {
+        kind: 'checkout_completed',
+        cartId: session.metadata?.cartId,
+        providerRef: session.id,
+        email: session.customer_details?.email,
+        raw: event,
+      };
+    }
+    if (event.type === 'payment_intent.payment_failed') {
+      return { kind: 'payment_failed', raw: event };
+    }
+    return { kind: 'unknown', raw: event };
+  },
+};

package/kit/registry/checkout-stripe/files/lib/checkout-stripe/register.ts

@@ -0,0 +1,7 @@
+// Registers the Stripe payment provider. The CLI calls this from lib/payments.ts.
+import { payments } from '@vitrine-kit/core';
+import { stripeProvider } from './provider.js';
+
+export function registerCheckoutStripeProvider(): void {
+  payments.register(stripeProvider);
+}

package/kit/registry/checkout-yookassa/docs/checkout-yookassa.md

@@ -0,0 +1,20 @@
+# Feature: checkout-yookassa (YooKassa payment provider)
+
+A YooKassa (yookassa.ru) provider — Russian acquiring: cards, SBP, wallets. For the
+`checkout` scaffold (which it depends on). Installed instead of `checkout-stripe` / `checkout-paddle`
+(mutually exclusive). No SDK needed — REST `/v3/payments` + Basic auth.
+
+- **Provider:** `lib/checkout-yookassa/provider.ts` → `yookassaProvider`
+  (`PaymentProvider`): `createCheckout` creates a payment (`confirmation.redirect`) →
+  `confirmation_url`; `verifyWebhook` confirms the payment with a follow-up request to the API.
+- **Registration:** `registerCheckoutYookassaProvider()` (from `lib/payments.ts`),
+  sets `integrations.payments: "yookassa"`.
+- **API (Next glue):** `POST /api/webhooks/yookassa` → `handlePaymentWebhook` →
+  `fulfillOrderFromEvent`.
+- **env:** `YOOKASSA_SHOP_ID`, `YOOKASSA_SECRET_KEY` (required).
+
+**Security:** YooKassa notifications are **not signed** — the provider re-verifies the
+payment via `GET /v3/payments/{id}` and trusts only `status: "succeeded"`.
+
+**Money:** YooKassa expects a decimal string (`"1990.00"`); `Money` is in minor
+units, so we divide by 100 (RUB and most currencies have 2 decimal places).

package/kit/registry/checkout-yookassa/feature.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "checkout-yookassa",
+  "title": "Payment — YooKassa",
+  "kitVersion": "0.4.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "checkout"
+  ],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [],
+  "files": [
+    {
+      "from": "files/lib/checkout-yookassa/",
+      "to": "lib/checkout-yookassa/"
+    },
+    {
+      "from": "files/app/",
+      "to": "app/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.checkout-yookassa": true
+    }
+  },
+  "payment": {
+    "provider": "yookassa"
+  },
+  "env": [
+    {
+      "key": "YOOKASSA_SHOP_ID",
+      "required": true
+    },
+    {
+      "key": "YOOKASSA_SECRET_KEY",
+      "required": true
+    }
+  ],
+  "claudeDoc": "docs/checkout-yookassa.md",
+  "conflicts": [
+    "checkout-stripe",
+    "checkout-paddle"
+  ],
+  "removable": true
+}

package/kit/registry/checkout-yookassa/files/app/api/webhooks/yookassa/route.ts

@@ -0,0 +1,22 @@
+// YooKassa webhook: the notification is unsigned — yookassaProvider.verifyWebhook
+// re-checks the payment via the API (we trust only succeeded) → normalized
+// event → handlePaymentWebhook → the shared fulfillOrderFromEvent.
+import { NextResponse } from 'next/server';
+import { handlePaymentWebhook } from '@vitrine-kit/core';
+import { yookassaProvider } from '@/lib/checkout-yookassa/provider';
+import { fulfillOrderFromEvent } from '@/lib/checkout/fulfill';
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+
+  try {
+    const result = await handlePaymentWebhook({
+      provider: yookassaProvider,
+      req: { rawBody, headers: {} },
+      handlers: { onCheckoutCompleted: (event) => fulfillOrderFromEvent(event, 'yookassa') },
+    });
+    return NextResponse.json(result);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 400 });
+  }
+}

package/kit/registry/checkout-yookassa/files/lib/checkout-yookassa/provider.ts

@@ -0,0 +1,82 @@
+// PaymentProvider over YooKassa (yookassa.ru) — Russian acquiring: cards, SBP, wallets.
+// No SDK needed: REST /v3/payments + Basic auth (shopId:secretKey). The core doesn't pull in
+// payment SDKs. createCheckout creates a payment with confirmation.redirect → confirmation_url.
+//
+// IMPORTANT: YooKassa notifications are NOT signed. verifyWebhook confirms authenticity
+// with a follow-up API request (GET /v3/payments/{id}) and trusts only status=succeeded.
+//
+// YooKassa expects the amount as a decimal string ("1990.00"); our Money is in minor units,
+// so we divide by 100 (RUB and most currencies have 2 decimal places).
+import { randomUUID } from 'node:crypto';
+import type { CreateCheckoutArgs, NormalizedPaymentEvent, PaymentProvider, PaymentWebhookRequest } from '@vitrine-kit/core';
+
+const API = 'https://api.yookassa.ru/v3/payments';
+const ZERO_DECIMAL = new Set(['JPY', 'KRW', 'VND', 'CLP']);
+
+/** Minor units → currency decimal string ("199000" RUB → "1990.00"). */
+function minorToDecimalString(amount: number, currency: string): string {
+  return ZERO_DECIMAL.has(currency.toUpperCase()) ? String(amount) : (amount / 100).toFixed(2);
+}
+
+function authHeader(): string {
+  const shopId = process.env.YOOKASSA_SHOP_ID ?? '';
+  const secret = process.env.YOOKASSA_SECRET_KEY ?? '';
+  return `Basic ${Buffer.from(`${shopId}:${secret}`).toString('base64')}`;
+}
+
+export const yookassaProvider: PaymentProvider = {
+  name: 'yookassa',
+
+  async createCheckout(args: CreateCheckoutArgs): Promise<{ redirectUrl: string }> {
+    const { cart, baseUrl, successPath = '/order/success', cancelPath = '/cart' } = args;
+    const res = await fetch(API, {
+      method: 'POST',
+      headers: {
+        Authorization: authHeader(),
+        'Idempotence-Key': randomUUID(),
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        amount: {
+          value: minorToDecimalString(cart.total, cart.currency),
+          currency: cart.currency.toUpperCase(),
+        },
+        capture: true,
+        confirmation: { type: 'redirect', return_url: `${baseUrl}${successPath}` },
+        description: `Order (cart ${cart.id})`,
+        metadata: { cartId: cart.id },
+      }),
+    });
+    if (!res.ok) throw new Error(`[vitrine] YooKassa: ${res.status} ${await res.text()}`);
+    const payment = (await res.json()) as { confirmation?: { confirmation_url?: string } };
+    return { redirectUrl: payment.confirmation?.confirmation_url ?? `${baseUrl}${cancelPath}` };
+  },
+
+  async verifyWebhook(req: PaymentWebhookRequest): Promise<NormalizedPaymentEvent> {
+    const body = JSON.parse(req.rawBody) as { event?: string; object?: { id?: string } };
+    const paymentId = body.object?.id;
+    if (!paymentId) return { kind: 'unknown', raw: body };
+
+    // The notification is unsigned — re-check the payment via the API.
+    const res = await fetch(`${API}/${paymentId}`, { headers: { Authorization: authHeader() } });
+    if (!res.ok) throw new Error(`[vitrine] YooKassa verify: ${res.status}`);
+    const payment = (await res.json()) as {
+      id?: string;
+      status?: string;
+      metadata?: { cartId?: string };
+    };
+
+    if (payment.status === 'succeeded') {
+      return {
+        kind: 'checkout_completed',
+        cartId: payment.metadata?.cartId,
+        providerRef: payment.id,
+        raw: payment,
+      };
+    }
+    if (payment.status === 'canceled') {
+      return { kind: 'payment_failed', raw: payment };
+    }
+    return { kind: 'unknown', raw: payment };
+  },
+};

package/kit/registry/checkout-yookassa/files/lib/checkout-yookassa/register.ts

@@ -0,0 +1,7 @@
+// Registers the YooKassa payment provider. The CLI calls this from lib/payments.ts.
+import { payments } from '@vitrine-kit/core';
+import { yookassaProvider } from './provider.js';
+
+export function registerCheckoutYookassaProvider(): void {
+  payments.register(yookassaProvider);
+}

package/kit/registry/product-page/docs/product-page.md

@@ -0,0 +1,16 @@
+# Feature: product-page
+
+The product detail page. Depends on `catalog` (registryDependencies).
+
+## Components
+- `components/product/ProductView` — the detail card. **Hosts the slots** `product.gallery`, `product.below-title`, `product.below-price`, `product.purchase`, `product.below-description`, `product.tabs` — other features (reviews, cart, wishlist) mount here.
+- `components/product/ProductGallery` — the image gallery.
+
+## Data
+- `lib/product/data` — `loadProduct(source, slug)` over `CatalogSource.getProduct`.
+
+## Slots
+The feature doesn't register slots, it **provides** them: so adding reviews/cart doesn't require editing `ProductView`.
+
+## Contracts
+Only `@vitrine-kit/contracts` (types) and `@vitrine-kit/core/react` (`<Slot>`).

package/kit/registry/product-page/feature.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "product-page",
+  "title": "Product page",
+  "kitVersion": "0.4.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "catalog",
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "catalog"
+  ],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [],
+  "files": [
+    {
+      "from": "files/components/product/",
+      "to": "components/product/"
+    },
+    {
+      "from": "files/lib/product/",
+      "to": "lib/product/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.product-page": true
+    }
+  },
+  "slots": [],
+  "env": [],
+  "claudeDoc": "docs/product-page.md",
+  "conflicts": [],
+  "removable": false
+}

package/kit/registry/product-page/files/components/product/ProductGallery.tsx

@@ -0,0 +1,37 @@
+// Product gallery — presentational, neutral.
+import type { ProductImage } from '@vitrine-kit/contracts';
+
+export interface ProductGalleryProps {
+  images: ProductImage[];
+  title: string;
+}
+
+export function ProductGallery({ images, title }: ProductGalleryProps) {
+  const cover = images[0];
+  if (!cover) {
+    return <div className="aspect-square w-full rounded-md bg-muted" aria-hidden="true" />;
+  }
+  const rest = images.slice(1);
+  return (
+    <div className="vt-product-gallery">
+      <img
+        src={cover.url}
+        alt={cover.alt ?? title}
+        className="w-full rounded-md object-cover"
+      />
+      {rest.length > 0 ? (
+        <ul role="list" className="mt-gutter flex gap-gutter">
+          {rest.map((img, i) => (
+            <li key={img.url}>
+              <img
+                src={img.url}
+                alt={img.alt ?? `${title} — image ${i + 2}`}
+                className="h-16 w-16 rounded-md object-cover"
+              />
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  );
+}

package/kit/registry/product-page/files/components/product/ProductView.tsx

@@ -0,0 +1,42 @@
+// Product detail card. HOSTS the product.* slots — other features (reviews,
+// cart, wishlist) mount into them without editing this component.
+import type { Product } from '@vitrine-kit/contracts';
+import { Slot } from '@vitrine-kit/core/react';
+import { ProductGallery } from './ProductGallery.js';
+import { formatPrice } from '../../lib/product/data.js';
+
+export interface ProductViewProps {
+  product: Product;
+}
+
+export function ProductView({ product }: ProductViewProps) {
+  const price = product.priceRange?.min ?? product.variants[0]?.price;
+  const currency = product.priceRange?.currency ?? product.variants[0]?.currency ?? 'USD';
+
+  return (
+    <article className="vt-product-view grid gap-section md:grid-cols-2">
+      <div>
+        <Slot
+          name="product.gallery"
+          fallback={<ProductGallery images={product.images} title={product.title} />}
+        />
+      </div>
+      <div className="flex flex-col gap-gutter">
+        <Slot name="product.below-title" />
+        <h1 className="font-heading text-fg">{product.title}</h1>
+        {price != null ? (
+          <p className="text-price text-xl">{formatPrice(price, currency)}</p>
+        ) : null}
+        <Slot name="product.below-price" />
+        <div className="vt-product-purchase">
+          <Slot name="product.purchase" product={product} />
+        </div>
+        {product.description ? (
+          <div className="vt-product-description text-fg">{product.description}</div>
+        ) : null}
+        <Slot name="product.below-description" />
+        <Slot name="product.tabs" />
+      </div>
+    </article>
+  );
+}

package/kit/registry/product-page/files/lib/product/data.ts

@@ -0,0 +1,10 @@
+import type { CatalogSource, Product } from '@vitrine-kit/contracts';
+
+export async function loadProduct(source: CatalogSource, slug: string): Promise<Product | null> {
+  return source.getProduct(slug);
+}
+
+/** Money — minor units (e.g. cents). */
+export function formatPrice(amount: number, currency: string, locale = 'en-US'): string {
+  return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount / 100);
+}