@vitrine-kit/vitrine 0.4.1 → 0.5.0

package/kit/registry/cart/files/app/api/cart/route.ts

@@ -3,39 +3,129 @@
 // the arithmetic lives in @vitrine-kit/core. Next glue, not typechecked in the monorepo.
 import { cookies } from 'next/headers';
 import { NextResponse } from 'next/server';
+import { checkRateLimit, clientIpFromHeaders } from '@vitrine-kit/core';
 import type { CommerceBackend } from '@vitrine-kit/contracts';
 import { getCommerceBackend } from '@/lib/adapter';
 
 const COOKIE = 'vitrine_cart';
+const MAX_QUANTITY = 999;
+const RATE_LIMIT = { limit: 30, windowMs: 60_000 };
+
+/** Per-IP rate limit on cart mutations — returns a 429 response, or null if under the limit. */
+function rateLimited(req: Request): NextResponse | null {
+  const { allowed, retryAfterMs } = checkRateLimit(`cart:${clientIpFromHeaders(req.headers)}`, RATE_LIMIT);
+  if (allowed) return null;
+  return NextResponse.json(
+    { error: 'too many requests' },
+    { status: 429, headers: { 'Retry-After': String(Math.ceil((retryAfterMs ?? 0) / 1000)) } },
+  );
+}
+
+function parseQuantity(value: unknown): number | null {
+  const n = typeof value === 'number' ? value : Number(value);
+  return Number.isInteger(n) && n >= 0 && n <= MAX_QUANTITY ? n : null;
+}
+
+function parseAddItemBody(body: unknown): { variantId: string; quantity: number } | null {
+  if (typeof body !== 'object' || body === null) return null;
+  const { variantId, quantity = 1 } = body as { variantId?: unknown; quantity?: unknown };
+  if (typeof variantId !== 'string' || variantId.length === 0) return null;
+  const parsedQuantity = parseQuantity(quantity);
+  if (parsedQuantity === null || parsedQuantity < 1) return null;
+  return { variantId, quantity: parsedQuantity };
+}
+
+function parseUpdateItemBody(body: unknown): { lineId: string; quantity: number } | null {
+  if (typeof body !== 'object' || body === null) return null;
+  const { lineId, quantity } = body as { lineId?: unknown; quantity?: unknown };
+  if (typeof lineId !== 'string' || lineId.length === 0) return null;
+  const parsedQuantity = parseQuantity(quantity);
+  if (parsedQuantity === null) return null;
+  return { lineId, quantity: parsedQuantity };
+}
+
+function parseRemoveItemBody(body: unknown): { lineId: string } | null {
+  if (typeof body !== 'object' || body === null) return null;
+  const { lineId } = body as { lineId?: unknown };
+  if (typeof lineId !== 'string' || lineId.length === 0) return null;
+  return { lineId };
+}
+
+function publicError(error: unknown): string {
+  if (!(error instanceof Error)) return 'cart update failed';
+  return error.message.replace(/^\[vitrine\]\s*/, '');
+}
 
 async function ensureCartId(commerce: CommerceBackend): Promise<string> {
   const jar = await cookies();
   const existing = jar.get(COOKIE)?.value;
   if (existing) return existing;
   const cart = await commerce.createCart();
-  jar.set(COOKIE, cart.id, { httpOnly: true, sameSite: 'lax', path: '/' });
+  jar.set(COOKIE, cart.id, {
+    httpOnly: true,
+    sameSite: 'lax',
+    path: '/',
+    secure: process.env.NODE_ENV === 'production',
+  });
   return cart.id;
 }
 
+export async function GET() {
+  const id = (await cookies()).get(COOKIE)?.value;
+  if (!id) {
+    return NextResponse.json({ id: null, lines: [], currency: 'USD', subtotal: 0, total: 0 });
+  }
+  try {
+    const commerce = await getCommerceBackend();
+    const cart = await commerce.getCart(id);
+    return NextResponse.json(cart ?? { id, lines: [], currency: 'USD', subtotal: 0, total: 0 });
+  } catch (error) {
+    return NextResponse.json({ error: publicError(error) }, { status: 500 });
+  }
+}
+
 export async function POST(req: Request) {
-  const { variantId, quantity = 1 } = (await req.json()) as { variantId: string; quantity?: number };
-  const commerce = await getCommerceBackend();
-  const id = await ensureCartId(commerce);
-  return NextResponse.json(await commerce.addItem(id, variantId, quantity));
+  const limited = rateLimited(req);
+  if (limited) return limited;
+  const parsed = parseAddItemBody(await req.json());
+  if (!parsed) return NextResponse.json({ error: 'invalid body' }, { status: 400 });
+  try {
+    const commerce = await getCommerceBackend();
+    const id = await ensureCartId(commerce);
+    return NextResponse.json(await commerce.addItem(id, parsed.variantId, parsed.quantity));
+  } catch (error) {
+    const message = publicError(error);
+    const status = /out of stock|not found/i.test(message) ? 409 : 500;
+    return NextResponse.json({ error: message }, { status });
+  }
 }
 
 export async function PATCH(req: Request) {
-  const { lineId, quantity } = (await req.json()) as { lineId: string; quantity: number };
+  const limited = rateLimited(req);
+  if (limited) return limited;
+  const parsed = parseUpdateItemBody(await req.json());
+  if (!parsed) return NextResponse.json({ error: 'invalid body' }, { status: 400 });
   const id = (await cookies()).get(COOKIE)?.value;
   if (!id) return NextResponse.json({ error: 'cart not found' }, { status: 400 });
-  const commerce = await getCommerceBackend();
-  return NextResponse.json(await commerce.updateItem(id, lineId, quantity));
+  try {
+    const commerce = await getCommerceBackend();
+    return NextResponse.json(await commerce.updateItem(id, parsed.lineId, parsed.quantity));
+  } catch (error) {
+    return NextResponse.json({ error: publicError(error) }, { status: 500 });
+  }
 }
 
 export async function DELETE(req: Request) {
-  const { lineId } = (await req.json()) as { lineId: string };
+  const limited = rateLimited(req);
+  if (limited) return limited;
+  const parsed = parseRemoveItemBody(await req.json());
+  if (!parsed) return NextResponse.json({ error: 'invalid body' }, { status: 400 });
   const id = (await cookies()).get(COOKIE)?.value;
   if (!id) return NextResponse.json({ error: 'cart not found' }, { status: 400 });
-  const commerce = await getCommerceBackend();
-  return NextResponse.json(await commerce.removeItem(id, lineId));
+  try {
+    const commerce = await getCommerceBackend();
+    return NextResponse.json(await commerce.removeItem(id, parsed.lineId));
+  } catch (error) {
+    return NextResponse.json({ error: publicError(error) }, { status: 500 });
+  }
 }

package/kit/registry/cart/files/components/cart/AddToCart.tsx

@@ -1,40 +1,167 @@
 // "Add to cart" button — client component. Mounted into the product.purchase slot
-// (ProductView passes product). Mutation goes through POST /api/cart (the feature's route).
+// (ProductView passes product). Supports option-based variants from the demo seed
+// (size/color). Mutation goes through POST /api/cart (the feature's route).
 'use client';
-import { useState } from 'react';
-import type { Product } from '@vitrine-kit/contracts';
+import { useMemo, useState } from 'react';
+import type { Product, Variant } from '@vitrine-kit/contracts';
+import { formatMoney } from '../../lib/cart/data.js';
+import { useChromeLabel } from '@/lib/i18n/useChromeLabel';
 
 export interface AddToCartProps {
   product: Product;
 }
 
+const SIZE_ORDER = ['XXS', 'XS', 'S', 'M', 'L', 'XL', 'XXL', 'XXXL'];
+
+function optionKeys(variants: Variant[]): string[] {
+  const keys = new Set<string>();
+  for (const v of variants) {
+    for (const key of Object.keys(v.options ?? {})) keys.add(key);
+  }
+  return [...keys];
+}
+
+function valuesFor(variants: Variant[], key: string): string[] {
+  const values = new Set<string>();
+  for (const v of variants) {
+    const value = v.options?.[key];
+    if (value) values.add(value);
+  }
+  const list = [...values];
+  if (key.toLowerCase() === 'size') {
+    return list.sort((a, b) => {
+      const ia = SIZE_ORDER.indexOf(a.toUpperCase());
+      const ib = SIZE_ORDER.indexOf(b.toUpperCase());
+      if (ia >= 0 && ib >= 0) return ia - ib;
+      if (ia >= 0) return -1;
+      if (ib >= 0) return 1;
+      return a.localeCompare(b);
+    });
+  }
+  return list.sort((a, b) => a.localeCompare(b));
+}
+
+function matchVariant(
+  variants: Variant[],
+  selected: Record<string, string>,
+  keys: string[],
+): Variant | undefined {
+  return variants.find((v) => keys.every((key) => (v.options?.[key] ?? '') === (selected[key] ?? '')));
+}
+
+function firstAvailable(variants: Variant[]): Variant | undefined {
+  return variants.find((v) => v.stock == null || v.stock > 0) ?? variants[0];
+}
+
+function variantLabel(variant: Variant): string {
+  const opts = variant.options;
+  if (opts && Object.keys(opts).length > 0) {
+    return Object.entries(opts)
+      .map(([k, v]) => `${k}: ${v}`)
+      .join(', ');
+  }
+  return variant.title ?? variant.sku;
+}
+
 export function AddToCart({ product }: AddToCartProps) {
+  const variants = product.variants;
+  const keys = useMemo(() => optionKeys(variants), [variants]);
   const [pending, setPending] = useState(false);
-  const variantId = product.variants[0]?.id;
+  const [error, setError] = useState<string | null>(null);
+  const addLabel = useChromeLabel('addToCart');
+  const [selected, setSelected] = useState<Record<string, string>>(() => ({
+    ...(firstAvailable(variants)?.options ?? {}),
+  }));
+  const [variantId, setVariantId] = useState<string | undefined>(() => firstAvailable(variants)?.id);
+
+  const matched =
+    keys.length > 0 ? matchVariant(variants, selected, keys) : variants.find((v) => v.id === variantId);
+  const active = matched ?? firstAvailable(variants);
+  const activeId = active?.id;
+  const outOfStock = active != null && active.stock != null && active.stock <= 0;
+  const currency = active?.currency ?? product.priceRange?.currency ?? 'USD';
 
   async function add(): Promise<void> {
-    if (!variantId) return;
+    if (!activeId || outOfStock) return;
     setPending(true);
+    setError(null);
     try {
-      await fetch('/api/cart', {
+      const res = await fetch('/api/cart', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ variantId, quantity: 1 }),
+        body: JSON.stringify({ variantId: activeId, quantity: 1 }),
       });
+      if (!res.ok) {
+        const data = (await res.json().catch(() => ({}))) as { error?: string };
+        setError(data.error ?? 'Could not add to cart.');
+        return;
+      }
       location.assign('/cart');
+    } catch {
+      setError('Could not add to cart.');
     } finally {
       setPending(false);
     }
   }
 
+  if (variants.length === 0) {
+    return <p className="text-muted-fg">This product has no purchasable variants yet.</p>;
+  }
+
   return (
-    <button
-      type="button"
-      onClick={add}
-      disabled={pending || !variantId}
-      className="vt-add-to-cart rounded-md bg-primary px-gutter py-unit text-primary-fg transition hover:opacity-90 disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 ring-ring"
-    >
-      {pending ? 'Adding…' : 'Add to cart'}
-    </button>
+    <div className="vt-add-to-cart-wrap flex flex-col gap-gutter">
+      {keys.length > 0 ? (
+        keys.map((key) => (
+          <label key={key} className="flex flex-col gap-unit text-sm">
+            <span className="font-medium capitalize text-fg">{key}</span>
+            <select
+              className="rounded-md border border-input bg-surface px-gutter py-unit text-surface-fg focus-visible:outline-none focus-visible:ring-2 ring-ring"
+              value={selected[key] ?? ''}
+              onChange={(e) => setSelected((prev) => ({ ...prev, [key]: e.target.value }))}
+            >
+              {valuesFor(variants, key).map((value) => (
+                <option key={value} value={value}>
+                  {value}
+                </option>
+              ))}
+            </select>
+          </label>
+        ))
+      ) : variants.length > 1 ? (
+        <label className="flex flex-col gap-unit text-sm">
+          <span className="font-medium text-fg">Option</span>
+          <select
+            className="rounded-md border border-input bg-surface px-gutter py-unit text-surface-fg focus-visible:outline-none focus-visible:ring-2 ring-ring"
+            value={activeId ?? ''}
+            onChange={(e) => setVariantId(e.target.value)}
+          >
+            {variants.map((v) => (
+              <option key={v.id} value={v.id} disabled={v.stock != null && v.stock <= 0}>
+                {variantLabel(v)}
+                {v.stock != null && v.stock <= 0 ? ' (out of stock)' : ''}
+              </option>
+            ))}
+          </select>
+        </label>
+      ) : null}
+
+      {active?.price != null ? (
+        <p className="text-price text-lg">{formatMoney(active.price, currency)}</p>
+      ) : null}
+
+      <button
+        type="button"
+        onClick={add}
+        disabled={pending || !activeId || outOfStock}
+        className="vt-add-to-cart rounded-md bg-primary px-gutter py-unit text-primary-fg transition hover:opacity-90 disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 ring-ring"
+      >
+        {pending ? 'Adding…' : outOfStock ? 'Out of stock' : addLabel}
+      </button>
+      {error ? (
+        <p role="alert" className="vt-add-to-cart-error text-danger">
+          {error}
+        </p>
+      ) : null}
+    </div>
   );
 }

package/kit/registry/cart/files/components/cart/CartIndicator.tsx

@@ -1,11 +1,36 @@
-// Header cart link (global.header-actions slot). Presentational.
+// Header cart link (global.header-actions slot). Client component loads the
+// item count from GET /api/cart so the kit typecheck stays free of Next imports.
+'use client';
+import { useEffect, useState } from 'react';
+import { useChromeLabel } from '@/lib/i18n/useChromeLabel';
+
 export function CartIndicator() {
+  const [count, setCount] = useState(0);
+  const label = useChromeLabel('cart');
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch('/api/cart')
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data: { lines?: Array<{ quantity?: number }> } | null) => {
+        if (cancelled || !data?.lines) return;
+        setCount(data.lines.reduce((sum, line) => sum + (line.quantity ?? 0), 0));
+      })
+      .catch(() => {
+        /* cart API missing on catalog-only installs */
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
   return (
     <a
       href="/cart"
       className="vt-cart-indicator text-fg transition hover:text-primary focus-visible:outline-none focus-visible:ring-2 ring-ring"
     >
-      Cart
+      {label}
+      {count > 0 ? ` (${count})` : ''}
     </a>
   );
 }

package/kit/registry/cart/files/components/cart/CartLineItem.tsx

@@ -1,4 +1,6 @@
-// Cart line item — presentational.
+// Cart line item — client controls for quantity and remove (PATCH/DELETE /api/cart).
+'use client';
+import { useState } from 'react';
 import type { CartLine } from '@vitrine-kit/contracts';
 import { formatMoney } from '../../lib/cart/data.js';
 
@@ -8,20 +10,76 @@ export interface CartLineItemProps {
 }
 
 export function CartLineItem({ line, currency }: CartLineItemProps) {
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function mutate(method: 'PATCH' | 'DELETE', body: Record<string, unknown>): Promise<void> {
+    setPending(true);
+    setError(null);
+    try {
+      const res = await fetch('/api/cart', {
+        method,
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        const data = (await res.json().catch(() => ({}))) as { error?: string };
+        setError(data.error ?? 'Could not update the cart.');
+        return;
+      }
+      location.reload();
+    } catch {
+      setError('Could not update the cart.');
+    } finally {
+      setPending(false);
+    }
+  }
+
   return (
-    <li className="vt-cart-line flex items-center gap-gutter border-b border-border py-unit">
-      {line.image ? (
-        <img src={line.image} alt="" className="h-16 w-16 rounded-md object-cover" />
-      ) : (
-        <div className="h-16 w-16 rounded-md bg-muted" aria-hidden="true" />
-      )}
-      <div className="flex-1">
-        <p className="text-fg">{line.title}</p>
-        <p className="text-muted-fg">
-          {line.quantity} × {formatMoney(line.unitPrice, currency)}
-        </p>
+    <li className="vt-cart-line flex flex-col gap-unit border-b border-border py-unit">
+      <div className="flex items-center gap-gutter">
+        {line.image ? (
+          <img src={line.image} alt="" className="h-16 w-16 rounded-md object-cover" />
+        ) : (
+          <div className="h-16 w-16 rounded-md bg-muted" aria-hidden="true" />
+        )}
+        <div className="flex-1">
+          <p className="text-fg">{line.title}</p>
+          <p className="text-muted-fg">{formatMoney(line.unitPrice, currency)} each</p>
+        </div>
+        <p className="text-price">{formatMoney(line.lineTotal, currency)}</p>
+      </div>
+      <div className="flex flex-wrap items-center gap-gutter">
+        <label className="flex items-center gap-unit text-sm text-fg">
+          <span className="text-muted-fg">Qty</span>
+          <input
+            type="number"
+            min={1}
+            max={999}
+            value={line.quantity}
+            disabled={pending}
+            className="w-16 rounded-md border border-input bg-surface px-unit py-unit text-surface-fg focus-visible:outline-none focus-visible:ring-2 ring-ring disabled:opacity-50"
+            onChange={(e) => {
+              const quantity = Number(e.target.value);
+              if (!Number.isInteger(quantity) || quantity < 1) return;
+              void mutate('PATCH', { lineId: line.id, quantity });
+            }}
+          />
+        </label>
+        <button
+          type="button"
+          disabled={pending}
+          onClick={() => void mutate('DELETE', { lineId: line.id })}
+          className="text-sm text-muted-fg underline underline-offset-2 transition hover:text-fg disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 ring-ring"
+        >
+          Remove
+        </button>
+        {error ? (
+          <p role="alert" className="text-sm text-danger">
+            {error}
+          </p>
+        ) : null}
       </div>
-      <p className="text-price">{formatMoney(line.lineTotal, currency)}</p>
     </li>
   );
 }

package/kit/registry/cart/files/components/cart/CartView.tsx

@@ -1,6 +1,9 @@
 // Cart contents — presentational. Hosts the cart.items-bottom / cart.below slots.
+'use client';
+
 import type { Cart } from '@vitrine-kit/contracts';
 import { Slot } from '@vitrine-kit/core/react';
+import { useChromeLabel } from '@/lib/i18n/useChromeLabel';
 import { CartLineItem } from './CartLineItem.js';
 import { CartSummary } from './CartSummary.js';
 
@@ -9,8 +12,25 @@ export interface CartViewProps {
 }
 
 export function CartView({ cart }: CartViewProps) {
+  const continueShopping = useChromeLabel('continueShopping');
+  const addToCart = useChromeLabel('addToCart');
+
   if (cart.lines.length === 0) {
-    return <p className="text-muted-fg">Your cart is empty.</p>;
+    return (
+      <div className="vt-cart-empty flex flex-col gap-gutter">
+        <p className="text-muted-fg">Your cart is empty.</p>
+        <p className="text-sm text-muted-fg">
+          Browse the catalog, open a product, then use <span className="text-fg">{addToCart}</span>{' '}
+          to start checkout.
+        </p>
+        <a
+          href="/"
+          className="w-fit rounded-md border border-border px-gutter py-unit text-fg transition hover:bg-muted focus-visible:outline-none focus-visible:ring-2 ring-ring"
+        >
+          {continueShopping}
+        </a>
+      </div>
+    );
   }
   return (
     <div className="vt-cart grid gap-section md:grid-cols-[2fr_1fr]">

package/kit/registry/catalog/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "catalog",
   "title": "Product catalog",
-  "kitVersion": "0.4.1",
+  "kitVersion": "0.5.0",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "catalog",

package/kit/registry/catalog/files/components/catalog/ProductCard.tsx

@@ -33,7 +33,11 @@ export function ProductCard({ product }: ProductCardProps) {
         <div className="p-gutter">
           <h3 className="font-heading text-fg">{product.title}</h3>
           {price != null ? (
-            <p className="text-price">{formatPrice(price, currency)}</p>
+            <p className="text-price">
+              {product.priceRange && product.priceRange.min !== product.priceRange.max
+                ? `From ${formatPrice(price, currency)}`
+                : formatPrice(price, currency)}
+            </p>
           ) : null}
         </div>
       </a>

package/kit/registry/catalog/files/lib/catalog/data.ts

@@ -1,7 +1,71 @@
 // Catalog access via the CatalogSource contract. The source (Payload*/Vendure*)
 // is resolved in the page data (template); a ready CatalogSource arrives here —
 // so the feature depends only on the contract and is portable across backends.
-import type { CatalogSource, Category, Product, ProductQuery } from '@vitrine-kit/contracts';
+import type {
+  CatalogSource,
+  Category,
+  Product,
+  ProductQuery,
+  ProductSort,
+} from '@vitrine-kit/contracts';
+
+export function parseProductSort(value: string | undefined | null): ProductSort | undefined {
+  if (value === 'newest' || value === 'price-asc' || value === 'price-desc' || value === 'relevance') {
+    return value;
+  }
+  return undefined;
+}
+
+/** Parse `?size=S&size=L&color=Black` style params into ProductQuery.filters. */
+export function parseProductFilters(
+  params: Record<string, string | string[] | undefined>,
+  facetKeys: string[] = ['size', 'color'],
+): Record<string, string[]> | undefined {
+  const filters: Record<string, string[]> = {};
+  for (const key of facetKeys) {
+    const raw = params[key];
+    if (raw == null) continue;
+    const values = (Array.isArray(raw) ? raw : [raw])
+      .flatMap((v) => String(v).split(','))
+      .map((v) => v.trim())
+      .filter(Boolean);
+    if (values.length) filters[key] = [...new Set(values)];
+  }
+  return Object.keys(filters).length ? filters : undefined;
+}
+
+export function parsePriceBound(value: string | string[] | undefined | null): number | undefined {
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (raw == null || raw === '') return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return undefined;
+  // URL values are major currency units ($); ProductQuery uses minor units.
+  return Math.round(n * 100);
+}
+
+/** Aggregate option values present on the given products (for toolbar facets). */
+export function collectOptionFacets(products: Product[]): Record<string, string[]> {
+  const buckets = new Map<string, Set<string>>();
+  for (const p of products) {
+    for (const v of p.variants) {
+      if (!v.options) continue;
+      for (const [key, val] of Object.entries(v.options)) {
+        if (!val) continue;
+        let set = buckets.get(key);
+        if (!set) {
+          set = new Set();
+          buckets.set(key, set);
+        }
+        set.add(val);
+      }
+    }
+  }
+  const out: Record<string, string[]> = {};
+  for (const [key, set] of [...buckets.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    out[key] = [...set].sort((a, b) => a.localeCompare(b));
+  }
+  return out;
+}
 
 export async function loadProducts(
   source: CatalogSource,
@@ -10,12 +74,16 @@ export async function loadProducts(
   return source.listProducts(query);
 }
 
-export async function loadProduct(source: CatalogSource, slug: string): Promise<Product | null> {
-  return source.getProduct(slug);
+export async function loadProduct(
+  source: CatalogSource,
+  slug: string,
+  locale?: string,
+): Promise<Product | null> {
+  return source.getProduct(slug, locale);
 }
 
-export async function loadCategories(source: CatalogSource): Promise<Category[]> {
-  return source.listCategories();
+export async function loadCategories(source: CatalogSource, locale?: string): Promise<Category[]> {
+  return source.listCategories(locale);
 }
 
 /** Money — minor units (e.g. cents); divide by 100 for 2-decimal currencies. */

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

@@ -8,10 +8,28 @@ A provider-agnostic checkout scaffold for `simple-store` / `full-store`. Depends
   `POST /api/checkout` and redirects to the provider URL. It knows nothing about the provider.
 - **API (Next glue):** `POST /api/checkout` — `CommerceBackend.startCheckout`
   delegates to the active provider (`payments.resolve` by `integrations.payments`).
+- **Success page:** `app/(frontend)/order/success` — post-payment landing (`order.*` slots).
 - **Shared webhook code:** `lib/checkout/fulfill.ts` → `fulfillOrderFromEvent` —
   idempotent order creation from a normalized event (used by all provider webhook
   routes). The critical logic (dedup by `paymentRef`, order snapshot) lives in
   `@vitrine-kit/core` (`shouldCreateOrder`, `buildOrderFromCart`).
+- **Email:** `lib/checkout/notify.ts` — after fulfill, calls `payload.sendEmail` when the
+  `email` feature + SMTP (or console adapter) is configured; otherwise logs to the server console.
 
 Flow: cart → `Checkout` → `POST /api/checkout` → redirect to the provider →
-provider webhook → `fulfillOrderFromEvent` → order in the admin, cart `converted`.
+provider webhook → `fulfillOrderFromEvent` → order in the admin, cart `converted` →
+confirmation email (or console log).
+
+## Shipping and tax (v1 scope)
+
+This kit uses **hosted checkout** (Stripe Checkout / Paddle / YooKassa). There is no
+in-store multi-step address form.
+
+| Concern | v1 behavior |
+|---|---|
+| **Shipping address** | Collected by the payment provider on their hosted page (when enabled in the PSP dashboard). Not stored on the Payload cart/order beyond what the webhook returns (email). |
+| **Shipping rates** | Configure in the PSP (Stripe Shipping Rates, etc.). The storefront does not compute rates. |
+| **Tax / VAT** | Prefer PSP tax (Stripe Tax, Paddle VAT). Cart/order only expose optional `discountTotal` — no tax engine in `@vitrine-kit/core` yet. |
+| **Digital goods** | Leave shipping disabled in the PSP; customers still get `/order/success` after pay. |
+
+Physical-goods merchants should enable shipping/tax in the chosen provider dashboard before going live.

package/kit/registry/checkout/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout",
   "title": "Checkout",
-  "kitVersion": "0.4.1",
+  "kitVersion": "0.5.0",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",