@vitrine-kit/contracts 1.2.1 → 1.3.0

package/dist/index.cjs

@@ -0,0 +1,388 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BACKENDS: () => BACKENDS,
+  BLUEPRINT_COLLECTIONS: () => BLUEPRINT_COLLECTIONS,
+  BLUEPRINT_FIELD_TYPES: () => BLUEPRINT_FIELD_TYPES,
+  COLOR_TOKENS: () => COLOR_TOKENS,
+  CONTRACTS_VERSION: () => CONTRACTS_VERSION,
+  FONT_TOKENS: () => FONT_TOKENS,
+  FONT_WEIGHT_TOKENS: () => FONT_WEIGHT_TOKENS,
+  LEADING_TOKENS: () => LEADING_TOKENS,
+  MOTION_TOKENS: () => MOTION_TOKENS,
+  RADIUS_TOKENS: () => RADIUS_TOKENS,
+  SHADOW_TOKENS: () => SHADOW_TOKENS,
+  SINGLETON_TOKENS: () => SINGLETON_TOKENS,
+  SLOT_IDS: () => SLOT_IDS,
+  SPACE_TOKENS: () => SPACE_TOKENS,
+  TIERS: () => TIERS,
+  TOKEN_CSS_VARS: () => TOKEN_CSS_VARS,
+  TRACKING_TOKENS: () => TRACKING_TOKENS,
+  backendSchema: () => backendSchema,
+  blueprintCollectionSchema: () => blueprintCollectionSchema,
+  blueprintFieldDefSchema: () => blueprintFieldDefSchema,
+  blueprintManifestSchema: () => blueprintManifestSchema,
+  cssVar: () => cssVar,
+  featureEnvSchema: () => featureEnvSchema,
+  featureFileMapSchema: () => featureFileMapSchema,
+  featureManifestSchema: () => featureManifestSchema,
+  i18nSchema: () => i18nSchema,
+  integrationsSchema: () => integrationsSchema,
+  layoutSectionSchema: () => layoutSectionSchema,
+  registryIndexSchema: () => registryIndexSchema,
+  siteConfigSchema: () => siteConfigSchema,
+  slotIdSchema: () => slotIdSchema,
+  slotRegistrationSchema: () => slotRegistrationSchema,
+  themeSchema: () => themeSchema,
+  tierSchema: () => tierSchema,
+  vitrineLockSchema: () => vitrineLockSchema,
+  vitrinePreset: () => vitrinePreset
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/common.ts
+var import_zod = require("zod");
+var TIERS = ["catalog", "simple-store", "full-store"];
+var tierSchema = import_zod.z.enum(TIERS);
+var BACKENDS = ["payload", "vendure"];
+var backendSchema = import_zod.z.enum(BACKENDS);
+
+// src/tokens.ts
+var COLOR_TOKENS = [
+  "bg",
+  "fg",
+  "muted",
+  "muted-fg",
+  "surface",
+  "surface-fg",
+  "border",
+  "input",
+  "ring",
+  "primary",
+  "primary-fg",
+  "secondary",
+  "secondary-fg",
+  "accent",
+  "accent-fg",
+  "success",
+  "warning",
+  "danger",
+  "danger-fg",
+  "price",
+  "sale"
+];
+var FONT_TOKENS = ["sans", "heading", "mono"];
+var FONT_WEIGHT_TOKENS = ["normal", "medium", "bold", "heading"];
+var LEADING_TOKENS = ["tight", "normal", "relaxed"];
+var TRACKING_TOKENS = ["tight", "normal", "wide"];
+var RADIUS_TOKENS = ["base", "sm", "md", "lg", "full"];
+var SHADOW_TOKENS = ["sm", "md", "lg", "color"];
+var SPACE_TOKENS = ["unit", "container-max", "container-padding", "section-gap"];
+var MOTION_TOKENS = ["duration-fast", "duration-normal", "ease-default"];
+var SINGLETON_TOKENS = ["density", "border-width"];
+function cssVar(group, name) {
+  return name ? `--vt-${group}-${name}` : `--vt-${group}`;
+}
+var TOKEN_CSS_VARS = [
+  ...COLOR_TOKENS.map((t) => cssVar("color", t)),
+  ...FONT_TOKENS.map((t) => cssVar("font", t)),
+  ...FONT_WEIGHT_TOKENS.map((t) => cssVar("weight", t)),
+  ...LEADING_TOKENS.map((t) => cssVar("leading", t)),
+  ...TRACKING_TOKENS.map((t) => cssVar("tracking", t)),
+  ...RADIUS_TOKENS.map((t) => cssVar("radius", t)),
+  ...SHADOW_TOKENS.map((t) => cssVar("shadow", t)),
+  ...SPACE_TOKENS.map((t) => cssVar("space", t)),
+  ...MOTION_TOKENS.map((t) => cssVar("motion", t)),
+  ...SINGLETON_TOKENS.map((t) => cssVar(t))
+];
+var ref = (group, name) => `var(${cssVar(group, name)})`;
+var vitrinePreset = {
+  theme: {
+    extend: {
+      colors: Object.fromEntries(
+        COLOR_TOKENS.map((t) => [t, ref("color", t)])
+      ),
+      fontFamily: {
+        sans: ref("font", "sans"),
+        heading: ref("font", "heading"),
+        mono: ref("font", "mono")
+      },
+      fontWeight: Object.fromEntries(
+        FONT_WEIGHT_TOKENS.map((t) => [t, ref("weight", t)])
+      ),
+      lineHeight: Object.fromEntries(
+        LEADING_TOKENS.map((t) => [t, ref("leading", t)])
+      ),
+      letterSpacing: Object.fromEntries(
+        TRACKING_TOKENS.map((t) => [t, ref("tracking", t)])
+      ),
+      borderRadius: Object.fromEntries(
+        RADIUS_TOKENS.map((t) => [t, ref("radius", t)])
+      ),
+      boxShadow: {
+        sm: ref("shadow", "sm"),
+        md: ref("shadow", "md"),
+        lg: ref("shadow", "lg")
+      },
+      borderWidth: { DEFAULT: ref("border-width") },
+      maxWidth: { container: ref("space", "container-max") },
+      spacing: {
+        unit: ref("space", "unit"),
+        gutter: ref("space", "container-padding"),
+        section: ref("space", "section-gap")
+      },
+      transitionDuration: {
+        fast: ref("motion", "duration-fast"),
+        normal: ref("motion", "duration-normal")
+      },
+      transitionTimingFunction: { DEFAULT: ref("motion", "ease-default") }
+    }
+  }
+};
+
+// src/slots.ts
+var import_zod2 = require("zod");
+var SLOT_IDS = [
+  // global — on every page
+  "global.banner-top",
+  "global.header-start",
+  "global.header-nav",
+  "global.header-actions",
+  "global.footer",
+  "global.body-end",
+  // home
+  "home.hero",
+  "home.below-hero",
+  "home.sections",
+  "home.bottom",
+  // catalog — listing/grid
+  "catalog.toolbar",
+  "catalog.sidebar",
+  "catalog.grid-top",
+  "catalog.grid-bottom",
+  // category
+  "category.header",
+  "category.below-products",
+  // product
+  "product.gallery",
+  "product.below-title",
+  "product.below-price",
+  "product.purchase",
+  "product.below-description",
+  "product.tabs",
+  "product.related",
+  // cart
+  "cart.items-bottom",
+  "cart.summary",
+  "cart.below",
+  // checkout
+  "checkout.top",
+  "checkout.below",
+  // order
+  "order.top",
+  "order.below",
+  // search
+  "search.results-top",
+  "search.empty"
+];
+var slotIdSchema = import_zod2.z.enum(SLOT_IDS);
+var slotRegistrationSchema = import_zod2.z.object({
+  slot: slotIdSchema,
+  component: import_zod2.z.string().min(1),
+  order: import_zod2.z.number().int().optional()
+});
+
+// src/config.ts
+var import_zod3 = require("zod");
+var layoutSectionSchema = import_zod3.z.object({
+  slot: slotIdSchema,
+  enabled: import_zod3.z.boolean().default(true),
+  /** Path to the override component in the client repo (unique — as an override, §13). */
+  override: import_zod3.z.string().optional()
+});
+var integrationsSchema = import_zod3.z.object({
+  payments: import_zod3.z.enum(["stripe", "paddle", "yookassa"]).optional(),
+  email: import_zod3.z.string().optional(),
+  analytics: import_zod3.z.string().optional(),
+  media: import_zod3.z.string().optional(),
+  shipping: import_zod3.z.string().optional()
+}).default({});
+var i18nSchema = import_zod3.z.object({
+  defaultLocale: import_zod3.z.string().default("en"),
+  locales: import_zod3.z.array(import_zod3.z.string()).default(["en"]),
+  currency: import_zod3.z.string().default("USD"),
+  priceFormat: import_zod3.z.string().optional()
+}).default({ defaultLocale: "en", locales: ["en"], currency: "USD" });
+var themeSchema = import_zod3.z.object({
+  name: import_zod3.z.string().default("default"),
+  /** File with token values (filled by the design step). */
+  cssFile: import_zod3.z.string().default("theme/client.css")
+}).default({ name: "default", cssFile: "theme/client.css" });
+var siteConfigSchema = import_zod3.z.object({
+  backend: backendSchema,
+  tier: tierSchema,
+  /**
+   * Storefront display name (header, metadata, footer). Set by `vitrine init`
+   * from the project name; optional for older clients.
+   */
+  name: import_zod3.z.string().min(1).optional(),
+  /** Feature flags: { 'reviews': true }. Set by the install primitive. */
+  features: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.boolean()).default({}),
+  layout: import_zod3.z.object({ sections: import_zod3.z.array(layoutSectionSchema).default([]) }).default({ sections: [] }),
+  theme: themeSchema,
+  integrations: integrationsSchema,
+  i18n: i18nSchema
+});
+
+// src/blueprint.ts
+var import_zod4 = require("zod");
+var BLUEPRINT_COLLECTIONS = [
+  "product",
+  "variant",
+  "category",
+  "media",
+  "order",
+  "user"
+];
+var blueprintCollectionSchema = import_zod4.z.enum(BLUEPRINT_COLLECTIONS);
+var BLUEPRINT_FIELD_TYPES = [
+  "text",
+  "textarea",
+  "richText",
+  "number",
+  "checkbox",
+  "select",
+  "relationship",
+  "date",
+  "json",
+  "array",
+  "group"
+];
+var blueprintFieldDefSchema = import_zod4.z.object({
+  name: import_zod4.z.string().min(1),
+  type: import_zod4.z.enum(BLUEPRINT_FIELD_TYPES),
+  required: import_zod4.z.boolean().optional(),
+  label: import_zod4.z.string().optional()
+}).passthrough();
+var blueprintManifestSchema = import_zod4.z.object({
+  extend: blueprintCollectionSchema,
+  addFields: import_zod4.z.array(import_zod4.z.string().min(1))
+});
+
+// src/manifest.ts
+var import_zod5 = require("zod");
+var featureFileMapSchema = import_zod5.z.object({
+  from: import_zod5.z.string().min(1),
+  to: import_zod5.z.string().min(1)
+});
+var featureEnvSchema = import_zod5.z.object({
+  key: import_zod5.z.string().min(1),
+  required: import_zod5.z.boolean().default(false)
+});
+var featureManifestSchema = import_zod5.z.object({
+  name: import_zod5.z.string().min(1),
+  title: import_zod5.z.string().min(1),
+  kitVersion: import_zod5.z.string().min(1),
+  /** semver range of required contracts, e.g. ">=1.0.0 <2.0.0". */
+  requiresContracts: import_zod5.z.string().min(1),
+  tier: import_zod5.z.array(tierSchema).nonempty(),
+  registryDependencies: import_zod5.z.array(import_zod5.z.string()).default([]),
+  /** Versioned packages: { "@vitrine-kit/core": ">=1.0.0" }. */
+  corePackages: import_zod5.z.record(import_zod5.z.string(), import_zod5.z.string()).default({}),
+  npm: import_zod5.z.array(import_zod5.z.string()).default([]),
+  files: import_zod5.z.array(featureFileMapSchema).default([]),
+  config: import_zod5.z.object({ set: import_zod5.z.record(import_zod5.z.string(), import_zod5.z.boolean()) }).optional(),
+  /**
+   * The payment provider of a checkout-<provider> feature. From it the CLI: (1) generates
+   * the provider registration in lib/payments.ts, (2) sets integrations.payments
+   * in site.config. register<Pascal>Provider() is exported from lib/<name>/register.ts.
+   */
+  payment: import_zod5.z.object({ provider: import_zod5.z.enum(["stripe", "paddle", "yookassa"]) }).optional(),
+  slots: import_zod5.z.array(slotRegistrationSchema).default([]),
+  blueprint: blueprintManifestSchema.optional(),
+  env: import_zod5.z.array(featureEnvSchema).default([]),
+  /** Doc appended to the client's CLAUDE.md. */
+  claudeDoc: import_zod5.z.string().optional(),
+  conflicts: import_zod5.z.array(import_zod5.z.string()).default([]),
+  removable: import_zod5.z.boolean().default(true)
+});
+var vitrineLockSchema = import_zod5.z.object({
+  kitVersion: import_zod5.z.string().min(1),
+  contracts: import_zod5.z.string().min(1),
+  backend: backendSchema,
+  tier: tierSchema,
+  features: import_zod5.z.record(import_zod5.z.string(), import_zod5.z.object({ version: import_zod5.z.string().min(1) })).default({})
+});
+var registryIndexSchema = import_zod5.z.object({
+  kitVersion: import_zod5.z.string().min(1),
+  contracts: import_zod5.z.string().min(1),
+  features: import_zod5.z.record(
+    import_zod5.z.string(),
+    import_zod5.z.object({
+      title: import_zod5.z.string(),
+      kitVersion: import_zod5.z.string(),
+      tier: import_zod5.z.array(tierSchema)
+    })
+  ).default({})
+});
+
+// src/index.ts
+var CONTRACTS_VERSION = "1.0.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BACKENDS,
+  BLUEPRINT_COLLECTIONS,
+  BLUEPRINT_FIELD_TYPES,
+  COLOR_TOKENS,
+  CONTRACTS_VERSION,
+  FONT_TOKENS,
+  FONT_WEIGHT_TOKENS,
+  LEADING_TOKENS,
+  MOTION_TOKENS,
+  RADIUS_TOKENS,
+  SHADOW_TOKENS,
+  SINGLETON_TOKENS,
+  SLOT_IDS,
+  SPACE_TOKENS,
+  TIERS,
+  TOKEN_CSS_VARS,
+  TRACKING_TOKENS,
+  backendSchema,
+  blueprintCollectionSchema,
+  blueprintFieldDefSchema,
+  blueprintManifestSchema,
+  cssVar,
+  featureEnvSchema,
+  featureFileMapSchema,
+  featureManifestSchema,
+  i18nSchema,
+  integrationsSchema,
+  layoutSectionSchema,
+  registryIndexSchema,
+  siteConfigSchema,
+  slotIdSchema,
+  slotRegistrationSchema,
+  themeSchema,
+  tierSchema,
+  vitrineLockSchema,
+  vitrinePreset
+});

package/dist/index.d.cts

@@ -0,0 +1,728 @@
+import { z } from 'zod';
+
+declare const TIERS: readonly ["catalog", "simple-store", "full-store"];
+type Tier = (typeof TIERS)[number];
+declare const tierSchema: z.ZodEnum<["catalog", "simple-store", "full-store"]>;
+declare const BACKENDS: readonly ["payload", "vendure"];
+type Backend = (typeof BACKENDS)[number];
+declare const backendSchema: z.ZodEnum<["payload", "vendure"]>;
+
+declare const COLOR_TOKENS: readonly ["bg", "fg", "muted", "muted-fg", "surface", "surface-fg", "border", "input", "ring", "primary", "primary-fg", "secondary", "secondary-fg", "accent", "accent-fg", "success", "warning", "danger", "danger-fg", "price", "sale"];
+type ColorToken = (typeof COLOR_TOKENS)[number];
+declare const FONT_TOKENS: readonly ["sans", "heading", "mono"];
+type FontToken = (typeof FONT_TOKENS)[number];
+declare const FONT_WEIGHT_TOKENS: readonly ["normal", "medium", "bold", "heading"];
+type FontWeightToken = (typeof FONT_WEIGHT_TOKENS)[number];
+declare const LEADING_TOKENS: readonly ["tight", "normal", "relaxed"];
+type LeadingToken = (typeof LEADING_TOKENS)[number];
+declare const TRACKING_TOKENS: readonly ["tight", "normal", "wide"];
+type TrackingToken = (typeof TRACKING_TOKENS)[number];
+declare const RADIUS_TOKENS: readonly ["base", "sm", "md", "lg", "full"];
+type RadiusToken = (typeof RADIUS_TOKENS)[number];
+declare const SHADOW_TOKENS: readonly ["sm", "md", "lg", "color"];
+type ShadowToken = (typeof SHADOW_TOKENS)[number];
+declare const SPACE_TOKENS: readonly ["unit", "container-max", "container-padding", "section-gap"];
+type SpaceToken = (typeof SPACE_TOKENS)[number];
+declare const MOTION_TOKENS: readonly ["duration-fast", "duration-normal", "ease-default"];
+type MotionToken = (typeof MOTION_TOKENS)[number];
+/** Single "knobs" without a group. */
+declare const SINGLETON_TOKENS: readonly ["density", "border-width"];
+type SingletonToken = (typeof SINGLETON_TOKENS)[number];
+/** CSS variable name for a token: cssVar('color','primary') → '--vt-color-primary'. */
+declare function cssVar(group: string, name?: string): `--vt-${string}`;
+/** Full list of the contract's CSS variable names — for theme scaffolding and docs. */
+declare const TOKEN_CSS_VARS: string[];
+/**
+ * The Vitrine Tailwind preset: maps Tailwind keys to the contract's CSS variables.
+ * Used in the client's tailwind.config: `presets: [vitrinePreset]`.
+ * Loosely typed so contracts don't take a dependency on tailwindcss.
+ */
+declare const vitrinePreset: {
+    theme: {
+        extend: Record<string, unknown>;
+    };
+};
+
+/**
+ * Money — an integer in the currency's minor units (cents).
+ * 2490 = 24.90. Decision is fixed (see the demo seed, spec §18.2).
+ */
+type Money = number;
+/** ISO 4217, e.g. 'USD', 'EUR', 'GBP'. */
+type CurrencyCode = string;
+interface Category {
+    id: string;
+    slug: string;
+    title: string;
+    parentId?: string | null;
+    description?: string;
+}
+interface ProductImage {
+    url: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+}
+interface Variant {
+    id: string;
+    sku: string;
+    title?: string;
+    price: Money;
+    currency: CurrencyCode;
+    /** null/undefined = stock not tracked. */
+    stock?: number | null;
+    /** Variant options, e.g. { size: 'M', color: 'red' }. */
+    options?: Record<string, string>;
+}
+interface Seo {
+    title?: string;
+    description?: string;
+    image?: string;
+}
+interface Product {
+    id: string;
+    slug: string;
+    title: string;
+    description?: string;
+    categoryIds: string[];
+    images: ProductImage[];
+    variants: Variant[];
+    priceRange?: {
+        min: Money;
+        max: Money;
+        currency: CurrencyCode;
+    };
+    seo?: Seo;
+    /**
+     * Fields added by features via blueprint extend() (contract 5),
+     * mapped here by the adapter. The contract stays stable — features read their own keys.
+     */
+    extensions?: Record<string, unknown>;
+}
+type ProductSort = 'newest' | 'price-asc' | 'price-desc' | 'relevance';
+interface ProductQuery {
+    /** Category slug. */
+    category?: string;
+    search?: string;
+    sort?: ProductSort;
+    page?: number;
+    perPage?: number;
+    /** Filter facets: { color: ['red','blue'], size: ['M'] }. */
+    filters?: Record<string, string[]>;
+    /** Inclusive lower bound on variant/list price (minor units, e.g. cents). */
+    priceMin?: number;
+    /** Inclusive upper bound on variant/list price (minor units, e.g. cents). */
+    priceMax?: number;
+    /**
+     * CMS / storefront locale (path cookie or explicit). Adapters that support
+     * localized fields pass this through to the backend; others ignore it.
+     */
+    locale?: string;
+}
+interface CartLine {
+    id: string;
+    variantId: string;
+    productId: string;
+    title: string;
+    quantity: number;
+    unitPrice: Money;
+    lineTotal: Money;
+    image?: string;
+}
+interface Cart {
+    id: string;
+    lines: CartLine[];
+    currency: CurrencyCode;
+    subtotal: Money;
+    discountTotal?: Money;
+    total: Money;
+}
+type OrderStatus = 'pending' | 'paid' | 'fulfilled' | 'cancelled' | 'refunded';
+interface OrderLine {
+    variantId: string;
+    productId: string;
+    title: string;
+    quantity: number;
+    unitPrice: Money;
+    lineTotal: Money;
+}
+interface Order {
+    id: string;
+    number?: string;
+    status: OrderStatus;
+    lines: OrderLine[];
+    currency: CurrencyCode;
+    subtotal: Money;
+    discountTotal?: Money;
+    total: Money;
+    email?: string;
+    /** ISO-8601. */
+    createdAt: string;
+}
+/**
+ * Catalog source. Implemented by the PayloadCatalog* / VendureCatalog* adapters.
+ * Needed at every tier (catalog and above).
+ */
+interface CatalogSource {
+    listProducts(query: ProductQuery): Promise<Product[]>;
+    /** Optional locale selects localized CMS fields when the backend supports them. */
+    getProduct(slug: string, locale?: string): Promise<Product | null>;
+    listCategories(locale?: string): Promise<Category[]>;
+    search(term: string, locale?: string): Promise<Product[]>;
+}
+/**
+ * Commerce backend. Only simple-store / full-store.
+ * Implemented by PayloadCommerce* / VendureCommerce*.
+ * The full cart surface is fixed in v1 (adding methods to the interface
+ * later = a breaking change for implementations).
+ */
+interface CommerceBackend {
+    createCart(): Promise<Cart>;
+    getCart(cartId: string): Promise<Cart | null>;
+    addItem(cartId: string, variantId: string, qty: number): Promise<Cart>;
+    updateItem(cartId: string, lineId: string, qty: number): Promise<Cart>;
+    removeItem(cartId: string, lineId: string): Promise<Cart>;
+    /** Hosted checkout of the active payment provider → redirectUrl. */
+    startCheckout(cartId: string): Promise<{
+        redirectUrl: string;
+    }>;
+    getOrder(id: string): Promise<Order | null>;
+}
+
+/** 32 v1 slots. Order and grouping match the approved proposal. */
+declare const SLOT_IDS: readonly ["global.banner-top", "global.header-start", "global.header-nav", "global.header-actions", "global.footer", "global.body-end", "home.hero", "home.below-hero", "home.sections", "home.bottom", "catalog.toolbar", "catalog.sidebar", "catalog.grid-top", "catalog.grid-bottom", "category.header", "category.below-products", "product.gallery", "product.below-title", "product.below-price", "product.purchase", "product.below-description", "product.tabs", "product.related", "cart.items-bottom", "cart.summary", "cart.below", "checkout.top", "checkout.below", "order.top", "order.below", "search.results-top", "search.empty"];
+type SlotId = (typeof SLOT_IDS)[number];
+/** Zod enum of slots (for validating feature.json / site.config). */
+declare const slotIdSchema: z.ZodEnum<["global.banner-top", "global.header-start", "global.header-nav", "global.header-actions", "global.footer", "global.body-end", "home.hero", "home.below-hero", "home.sections", "home.bottom", "catalog.toolbar", "catalog.sidebar", "catalog.grid-top", "catalog.grid-bottom", "category.header", "category.below-products", "product.gallery", "product.below-title", "product.below-price", "product.purchase", "product.below-description", "product.tabs", "product.related", "cart.items-bottom", "cart.summary", "cart.below", "checkout.top", "checkout.below", "order.top", "order.below", "search.results-top", "search.empty"]>;
+/**
+ * Declarative slot registration in the feature manifest (feature.json, spec §8):
+ * component is the component NAME, resolved in the client repository.
+ */
+declare const slotRegistrationSchema: z.ZodObject<{
+    slot: z.ZodEnum<["global.banner-top", "global.header-start", "global.header-nav", "global.header-actions", "global.footer", "global.body-end", "home.hero", "home.below-hero", "home.sections", "home.bottom", "catalog.toolbar", "catalog.sidebar", "catalog.grid-top", "catalog.grid-bottom", "category.header", "category.below-products", "product.gallery", "product.below-title", "product.below-price", "product.purchase", "product.below-description", "product.tabs", "product.related", "cart.items-bottom", "cart.summary", "cart.below", "checkout.top", "checkout.below", "order.top", "order.below", "search.results-top", "search.empty"]>;
+    component: z.ZodString;
+    order: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+    component: string;
+    order?: number | undefined;
+}, {
+    slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+    component: string;
+    order?: number | undefined;
+}>;
+type SlotRegistration = z.infer<typeof slotRegistrationSchema>;
+/**
+ * Runtime binding of a name to an actual component (used by @vitrine-kit/core
+ * in the client's lib/slots.ts). Generic over the component type so the contract
+ * doesn't depend on React.
+ */
+interface SlotMount<TComponent = unknown> {
+    slot: SlotId;
+    component: TComponent;
+    order?: number;
+}
+
+/** Override/ordering of a page section (composition over the wireframe). */
+declare const layoutSectionSchema: z.ZodObject<{
+    slot: z.ZodEnum<["global.banner-top", "global.header-start", "global.header-nav", "global.header-actions", "global.footer", "global.body-end", "home.hero", "home.below-hero", "home.sections", "home.bottom", "catalog.toolbar", "catalog.sidebar", "catalog.grid-top", "catalog.grid-bottom", "category.header", "category.below-products", "product.gallery", "product.below-title", "product.below-price", "product.purchase", "product.below-description", "product.tabs", "product.related", "cart.items-bottom", "cart.summary", "cart.below", "checkout.top", "checkout.below", "order.top", "order.below", "search.results-top", "search.empty"]>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /** Path to the override component in the client repo (unique — as an override, §13). */
+    override: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+    enabled: boolean;
+    override?: string | undefined;
+}, {
+    slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+    enabled?: boolean | undefined;
+    override?: string | undefined;
+}>;
+type LayoutSection = z.infer<typeof layoutSectionSchema>;
+declare const integrationsSchema: z.ZodDefault<z.ZodObject<{
+    payments: z.ZodOptional<z.ZodEnum<["stripe", "paddle", "yookassa"]>>;
+    email: z.ZodOptional<z.ZodString>;
+    analytics: z.ZodOptional<z.ZodString>;
+    media: z.ZodOptional<z.ZodString>;
+    shipping: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    payments?: "stripe" | "paddle" | "yookassa" | undefined;
+    email?: string | undefined;
+    analytics?: string | undefined;
+    media?: string | undefined;
+    shipping?: string | undefined;
+}, {
+    payments?: "stripe" | "paddle" | "yookassa" | undefined;
+    email?: string | undefined;
+    analytics?: string | undefined;
+    media?: string | undefined;
+    shipping?: string | undefined;
+}>>;
+declare const i18nSchema: z.ZodDefault<z.ZodObject<{
+    defaultLocale: z.ZodDefault<z.ZodString>;
+    locales: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    currency: z.ZodDefault<z.ZodString>;
+    priceFormat: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    defaultLocale: string;
+    locales: string[];
+    currency: string;
+    priceFormat?: string | undefined;
+}, {
+    defaultLocale?: string | undefined;
+    locales?: string[] | undefined;
+    currency?: string | undefined;
+    priceFormat?: string | undefined;
+}>>;
+declare const themeSchema: z.ZodDefault<z.ZodObject<{
+    name: z.ZodDefault<z.ZodString>;
+    /** File with token values (filled by the design step). */
+    cssFile: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    cssFile: string;
+}, {
+    name?: string | undefined;
+    cssFile?: string | undefined;
+}>>;
+declare const siteConfigSchema: z.ZodObject<{
+    backend: z.ZodEnum<["payload", "vendure"]>;
+    tier: z.ZodEnum<["catalog", "simple-store", "full-store"]>;
+    /**
+     * Storefront display name (header, metadata, footer). Set by `vitrine init`
+     * from the project name; optional for older clients.
+     */
+    name: z.ZodOptional<z.ZodString>;
+    /** Feature flags: { 'reviews': true }. Set by the install primitive. */
+    features: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    layout: z.ZodDefault<z.ZodObject<{
+        sections: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            slot: z.ZodEnum<["global.banner-top", "global.header-start", "global.header-nav", "global.header-actions", "global.footer", "global.body-end", "home.hero", "home.below-hero", "home.sections", "home.bottom", "catalog.toolbar", "catalog.sidebar", "catalog.grid-top", "catalog.grid-bottom", "category.header", "category.below-products", "product.gallery", "product.below-title", "product.below-price", "product.purchase", "product.below-description", "product.tabs", "product.related", "cart.items-bottom", "cart.summary", "cart.below", "checkout.top", "checkout.below", "order.top", "order.below", "search.results-top", "search.empty"]>;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            /** Path to the override component in the client repo (unique — as an override, §13). */
+            override: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+            enabled: boolean;
+            override?: string | undefined;
+        }, {
+            slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+            enabled?: boolean | undefined;
+            override?: string | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        sections: {
+            slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+            enabled: boolean;
+            override?: string | undefined;
+        }[];
+    }, {
+        sections?: {
+            slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+            enabled?: boolean | undefined;
+            override?: string | undefined;
+        }[] | undefined;
+    }>>;
+    theme: z.ZodDefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        /** File with token values (filled by the design step). */
+        cssFile: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        cssFile: string;
+    }, {
+        name?: string | undefined;
+        cssFile?: string | undefined;
+    }>>;
+    integrations: z.ZodDefault<z.ZodObject<{
+        payments: z.ZodOptional<z.ZodEnum<["stripe", "paddle", "yookassa"]>>;
+        email: z.ZodOptional<z.ZodString>;
+        analytics: z.ZodOptional<z.ZodString>;
+        media: z.ZodOptional<z.ZodString>;
+        shipping: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        payments?: "stripe" | "paddle" | "yookassa" | undefined;
+        email?: string | undefined;
+        analytics?: string | undefined;
+        media?: string | undefined;
+        shipping?: string | undefined;
+    }, {
+        payments?: "stripe" | "paddle" | "yookassa" | undefined;
+        email?: string | undefined;
+        analytics?: string | undefined;
+        media?: string | undefined;
+        shipping?: string | undefined;
+    }>>;
+    i18n: z.ZodDefault<z.ZodObject<{
+        defaultLocale: z.ZodDefault<z.ZodString>;
+        locales: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        currency: z.ZodDefault<z.ZodString>;
+        priceFormat: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        defaultLocale: string;
+        locales: string[];
+        currency: string;
+        priceFormat?: string | undefined;
+    }, {
+        defaultLocale?: string | undefined;
+        locales?: string[] | undefined;
+        currency?: string | undefined;
+        priceFormat?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    backend: "payload" | "vendure";
+    tier: "catalog" | "simple-store" | "full-store";
+    features: Record<string, boolean>;
+    layout: {
+        sections: {
+            slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+            enabled: boolean;
+            override?: string | undefined;
+        }[];
+    };
+    theme: {
+        name: string;
+        cssFile: string;
+    };
+    integrations: {
+        payments?: "stripe" | "paddle" | "yookassa" | undefined;
+        email?: string | undefined;
+        analytics?: string | undefined;
+        media?: string | undefined;
+        shipping?: string | undefined;
+    };
+    i18n: {
+        defaultLocale: string;
+        locales: string[];
+        currency: string;
+        priceFormat?: string | undefined;
+    };
+    name?: string | undefined;
+}, {
+    backend: "payload" | "vendure";
+    tier: "catalog" | "simple-store" | "full-store";
+    name?: string | undefined;
+    features?: Record<string, boolean> | undefined;
+    layout?: {
+        sections?: {
+            slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+            enabled?: boolean | undefined;
+            override?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    theme?: {
+        name?: string | undefined;
+        cssFile?: string | undefined;
+    } | undefined;
+    integrations?: {
+        payments?: "stripe" | "paddle" | "yookassa" | undefined;
+        email?: string | undefined;
+        analytics?: string | undefined;
+        media?: string | undefined;
+        shipping?: string | undefined;
+    } | undefined;
+    i18n?: {
+        defaultLocale?: string | undefined;
+        locales?: string[] | undefined;
+        currency?: string | undefined;
+        priceFormat?: string | undefined;
+    } | undefined;
+}>;
+type SiteConfig = z.infer<typeof siteConfigSchema>;
+
+/** Base blueprint collections a feature can extend. */
+declare const BLUEPRINT_COLLECTIONS: readonly ["product", "variant", "category", "media", "order", "user"];
+type BlueprintCollection = (typeof BLUEPRINT_COLLECTIONS)[number];
+declare const blueprintCollectionSchema: z.ZodEnum<["product", "variant", "category", "media", "order", "user"]>;
+/** Supported types for added fields (minimal v1 set). */
+declare const BLUEPRINT_FIELD_TYPES: readonly ["text", "textarea", "richText", "number", "checkbox", "select", "relationship", "date", "json", "array", "group"];
+type BlueprintFieldType = (typeof BLUEPRINT_FIELD_TYPES)[number];
+/**
+ * Definition of an added field (runtime form for @vitrine-kit/payload-blueprint).
+ * Allows extra Payload field keys (options, relationTo, …) via passthrough.
+ */
+declare const blueprintFieldDefSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<["text", "textarea", "richText", "number", "checkbox", "select", "relationship", "date", "json", "array", "group"]>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    name: z.ZodString;
+    type: z.ZodEnum<["text", "textarea", "richText", "number", "checkbox", "select", "relationship", "date", "json", "array", "group"]>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    name: z.ZodString;
+    type: z.ZodEnum<["text", "textarea", "richText", "number", "checkbox", "select", "relationship", "date", "json", "array", "group"]>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+type BlueprintFieldDef = z.infer<typeof blueprintFieldDefSchema>;
+/** Runtime extension applied by extend(). */
+interface BlueprintExtension {
+    extend: BlueprintCollection;
+    addFields: BlueprintFieldDef[];
+}
+/**
+ * The extend() signature, implemented in @vitrine-kit/payload-blueprint.
+ * Additive by contract: it adds fields to a collection.
+ */
+type Extend = (collection: BlueprintCollection, patch: {
+    addFields: BlueprintFieldDef[];
+}) => void;
+/**
+ * The blueprint shape in the feature manifest (feature.json, §8): addFields are field NAMES
+ * (strings); the actual definitions live in the feature code / payload-blueprint.
+ */
+declare const blueprintManifestSchema: z.ZodObject<{
+    extend: z.ZodEnum<["product", "variant", "category", "media", "order", "user"]>;
+    addFields: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    extend: "order" | "media" | "product" | "variant" | "category" | "user";
+    addFields: string[];
+}, {
+    extend: "order" | "media" | "product" | "variant" | "category" | "user";
+    addFields: string[];
+}>;
+type BlueprintManifest = z.infer<typeof blueprintManifestSchema>;
+
+declare const featureFileMapSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    from: string;
+    to: string;
+}, {
+    from: string;
+    to: string;
+}>;
+declare const featureEnvSchema: z.ZodObject<{
+    key: z.ZodString;
+    required: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    required: boolean;
+    key: string;
+}, {
+    key: string;
+    required?: boolean | undefined;
+}>;
+/** registry/<feature>/feature.json — the declarative feature manifest (§8). */
+declare const featureManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodString;
+    kitVersion: z.ZodString;
+    /** semver range of required contracts, e.g. ">=1.0.0 <2.0.0". */
+    requiresContracts: z.ZodString;
+    tier: z.ZodArray<z.ZodEnum<["catalog", "simple-store", "full-store"]>, "atleastone">;
+    registryDependencies: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Versioned packages: { "@vitrine-kit/core": ">=1.0.0" }. */
+    corePackages: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    npm: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        from: string;
+        to: string;
+    }, {
+        from: string;
+        to: string;
+    }>, "many">>;
+    config: z.ZodOptional<z.ZodObject<{
+        set: z.ZodRecord<z.ZodString, z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        set: Record<string, boolean>;
+    }, {
+        set: Record<string, boolean>;
+    }>>;
+    /**
+     * The payment provider of a checkout-<provider> feature. From it the CLI: (1) generates
+     * the provider registration in lib/payments.ts, (2) sets integrations.payments
+     * in site.config. register<Pascal>Provider() is exported from lib/<name>/register.ts.
+     */
+    payment: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodEnum<["stripe", "paddle", "yookassa"]>;
+    }, "strip", z.ZodTypeAny, {
+        provider: "stripe" | "paddle" | "yookassa";
+    }, {
+        provider: "stripe" | "paddle" | "yookassa";
+    }>>;
+    slots: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        slot: z.ZodEnum<["global.banner-top", "global.header-start", "global.header-nav", "global.header-actions", "global.footer", "global.body-end", "home.hero", "home.below-hero", "home.sections", "home.bottom", "catalog.toolbar", "catalog.sidebar", "catalog.grid-top", "catalog.grid-bottom", "category.header", "category.below-products", "product.gallery", "product.below-title", "product.below-price", "product.purchase", "product.below-description", "product.tabs", "product.related", "cart.items-bottom", "cart.summary", "cart.below", "checkout.top", "checkout.below", "order.top", "order.below", "search.results-top", "search.empty"]>;
+        component: z.ZodString;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+        component: string;
+        order?: number | undefined;
+    }, {
+        slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+        component: string;
+        order?: number | undefined;
+    }>, "many">>;
+    blueprint: z.ZodOptional<z.ZodObject<{
+        extend: z.ZodEnum<["product", "variant", "category", "media", "order", "user"]>;
+        addFields: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        extend: "order" | "media" | "product" | "variant" | "category" | "user";
+        addFields: string[];
+    }, {
+        extend: "order" | "media" | "product" | "variant" | "category" | "user";
+        addFields: string[];
+    }>>;
+    env: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        required: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        required: boolean;
+        key: string;
+    }, {
+        key: string;
+        required?: boolean | undefined;
+    }>, "many">>;
+    /** Doc appended to the client's CLAUDE.md. */
+    claudeDoc: z.ZodOptional<z.ZodString>;
+    conflicts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    removable: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    tier: ["catalog" | "simple-store" | "full-store", ...("catalog" | "simple-store" | "full-store")[]];
+    title: string;
+    kitVersion: string;
+    requiresContracts: string;
+    registryDependencies: string[];
+    corePackages: Record<string, string>;
+    npm: string[];
+    files: {
+        from: string;
+        to: string;
+    }[];
+    slots: {
+        slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+        component: string;
+        order?: number | undefined;
+    }[];
+    env: {
+        required: boolean;
+        key: string;
+    }[];
+    conflicts: string[];
+    removable: boolean;
+    config?: {
+        set: Record<string, boolean>;
+    } | undefined;
+    payment?: {
+        provider: "stripe" | "paddle" | "yookassa";
+    } | undefined;
+    blueprint?: {
+        extend: "order" | "media" | "product" | "variant" | "category" | "user";
+        addFields: string[];
+    } | undefined;
+    claudeDoc?: string | undefined;
+}, {
+    name: string;
+    tier: ["catalog" | "simple-store" | "full-store", ...("catalog" | "simple-store" | "full-store")[]];
+    title: string;
+    kitVersion: string;
+    requiresContracts: string;
+    registryDependencies?: string[] | undefined;
+    corePackages?: Record<string, string> | undefined;
+    npm?: string[] | undefined;
+    files?: {
+        from: string;
+        to: string;
+    }[] | undefined;
+    config?: {
+        set: Record<string, boolean>;
+    } | undefined;
+    payment?: {
+        provider: "stripe" | "paddle" | "yookassa";
+    } | undefined;
+    slots?: {
+        slot: "global.banner-top" | "global.header-start" | "global.header-nav" | "global.header-actions" | "global.footer" | "global.body-end" | "home.hero" | "home.below-hero" | "home.sections" | "home.bottom" | "catalog.toolbar" | "catalog.sidebar" | "catalog.grid-top" | "catalog.grid-bottom" | "category.header" | "category.below-products" | "product.gallery" | "product.below-title" | "product.below-price" | "product.purchase" | "product.below-description" | "product.tabs" | "product.related" | "cart.items-bottom" | "cart.summary" | "cart.below" | "checkout.top" | "checkout.below" | "order.top" | "order.below" | "search.results-top" | "search.empty";
+        component: string;
+        order?: number | undefined;
+    }[] | undefined;
+    blueprint?: {
+        extend: "order" | "media" | "product" | "variant" | "category" | "user";
+        addFields: string[];
+    } | undefined;
+    env?: {
+        key: string;
+        required?: boolean | undefined;
+    }[] | undefined;
+    claudeDoc?: string | undefined;
+    conflicts?: string[] | undefined;
+    removable?: boolean | undefined;
+}>;
+type FeatureManifest = z.infer<typeof featureManifestSchema>;
+/** vitrine.json — the client repo's lock file (§6). */
+declare const vitrineLockSchema: z.ZodObject<{
+    kitVersion: z.ZodString;
+    contracts: z.ZodString;
+    backend: z.ZodEnum<["payload", "vendure"]>;
+    tier: z.ZodEnum<["catalog", "simple-store", "full-store"]>;
+    features: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        version: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+    }, {
+        version: string;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    backend: "payload" | "vendure";
+    tier: "catalog" | "simple-store" | "full-store";
+    features: Record<string, {
+        version: string;
+    }>;
+    kitVersion: string;
+    contracts: string;
+}, {
+    backend: "payload" | "vendure";
+    tier: "catalog" | "simple-store" | "full-store";
+    kitVersion: string;
+    contracts: string;
+    features?: Record<string, {
+        version: string;
+    }> | undefined;
+}>;
+type VitrineLock = z.infer<typeof vitrineLockSchema>;
+/** registry/_index.json — the registry manifest: all features + the kit version. */
+declare const registryIndexSchema: z.ZodObject<{
+    kitVersion: z.ZodString;
+    contracts: z.ZodString;
+    features: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        title: z.ZodString;
+        kitVersion: z.ZodString;
+        tier: z.ZodArray<z.ZodEnum<["catalog", "simple-store", "full-store"]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        tier: ("catalog" | "simple-store" | "full-store")[];
+        title: string;
+        kitVersion: string;
+    }, {
+        tier: ("catalog" | "simple-store" | "full-store")[];
+        title: string;
+        kitVersion: string;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    features: Record<string, {
+        tier: ("catalog" | "simple-store" | "full-store")[];
+        title: string;
+        kitVersion: string;
+    }>;
+    kitVersion: string;
+    contracts: string;
+}, {
+    kitVersion: string;
+    contracts: string;
+    features?: Record<string, {
+        tier: ("catalog" | "simple-store" | "full-store")[];
+        title: string;
+        kitVersion: string;
+    }> | undefined;
+}>;
+type RegistryIndex = z.infer<typeof registryIndexSchema>;
+
+declare const CONTRACTS_VERSION: "1.0.0";
+
+export { BACKENDS, BLUEPRINT_COLLECTIONS, BLUEPRINT_FIELD_TYPES, type Backend, type BlueprintCollection, type BlueprintExtension, type BlueprintFieldDef, type BlueprintFieldType, type BlueprintManifest, COLOR_TOKENS, CONTRACTS_VERSION, type Cart, type CartLine, type CatalogSource, type Category, type ColorToken, type CommerceBackend, type CurrencyCode, type Extend, FONT_TOKENS, FONT_WEIGHT_TOKENS, type FeatureManifest, type FontToken, type FontWeightToken, LEADING_TOKENS, type LayoutSection, type LeadingToken, MOTION_TOKENS, type Money, type MotionToken, type Order, type OrderLine, type OrderStatus, type Product, type ProductImage, type ProductQuery, type ProductSort, RADIUS_TOKENS, type RadiusToken, type RegistryIndex, SHADOW_TOKENS, SINGLETON_TOKENS, SLOT_IDS, SPACE_TOKENS, type Seo, type ShadowToken, type SingletonToken, type SiteConfig, type SlotId, type SlotMount, type SlotRegistration, type SpaceToken, TIERS, TOKEN_CSS_VARS, TRACKING_TOKENS, type Tier, type TrackingToken, type Variant, type VitrineLock, backendSchema, blueprintCollectionSchema, blueprintFieldDefSchema, blueprintManifestSchema, cssVar, featureEnvSchema, featureFileMapSchema, featureManifestSchema, i18nSchema, integrationsSchema, layoutSectionSchema, registryIndexSchema, siteConfigSchema, slotIdSchema, slotRegistrationSchema, themeSchema, tierSchema, vitrineLockSchema, vitrinePreset };

package/dist/index.d.ts

@@ -45,7 +45,7 @@ declare const vitrinePreset: {
 
 /**
  * Money — an integer in the currency's minor units (cents).
- * 199000 = 1990.00. Decision is fixed (see the demo seed, spec §18.2).
+ * 2490 = 24.90. Decision is fixed (see the demo seed, spec §18.2).
  */
 type Money = number;
 /** ISO 4217, e.g. 'USD', 'EUR', 'GBP'. */
@@ -109,6 +109,15 @@ interface ProductQuery {
     perPage?: number;
     /** Filter facets: { color: ['red','blue'], size: ['M'] }. */
     filters?: Record<string, string[]>;
+    /** Inclusive lower bound on variant/list price (minor units, e.g. cents). */
+    priceMin?: number;
+    /** Inclusive upper bound on variant/list price (minor units, e.g. cents). */
+    priceMax?: number;
+    /**
+     * CMS / storefront locale (path cookie or explicit). Adapters that support
+     * localized fields pass this through to the backend; others ignore it.
+     */
+    locale?: string;
 }
 interface CartLine {
     id: string;
@@ -156,9 +165,10 @@ interface Order {
  */
 interface CatalogSource {
     listProducts(query: ProductQuery): Promise<Product[]>;
-    getProduct(slug: string): Promise<Product | null>;
-    listCategories(): Promise<Category[]>;
-    search(term: string): Promise<Product[]>;
+    /** Optional locale selects localized CMS fields when the backend supports them. */
+    getProduct(slug: string, locale?: string): Promise<Product | null>;
+    listCategories(locale?: string): Promise<Category[]>;
+    search(term: string, locale?: string): Promise<Product[]>;
 }
 /**
  * Commerce backend. Only simple-store / full-store.
@@ -278,6 +288,11 @@ declare const themeSchema: z.ZodDefault<z.ZodObject<{
 declare const siteConfigSchema: z.ZodObject<{
     backend: z.ZodEnum<["payload", "vendure"]>;
     tier: z.ZodEnum<["catalog", "simple-store", "full-store"]>;
+    /**
+     * Storefront display name (header, metadata, footer). Set by `vitrine init`
+     * from the project name; optional for older clients.
+     */
+    name: z.ZodOptional<z.ZodString>;
     /** Feature flags: { 'reviews': true }. Set by the install primitive. */
     features: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
     layout: z.ZodDefault<z.ZodObject<{
@@ -382,9 +397,11 @@ declare const siteConfigSchema: z.ZodObject<{
         currency: string;
         priceFormat?: string | undefined;
     };
+    name?: string | undefined;
 }, {
     backend: "payload" | "vendure";
     tier: "catalog" | "simple-store" | "full-store";
+    name?: string | undefined;
     features?: Record<string, boolean> | undefined;
     layout?: {
         sections?: {

package/dist/index.js

@@ -179,6 +179,11 @@ var themeSchema = z3.object({
 var siteConfigSchema = z3.object({
   backend: backendSchema,
   tier: tierSchema,
+  /**
+   * Storefront display name (header, metadata, footer). Set by `vitrine init`
+   * from the project name; optional for older clients.
+   */
+  name: z3.string().min(1).optional(),
   /** Feature flags: { 'reviews': true }. Set by the install primitive. */
   features: z3.record(z3.string(), z3.boolean()).default({}),
   layout: z3.object({ sections: z3.array(layoutSectionSchema).default([]) }).default({ sections: [] }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitrine-kit/contracts",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Vitrine — the five stable contracts: Tokens, Data, Slots, Config, Blueprint.",
   "license": "MIT",
   "type": "module",
@@ -9,12 +9,14 @@
     "node": ">=20"
   },
   "types": "./dist/index.d.ts",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -36,7 +38,7 @@
     "zod-to-json-schema": "^3.24.1"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
     "schemas": "tsx scripts/generate-schemas.ts"