@vitrine-kit/vitrine 0.4.1 → 0.4.3

package/dist/index.js

@@ -1192,10 +1192,10 @@ import { readdirSync as readdirSync4 } from "fs";
 import { join as join13 } from "path";
 
 // src/kit-versions.generated.ts
-var KIT_VERSION = "0.4.1";
+var KIT_VERSION = "0.4.3";
 var CONTRACTS_VERSION = "1.0.0";
 var CONTRACTS_RANGE = "^1.0.0";
-var CORE_RANGE = "^0.2.0";
+var CORE_RANGE = "^0.3.0";
 var BLUEPRINT_RANGE = "^0.2.0";
 
 // src/kit.ts
@@ -1385,8 +1385,9 @@ function clientReadme(name, backend, tier) {
     "- Admin: http://localhost:3000/admin",
     "",
     "Without Postgres, dev starts a built-in SQLite (`.vitrine/dev.sqlite`), seeds a",
-    "demo catalog (5 products, 2 categories) and creates a dev admin (login/password printed",
-    "to the console once). Disable the fallback in dev too with `VITRINE_DB_STRICT=1`."
+    "demo catalog (5 products, 2 categories, size/color variants, gallery images) and creates a",
+    "dev admin (login/password printed to the console once). Disable the fallback in",
+    "dev too with `VITRINE_DB_STRICT=1`."
   ].join("\n");
   const deploySecret = backend === "vendure" ? "export VENDURE_COOKIE_SECRET=...  # Vendure cookie secret" : "export PAYLOAD_SECRET=...         # random Payload secret";
   return `# ${name}

package/kit/registry/_index.json

@@ -1,11 +1,11 @@
 {
   "$schema": "../schemas/registry-index.schema.json",
-  "kitVersion": "0.4.1",
+  "kitVersion": "0.4.3",
   "contracts": "1.0.0",
   "features": {
     "catalog": {
       "title": "Product catalog",
-      "kitVersion": "0.4.1",
+      "kitVersion": "0.4.3",
       "tier": [
         "catalog",
         "simple-store",
@@ -14,7 +14,7 @@
     },
     "product-page": {
       "title": "Product page",
-      "kitVersion": "0.4.1",
+      "kitVersion": "0.4.3",
       "tier": [
         "catalog",
         "simple-store",
@@ -23,7 +23,7 @@
     },
     "seo": {
       "title": "SEO — metadata and JSON-LD",
-      "kitVersion": "0.4.1",
+      "kitVersion": "0.4.3",
       "tier": [
         "catalog",
         "simple-store",
@@ -32,7 +32,7 @@
     },
     "cart": {
       "title": "Cart",
-      "kitVersion": "0.4.1",
+      "kitVersion": "0.4.3",
       "tier": [
         "simple-store",
         "full-store"
@@ -40,7 +40,7 @@
     },
     "checkout": {
       "title": "Checkout",
-      "kitVersion": "0.4.1",
+      "kitVersion": "0.4.3",
       "tier": [
         "simple-store",
         "full-store"
@@ -48,7 +48,7 @@
     },
     "checkout-stripe": {
       "title": "Payment — Stripe",
-      "kitVersion": "0.4.1",
+      "kitVersion": "0.4.3",
       "tier": [
         "simple-store",
         "full-store"
@@ -56,7 +56,7 @@
     },
     "checkout-paddle": {
       "title": "Payment — Paddle",
-      "kitVersion": "0.4.1",
+      "kitVersion": "0.4.3",
       "tier": [
         "simple-store",
         "full-store"
@@ -64,7 +64,7 @@
     },
     "checkout-yookassa": {
       "title": "Payment — YooKassa",
-      "kitVersion": "0.4.1",
+      "kitVersion": "0.4.3",
       "tier": [
         "simple-store",
         "full-store"

package/kit/registry/cart/feature.json

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

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

@@ -3,10 +3,53 @@
 // 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 };
+}
 
 async function ensureCartId(commerce: CommerceBackend): Promise<string> {
   const jar = await cookies();
@@ -18,24 +61,33 @@ async function ensureCartId(commerce: CommerceBackend): Promise<string> {
 }
 
 export async function POST(req: Request) {
-  const { variantId, quantity = 1 } = (await req.json()) as { variantId: string; quantity?: number };
+  const limited = rateLimited(req);
+  if (limited) return limited;
+  const parsed = parseAddItemBody(await req.json());
+  if (!parsed) return NextResponse.json({ error: 'invalid body' }, { status: 400 });
   const commerce = await getCommerceBackend();
   const id = await ensureCartId(commerce);
-  return NextResponse.json(await commerce.addItem(id, variantId, quantity));
+  return NextResponse.json(await commerce.addItem(id, parsed.variantId, parsed.quantity));
 }
 
 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));
+  return NextResponse.json(await commerce.updateItem(id, parsed.lineId, parsed.quantity));
 }
 
 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));
+  return NextResponse.json(await commerce.removeItem(id, parsed.lineId));
 }

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

@@ -1,25 +1,76 @@
 // "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';
 
 export interface AddToCartProps {
   product: Product;
 }
 
+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);
+  }
+  return [...values];
+}
+
+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 [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;
 
   async function add(): Promise<void> {
-    if (!variantId) return;
+    if (!activeId || outOfStock) return;
     setPending(true);
     try {
       await fetch('/api/cart', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ variantId, quantity: 1 }),
+        body: JSON.stringify({ variantId: activeId, quantity: 1 }),
       });
       location.assign('/cart');
     } finally {
@@ -27,14 +78,55 @@ export function AddToCart({ product }: AddToCartProps) {
     }
   }
 
+  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}
+
+      <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' : 'Add to cart'}
+      </button>
+    </div>
   );
 }

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

@@ -10,7 +10,25 @@ export interface CartViewProps {
 
 export function CartView({ cart }: CartViewProps) {
   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">
+          Open a product such as{' '}
+          <a href="/products/classic-tee" className="text-fg underline underline-offset-2">
+            Classic T-Shirt
+          </a>
+          , pick a size, then use <span className="text-fg">Add to cart</span> to try the checkout
+          flow.
+        </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"
+        >
+          Continue shopping
+        </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.4.3",
   "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/checkout/feature.json

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

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

@@ -3,9 +3,19 @@
 // redirect URL. Provider-agnostic: startCheckout delegates to payments.resolve. Next glue.
 import { cookies } from 'next/headers';
 import { NextResponse } from 'next/server';
+import { checkRateLimit, clientIpFromHeaders } from '@vitrine-kit/core';
 import { getCommerceBackend } from '@/lib/adapter';
 
-export async function POST() {
+const RATE_LIMIT = { limit: 10, windowMs: 60_000 };
+
+export async function POST(req: Request) {
+  const { allowed, retryAfterMs } = checkRateLimit(`checkout:${clientIpFromHeaders(req.headers)}`, RATE_LIMIT);
+  if (!allowed) {
+    return NextResponse.json(
+      { error: 'too many requests' },
+      { status: 429, headers: { 'Retry-After': String(Math.ceil((retryAfterMs ?? 0) / 1000)) } },
+    );
+  }
   const cartId = (await cookies()).get('vitrine_cart')?.value;
   if (!cartId) return NextResponse.json({ error: 'cart is empty' }, { status: 400 });
   const commerce = await getCommerceBackend();

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

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

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

@@ -1,11 +1,16 @@
 // Paddle webhook: paddleProvider.verifyWebhook (Paddle-Signature) →
 // normalized event → handlePaymentWebhook → the shared fulfillOrderFromEvent.
 import { NextResponse } from 'next/server';
-import { handlePaymentWebhook } from '@vitrine-kit/core';
+import { checkRateLimit, clientIpFromHeaders, handlePaymentWebhook } from '@vitrine-kit/core';
 import { paddleProvider } from '@/lib/checkout-paddle/provider';
 import { fulfillOrderFromEvent } from '@/lib/checkout/fulfill';
 
+const RATE_LIMIT = { limit: 120, windowMs: 60_000 };
+
 export async function POST(req: Request) {
+  const { allowed } = checkRateLimit(`webhook:paddle:${clientIpFromHeaders(req.headers)}`, RATE_LIMIT);
+  if (!allowed) return NextResponse.json({ error: 'too many requests' }, { status: 429 });
+
   const rawBody = await req.text();
   const headers = { 'paddle-signature': req.headers.get('paddle-signature') };
 
@@ -17,6 +22,8 @@ export async function POST(req: Request) {
     });
     return NextResponse.json(result);
   } catch (err) {
-    return NextResponse.json({ error: (err as Error).message }, { status: 400 });
+    // Don't echo provider-specific error text (e.g. signature failure detail) to the caller.
+    console.error('[vitrine] paddle webhook error:', err);
+    return NextResponse.json({ error: 'invalid webhook' }, { status: 400 });
   }
 }

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

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

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

@@ -2,11 +2,16 @@
 // 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 { checkRateLimit, clientIpFromHeaders, handlePaymentWebhook } from '@vitrine-kit/core';
 import { stripeProvider } from '@/lib/checkout-stripe/provider';
 import { fulfillOrderFromEvent } from '@/lib/checkout/fulfill';
 
+const RATE_LIMIT = { limit: 120, windowMs: 60_000 };
+
 export async function POST(req: Request) {
+  const { allowed } = checkRateLimit(`webhook:stripe:${clientIpFromHeaders(req.headers)}`, RATE_LIMIT);
+  if (!allowed) return NextResponse.json({ error: 'too many requests' }, { status: 429 });
+
   const rawBody = await req.text();
   const headers = { 'stripe-signature': req.headers.get('stripe-signature') };
 
@@ -18,6 +23,8 @@ export async function POST(req: Request) {
     });
     return NextResponse.json(result);
   } catch (err) {
-    return NextResponse.json({ error: (err as Error).message }, { status: 400 });
+    // Don't echo provider-specific error text (e.g. signature failure detail) to the caller.
+    console.error('[vitrine] stripe webhook error:', err);
+    return NextResponse.json({ error: 'invalid webhook' }, { status: 400 });
   }
 }

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

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

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

@@ -2,11 +2,16 @@
 // 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 { checkRateLimit, clientIpFromHeaders, handlePaymentWebhook } from '@vitrine-kit/core';
 import { yookassaProvider } from '@/lib/checkout-yookassa/provider';
 import { fulfillOrderFromEvent } from '@/lib/checkout/fulfill';
 
+const RATE_LIMIT = { limit: 120, windowMs: 60_000 };
+
 export async function POST(req: Request) {
+  const { allowed } = checkRateLimit(`webhook:yookassa:${clientIpFromHeaders(req.headers)}`, RATE_LIMIT);
+  if (!allowed) return NextResponse.json({ error: 'too many requests' }, { status: 429 });
+
   const rawBody = await req.text();
 
   try {
@@ -17,6 +22,8 @@ export async function POST(req: Request) {
     });
     return NextResponse.json(result);
   } catch (err) {
-    return NextResponse.json({ error: (err as Error).message }, { status: 400 });
+    // Don't echo provider-specific error text (e.g. re-confirmation failure detail) to the caller.
+    console.error('[vitrine] yookassa webhook error:', err);
+    return NextResponse.json({ error: 'invalid webhook' }, { status: 400 });
   }
 }

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

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

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

@@ -25,7 +25,11 @@ export function ProductView({ product }: ProductViewProps) {
         <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>
+          <p className="text-price text-xl">
+            {product.priceRange && product.priceRange.min !== product.priceRange.max
+              ? `${formatPrice(product.priceRange.min, currency)} – ${formatPrice(product.priceRange.max, currency)}`
+              : formatPrice(price, currency)}
+          </p>
         ) : null}
         <Slot name="product.below-price" />
         <div className="vt-product-purchase">

package/kit/registry/seo/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "seo",
   "title": "SEO — metadata and JSON-LD",
-  "kitVersion": "0.4.1",
+  "kitVersion": "0.4.3",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "catalog",

package/kit/templates/backend-payload/files/lib/seed/admin.ts

@@ -14,9 +14,15 @@ export async function ensureDevAdmin(payload: Payload): Promise<void> {
   const { totalDocs } = await payload.count({ collection: 'users' });
   if (!shouldRunDevTask({ isProd, existingCount: totalDocs })) return;
 
-  const email = process.env.DEV_ADMIN_EMAIL ?? 'admin@dev.local';
-  const password = process.env.DEV_ADMIN_PASSWORD ?? randomPassword();
-  await payload.create({ collection: 'users', data: { email, password } });
+  // `.env.example` ships `DEV_ADMIN_EMAIL=` / `DEV_ADMIN_PASSWORD=` — empty strings must
+  // not win over defaults (`??` only treats null/undefined).
+  const email = process.env.DEV_ADMIN_EMAIL?.trim() || 'admin@example.com';
+  const password = process.env.DEV_ADMIN_PASSWORD?.trim() || randomPassword();
+  await payload.create({
+    collection: 'users',
+    data: { email, password },
+    overrideAccess: true,
+  });
   payload.logger.warn(
     `[vitrine] DEV ADMIN ${email} / ${password} — development only, change before deploying`,
   );

package/kit/templates/backend-payload/files/lib/seed/demo.ts

@@ -1,10 +1,12 @@
-// Demo data for zero-config dev (§18.2): 5 products + 2 categories + local
-// placeholder images (seed-assets/). Prices are in minor units (e.g. cents):
-// 199000 = 1990.00. Pure data — covered by an invariants test.
+// Demo data for zero-config dev (§18.2): a small but realistic catalog so a
+// freshly scaffolded shop has browseable examples (categories, variants,
+// gallery images, SEO). Prices are integer minor units (cents): 2490 = $24.90.
+// Pure data — covered by invariants tests in sandbox.
 
 export interface DemoCategory {
   slug: string;
   title: string;
+  description: string;
 }
 
 export interface DemoVariant {
@@ -12,6 +14,8 @@ export interface DemoVariant {
   /** Minor units (e.g. cents). */
   price: number;
   stock: number;
+  /** e.g. { size: 'M', color: 'Black' }. */
+  options?: Record<string, string>;
 }
 
 export interface DemoProduct {
@@ -19,15 +23,23 @@ export interface DemoProduct {
   title: string;
   category: string;
   description: string;
-  /** File name in seed-assets/. */
-  image: string;
+  /** File names in seed-assets/ (first = cover; extras feed the gallery). */
+  images: string[];
   seo: { title: string; description: string };
   variants: DemoVariant[];
 }
 
 export const demoCategories: DemoCategory[] = [
-  { slug: 'apparel', title: 'Apparel' },
-  { slug: 'accessories', title: 'Accessories' },
+  {
+    slug: 'apparel',
+    title: 'Apparel',
+    description: 'Everyday layers — tees, hoodies, and socks with size options you can add to the cart.',
+  },
+  {
+    slug: 'accessories',
+    title: 'Accessories',
+    description: 'Caps and bags that round out a simple merch assortment.',
+  },
 ];
 
 export const demoProducts: DemoProduct[] = [
@@ -35,45 +47,79 @@ export const demoProducts: DemoProduct[] = [
     slug: 'classic-tee',
     title: 'Classic T-Shirt',
     category: 'apparel',
-    description: 'A straight-cut cotton T-shirt.',
-    image: 'placeholder-1.svg',
-    seo: { title: 'Classic T-Shirt', description: 'A basic cotton T-shirt.' },
-    variants: [{ sku: 'TEE-001', price: 199000, stock: 25 }],
+    description:
+      'A straight-cut midweight cotton tee for daily wear. Soft hand-feel, reinforced shoulder seams, and a slightly longer hem that stays tucked. Pick a size below, add it to your cart, then open /cart to try checkout.',
+    images: ['placeholder-1.svg', 'placeholder-1b.svg'],
+    seo: {
+      title: 'Classic T-Shirt — midweight cotton',
+      description: 'Demo apparel product with multiple sizes. Midweight cotton, straight cut.',
+    },
+    variants: [
+      { sku: 'TEE-S', price: 2490, stock: 18, options: { size: 'S' } },
+      { sku: 'TEE-M', price: 2490, stock: 32, options: { size: 'M' } },
+      { sku: 'TEE-L', price: 2490, stock: 21, options: { size: 'L' } },
+      { sku: 'TEE-XL', price: 2690, stock: 9, options: { size: 'XL' } },
+    ],
   },
   {
     slug: 'zip-hoodie',
     title: 'Zip Hoodie',
     category: 'apparel',
-    description: 'A warm hooded sweatshirt.',
-    image: 'placeholder-2.svg',
-    seo: { title: 'Zip Hoodie', description: 'An insulated hoodie.' },
-    variants: [{ sku: 'HOD-001', price: 459000, stock: 12 }],
+    description:
+      'A brushed-fleece zip hoodie with a roomy hood and metal zipper. Wear it open over the Classic Tee or zipped for cooler evenings. Sizes share the same cut; XL is a touch longer in the body.',
+    images: ['placeholder-2.svg', 'placeholder-2b.svg'],
+    seo: {
+      title: 'Zip Hoodie — brushed fleece',
+      description: 'Demo hoodie with size variants and a two-image gallery.',
+    },
+    variants: [
+      { sku: 'HOD-S', price: 6900, stock: 8, options: { size: 'S' } },
+      { sku: 'HOD-M', price: 6900, stock: 14, options: { size: 'M' } },
+      { sku: 'HOD-L', price: 6900, stock: 11, options: { size: 'L' } },
+      { sku: 'HOD-XL', price: 7200, stock: 4, options: { size: 'XL' } },
+    ],
   },
   {
     slug: 'logo-cap',
     title: 'Logo Cap',
     category: 'accessories',
-    description: 'An adjustable cap.',
-    image: 'placeholder-3.svg',
-    seo: { title: 'Cap', description: 'A cap with a logo.' },
-    variants: [{ sku: 'CAP-001', price: 129000, stock: 40 }],
+    description:
+      'A structured six-panel cap with an adjustable strap. One size fits most; choose color to see how option-based variants appear on accessories.',
+    images: ['placeholder-3.svg'],
+    seo: {
+      title: 'Logo Cap — adjustable',
+      description: 'Demo accessory with color options.',
+    },
+    variants: [
+      { sku: 'CAP-BLK', price: 2900, stock: 24, options: { color: 'Black' } },
+      { sku: 'CAP-NAV', price: 2900, stock: 16, options: { color: 'Navy' } },
+      { sku: 'CAP-SND', price: 2900, stock: 12, options: { color: 'Sand' } },
+    ],
   },
   {
     slug: 'tote-bag',
     title: 'Tote Bag',
     category: 'accessories',
-    description: 'A sturdy cotton tote.',
-    image: 'placeholder-4.svg',
-    seo: { title: 'Tote', description: 'A cotton tote bag.' },
-    variants: [{ sku: 'TOT-001', price: 99000, stock: 60 }],
+    description:
+      'A heavyweight canvas tote with an interior pocket. Single SKU — useful for comparing a simple product against multi-variant apparel on the product page.',
+    images: ['placeholder-4.svg'],
+    seo: {
+      title: 'Tote Bag — heavyweight canvas',
+      description: 'Demo single-variant accessory for a simple add-to-cart path.',
+    },
+    variants: [{ sku: 'TOT-001', price: 1800, stock: 60 }],
   },
   {
     slug: 'crew-socks',
-    title: 'Socks, 3 Pairs',
+    title: 'Crew Socks (3-Pack)',
     category: 'apparel',
-    description: 'A set of three pairs.',
-    image: 'placeholder-5.svg',
-    seo: { title: 'Socks', description: 'A pack of socks, 3 pairs.' },
-    variants: [{ sku: 'SOC-001', price: 79000, stock: 100 }],
+    description:
+      'A three-pair pack of ribbed crew socks. Soft cuff, reinforced heel and toe. Sold as one pack SKU so cart lines stay simple while you explore quantity updates on /cart.',
+    images: ['placeholder-5.svg'],
+    seo: {
+      title: 'Crew Socks — 3-pack',
+      description: 'Demo pack product with a single variant and high stock.',
+    },
+    variants: [{ sku: 'SOC-3PK', price: 1400, stock: 100 }],
   },
 ];

package/kit/templates/backend-payload/files/lib/seed/run.ts

@@ -17,16 +17,26 @@ export async function seedDemo(payload: Payload): Promise<void> {
 
   const categoryId = new Map<string, string | number>();
   for (const c of demoCategories) {
-    const doc = await payload.create({ collection: 'categories', data: { slug: c.slug, title: c.title } });
+    const doc = await payload.create({
+      collection: 'categories',
+      data: { slug: c.slug, title: c.title, description: c.description },
+      overrideAccess: true,
+    });
     categoryId.set(c.slug, doc.id);
   }
 
   for (const p of demoProducts) {
-    const media = await payload.create({
-      collection: 'media',
-      data: { alt: p.title },
-      filePath: path.join(seedAssets, p.image),
-    });
+    const mediaIds: Array<string | number> = [];
+    for (const [index, image] of p.images.entries()) {
+      const media = await payload.create({
+        collection: 'media',
+        data: { alt: index === 0 ? p.title : `${p.title} — detail` },
+        filePath: path.join(seedAssets, image),
+        overrideAccess: true,
+      });
+      mediaIds.push(media.id);
+    }
+    const coverId = mediaIds[0];
     const catId = categoryId.get(p.category);
     const product = await payload.create({
       collection: 'products',
@@ -35,17 +45,32 @@ export async function seedDemo(payload: Payload): Promise<void> {
         title: p.title,
         description: plainToRichText(p.description),
         categories: catId ? [catId] : [],
-        images: [media.id],
-        seo: { title: p.seo.title, description: p.seo.description, image: media.id },
+        images: mediaIds,
+        seo: {
+          title: p.seo.title,
+          description: p.seo.description,
+          image: coverId,
+        },
       },
+      overrideAccess: true,
     });
     for (const v of p.variants) {
       await payload.create({
         collection: 'variants',
-        data: { sku: v.sku, price: v.price, stock: v.stock, product: product.id },
+        data: {
+          sku: v.sku,
+          price: v.price,
+          stock: v.stock,
+          product: product.id,
+          ...(v.options ? { options: v.options } : {}),
+        },
+        overrideAccess: true,
       });
     }
   }
 
-  payload.logger.info('[vitrine] demo seed: created 5 products');
+  const variantCount = demoProducts.reduce((n, p) => n + p.variants.length, 0);
+  payload.logger.info(
+    `[vitrine] demo seed: ${demoProducts.length} products, ${demoCategories.length} categories, ${variantCount} variants — browse / then try Add to cart`,
+  );
 }

package/kit/templates/backend-payload/files/next.config.mjs

@@ -2,9 +2,37 @@
 // API into Next). output: 'standalone' — for the Docker image (VPS).
 import { withPayload } from '@payloadcms/next/withPayload';
 
+// Baseline security headers (OWASP A05: Security Misconfiguration) applied to every route.
+// The CSP below is a conservative starting point — payment providers with client-side widgets
+// (e.g. embedded Stripe Elements) may need their domains added to script-src/connect-src/frame-src.
+const securityHeaders = [
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'X-Frame-Options', value: 'DENY' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
+  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
+  {
+    key: 'Content-Security-Policy',
+    value:
+      "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https:; frame-ancestors 'none';",
+  },
+];
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   output: 'standalone',
+  // Registry/template sources use TypeScript ESM-style relative imports (`.js` → `.ts`/`.tsx`).
+  // Webpack needs an explicit extensionAlias; without it, `pnpm dev` fails to resolve components.
+  webpack(config) {
+    config.resolve.extensionAlias = {
+      ...(config.resolve.extensionAlias ?? {}),
+      '.js': ['.ts', '.tsx', '.js', '.jsx'],
+    };
+    return config;
+  },
+  async headers() {
+    return [{ source: '/:path*', headers: securityHeaders }];
+  },
 };
 
 export default withPayload(nextConfig);

package/kit/templates/backend-payload/files/payload.config.ts

@@ -14,6 +14,12 @@ import { ensureDevAdmin } from './lib/seed/admin.js';
 
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 
+const payloadSecret = process.env.PAYLOAD_SECRET;
+if (!payloadSecret && process.env.NODE_ENV === 'production') {
+  // No silent fallback to the dev secret in production (mirrors the Vendure DATABASE_URL guard).
+  throw new Error('[vitrine] PAYLOAD_SECRET is required in production');
+}
+
 export default buildConfig({
   admin: {
     user: 'users',
@@ -21,7 +27,7 @@ export default buildConfig({
   },
   collections: collections as unknown as CollectionConfig[],
   editor: lexicalEditor(),
-  secret: process.env.PAYLOAD_SECRET ?? 'dev-secret-change-me',
+  secret: payloadSecret ?? 'dev-secret-change-me',
   db: await resolveDbAdapter(),
   sharp,
   typescript: { outputFile: path.resolve(dirname, 'payload-types.ts') },

package/kit/templates/backend-payload/files/seed-assets/placeholder-1b.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="600" viewBox="0 0 600 600" role="img" aria-label="Classic T-Shirt detail">
+  <rect width="600" height="600" fill="#f5f5f4"/>
+  <rect x="40" y="40" width="520" height="520" rx="16" fill="#e7e5e4"/>
+  <text x="300" y="290" font-family="system-ui, sans-serif" font-size="36" fill="#57534e" text-anchor="middle">T-Shirt</text>
+  <text x="300" y="340" font-family="system-ui, sans-serif" font-size="22" fill="#78716c" text-anchor="middle">detail view</text>
+</svg>

package/kit/templates/backend-payload/files/seed-assets/placeholder-2b.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="600" viewBox="0 0 600 600" role="img" aria-label="Zip Hoodie detail">
+  <rect width="600" height="600" fill="#fafaf9"/>
+  <rect x="40" y="40" width="520" height="520" rx="16" fill="#e7e5e4"/>
+  <text x="300" y="290" font-family="system-ui, sans-serif" font-size="36" fill="#44403c" text-anchor="middle">Hoodie</text>
+  <text x="300" y="340" font-family="system-ui, sans-serif" font-size="22" fill="#78716c" text-anchor="middle">detail view</text>
+</svg>

package/kit/templates/backend-vendure/files/vendure-config.ts

@@ -5,10 +5,36 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DefaultJobQueuePlugin, DefaultSearchPlugin, type VendureConfig } from '@vendure/core';
 import { AssetServerPlugin } from '@vendure/asset-server-plugin';
+import { checkRateLimit } from '@vitrine-kit/core';
 
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 const IS_DEV = process.env.NODE_ENV !== 'production';
 
+// Structural Express req/res shape — avoids a direct dependency on `express` (it's only a
+// transitive dep of @vendure/core); any real Express Request/Response satisfies this.
+interface MiddlewareRequest {
+  headers: Record<string, string | string[] | undefined>;
+  ip?: string;
+}
+interface MiddlewareResponse {
+  setHeader(name: string, value: string): void;
+  status(code: number): { json(body: unknown): void };
+}
+
+// Coarse per-IP rate limit on the whole admin API — brute-force protection for the
+// superadmin login mutation (Vendure has no built-in login lockout, unlike Payload).
+function adminApiRateLimit(req: MiddlewareRequest, res: MiddlewareResponse, next: () => void): void {
+  const forwardedFor = req.headers['x-forwarded-for'];
+  const ip = (Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor?.split(',')[0].trim()) ?? req.ip ?? 'unknown';
+  const { allowed, retryAfterMs } = checkRateLimit(`admin-api:${ip}`, { limit: 60, windowMs: 60_000 });
+  if (!allowed) {
+    res.setHeader('Retry-After', String(Math.ceil((retryAfterMs ?? 0) / 1000)));
+    res.status(429).json({ error: 'too many requests' });
+    return;
+  }
+  next();
+}
+
 function dbConnectionOptions(): VendureConfig['dbConnectionOptions'] {
   const url = process.env.DATABASE_URL;
   if (url) {
@@ -26,17 +52,28 @@ function dbConnectionOptions(): VendureConfig['dbConnectionOptions'] {
   } as VendureConfig['dbConnectionOptions'];
 }
 
+if (!IS_DEV) {
+  // No silent fallback to the well-known dev defaults in production (mirrors the DATABASE_URL guard below).
+  if (!process.env.VENDURE_SUPERADMIN_PASSWORD) {
+    throw new Error('[vitrine] VENDURE_SUPERADMIN_PASSWORD is required in production');
+  }
+  if (!process.env.VENDURE_COOKIE_SECRET) {
+    throw new Error('[vitrine] VENDURE_COOKIE_SECRET is required in production');
+  }
+}
+
 export const config: VendureConfig = {
   apiOptions: {
     port: Number(process.env.VENDURE_PORT ?? 3001),
     adminApiPath: 'admin-api',
     shopApiPath: 'shop-api',
+    middleware: [{ handler: adminApiRateLimit, route: 'admin-api' }],
   },
   authOptions: {
     tokenMethod: ['bearer', 'cookie'],
     superadminCredentials: {
       identifier: process.env.VENDURE_SUPERADMIN_USERNAME ?? 'superadmin',
-      // dev default; for prod you must set VENDURE_SUPERADMIN_PASSWORD.
+      // dev default; production is guarded above.
       password: process.env.VENDURE_SUPERADMIN_PASSWORD ?? 'superadmin',
     },
     cookieOptions: { secret: process.env.VENDURE_COOKIE_SECRET ?? 'dev-cookie-secret' },

package/kit/templates/base/files/app/(frontend)/categories/[slug]/page.tsx

@@ -20,7 +20,12 @@ export default async function CategoryPage({ params }: PageProps) {
   return (
     <div className="flex flex-col gap-section">
       <Slot name="category.header" category={category} />
-      <h1 className="font-heading text-fg">{category.title}</h1>
+      <header className="flex flex-col gap-unit">
+        <h1 className="font-heading text-fg">{category.title}</h1>
+        {category.description ? (
+          <p className="max-w-prose text-muted-fg">{category.description}</p>
+        ) : null}
+      </header>
       <ProductGrid products={products} />
       <Slot name="category.below-products" />
     </div>

package/kit/templates/base/files/app/(frontend)/page.tsx

@@ -5,17 +5,50 @@ import { getCatalogSource } from '@/lib/adapter';
 import { loadProducts } from '@/lib/catalog/data';
 import { ProductGrid } from '@/components/catalog/ProductGrid';
 
+function DemoHero() {
+  return (
+    <section
+      aria-labelledby="demo-hero-heading"
+      className="flex flex-col gap-gutter border-b border-border pb-section"
+    >
+      <p className="text-sm uppercase tracking-wide text-muted-fg">Demo catalog</p>
+      <h1 id="demo-hero-heading" className="font-heading text-3xl text-fg md:text-4xl">
+        Vitrine
+      </h1>
+      <p className="max-w-prose text-muted-fg">
+        Zero-config seed data is loaded for local development — five products across Apparel and
+        Accessories. Browse a category, open a product with size or color options, add it to the
+        cart, then continue to checkout when a payment provider is configured.
+      </p>
+      <div className="flex flex-wrap gap-gutter">
+        <a
+          href="/categories/apparel"
+          className="rounded-md bg-primary px-gutter py-unit text-primary-fg transition hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 ring-ring"
+        >
+          Shop apparel
+        </a>
+        <a
+          href="/products/classic-tee"
+          className="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"
+        >
+          Try Classic T-Shirt
+        </a>
+      </div>
+    </section>
+  );
+}
+
 export default async function HomePage() {
   const source = await getCatalogSource();
   const products = await loadProducts(source, { perPage: 12 });
 
   return (
     <div className="flex flex-col gap-section">
-      <Slot name="home.hero" />
+      <Slot name="home.hero" fallback={<DemoHero />} />
       <section aria-labelledby="catalog-heading" className="flex flex-col gap-gutter">
-        <h1 id="catalog-heading" className="font-heading text-fg">
+        <h2 id="catalog-heading" className="font-heading text-fg">
           Catalog
-        </h1>
+        </h2>
         <Slot name="catalog.grid-top" />
         <ProductGrid products={products} />
         <Slot name="catalog.grid-bottom" />

package/kit/templates/base/files/next.config.mjs

@@ -1,6 +1,34 @@
+// Baseline security headers (OWASP A05: Security Misconfiguration) applied to every route.
+// The CSP below is a conservative starting point — payment providers with client-side widgets
+// (e.g. embedded Stripe Elements) may need their domains added to script-src/connect-src/frame-src.
+const securityHeaders = [
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'X-Frame-Options', value: 'DENY' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
+  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
+  {
+    key: 'Content-Security-Policy',
+    value:
+      "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https:; frame-ancestors 'none';",
+  },
+];
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   output: 'standalone',
+  // Registry/template sources use TypeScript ESM-style relative imports (`.js` → `.ts`/`.tsx`).
+  // Webpack needs an explicit extensionAlias; without it, `pnpm dev` fails to resolve components.
+  webpack(config) {
+    config.resolve.extensionAlias = {
+      ...(config.resolve.extensionAlias ?? {}),
+      '.js': ['.ts', '.tsx', '.js', '.jsx'],
+    };
+    return config;
+  },
+  async headers() {
+    return [{ source: '/:path*', headers: securityHeaders }];
+  },
 };
 
 // backend-payload overwrites this file (wraps it in withPayload).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitrine-kit/vitrine",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Vitrine CLI — feature install primitive, init (wizard), add, update, doctor, design apply.",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,7 @@
   "dependencies": {
     "@clack/prompts": "^0.8.2",
     "commander": "^12.1.0",
-    "@vitrine-kit/contracts": "1.2.1"
+    "@vitrine-kit/contracts": "1.2.2"
   },
   "scripts": {
     "build": "node scripts/generate-kit-versions.mjs && tsup src/index.ts --format esm --clean && node scripts/copy-kit.mjs",