@vitrine-kit/vitrine 0.4.0 → 0.4.3

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

@@ -11,10 +11,13 @@ A YooKassa (yookassa.ru) provider — Russian acquiring: cards, SBP, wallets. Fo
   sets `integrations.payments: "yookassa"`.
 - **API (Next glue):** `POST /api/webhooks/yookassa` → `handlePaymentWebhook` →
   `fulfillOrderFromEvent`.
-- **env:** `YOOKASSA_SHOP_ID`, `YOOKASSA_SECRET_KEY` (required).
+- **env:** `YOOKASSA_SHOP_ID`, `YOOKASSA_SECRET_KEY` (required — read at call time, a
+  missing key throws `[vitrine] <KEY> is not set …`; webhook route → 400).
 
 **Security:** YooKassa notifications are **not signed** — the provider re-verifies the
-payment via `GET /v3/payments/{id}` and trusts only `status: "succeeded"`.
+payment via `GET /v3/payments/{id}` and trusts only `status: "succeeded"`. A 404 on that
+check (forged/foreign payment id) is acked as `kind: "unknown"`; other API failures throw,
+so the non-200 response makes YooKassa redeliver the notification.
 
 **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

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout-yookassa",
   "title": "Payment — YooKassa",
-  "kitVersion": "0.4.0",
+  "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/checkout-yookassa/files/lib/checkout-yookassa/provider.ts

@@ -18,9 +18,16 @@ function minorToDecimalString(amount: number, currency: string): string {
   return ZERO_DECIMAL.has(currency.toUpperCase()) ? String(amount) : (amount / 100).toFixed(2);
 }
 
+/** Required env, read at call time — `next build` must not need secrets. */
+function requiredEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) throw new Error(`[vitrine] ${key} is not set — add it to .env (see .env.example)`);
+  return value;
+}
+
 function authHeader(): string {
-  const shopId = process.env.YOOKASSA_SHOP_ID ?? '';
-  const secret = process.env.YOOKASSA_SECRET_KEY ?? '';
+  const shopId = requiredEnv('YOOKASSA_SHOP_ID');
+  const secret = requiredEnv('YOOKASSA_SECRET_KEY');
   return `Basic ${Buffer.from(`${shopId}:${secret}`).toString('base64')}`;
 }
 
@@ -57,9 +64,12 @@ export const yookassaProvider: PaymentProvider = {
     const paymentId = body.object?.id;
     if (!paymentId) return { kind: 'unknown', raw: body };
 
-    // The notification is unsigned — re-check the payment via the API.
+    // The notification is unsigned — re-check the payment via the API. 404 = no such
+    // payment for this shop (forged/foreign notification) → ack as 'unknown'; any other
+    // failure is transient → throw (a non-200 response makes YooKassa redeliver later).
     const res = await fetch(`${API}/${paymentId}`, { headers: { Authorization: authHeader() } });
-    if (!res.ok) throw new Error(`[vitrine] YooKassa verify: ${res.status}`);
+    if (res.status === 404) return { kind: 'unknown', raw: body };
+    if (!res.ok) throw new Error(`[vitrine] YooKassa verify: ${res.status} (transient — expecting a redelivery)`);
     const payment = (await res.json()) as {
       id?: string;
       status?: string;

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.0",
+  "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.0",
+  "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/.gitattributes

@@ -0,0 +1,12 @@
+# Normalize line endings to LF — keeps `vitrine update` 3-way merges clean on Windows
+# (.vitrine/originals and the registry are LF; a CRLF working tree would look all-changed).
+* text=auto eol=lf
+
+# Binary assets — no normalization.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary

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).