@fayz-ai/storefront 0.9.0 → 0.10.0

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

@@ -1,11 +1,17 @@
-import React from 'react';
+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 } from '@fayz-ai/shop/types';
-import type { StorefrontTheme } from './theme';
-import type { HomeConfig, NavLink, FooterConfig } from './sections';
-import type { StorefrontAuthConfig } from './auth';
-import type { StorefrontComponents } from './component-contracts';
+import type { PaymentMethodKind, Product } 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 {
@@ -74,8 +80,41 @@ export interface StorefrontConfig {
     commerceMode?: StorefrontCommerceMode;
     /** Promo message above the header (e.g. 'FRETE GRÁTIS ACIMA DE R$ 300') */
     announcement?: string;
-    /** Home page blueprint. When set, `/` renders it and the catalog moves to /catalog. */
+    /**
+     * 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) */
@@ -93,8 +132,23 @@ export interface StorefrontConfig {
     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
@@ -125,7 +179,42 @@ export interface StorefrontConfig {
          * 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. */
@@ -137,6 +226,8 @@ export interface StorefrontConfig {
     };
     /** Global storefront image reveal behavior. Default is a soft fade. */
     imageLoading?: StorefrontImageLoadingConfig;
+    /** Header search behaviour. Omit for the inline live-filter. */
+    search?: StorefrontSearchConfig;
     /** Code-level component replacements. Kept out of serialized manifests. */
     components?: StorefrontComponents;
     /** Code-level route overrides/custom routes. Kept out of serialized manifests. */
@@ -152,6 +243,7 @@ export interface ResolvedStorefrontConfig extends StorefrontConfig {
     payments: {
         mode: 'mock' | 'pix-mercadopago';
         methods: readonly PaymentMethodKind[];
+        terms?: NonNullable<StorefrontConfig['payments']>['terms'];
     };
     commerceMode: StorefrontCommerceMode;
     enquiry: Required<Pick<StorefrontEnquiryConfig, 'label' | 'successMessage' | 'subjectPrefix'>> & Omit<StorefrontEnquiryConfig, 'label' | 'successMessage' | 'subjectPrefix'>;
@@ -165,6 +257,33 @@ export interface ResolvedStorefrontConfig extends StorefrontConfig {
     /** 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>;

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,MAAM,qBAAqB,CAAA;AACrE,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,IAAI,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAA;QACjC;;;;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,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,MAAM,GAAG,iBAAiB,CAAA;QAChC,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":"AASA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,UAAU,EACV,gBAAgB,EAChB,uBAAuB,EACxB,MAAM,eAAe,CAAA;AAEtB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AAKhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAGrD,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAUvD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAA;IACf,mDAAmD;IACnD,aAAa,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,mFAAmF;IACnF,aAAa,EAAE,OAAO,CAAA;IACtB,uDAAuD;IACvD,QAAQ,EAAE,OAAO,CAAA;IACjB,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAA;IAChB;;;;6CAIyC;IACzC,UAAU,EAAE,OAAO,CAAA;IACnB;;;sEAGkE;IAClE,cAAc,EAAE,OAAO,CAAA;IACvB;;kDAE8C;IAC9C,eAAe,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,wDAAwD;IACxD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,mFAAmF;IACnF,MAAM,EAAE,UAAU,CAAA;CACnB;AAED,+DAA+D;AAC/D;4EAC4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,qBAAqB,CAAA;IAC7B,YAAY,EAAE,eAAe,EAAE,CAAA;IAC/B,QAAQ,EAAE,sBAAsB,EAAE,CAAA;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wCAAwC;IACxC,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB;;mEAE+D;IAC/D,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,yEAAyE;IACzE,YAAY,EAAE,uBAAuB,EAAE,CAAA;IACvC,UAAU,EAAE,qBAAqB,CAAA;CAClC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,eAAe,GAAG,eAAe,GAAG,aAAa,GAAG,aAAa,CAAA;IACvE,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,mCAAmC;IACnC,MAAM,EAAE,OAAO,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,KAAK,EAAE,UAAU,CAAA;IACjB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,CAAC,CAAA;IACV,YAAY,EAAE,iBAAiB,CAAA;IAC/B,+DAA+D;IAC/D,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC5C,QAAQ,EAAE,MAAM,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,CAAA;IAC3D;6EACyE;IACzE,QAAQ,EAAE,wBAAwB,CAAA;IAClC,UAAU,EAAE;QACV,MAAM,EAAE,eAAe,EAAE,CAAA;QACzB,OAAO,EAAE,gBAAgB,EAAE,CAAA;QAC3B,QAAQ,EAAE,gBAAgB,EAAE,CAAA;QAC5B,OAAO,EAAE,uBAAuB,EAAE,CAAA;QAClC;4EACoE;QACpE,cAAc,EAAE,aAAa,EAAE,CAAA;QAC/B;sEAC8D;QAC9D,eAAe,EAAE,wBAAwB,EAAE,CAAA;KAC5C,CAAA;IACD,6CAA6C;IAC7C,aAAa,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,KAAK,EAAE,SAAS,cAAc,EAAE,CAAA;IAChC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B,iEAAiE;IACjE,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,EAAE,oBAAoB,CAAA;CAChC;AAmKD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,CAkD7F"}

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"}

package/dist/document/render.d.ts

@@ -0,0 +1,171 @@
+import type { RouterAdapter } from '@fayz-ai/core';
+import type { ShopProvider } from '@fayz-ai/shop/provider';
+import type { StaticHeadInput } from '../app/static-render';
+import type { StoreDocument } from './sections';
+import type { StoreValidationReport } from './validate';
+export interface StoreRenderDataEntry {
+    /** Canonical `dataNeedKey` — the same key the browser would dedupe on. */
+    key: string;
+    loader: string;
+    params: Record<string, unknown>;
+    status: 'ready' | 'error' | 'unresolved';
+    /** Item count for an array result, so "the rail is empty" is one field. */
+    count?: number;
+    error?: string;
+}
+export interface StoreRenderDiagnostic {
+    level: 'error' | 'warn';
+    /** Where it came from: 'blocks' (core), 'storefront', or 'render'. */
+    source: string;
+    message: string;
+}
+export interface StoreRenderHeading {
+    level: number;
+    text: string;
+}
+export interface StoreRenderBlock {
+    type: string;
+    id?: string;
+    /** Ancestor block types, outermost first — empty for a top-level block. */
+    within?: string[];
+}
+export interface RenderStoreOptions {
+    /** Route to render, in the storefront's own path space ('/', '/catalog',
+     *  '/product/anel-de-ouro', '/biography'). Default '/'. */
+    path?: string;
+    /**
+     * Where catalog data comes from.
+     *
+     * - `'config'` (default): the provider the config implies — its explicit
+     *   provider, or a mock seeded from its catalog. What the shopper sees.
+     * - `'document'`: a mock seeded from the document's own `catalog` section.
+     *   Deterministic and network-free, which is what you want while iterating
+     *   on a document whose store is backed by a live database.
+     * - a `ShopProvider`: bring your own.
+     */
+    provider?: ShopProvider | 'config' | 'document';
+    /**
+     * 'report' (default) renders an invalid document anyway and returns the
+     * findings — an agent fixing a broken store needs to see the broken store.
+     * 'throw' refuses, for a caller using this as a gate.
+     */
+    onError?: 'throw' | 'report';
+    /** 'document' (default) wraps the markup in a full HTML document with the
+     *  theme CSS and the route's title; 'fragment' returns the shell markup. */
+    html?: 'document' | 'fragment';
+    /**
+     * How many render/resolve rounds to run. One page's data can reveal the
+     * next need (a route param feeding a rail), so the loop repeats until no new
+     * need appears. Reaching the cap is reported as a diagnostic rather than
+     * silently truncating the page. Default 4.
+     */
+    maxPasses?: number;
+    /**
+     * Which frame of an image's reveal animation to render.
+     *
+     * `'settled'` (default) renders images at their loaded state. A store with
+     * `imageLoading.mode: 'fade'` paints every image at `opacity: 0` until its
+     * load event fires — an event a static render never has — so the honest
+     * frame to show is the one every shopper's browser reaches milliseconds
+     * later, not a blank page. `'initial'` renders the pre-load frame verbatim,
+     * for a caller specifically inspecting first paint.
+     */
+    imageReveal?: 'settled' | 'initial';
+    /** Stylesheet URLs to link from the emitted document — how a preview server
+     *  hands in the app's real (Tailwind) CSS. */
+    stylesheets?: readonly string[];
+    /** Extra markup for the emitted `<head>`. */
+    head?: string;
+    /**
+     * How the rendered store is ADDRESSED when served.
+     *
+     * Defaults to hash, matching how storefronts ship today, so a headless render
+     * describes links that actually resolve. Pass `historyRouterAdapter()` (or any
+     * adapter) for a store served at real URLs — that is what makes each page
+     * come out with a crawlable href of its own, which is the difference between
+     * prerendered HTML that can be indexed and prerendered HTML that cannot.
+     */
+    router?: RouterAdapter;
+    /**
+     * Absolute origin, e.g. 'https://loja.example.com'. Required for canonical
+     * and OpenGraph URLs — without it they are omitted rather than emitted
+     * relative, because a relative canonical is ignored.
+     */
+    origin?: string;
+    /** `<html lang>`. Defaults to the document's locale, then 'pt-BR'. */
+    lang?: string;
+    /**
+     * Stamp every block with its document path (`data-fayz-block`).
+     *
+     * Off by default, because a shopper's page must not carry it. On, the emitted
+     * HTML says which document node produced which part of the page — which lets
+     * an editor resolve a click to a path, and lets a test assert the identity
+     * seam without a browser.
+     */
+    editor?: boolean;
+}
+export interface StoreRenderResult {
+    /** True when the document validates, the path resolved, and nothing on the
+     *  page reported an error. The one field a gate should read. */
+    ok: boolean;
+    path: string;
+    /** The title this route declared through `useStorefrontHead`. */
+    title: string;
+    description?: string;
+    /** The path resolved to a real page (false = the 404 page rendered). */
+    found: boolean;
+    html: string;
+    /** Visible text, tags stripped and whitespace collapsed — what a reader sees. */
+    text: string;
+    /** h1–h6 in document order: the page's shape in one glance. */
+    outline: StoreRenderHeading[];
+    /** Every block that rendered, in order, including forced-layout repairs. */
+    blocks: StoreRenderBlock[];
+    /** Outbound hrefs, deduped — how an agent checks its nav actually links. */
+    links: string[];
+    images: number;
+    data: StoreRenderDataEntry[];
+    diagnostics: StoreRenderDiagnostic[];
+    validation: StoreValidationReport;
+    /** Render/resolve rounds actually run. */
+    passes: number;
+    bytes: number;
+}
+/** Visible text of a markup string. Regex rather than a DOM because the
+ *  workspace has no jsdom and the question — "what words are on this page" —
+ *  does not need one. */
+export declare function htmlToText(html: string): string;
+/**
+ * Render a Store Document to HTML, headless, plus everything an agent needs to
+ * understand the result.
+ *
+ *     const result = await renderStore(doc, { path: '/biography' })
+ *     result.ok        // did anything on the page go wrong
+ *     result.outline   // [{ level: 1, text: 'Biography' }, …]
+ *     result.data      // [{ loader: 'products.list', status: 'ready', count: 12 }]
+ *     result.diagnostics
+ */
+export declare function renderStore(input: StoreDocument | Record<string, unknown>, options?: RenderStoreOptions): Promise<StoreRenderResult>;
+interface WrapOptions {
+    title: string;
+    description?: string;
+    lang: string;
+    themeCss: string;
+    stylesheets: readonly string[];
+    head: string;
+    /** Canonical / OpenGraph / JSON-LD declared by the route being rendered. */
+    seo?: Pick<StaticHeadInput, 'canonical' | 'image' | 'type' | 'jsonLd'>;
+    siteName?: string;
+}
+/**
+ * The HTML document around the shell markup.
+ *
+ * Deliberately minimal and self-contained: the theme's CSS variables ride
+ * inline (they are already data — M2's brand tokens), and any real stylesheet
+ * is LINKED rather than inlined, because the only thing that can produce the
+ * app's utility CSS is the app's own build. A caller with no stylesheet gets
+ * honest unstyled markup instead of a page that pretends to be styled.
+ */
+export declare function wrapDocument(markup: string, options: WrapOptions): string;
+export {};
+//# sourceMappingURL=render.d.ts.map

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

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

package/dist/document/round-trip.d.ts

@@ -0,0 +1,46 @@
+import type { StorefrontConfig } from './config';
+import { STORE_DOCUMENT_KIND } from './sections';
+import type { StoreDocument } from './sections';
+export declare function slugifyStoreName(name: string): string;
+export interface ExportStoreOptions {
+    /** Namespace for auto-registered handles. Default: slug of the store name. */
+    appId?: string;
+    /**
+     * Register a deterministic handle (`<appId>.<config-path>`) for any code
+     * value that has none, instead of failing. `defineStorefront` turns this on
+     * so a store written today keeps working; a store that names its own handles
+     * (registerHandle) keeps its names — explicit registration always wins the
+     * reverse lookup.
+     */
+    registerMissingHandles?: boolean;
+}
+/**
+ * Serialize a defined/live store to Store Document v1.
+ *
+ * Data fields map to sections verbatim (the authored block form is preserved,
+ * flat or nested — both are data). Code fields become handle names in the
+ * `code` section. A data field smuggling code (JSX inside a page tree) is a
+ * hard error naming the offending path rather than a document that lies.
+ */
+export declare function exportStore(config: StorefrontConfig, options?: ExportStoreOptions): StoreDocument;
+export interface HydrateStoreOptions {
+    /**
+     * 'throw' (default): a document that fails validation aborts hydration with
+     * an error listing every finding — the authoring-loop contract (I2).
+     * 'report': log the findings and hydrate best-effort, dropping unresolvable
+     * code refs — the shopper-facing contract (I7: a broken document degrades
+     * instead of white-screening the store). The scaffold uses 'report'.
+     */
+    onError?: 'throw' | 'report';
+}
+/**
+ * Reconstitute a StorefrontConfig from a Store Document.
+ *
+ * Every code reference resolves through the handle registry by NAME — the
+ * document alone plus the app's registered handles is the whole story; there
+ * is no in-memory side channel keyed by app id anymore.
+ */
+export declare function hydrateStoreDocument(input: StoreDocument | Record<string, unknown>, options?: HydrateStoreOptions): StorefrontConfig;
+/** Re-export so document consumers need one import. */
+export { STORE_DOCUMENT_KIND };
+//# sourceMappingURL=round-trip.d.ts.map

package/dist/document/round-trip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-trip.d.ts","sourceRoot":"","sources":["../../src/document/round-trip.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,gBAAgB,EAIjB,MAAM,UAAU,CAAA;AAKjB,OAAO,EAAE,mBAAmB,EAAwB,MAAM,YAAY,CAAA;AACtE,OAAO,KAAK,EAAuC,aAAa,EAAE,MAAM,YAAY,CAAA;AAoBpF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACjC;AA4DD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,GAAE,kBAAuB,GAAG,aAAa,CAgKrG;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAA;CAC7B;AAQD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,OAAO,GAAE,mBAAwB,GAChC,gBAAgB,CAuIlB;AAED,uDAAuD;AACvD,OAAO,EAAE,mBAAmB,EAAE,CAAA"}