@fayz-ai/storefront 0.9.0 → 0.11.0

package/dist/document/config.d.ts

@@ -0,0 +1,311 @@
+import React, { type ReactNode } from 'react';
+import type { EntityDeclarationInput } from '@fayz-ai/core';
+import type { ShopProvider } from '@fayz-ai/shop/provider';
+import type { MockShopSeed } from '@fayz-ai/shop/mock';
+import type { PaymentMethodKind, Product, StoreSettings } from '@fayz-ai/shop/types';
+import type { Promotion } from '@fayz-ai/shop/rules';
+import type { StorefrontTheme } from '../lib/theme';
+import type { HomeConfig, NavLink, FooterConfig } from '../blocks/sections';
+import type { StorefrontPagesConfig } from '../blocks/page-blocks';
+import type { StorefrontSlots } from '../extend/slots';
+import type { StorefrontAuthConfig } from '../data/auth';
+import type { StorefrontComponents } from '../extend/component-contracts';
+import type { StorefrontReviewsConfig } from '../components/product/ProductReviews';
+import type { CatalogFacetConfig } from '../components/collection/FiltersPanel';
+export type StorefrontRouteKind = 'home' | 'catalog' | 'product' | 'checkout' | 'account' | 'order' | 'custom';
+export type StorefrontRouteParams = Record<string, string>;
+export interface StorefrontRouteComponentProps {
+    path: string;
+    params: StorefrontRouteParams;
+    config: ResolvedStorefrontConfig;
+}
+export type StorefrontRouteChrome = 'default' | 'focused';
+export type StorefrontCommerceMode = 'checkout' | 'catalog' | 'enquiry';
+export type StorefrontImageLoadingMode = 'fade' | 'none';
+export interface StorefrontImageLoadingConfig {
+    mode?: StorefrontImageLoadingMode;
+    durationMs?: number;
+    easing?: string;
+    blur?: boolean;
+}
+export interface StorefrontRouteDefinition {
+    /**
+     * Stable identifier for generated-code diffs, QA reports, and route ownership.
+     */
+    id: string;
+    /**
+     * Hash route pattern. Supports the same params as matchPath, e.g. '/checkout'
+     * or '/collections/:slug'. Custom routes are matched before SDK defaults.
+     */
+    path: string;
+    /**
+     * Intent label for agents and manifests. It does not change matching behavior.
+     */
+    kind?: StorefrontRouteKind;
+    /**
+     * Shell chrome for the route. `focused` hides storefront nav/footer/cart
+     * around high-intent flows such as checkout.
+     */
+    chrome?: StorefrontRouteChrome;
+    /**
+     * App-owned screen/workflow that can still use storefront/shop primitives.
+     */
+    component: React.ComponentType<StorefrontRouteComponentProps>;
+}
+export interface StorefrontDiscountConfig {
+    code: string;
+    percent: number;
+    title?: string;
+}
+export interface StorefrontEnquiryConfig {
+    label?: string;
+    successMessage?: string;
+    subjectPrefix?: string;
+    email?: string;
+    whatsappUrl?: string;
+    requirePhone?: boolean;
+}
+export interface StorefrontConfig {
+    /** Store display name (header, page title) */
+    name: string;
+    /** Optional logo node; defaults to the store name */
+    logo?: React.ReactNode;
+    /** ISO 4217 — default 'BRL' */
+    currency?: string;
+    /** Intl locale for money/date formatting — default 'pt-BR' */
+    locale?: string;
+    /** Visual identity: colors, fonts, radius, header/card personality */
+    theme?: StorefrontTheme;
+    /** Checkout-first default, catalog-only browsing, or product enquiry flow. */
+    commerceMode?: StorefrontCommerceMode;
+    /** Promo message above the header (e.g. 'FRETE GRÁTIS ACIMA DE R$ 300') */
+    announcement?: string;
+    /**
+     * How pages are addressed when this store is served.
+     *
+     * `'hash'` (the default) needs no server configuration and is how every
+     * shipped store works today. `'history'` gives each page a real URL, which is
+     * what makes it indexable, shareable with its own link preview, and
+     * prerenderable — and requires the host to serve the app shell for unknown
+     * paths, or a deep link 404s before the app ever runs.
+     */
+    routing?: 'hash' | 'history';
+    /**
+     * Home page blueprint. When set, `/` renders it and the catalog moves to /catalog.
+     *
+     * Still fully supported — five of seven live stores write it. `pages.home` is
+     * the same thing with room for the other routes; this stays as the short form.
+     */
+    home?: HomeConfig;
+    /**
+     * Pages composed from blocks.
+     *
+     * `catalog` and `product` compose AROUND the native body block rather than
+     * replacing it, so a store adds content to those pages without taking over
+     * their maintenance. Omitting a page renders the SDK default — adopting this
+     * field changes nothing until something is added.
+     */
+    pages?: StorefrontPagesConfig;
+    /**
+     * Blocks grafted into named positions inside SDK pages.
+     *
+     * This is the rung between "configure a section" and "rewrite the page". If
+     * you are about to reimplement an SDK page to add one thing to it, look for
+     * the slot first — and if the position you need is missing, that is a gap in
+     * this list rather than a reason to fork. `listSlots()` enumerates them.
+     */
+    slots?: StorefrontSlots;
+    /** Header nav links — defaults derived from home/catalog routing */
+    nav?: NavLink[];
+    /** Footer content (about text, contact, social) */
+    footer?: FooterConfig;
+    /** Preferred backend descriptor for manifest/scaffold metadata. */
+    backend?: {
+        provider?: 'mock' | 'fayz-api' | 'fayz-shop' | 'custom';
+        url?: string;
+    };
+    /** @deprecated Use backend/provider adapters. Storefront no longer creates Supabase clients. */
+    supabaseUrl?: string;
+    /** @deprecated Use backend/provider adapters. Storefront no longer creates Supabase clients. */
+    supabaseAnonKey?: string;
+    /** Explicit provider override (tests, custom backends) */
+    provider?: ShopProvider;
+    /** Per-store mock catalog (products/categories/discounts) for mock mode */
+    catalog?: MockShopSeed;
+    /**
+     * Custom entity declarations (spine M4), keyed by entity key. Registered
+     * through defineEntity at runtime init, so one config field yields the
+     * record schema, the storage descriptor, the generated RLS, the entity.*
+     * loaders and the admin form.
+     */
+    entities?: Record<string, EntityDeclarationInput>;
+    /** Store-level discount codes available regardless of provider backend. */
+    discounts?: StorefrontDiscountConfig[];
+    /**
+     * Rule-engine promotions (spine M6) — the serializable Promotion shape:
+     * eligibility rules + application method, pure data. Rides in the Store
+     * Document's `promotions` section; the mock provider evaluates them with
+     * the reference evaluator, a live backend re-evaluates server-side. A
+     * `{code, percent}` entry in `discounts` is the same thing in shorthand.
+     */
+    promotions?: Promotion[];
+    /**
+     * Institutional/legal page content (privacy, terms, returns). Plain text —
+     * blank lines separate paragraphs. Unset pages render a placeholder so the
+     * routes (and footer links) exist even before the store writes its policy.
+     */
+    legal?: {
+        privacy?: string;
+        terms?: string;
+        returns?: string;
+    };
+    /** Customer auth — same AuthAdapter contract as createSaasApp. Default: mock. */
+    auth?: StorefrontAuthConfig;
+    /** Shipping pricing — default { flatRate: 0 } */
+    shipping?: {
+        flatRate?: number;
+        freeAbove?: number;
+    };
+    /**
+     * Payment behavior. v1 default 'mock' instantly marks orders paid with NO
+     * real charge (demo). M4 sets 'pix-mercadopago' so orders stay pending until
+     * a real payment webhook confirms settlement.
+     */
+    payments?: {
+        /**
+         * 'gateway' means a real PSP is connected: the checkout opens a charge and
+         * the order waits for it. WHICH provider is deliberately not spelled here —
+         * that lives in the store's connection row, server side. A storefront that
+         * named the acquirer would need a redeploy to change acquirer.
+         */
+        mode?: 'mock' | 'pix-mercadopago' | 'gateway';
+        /**
+         * Which methods the checkout offers. Declaring them is what lets the order
+         * record how the buyer intends to pay instead of assuming 'credit_card',
+         * which is what it did while the card form was a simulation.
+         */
+        methods?: readonly PaymentMethodKind[];
+        /**
+         * Published payment terms, shown on the card and the PDP. These are the two
+         * lines every Brazilian storefront carries and the SDK had no model for:
+         * the Pix discount and the interest-free instalment.
+         *
+         * Display only — they describe what the merchant advertises, not a charge
+         * the checkout computes. A product may override the Pix price per SKU via
+         * `metadata.pixPrice`.
+         */
+        terms?: {
+            /** e.g. 5 → "5% de desconto no Pix". */
+            pixDiscountPercent?: number;
+            /** Longest interest-free plan offered. */
+            maxInstallments?: number;
+            /** Don't split below this per-instalment value. Default 10. */
+            minInstallmentValue?: number;
+        };
+    };
+    /**
+     * The PDP specification table renders scalar `product.metadata` alongside
+     * SKU/category/weight. Stores also keep bookkeeping in metadata; `exclude`
+     * hides those keys and `labels` names the rest, so a store doesn't have to
+     * fork ProductSpecs to stop showing an internal field.
+     */
+    productSpecs?: {
+        exclude?: readonly string[];
+        labels?: Readonly<Record<string, string>>;
+    };
+    /** Product reviews shown on the PDP. See ./components/product/ProductReviews. */
+    reviews?: StorefrontReviewsConfig;
+    /**
+     * Extra catalog refinements over `product.metadata`, rendered in the filters
+     * panel and reflected in `?<key>=<value>`. This is how a store adds its own
+     * discovery axis — colour, purpose, brand — without forking FiltersPanel.
+     */
+    catalogFacets?: readonly CatalogFacetConfig[];
+    /** Product enquiry behavior for catalog/enquiry stores. */
+    enquiry?: StorefrontEnquiryConfig;
+    /** Feature toggles — defaults depend on commerceMode. */
+    features?: {
+        discounts?: boolean;
+        accounts?: boolean;
+        cart?: boolean;
+        checkout?: boolean;
+    };
+    /** Global storefront image reveal behavior. Default is a soft fade. */
+    imageLoading?: StorefrontImageLoadingConfig;
+    /** Header search behaviour. Omit for the inline live-filter. */
+    search?: StorefrontSearchConfig;
+    /**
+     * The merchant's own commercial policy, read from the store's settings row at
+     * boot (see ./store-policy). NOT authored here: an app declares its defaults
+     * through the fields above, and this arrives from the database to override the
+     * ones the merchant actually decided.
+     *
+     * Present so components can read the decisions that have no equivalent
+     * config field — whether an account is required, which optional checkout
+     * fields to show. The ones that DO have a field (currency, payment methods)
+     * are folded into those fields instead, so nothing has to read both.
+     */
+    policy?: StoreSettings;
+    /** Code-level component replacements. Kept out of serialized manifests. */
+    components?: StorefrontComponents;
+    /** Code-level route overrides/custom routes. Kept out of serialized manifests. */
+    routes?: readonly StorefrontRouteDefinition[];
+}
+export interface ResolvedStorefrontConfig extends StorefrontConfig {
+    currency: string;
+    locale: string;
+    shipping: {
+        flatRate: number;
+        freeAbove?: number;
+    };
+    payments: {
+        mode: NonNullable<NonNullable<StorefrontConfig['payments']>['mode']>;
+        methods: readonly PaymentMethodKind[];
+        terms?: NonNullable<StorefrontConfig['payments']>['terms'];
+    };
+    commerceMode: StorefrontCommerceMode;
+    enquiry: Required<Pick<StorefrontEnquiryConfig, 'label' | 'successMessage' | 'subjectPrefix'>> & Omit<StorefrontEnquiryConfig, 'label' | 'successMessage' | 'subjectPrefix'>;
+    features: {
+        discounts: boolean;
+        accounts: boolean;
+        cart: boolean;
+        checkout: boolean;
+    };
+    imageLoading: Required<StorefrontImageLoadingConfig>;
+    /** Where the full product list lives ('/' without a home page, '/catalog' with one) */
+    catalogPath: string;
+    nav: NavLink[];
+    /** `pages` with the legacy `home` short form folded in — always read this one. */
+    pages: StorefrontPagesConfig;
+    search: Required<Omit<StorefrontSearchConfig, 'renderSuggestion'>> & Pick<StorefrontSearchConfig, 'renderSuggestion'>;
+}
+/**
+ * Header search. Defaults reproduce the inline live-filter the storefront has
+ * always had, so turning this on is opt-in; every label and limit is a knob
+ * because "what a search feels like" is a per-store decision, not the SDK's.
+ */
+export interface StorefrontSearchConfig {
+    /**
+     * 'inline' filters the catalogue as you type (the original behaviour).
+     * 'overlay' dims the page and shows suggestions under the field, with a
+     * link through to the full result page.
+     */
+    mode?: 'inline' | 'overlay';
+    placeholder?: string;
+    /** Where "see all results" lands, carrying `?q=`. */
+    resultsPath?: string;
+    /** Suggestions shown under the field before the shopper commits. */
+    suggestionsLimit?: number;
+    /** Characters before anything is queried — 1 matches everything, which is noise. */
+    minChars?: number;
+    ctaLabel?: string;
+    emptyLabel?: string;
+    /** Full control of a suggestion row when the default card is wrong for the store. */
+    renderSuggestion?: (product: Product) => ReactNode;
+}
+export declare function resolveConfig(config: StorefrontConfig): ResolvedStorefrontConfig;
+export declare const StorefrontConfigProvider: React.Provider<ResolvedStorefrontConfig | null>;
+export declare function useStorefrontConfig(): ResolvedStorefrontConfig;
+export declare function useStorefrontConfigOptional(): ResolvedStorefrontConfig | null;
+export declare function getStorefrontComponents(config: ResolvedStorefrontConfig): StorefrontComponents;
+//# sourceMappingURL=config.d.ts.map

package/dist/document/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/document/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AACxE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAGlE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AACzE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AACnF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAA;AAE/E,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,SAAS,GACT,SAAS,GACT,UAAU,GACV,SAAS,GACT,OAAO,GACP,QAAQ,CAAA;AAEZ,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE1D,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,qBAAqB,CAAA;IAC7B,MAAM,EAAE,wBAAwB,CAAA;CACjC;AAED,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,CAAA;AACzD,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAA;AACvE,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,MAAM,CAAA;AAExD,MAAM,WAAW,4BAA4B;IAC3C,IAAI,CAAC,EAAE,0BAA0B,CAAA;IACjC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAA;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAA;IAC9B;;OAEG;IACH,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC,6BAA6B,CAAC,CAAA;CAC9D;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,qDAAqD;IACrD,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,sBAAsB,CAAA;IACrC,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAA;IAC7B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,oEAAoE;IACpE,GAAG,CAAC,EAAE,OAAO,EAAE,CAAA;IACf,mDAAmD;IACnD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,mEAAmE;IACnE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACnF,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gGAAgG;IAChG,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAA;IACjD,2EAA2E;IAC3E,SAAS,CAAC,EAAE,wBAAwB,EAAE,CAAA;IACtC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,EAAE,CAAA;IACxB;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9D,iFAAiF;IACjF,IAAI,CAAC,EAAE,oBAAoB,CAAA;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACpD;;;;OAIG;IACH,QAAQ,CAAC,EAAE;QACT;;;;;WAKG;QACH,IAAI,CAAC,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAA;QAC7C;;;;WAIG;QACH,OAAO,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;QACtC;;;;;;;;WAQG;QACH,KAAK,CAAC,EAAE;YACN,wCAAwC;YACxC,kBAAkB,CAAC,EAAE,MAAM,CAAA;YAC3B,0CAA0C;YAC1C,eAAe,CAAC,EAAE,MAAM,CAAA;YACxB,+DAA+D;YAC/D,mBAAmB,CAAC,EAAE,MAAM,CAAA;SAC7B,CAAA;KACF,CAAA;IACD;;;;;OAKG;IACH,YAAY,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;KAAE,CAAA;IACzF,iFAAiF;IACjF,OAAO,CAAC,EAAE,uBAAuB,CAAA;IACjC;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC7C,2DAA2D;IAC3D,OAAO,CAAC,EAAE,uBAAuB,CAAA;IACjC,yDAAyD;IACzD,QAAQ,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;IAC1F,uEAAuE;IACvE,YAAY,CAAC,EAAE,4BAA4B,CAAA;IAC3C,gEAAgE;IAChE,MAAM,CAAC,EAAE,sBAAsB,CAAA;IAC/B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,oBAAoB,CAAA;IACjC,kFAAkF;IAClF,MAAM,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAA;CAC9C;AAED,MAAM,WAAW,wBAAyB,SAAQ,gBAAgB;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,QAAQ,EAAE;QACR,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;QACpE,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAA;QACrC,KAAK,CAAC,EAAE,WAAW,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;KAC3D,CAAA;IACD,YAAY,EAAE,sBAAsB,CAAA;IACpC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,uBAAuB,EAAE,OAAO,GAAG,gBAAgB,GAAG,eAAe,CAAC,CAAC,GAC5F,IAAI,CAAC,uBAAuB,EAAE,OAAO,GAAG,gBAAgB,GAAG,eAAe,CAAC,CAAA;IAC7E,QAAQ,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAA;IACrF,YAAY,EAAE,QAAQ,CAAC,4BAA4B,CAAC,CAAA;IACpD,uFAAuF;IACvF,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,OAAO,EAAE,CAAA;IACd,kFAAkF;IAClF,KAAK,EAAE,qBAAqB,CAAA;IAC5B,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,sBAAsB,EAAE,kBAAkB,CAAC,CAAC,GAChE,IAAI,CAAC,sBAAsB,EAAE,kBAAkB,CAAC,CAAA;CACnD;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,CAAA;CACnD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,wBAAwB,CA2EhF;AAID,eAAO,MAAM,wBAAwB,iDAAmC,CAAA;AAExE,wBAAgB,mBAAmB,IAAI,wBAAwB,CAI9D;AAED,wBAAgB,2BAA2B,IAAI,wBAAwB,GAAG,IAAI,CAE7E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,wBAAwB,GAAG,oBAAoB,CAE9F"}

package/dist/document/describe.d.ts

@@ -0,0 +1,135 @@
+import type { BlockDescriptor, EntityDescriptor, ExtensionPointDescriptor, JsonSchema, LoaderDescriptor, RegistryEntryDescriptor } from '@fayz-ai/core';
+import type { RuleAttribute } from '@fayz-ai/shop/rules';
+import type { FayzDeprecation, FayzDeprecationPolicy } from '@fayz-ai/sdk/deprecations';
+import type { StoreCodemodDescriptor, StoreDeprecationFinding } from './upgrade';
+import type { SlotDescriptor } from '../extend/slots';
+import type { StoreDocument, StoreSectionName } from './sections';
+import type { StoreValidationReport } from './validate';
+/**
+ * What this store's backend can do.
+ *
+ * Designed to become backend-aware: today every store is Fayz-backed, so the
+ * values are constants. When a second backend lands (spine I11 — e.g. a
+ * Shopify-backed store whose catalog is mirrored into canonical tables), this
+ * shape is derived from the backend provider instead: a Shopify-backed store
+ * keeps `catalogMirror` but cannot run our rule engine, so `ruleEngine`
+ * flips false while the document stays identical. Consumers must branch on
+ * these flags, never on the provider name.
+ */
+export interface StoreCapabilities {
+    /** Backend family serving the store. */
+    backend: string;
+    /** Commerce modes the storefront shell can run. */
+    commerceModes: readonly string[];
+    /** Reads come from the canonical Fayz catalog (mirrored for ERP-backed stores). */
+    catalogMirror: boolean;
+    /** Cart + checkout run against the Fayz order path. */
+    checkout: boolean;
+    /** Declared data loaders resolved once per page (spine M3). */
+    loaders: boolean;
+    /** Rule engine (spine M6): promotions as data, evaluated by the reference
+     *  evaluator (mock) or shop_compute_promotion_actions (Supabase). True for
+     *  Fayz-backed stores; a backend that cannot run our rules (e.g. a
+     *  Shopify-mirrored store) flips this false and consumers must branch on
+     *  the flag, never the provider name. */
+    ruleEngine: boolean;
+    /** Custom entity declarations (spine M4): defineEntity + entity.* loaders +
+     *  generic storage. True for Fayz-backed stores (both providers implement
+     *  the entity surface); a future backend without it flips this false and
+     *  consumers must branch on the flag, never the provider name. */
+    customEntities: boolean;
+    /** Extension point registry (spine M7): declared seams with enforced
+     *  input+output schemas, many dependency-ordered handlers, and exactly one
+     *  nullable beforePlaceOrder escape valve. */
+    extensionPoints: boolean;
+}
+export interface StoreSectionDescription {
+    description: string;
+    /** Section versions this SDK understands, ascending. */
+    versions: readonly number[];
+    /** JSON Schema for the section, compiled from the same spec the validator runs. */
+    schema: JsonSchema;
+}
+/** Summary of one concrete document, when one is passed in. */
+/** The I10 contract, as data the agent reads before authoring (spine M10):
+ *  the policy, every deprecation, and the codemod that answers each one. */
+export interface StoreContractDescription {
+    policy: FayzDeprecationPolicy;
+    deprecations: FayzDeprecation[];
+    codemods: StoreCodemodDescriptor[];
+}
+export interface StoreDocumentSummary {
+    name?: string;
+    /** Sections present in the document. */
+    sections: string[];
+    /** Block types the document places (pages, home, slots), sorted, deduped. */
+    blocksUsed: string[];
+    /** Loader ids the document's data declarations reference, sorted, deduped.
+     *  Meta-level needs of placed blocks are not repeated here — they are the
+     *  block's own contract, readable from the blocks registry. */
+    loadersUsed: string[];
+    /** Handle names the document references, sorted, deduped. */
+    handlesUsed: string[];
+    /** What in THIS store is deprecated, and what replaces it (I10 + I2). */
+    deprecations: StoreDeprecationFinding[];
+    validation: StoreValidationReport;
+}
+/**
+ * One of the author-facing abilities (spine §3 L5).
+ *
+ * Enumerating them is the point. WooCommerce's own conclusion about agent
+ * surfaces — quoted in the spine — is that the surface must be "purpose-built
+ * domain abilities … instead of automatically projecting every REST-shaped
+ * operation", and an ability an agent cannot discover is an ability it will not
+ * use. There are four, they are listed here with their input schemas, and the
+ * list is derived from nothing: if a fifth is added it must be added here.
+ */
+export interface StoreAbilityDescriptor {
+    name: 'describeStore' | 'validateStore' | 'renderStore' | 'applyChange';
+    /** Where it is imported from. */
+    module: string;
+    /** Does it change the document? */
+    writes: boolean;
+    description: string;
+    /** JSON Schema of the options/arguments beyond the document itself. */
+    input: JsonSchema;
+    /** What the caller gets back, in prose — the shapes are exported types. */
+    output: string;
+}
+export interface StoreDescription {
+    version: 1;
+    capabilities: StoreCapabilities;
+    /** The four abilities, with their input schemas (spine L5). */
+    abilities: readonly StoreAbilityDescriptor[];
+    sections: Record<StoreSectionName, StoreSectionDescription>;
+    /** The deprecation contract (spine M10, I10). Enumerable on purpose: an
+     *  agent that cannot read what is going away will keep generating it. */
+    contract: StoreContractDescription;
+    registries: {
+        blocks: BlockDescriptor[];
+        loaders: LoaderDescriptor[];
+        entities: EntityDescriptor[];
+        handles: RegistryEntryDescriptor[];
+        /** The rule attribute vocabulary AS ROWS (I9) — the same rows the admin
+         *  promotion form renders from and validateStore checks against. */
+        ruleAttributes: RuleAttribute[];
+        /** Every extension point with its input/output schemas AND registered
+         *  handlers (spine M7) — the enumerable behaviour surface. */
+        extensionPoints: ExtensionPointDescriptor[];
+    };
+    /** The closed operator set rules may use. */
+    ruleOperators: readonly string[];
+    pageKinds: readonly string[];
+    slots: readonly SlotDescriptor[];
+    componentSlots: readonly string[];
+    settingTypes: readonly string[];
+    /** The field-type vocabulary defineEntity accepts (spine M4). */
+    entityFieldTypes: readonly string[];
+    document?: StoreDocumentSummary;
+}
+/**
+ * The machine-readable description of the storefront authoring surface, plus —
+ * when a document is passed — a summary of that document against it.
+ */
+export declare function describeStore(doc?: StoreDocument | Record<string, unknown>): StoreDescription;
+//# sourceMappingURL=describe.d.ts.map

package/dist/document/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../../src/document/describe.ts"],"names":[],"mappings":"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"}

package/dist/document/overlay.d.ts

@@ -0,0 +1,58 @@
+import type { StoreDocument } from './sections';
+import type { StoreValidationReport } from './validate';
+/** Sparse map of document path -> value. Absent means "use the document's". */
+export type StoreOverlay = Record<string, unknown>;
+export interface OverlayRejection {
+    path: string;
+    code: 'unparseable-path' | 'not-a-setting' | 'section-not-overlayable' | 'no-block-at-path';
+    message: string;
+}
+export interface ApplyOverlayResult {
+    /** The document a shopper is served: base with the accepted settings applied. */
+    document: Record<string, unknown>;
+    /** Paths that were applied, in the order they were. */
+    applied: string[];
+    /** Paths the rule refused, each saying why. */
+    rejected: OverlayRejection[];
+    /** Validation of the MERGED document — the only one that matters. */
+    validation: StoreValidationReport;
+}
+/**
+ * Sections an overlay may reach into at all. Everything else is mirrored from
+ * the backend (catalog), money (commerce), infrastructure (backend, auth) or
+ * code — none of which is a settings-panel change.
+ */
+export declare const OVERLAYABLE_SECTIONS: readonly ["presentation", "theme"];
+/**
+ * Is this path a setting? Needs the document, and cannot work without it —
+ * a path-only rule ("settings live under `props`") failed the fleet twice:
+ *
+ *   - the two block forms MIX inside one array (artorious's home page is 3
+ *     nested and 5 flat), so requiring `props` made the flat ones uneditable;
+ *   - a setting VALUE can look exactly like a block — a form field is
+ *     `{id, label, type, required}` — so keying on `type` would refuse a
+ *     legitimate edit.
+ *
+ * The walk resolves against the real document and asks the renderer's own
+ * `isNestedBlockRef` which form each block took. It stops the moment it enters
+ * a setting, which is what makes the form-field case need no exception.
+ *
+ * `theme` is settings throughout — it is nothing but tokens.
+ */
+export declare function isSettingPath(document: StoreDocument | Record<string, unknown>, path: string): OverlayRejection | null;
+/**
+ * Merge an overlay onto a document. Never mutates the input. Rejections are
+ * reported rather than thrown: an overlay with one bad entry must still deliver
+ * the other forty, or a store stops updating and nobody knows why.
+ */
+export declare function applyOverlay(document: StoreDocument | Record<string, unknown>, overlay: StoreOverlay): ApplyOverlayResult;
+/**
+ * Drop overlay entries the document can no longer accept. Orphans are harmless
+ * on their own — applyOverlay refuses them — but they accumulate, and an
+ * overlay nobody prunes hides a real mistake among a hundred dead ones.
+ */
+export declare function pruneOverlay(document: StoreDocument | Record<string, unknown>, overlay: StoreOverlay): {
+    overlay: StoreOverlay;
+    dropped: string[];
+};
+//# sourceMappingURL=overlay.d.ts.map

package/dist/document/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../src/document/overlay.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG/C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAavD,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAElD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,kBAAkB,GAAG,eAAe,GAAG,yBAAyB,GAAG,kBAAkB,CAAA;IAC3F,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,uDAAuD;IACvD,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B,qEAAqE;IACrE,UAAU,EAAE,qBAAqB,CAAA;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,oCAAqC,CAAA;AAMtE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjD,IAAI,EAAE,MAAM,GACX,gBAAgB,GAAG,IAAI,CAsFzB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjD,OAAO,EAAE,YAAY,GACpB,kBAAkB,CA2DpB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjD,OAAO,EAAE,YAAY,GACpB;IAAE,OAAO,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAQ9C"}

package/dist/{presets.d.ts → document/presets.d.ts}

@@ -1,5 +1,5 @@
-import type { StorefrontTheme } from './theme';
-import type { HomeConfig } from './sections';
+import type { StorefrontTheme } from '../lib/theme';
+import type { HomeConfig } from '../blocks/sections';
 /** Real imagery for a template home — resolved at build time (e.g. via
  *  scripts/fetch-unsplash.mjs); falls back to gradient placeholders when omitted. */
 export interface TemplateImages {

package/dist/document/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../src/document/presets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AASpD;qFACqF;AACrF,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IAChC,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,eAAe,CAAA;IACtB,0EAA0E;IAC1E,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,KAAK,UAAU,CAAA;IAChE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,yFAAyF;AACzF,eAAO,MAAM,YAAY,EAAE,kBA0C1B,CAAA;AAED,gGAAgG;AAChG,eAAO,MAAM,cAAc,EAAE,kBA2D5B,CAAA;AAED,kHAAkH;AAClH,eAAO,MAAM,YAAY,EAAE,kBAkD1B,CAAA;AAED,0GAA0G;AAC1G,eAAO,MAAM,eAAe,EAAE,kBA4D7B,CAAA;AAED;;2FAE2F;AAC3F,eAAO,MAAM,YAAY,EAAE,kBA4D1B,CAAA;AAED,eAAO,MAAM,mBAAmB;;;;;;CAMtB,CAAA;AAEV,MAAM,MAAM,oBAAoB,GAAG,MAAM,OAAO,mBAAmB,CAAA"}