@vitrine-kit/core 0.2.0 → 0.2.2

package/README.md

@@ -1,7 +1,24 @@
 # @vitrine-kit/core
 
-Критическая логика Vitrine: runtime слотов и адаптера, order pipeline, обработчик Stripe-вебхука.
+Vitrine's critical logic: the slot and adapter runtime, the order pipeline, and provider-neutral payment webhook dispatch.
 
-Здесь — то, где «баг = инцидент у всех клиентов сразу» (§4 спеки). Поэтому это **версионируемый пакет**, а не copy-in: критфикс прилетает всем бампом версии.
+This is where "a bug = an incident for every client at once" (spec §4). That's why it's a **versioned package** rather than copy-in: a critical fix reaches everyone via a version bump.
 
-Скелет (M0). Наполняется в M2 (runtime) и M8 (коммерция).
+## Global registries and isolation
+
+`slotRegistry`, `adapters`, and `payments` are **module-level singletons** — state is shared by
+everything importing this package in one process. That is the right default for a Vitrine client
+(1 client = 1 repository = 1 store; `lib/slots.ts` / `lib/payments.ts` register once at module
+load, which is idempotent-safe because generated registration modules only run once per process).
+
+Do NOT reach for the globals when you need isolation:
+
+- **Tests** — create your own: `createSlotRegistry()`, `createAdapterRegistry()`,
+  `createPaymentRegistry()`; `<Slot registry={...}>` accepts one. Or `clear()` the global in a
+  `finally` block.
+- **Multi-tenant / multi-store servers** — one process serving several stores must NOT share the
+  globals (registrations from one tenant would leak into another). Keep a registry instance per
+  tenant and pass it explicitly.
+
+Registering the same mount twice (e.g. calling a `register<Feature>Slots()` again after HMR)
+duplicates it — re-registration should go through `clear()` first.

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-export { S as SlotRegistry, c as createSlotRegistry, g as getSlotMounts, r as registerSlot, s as slotRegistry } from './registry-B4Ak1hIR.js';
+export { S as SlotRegistry, c as createSlotRegistry, g as getSlotMounts, r as registerSlot, s as slotRegistry } from './registry-CfORxf9H.js';
 import { Backend, SiteConfig, CatalogSource, CommerceBackend, Cart, Order, Money, CurrencyCode, OrderStatus } from '@vitrine-kit/contracts';
 
+declare const CORE_VERSION: "0.2.2";
+
 interface AdapterFactory {
     backend: Backend;
     createCatalog(config: SiteConfig): CatalogSource;
-    /** Отсутствует для чисто-каталожных бэкендов. */
+    /** Absent for catalog-only backends. */
     createCommerce?(config: SiteConfig): CommerceBackend;
 }
 interface AdapterRegistry {
@@ -14,82 +16,82 @@ interface AdapterRegistry {
     clear(): void;
 }
 declare function createAdapterRegistry(): AdapterRegistry;
-/** Глобальный реестр адаптеров по умолчанию. */
+/** The default global adapter registry. */
 declare const adapters: AdapterRegistry;
 
 interface OrderPipelineContext {
     cart: Cart;
-    /** Заполняется шагами пайплайна (создание заказа). */
+    /** Filled by pipeline stages (order creation). */
     order?: Order;
-    /** Произвольные данные шагов (платёж, резерв склада, доставка). */
+    /** Arbitrary stage data (payment, stock reservation, shipping). */
     meta: Record<string, unknown>;
 }
 type OrderStage<T = OrderPipelineContext> = (ctx: T) => T | Promise<T>;
 /**
- * Последовательно прогоняет контекст через шаги. Любая ошибка шага прерывает
- * пайплайн (откат/идемпотентность — ответственность конкретных шагов в M8).
+ * Runs the context through the stages sequentially. Any stage error aborts the
+ * pipeline (rollback/idempotency are the responsibility of specific stages).
  */
 declare function runPipeline<T>(ctx: T, stages: ReadonlyArray<OrderStage<T>>): Promise<T>;
 
 interface OrderCreationGuard {
-    /** Статус корзины (карты Payload `carts`): 'converted' = уже оплачена. */
+    /** Cart status (the Payload `carts` map): 'converted' = already paid. */
     cartStatus?: string | null;
-    /** Референс платежа текущего события (session/transaction/payment id). */
+    /** Payment reference of the current event (session/transaction/payment id). */
     providerRef?: string;
-    /** paymentRef уже существующих заказов (обычно результат точечного поиска). */
+    /** paymentRef of existing orders (usually the result of a targeted lookup). */
     existingOrderRefs?: ReadonlyArray<string | undefined>;
 }
 /**
- * Создавать ли заказ для этого события. false, если корзина уже converted ИЛИ
- * для этого референса платежа заказ уже есть (повторная доставка/ретрай webhook).
+ * Whether to create an order for this event. false if the cart is already converted OR
+ * an order already exists for this payment reference (redelivery/retry of the webhook).
  */
 declare function shouldCreateOrder(guard: OrderCreationGuard): boolean;
 
-/** Совпадает с integrations.payments в site.config (контракт 4). */
+/** Matches integrations.payments in site.config (contract 4). */
 type PaymentProviderName = 'stripe' | 'paddle' | 'yookassa';
 interface CreateCheckoutArgs {
     cart: Cart;
-    /** Базовый URL витрины; success/cancel строятся относительно него. */
+    /** The storefront base URL; success/cancel are built relative to it. */
     baseUrl: string;
-    /** По умолчанию '/order/success'. */
+    /** Defaults to '/order/success'. */
     successPath?: string;
-    /** По умолчанию '/cart'. */
+    /** Defaults to '/cart'. */
     cancelPath?: string;
 }
 interface PaymentWebhookRequest {
     rawBody: string;
     headers: Record<string, string | null>;
 }
-/** Нормализованное событие провайдера — общий язык для роутов вебхуков. */
+/** A normalized provider event — the common language for webhook routes. */
 interface NormalizedPaymentEvent {
     kind: 'checkout_completed' | 'payment_failed' | 'unknown';
-    /** Из metadata/custom_data/label провайдера. */
+    /** From the provider's metadata/custom_data/label. */
     cartId?: string;
-    /** Уникальный референс платежа провайдера — ключ идемпотентности. */
+    /** The provider's unique payment reference — the idempotency key. */
     providerRef?: string;
     email?: string;
-    /** Исходный объект провайдера (на случай, если роуту нужны доп. поля). */
+    /** The raw provider object (in case the route needs extra fields). */
     raw: unknown;
 }
 interface PaymentProvider {
     name: PaymentProviderName;
-    /** Создаёт hosted-checkout у провайдера → URL для редиректа. */
+    /** Creates a hosted checkout at the provider → redirect URL. */
     createCheckout(args: CreateCheckoutArgs): Promise<{
         redirectUrl: string;
     }>;
-    /** Верифицирует подпись/подлинность и нормализует событие. Бросает при невалидном. */
+    /** Verifies the signature/authenticity and normalizes the event. Throws if invalid. */
     verifyWebhook(req: PaymentWebhookRequest): Promise<NormalizedPaymentEvent>;
 }
 
 interface PaymentRegistry {
     register(provider: PaymentProvider): void;
-    /** Активный провайдер по site.config.integrations.payments. */
+    /** The active provider by site.config.integrations.payments. */
     resolve(config: SiteConfig): PaymentProvider;
     get(name: PaymentProviderName): PaymentProvider | undefined;
     clear(): void;
 }
 declare function createPaymentRegistry(): PaymentRegistry;
-/** Глобальный реестр провайдеров по умолчанию. */
+/** The default global provider registry. */
 declare const payments: PaymentRegistry;
 
 interface PaymentWebhookHandlers {
@@ -99,7 +101,7 @@ interface PaymentWebhookHandlers {
 interface PaymentWebhookResult {
     received: true;
     kind: NormalizedPaymentEvent['kind'];
-    /** Был ли зарегистрирован обработчик для этого вида события. */
+    /** Whether a handler was registered for this event kind. */
     handled: boolean;
 }
 declare function handlePaymentWebhook(args: {
@@ -109,9 +111,9 @@ declare function handlePaymentWebhook(args: {
 }): Promise<PaymentWebhookResult>;
 
 declare function computeLineTotal(unitPrice: Money, quantity: number): Money;
-/** Пустая корзина. */
+/** An empty cart. */
 declare function emptyCart(id: string, currency: CurrencyCode): Cart;
-/** Пересчитывает lineTotal каждой строки и итоги (subtotal/total с учётом скидки). */
+/** Recomputes each line's lineTotal and the totals (subtotal/total incl. discount). */
 declare function recalcCart(cart: Cart): Cart;
 interface NewLineInput {
     id: string;
@@ -122,12 +124,12 @@ interface NewLineInput {
     quantity: number;
     image?: string;
 }
-/** Добавляет строку; если вариант уже в корзине — увеличивает количество. */
+/** Adds a line; if the variant is already in the cart, increases its quantity. */
 declare function addCartLine(cart: Cart, input: NewLineInput): Cart;
-/** Меняет количество строки; quantity ≤ 0 удаляет строку. */
+/** Changes a line's quantity; quantity ≤ 0 removes the line. */
 declare function setCartLineQty(cart: Cart, lineId: string, quantity: number): Cart;
 declare function removeCartLine(cart: Cart, lineId: string): Cart;
-/** Суммарное число единиц в корзине (для индикатора в шапке). */
+/** Total number of units in the cart (for the header indicator). */
 declare function cartItemCount(cart: Cart): number;
 
 interface BuildOrderOptions {
@@ -135,12 +137,10 @@ interface BuildOrderOptions {
     status?: OrderStatus;
     email?: string;
     number?: string;
-    /** ISO-8601; по умолчанию — сейчас. */
+    /** ISO-8601; defaults to now. */
     createdAt?: string;
 }
-/** Снимок корзины в заказ (после оплаты). Итоги берём из корзины — не пересчитываем. */
+/** Snapshots the cart into an order (after payment). Totals come from the cart — not recomputed. */
 declare function buildOrderFromCart(cart: Cart, opts: BuildOrderOptions): Order;
 
-declare const CORE_VERSION: "0.1.0";
-
 export { type AdapterFactory, type AdapterRegistry, type BuildOrderOptions, CORE_VERSION, type CreateCheckoutArgs, type NewLineInput, type NormalizedPaymentEvent, type OrderCreationGuard, type OrderPipelineContext, type OrderStage, type PaymentProvider, type PaymentProviderName, type PaymentRegistry, type PaymentWebhookHandlers, type PaymentWebhookRequest, type PaymentWebhookResult, adapters, addCartLine, buildOrderFromCart, cartItemCount, computeLineTotal, createAdapterRegistry, createPaymentRegistry, emptyCart, handlePaymentWebhook, payments, recalcCart, removeCartLine, runPipeline, setCartLineQty, shouldCreateOrder };

package/dist/index.js

@@ -5,6 +5,9 @@ import {
   slotRegistry
 } from "./chunk-BQVNYHVU.js";
 
+// src/version.generated.ts
+var CORE_VERSION = "0.2.2";
+
 // src/adapter/resolver.ts
 function createAdapterRegistry() {
   const factories = /* @__PURE__ */ new Map();
@@ -14,7 +17,7 @@ function createAdapterRegistry() {
   function factoryFor(config) {
     const f = factories.get(config.backend);
     if (!f) {
-      throw new Error(`[vitrine] \u043D\u0435 \u0437\u0430\u0440\u0435\u0433\u0438\u0441\u0442\u0440\u0438\u0440\u043E\u0432\u0430\u043D \u0430\u0434\u0430\u043F\u0442\u0435\u0440 \u0434\u043B\u044F backend "${config.backend}"`);
+      throw new Error(`[vitrine] no adapter registered for backend "${config.backend}"`);
     }
     return f;
   }
@@ -23,11 +26,11 @@ function createAdapterRegistry() {
   }
   function resolveCommerce(config) {
     if (config.tier === "catalog") {
-      throw new Error('[vitrine] CommerceBackend \u043D\u0435\u0434\u043E\u0441\u0442\u0443\u043F\u0435\u043D \u043D\u0430 \u0443\u0440\u043E\u0432\u043D\u0435 tier "catalog"');
+      throw new Error('[vitrine] CommerceBackend is unavailable at tier "catalog"');
     }
     const f = factoryFor(config);
     if (!f.createCommerce) {
-      throw new Error(`[vitrine] backend "${config.backend}" \u043D\u0435 \u0440\u0435\u0430\u043B\u0438\u0437\u0443\u0435\u0442 CommerceBackend`);
+      throw new Error(`[vitrine] backend "${config.backend}" does not implement CommerceBackend`);
     }
     return f.createCommerce(config);
   }
@@ -66,12 +69,12 @@ function createPaymentRegistry() {
     const name = config.integrations.payments;
     if (!name) {
       throw new Error(
-        "[vitrine] integrations.payments \u043D\u0435 \u0437\u0430\u0434\u0430\u043D \u0432 site.config \u2014 \u0443\u0441\u0442\u0430\u043D\u043E\u0432\u0438\u0442\u0435 \u0444\u0438\u0447\u0443 checkout-<provider>"
+        "[vitrine] integrations.payments is not set in site.config \u2014 install a checkout-<provider> feature"
       );
     }
     const provider = providers.get(name);
     if (!provider) {
-      throw new Error(`[vitrine] \u043F\u043B\u0430\u0442\u0451\u0436\u043D\u044B\u0439 \u043F\u0440\u043E\u0432\u0430\u0439\u0434\u0435\u0440 "${name}" \u043D\u0435 \u0437\u0430\u0440\u0435\u0433\u0438\u0441\u0442\u0440\u0438\u0440\u043E\u0432\u0430\u043D`);
+      throw new Error(`[vitrine] payment provider "${name}" is not registered`);
     }
     return provider;
   }
@@ -123,7 +126,7 @@ function recalcCart(cart) {
 }
 function addCartLine(cart, input) {
   if (!Number.isInteger(input.quantity) || input.quantity <= 0) {
-    throw new Error(`[vitrine] \u043D\u0435\u0434\u043E\u043F\u0443\u0441\u0442\u0438\u043C\u043E\u0435 \u043A\u043E\u043B\u0438\u0447\u0435\u0441\u0442\u0432\u043E \u0441\u0442\u0440\u043E\u043A\u0438: ${input.quantity} (\u043D\u0443\u0436\u043D\u043E \u0446\u0435\u043B\u043E\u0435 > 0)`);
+    throw new Error(`[vitrine] invalid line quantity: ${input.quantity} (must be an integer > 0)`);
   }
   const exists = cart.lines.some((l) => l.variantId === input.variantId);
   const lines = exists ? cart.lines.map(
@@ -145,7 +148,7 @@ function addCartLine(cart, input) {
 }
 function setCartLineQty(cart, lineId, quantity) {
   if (!Number.isInteger(quantity)) {
-    throw new Error(`[vitrine] \u043D\u0435\u0434\u043E\u043F\u0443\u0441\u0442\u0438\u043C\u043E\u0435 \u043A\u043E\u043B\u0438\u0447\u0435\u0441\u0442\u0432\u043E: ${quantity} (\u043D\u0443\u0436\u043D\u043E \u0446\u0435\u043B\u043E\u0435)`);
+    throw new Error(`[vitrine] invalid quantity: ${quantity} (must be an integer)`);
   }
   if (quantity <= 0) return removeCartLine(cart, lineId);
   return recalcCart({
@@ -183,9 +186,6 @@ function buildOrderFromCart(cart, opts) {
     createdAt: opts.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-
-// src/index.ts
-var CORE_VERSION = "0.1.0";
 export {
   CORE_VERSION,
   adapters,

package/dist/react.d.ts

@@ -1,15 +1,15 @@
 import { ComponentType, ReactNode } from 'react';
 import { SlotId } from '@vitrine-kit/contracts';
-import { S as SlotRegistry } from './registry-B4Ak1hIR.js';
+import { S as SlotRegistry } from './registry-CfORxf9H.js';
 
 type SlotComponentRegistry = SlotRegistry<ComponentType<Record<string, unknown>>>;
 interface SlotProps {
     name: SlotId;
-    /** Реестр (по умолчанию — глобальный). Для тестов/изоляции можно передать свой. */
+    /** The registry (global by default). Pass your own for tests/isolation. */
     registry?: SlotComponentRegistry;
-    /** Что рендерить, если слот пуст. */
+    /** What to render if the slot is empty. */
     fallback?: ReactNode;
-    /** Остальные пропсы прокидываются в каждый смонтированный компонент. */
+    /** The remaining props are forwarded to each mounted component. */
     [prop: string]: unknown;
 }
 declare function Slot(props: SlotProps): ReactNode;

package/dist/react.js

@@ -12,10 +12,17 @@ function Slot(props) {
   const reg = registry ?? slotRegistry;
   const mounts = reg.get(name);
   if (mounts.length === 0) return fallback;
+  const seen = /* @__PURE__ */ new Map();
   return createElement(
     Fragment,
     null,
-    ...mounts.map((m, i) => createElement(m.component, { key: i, ...rest }))
+    ...mounts.map((m) => {
+      const c = m.component;
+      const base = c.displayName ?? (c.name || "mount");
+      const n = seen.get(base) ?? 0;
+      seen.set(base, n + 1);
+      return createElement(m.component, { key: n === 0 ? base : `${base}:${n}`, ...rest });
+    })
   );
 }
 export {

package/dist/{registry-B4Ak1hIR.d.ts → registry-CfORxf9H.d.ts}

@@ -3,12 +3,12 @@ import { SlotMount, SlotId } from '@vitrine-kit/contracts';
 interface SlotRegistry<C = unknown> {
     register(mount: SlotMount<C>): void;
     registerMany(mounts: ReadonlyArray<SlotMount<C>>): void;
-    /** Привязки слота, отсортированные по order (стабильно по порядку регистрации). */
+    /** A slot's bindings, sorted by order (stable by registration order). */
     get(slot: SlotId): SlotMount<C>[];
     clear(): void;
 }
 declare function createSlotRegistry<C = unknown>(): SlotRegistry<C>;
-/** Глобальный реестр по умолчанию (клиент регистрирует слоты в lib/slots.ts). */
+/** The default global registry (the client registers slots in lib/slots.ts). */
 declare const slotRegistry: SlotRegistry;
 declare function registerSlot<C = unknown>(mount: SlotMount<C>): void;
 declare function getSlotMounts<C = unknown>(slot: SlotId): SlotMount<C>[];

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@vitrine-kit/core",
-  "version": "0.2.0",
-  "description": "Vitrine core — runtime слотов/адаптера, order pipeline, Stripe webhook. Критическая логика (баг = инцидент у всех).",
+  "version": "0.2.2",
+  "description": "Vitrine core — slot/adapter runtime, order pipeline, provider-neutral payment webhook dispatch. Critical logic (a bug = an incident for everyone).",
   "license": "MIT",
   "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -29,7 +33,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@vitrine-kit/contracts": "1.1.0"
+    "@vitrine-kit/contracts": "1.2.1"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
@@ -44,8 +48,8 @@
     "react": "^18.3.1"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/react.ts --format esm --dts --clean",
-    "typecheck": "tsc --noEmit",
+    "build": "node scripts/generate-version.mjs && tsup src/index.ts src/react.ts --format esm --dts --clean",
+    "typecheck": "node scripts/generate-version.mjs && tsc --noEmit",
     "test": "vitest run --passWithNoTests"
   }
 }