@fayz-ai/storefront 0.9.0 → 0.10.0

package/dist/document/sections.d.ts

@@ -0,0 +1,194 @@
+import type { EntityDeclarationInput, JsonSchema } from '@fayz-ai/core';
+import type { MockShopSeed } from '@fayz-ai/shop/mock';
+import type { Promotion } from '@fayz-ai/shop/rules';
+import type { StorefrontCommerceMode, StorefrontConfig, StorefrontDiscountConfig, StorefrontEnquiryConfig, StorefrontImageLoadingConfig, StorefrontRouteChrome, StorefrontRouteKind, StorefrontSearchConfig } from './config';
+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';
+export declare const STORE_DOCUMENT_KIND = "fayz.store";
+export declare const STORE_COMMERCE_MODES: readonly ["checkout", "catalog", "enquiry"];
+export declare const STORE_PAYMENT_MODES: readonly ["mock", "pix-mercadopago"];
+export declare const STORE_PAYMENT_METHOD_KINDS: readonly ["pix", "credit_card", "debit_card", "boleto", "cash", "other"];
+type ConfiguredBackendProvider = NonNullable<NonNullable<StorefrontConfig['backend']>['provider']>;
+export declare const STORE_BACKEND_PROVIDERS: readonly ["mock", "fayz-api", "fayz-shop", "custom"];
+export declare const STORE_ROUTE_KINDS: readonly ["home", "catalog", "product", "checkout", "account", "order", "custom"];
+export declare const STORE_ROUTE_CHROMES: readonly ["default", "focused"];
+export declare const STORE_THEME_RADII: readonly ["none", "soft", "round", "pill"];
+interface StoreSectionBase {
+    /** This section's own schema version — sections evolve independently. */
+    version: number;
+}
+/** Identity: who the store is. The only mandatory section. */
+export interface StoreIdentitySection extends StoreSectionBase {
+    name: string;
+    /** ISO 4217 — default 'BRL'. */
+    currency?: string;
+    /** Intl locale — default 'pt-BR'. */
+    locale?: string;
+}
+/** Visual identity — StorefrontTheme, spread into the section. */
+export interface StoreThemeSection extends StoreSectionBase, StorefrontTheme {
+}
+/** Commercial behavior: mode, money, offers. */
+export interface StoreCommerceSection extends StoreSectionBase {
+    commerceMode?: StorefrontCommerceMode;
+    shipping?: StorefrontConfig['shipping'];
+    payments?: StorefrontConfig['payments'];
+    discounts?: StorefrontDiscountConfig[];
+    enquiry?: StorefrontEnquiryConfig;
+    features?: StorefrontConfig['features'];
+}
+/** What the shopper sees: composed pages, slots, chrome. `footer` here holds
+ *  only the serializable part — a non-string `credit` node moves to
+ *  `code.footerCredit`. */
+export interface StorePresentationSection extends StoreSectionBase {
+    announcement?: string;
+    /** Text logo. A JSX logo is code — it lives at `code.logo`. */
+    logo?: string;
+    home?: HomeConfig;
+    pages?: StorefrontPagesConfig;
+    slots?: StorefrontSlots;
+    nav?: NavLink[];
+    footer?: FooterConfig;
+    imageLoading?: StorefrontImageLoadingConfig;
+    catalogFacets?: StorefrontConfig['catalogFacets'];
+    productSpecs?: StorefrontConfig['productSpecs'];
+    /** Header search knobs. `renderSuggestion` is code — it lives at
+     *  `code.searchRenderSuggestion`. */
+    search?: Omit<StorefrontSearchConfig, 'renderSuggestion'>;
+}
+/** Long-form content: legal/institutional pages and store-supplied reviews. */
+export interface StoreContentSection extends StoreSectionBase {
+    legal?: StorefrontConfig['legal'];
+    reviews?: StorefrontConfig['reviews'];
+}
+/** The mock catalog seed (products/categories/discounts). */
+export interface StoreCatalogSection extends StoreSectionBase, MockShopSeed {
+}
+/** Rule-engine promotions (spine M6): serializable Promotion values —
+ *  eligibility rules + application method, attributes drawn from the
+ *  rule_attribute vocabulary. "Buy 3 pay 2" and "REVENDA10 = 10% off" are
+ *  both entries here, as pure data. */
+export interface StorePromotionsSection extends StoreSectionBase {
+    promotions?: Promotion[];
+}
+/** Custom entity declarations (spine M4): the defineEntity inputs, keyed by
+ *  entity key. Pure data — hydration re-declares them through defineEntity,
+ *  which re-derives the schema, storage, RLS and loaders from the same input. */
+export interface StoreEntitiesSection extends StoreSectionBase {
+    definitions?: Record<string, EntityDeclarationInput>;
+}
+/** Backend descriptor. The deprecated supabase fields ride along so a legacy
+ *  config still round-trips losslessly; new stores use `auth.supabase`. */
+export interface StoreBackendSection extends StoreSectionBase {
+    provider?: ConfiguredBackendProvider;
+    url?: string;
+    /** @deprecated legacy StorefrontConfig field, kept for lossless round-trip. */
+    supabaseUrl?: string;
+    /** @deprecated legacy StorefrontConfig field, kept for lossless round-trip. */
+    supabaseAnonKey?: string;
+}
+/** Customer auth, when it is expressible as data ('mock' / 'supabase' + urls).
+ *  An auth config carrying code (an AuthAdapter object, a supabase client)
+ *  moves whole to `code.auth`. */
+export interface StoreAuthSection extends StoreSectionBase, StorefrontAuthConfig {
+}
+/** A custom route whose component is referenced by handle name. */
+export interface StoreCodeRouteRef {
+    id: string;
+    path: string;
+    kind?: StorefrontRouteKind;
+    chrome?: StorefrontRouteChrome;
+    /** Handle name of the route component. */
+    component: string;
+}
+/**
+ * The code sidecar: every config field that holds code, referenced by the
+ * handle NAME it was registered under. Hydration resolves these through the
+ * handle registry — an unknown name is a hard error naming the valid set (I2),
+ * never a silent drop.
+ */
+export interface StoreCodeSection extends StoreSectionBase {
+    /** Handle → React.ReactNode (JSX logo). */
+    logo?: string;
+    /** Handle → ShopProvider. */
+    provider?: string;
+    /** Handle → StorefrontAuthConfig carrying code. */
+    auth?: string;
+    /** Handle → React.ReactNode rendered as the footer credit line. */
+    footerCredit?: string;
+    /** Handle → the `(product) => ReactNode` renderer for a search suggestion. */
+    searchRenderSuggestion?: string;
+    /** Component-slot name → handle of its ComponentOverride. */
+    components?: Record<string, string>;
+    routes?: StoreCodeRouteRef[];
+}
+/** Store Document v1 — the serializable form of a whole storefront. */
+export interface StoreDocument {
+    $kind: typeof STORE_DOCUMENT_KIND;
+    store: StoreIdentitySection;
+    theme?: StoreThemeSection;
+    commerce?: StoreCommerceSection;
+    presentation?: StorePresentationSection;
+    content?: StoreContentSection;
+    catalog?: StoreCatalogSection;
+    entities?: StoreEntitiesSection;
+    promotions?: StorePromotionsSection;
+    backend?: StoreBackendSection;
+    auth?: StoreAuthSection;
+    code?: StoreCodeSection;
+}
+export type StoreSectionName = Exclude<keyof StoreDocument, '$kind'>;
+/**
+ * A field that is on its way out (spine I10).
+ *
+ * The section VERSION is what makes this mechanical rather than advisory:
+ * while the section is at a version below `removedAtVersion` the field is
+ * accepted and the store keeps working; a document that has been through the
+ * codemod carries the higher version, and at that version the field is a hard
+ * validation error naming `replacement` (I2). That is what lets one SDK serve
+ * both a migrated and an unmigrated fleet without a flag.
+ */
+export interface StoreFieldDeprecation {
+    /** Row id in @fayz-ai/sdk's deprecation registry — the single source of the
+     *  version window, the shim prose and the codemod id. */
+    id: string;
+    /** Section version at which this field stops being accepted. */
+    removedAtVersion: number;
+    /** Document path to write instead. */
+    replacement: string;
+}
+export interface StoreFieldSpec {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    description: string;
+    required?: boolean;
+    enum?: readonly string[];
+    /** Present when the field is deprecated. See {@link StoreFieldDeprecation}. */
+    deprecated?: StoreFieldDeprecation;
+}
+export interface StoreSectionSpec {
+    description: string;
+    /** Versions of this section this SDK understands, ascending. */
+    versions: readonly number[];
+    fields: Record<string, StoreFieldSpec>;
+}
+export declare const STORE_SECTIONS: Record<StoreSectionName, StoreSectionSpec>;
+export declare const STORE_SECTION_NAMES: StoreSectionName[];
+/** Compile a section's field spec to JSON Schema — the same one-declaration
+ *  principle as `settingsToJsonSchema` (I1). */
+export declare function sectionToJsonSchema(name: StoreSectionName): JsonSchema;
+/**
+ * True when a value survives JSON serialization unchanged: the test that
+ * routes a config field into a data section versus the code sidecar. React
+ * elements (`$$typeof`), functions, class instances (providers, adapters,
+ * supabase clients) all fail it.
+ */
+export declare function isJsonValue(value: unknown): boolean;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Copy of `obj` without `undefined`-valued keys, so a document holds exactly
+ *  what JSON can carry and object equality means what it looks like. */
+export declare function compact<T extends Record<string, unknown>>(obj: T): T;
+export {};
+//# sourceMappingURL=sections.d.ts.map

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

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

package/dist/document/upgrade.d.ts

@@ -0,0 +1,112 @@
+import type { StoreDocument, StoreSectionName } from './sections';
+import type { StoreValidationReport } from './validate';
+/** One deprecated thing found in one store. */
+export interface StoreDeprecationFinding {
+    /** Registry row id. */
+    id: string;
+    /** Dotted document path, when the deprecation is on the document surface. */
+    path?: string;
+    /** What exactly was found, in the author's words. */
+    detail: string;
+    deprecatedIn: string;
+    removeIn: string;
+    /** I2 — always present, always the thing to write instead. */
+    replacement: string;
+    /** The codemod that answers it. */
+    codemod: string;
+    /** False when only a human can retire it (pool state, code outside the document). */
+    automatable: boolean;
+}
+/** Why a codemod would not run, and what a human has to decide instead. */
+export interface StoreCodemodRefusal {
+    reason: string;
+    /** The decisions, one per line. Never a suggestion the codemod could have
+     *  taken itself — if it could, it would have. */
+    decide: string[];
+}
+export type StoreCodemodStatus = 
+/** The document changed (possibly only its section version). */
+'applied'
+/** Nothing here to migrate: the section is absent, or already past this version. */
+ | 'not-applicable'
+/** Something is here, and moving it safely needs a human. */
+ | 'refused';
+/** A section version move — the key the codemod is filed under. */
+export interface StoreCodemodVersionKey {
+    section: StoreSectionName;
+    from: number;
+    to: number;
+}
+export interface StoreCodemodResult {
+    codemod: string;
+    status: StoreCodemodStatus;
+    /** Registry ids this codemod retires. */
+    deprecations: string[];
+    /** The version move, or null for a deprecation that is not on the document
+     *  surface at all — which is itself why such a codemod always refuses. */
+    version: StoreCodemodVersionKey | null;
+    /** One line per document change, in the applyChange path vocabulary. */
+    changes: string[];
+    note: string;
+    refusal?: StoreCodemodRefusal;
+}
+export interface StoreUpgradeOptions {
+    /** Restrict the run to these codemod ids. Unknown ids are a hard error
+     *  naming the valid set (I2). */
+    only?: readonly string[];
+}
+export interface StoreUpgradeResult {
+    /** False when a codemod refused or the result would not validate. */
+    ok: boolean;
+    /** The upgraded document. Deep-equal to the input when `changed` is false. */
+    doc: StoreDocument;
+    changed: boolean;
+    deprecations: StoreDeprecationFinding[];
+    codemods: StoreCodemodResult[];
+    /** The result validated. A codemod that would break the document is a bug
+     *  in the codemod, and this is where it surfaces. */
+    validation: StoreValidationReport;
+}
+/**
+ * What in THIS document is deprecated — the machine-readable answer to the
+ * question I10 exists to make askable.
+ *
+ * Only the document surface is visible from here. A deprecation living in the
+ * store's own code (the productMetadata overlay) or in a pool (the two SQL
+ * ones) is reported by its row as un-automatable rather than omitted: an
+ * enumerable deprecation that quietly drops the ones you cannot see from a
+ * JSON file would be the silent-failure mode the whole spine is against.
+ */
+export declare function scanStoreDeprecations(input: StoreDocument | Record<string, unknown>): StoreDeprecationFinding[];
+/**
+ * The deprecations no document can answer for, with the reason.
+ *
+ * The CLI merges these into its report so `fayz upgrade` never implies a store
+ * is clean when the only reason it looks clean is that the evidence is not in
+ * the repo.
+ */
+export declare function unobservableDeprecations(): StoreDeprecationFinding[];
+/** Every codemod id, in run order. */
+export declare const STORE_CODEMOD_IDS: readonly string[];
+/** What each codemod is, as data — describeStore publishes this. */
+export interface StoreCodemodDescriptor {
+    id: string;
+    title: string;
+    /** Registry ids it retires. */
+    deprecations: string[];
+    /** The section version it is keyed to, or null when the deprecation is not
+     *  on the document surface (such a codemod always refuses). */
+    version: StoreCodemodVersionKey | null;
+    /** Can it ever apply without a human? */
+    automatable: boolean;
+}
+export declare function describeCodemods(): StoreCodemodDescriptor[];
+/**
+ * Run the codemods against a document and report exactly what would change.
+ *
+ * PURE: the input document is never mutated, and a refused codemod contributes
+ * nothing to the output — a refusal must leave the document byte-identical or
+ * the refusal was not a refusal.
+ */
+export declare function upgradeStore(input: StoreDocument | Record<string, unknown>, options?: StoreUpgradeOptions): StoreUpgradeResult;
+//# sourceMappingURL=upgrade.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/document/upgrade.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAyBvD,+CAA+C;AAC/C,MAAM,WAAW,uBAAuB;IACtC,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAA;IACnB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,WAAW,EAAE,OAAO,CAAA;CACrB;AAED,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd;qDACiD;IACjD,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,MAAM,MAAM,kBAAkB;AAC5B,gEAAgE;AAC9D,SAAS;AACX,oFAAoF;GAClF,gBAAgB;AAClB,6DAA6D;GAC3D,SAAS,CAAA;AAEb,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,gBAAgB,CAAA;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,kBAAkB,CAAA;IAC1B,yCAAyC;IACzC,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB;8EAC0E;IAC1E,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAA;IACtC,wEAAwE;IACxE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC;qCACiC;IACjC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,EAAE,EAAE,OAAO,CAAA;IACX,8EAA8E;IAC9E,GAAG,EAAE,aAAa,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;IAChB,YAAY,EAAE,uBAAuB,EAAE,CAAA;IACvC,QAAQ,EAAE,kBAAkB,EAAE,CAAA;IAC9B;yDACqD;IACrD,UAAU,EAAE,qBAAqB,CAAA;CAClC;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,uBAAuB,EAAE,CAgC/G;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,IAAI,uBAAuB,EAAE,CAIpE;AAsUD,sCAAsC;AACtC,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAAkC,CAAA;AAEjF,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,+BAA+B;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB;mEAC+D;IAC/D,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAA;IACtC,yCAAyC;IACzC,WAAW,EAAE,OAAO,CAAA;CACrB;AAED,wBAAgB,gBAAgB,IAAI,sBAAsB,EAAE,CAQ3D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAqCpB"}

package/dist/document/validate.d.ts

@@ -0,0 +1,24 @@
+export interface StoreValidationError {
+    /** Dotted path into the document ('presentation.pages.home.blocks[2].type'). */
+    path: string;
+    /** Stable machine-readable code ('unknown-block', 'unsupported-section-version', …). */
+    code: string;
+    message: string;
+    /** The valid set, present on every unknown-id error — what the AI corrects on. */
+    valid?: string[];
+}
+export interface StoreValidationReport {
+    ok: boolean;
+    errors: StoreValidationError[];
+}
+export declare const STOREFRONT_PAGE_KINDS: readonly ["home", "catalog", "product", "collection", "content"];
+/**
+ * Validate a Store Document against the registries and section schemas.
+ *
+ * Self-sufficient: registers the SDK blocks before checking, so "unknown
+ * block" always names the true valid set. App-local blocks and handles must be
+ * registered by the app's own modules before this runs — which is the same
+ * precondition rendering has.
+ */
+export declare function validateStore(doc: unknown): StoreValidationReport;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/document/validate.ts"],"names":[],"mappings":"AA6DA,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,oBAAoB,EAAE,CAAA;CAC/B;AAED,eAAO,MAAM,qBAAqB,kEAAmE,CAAA;AAq4BrG;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,CA4DjE"}

package/dist/{component-contracts.d.ts → extend/component-contracts.d.ts}

@@ -1,9 +1,10 @@
 import type React from 'react';
 import type { Category, CreateProductEnquiryInput, Product, ProductEnquiry, ProductImage } from '@fayz-ai/shop/types';
-import type { ProductOptionGroup, ProductOptionSelection } from './product-options';
-import type { ResolvedStorefrontConfig, StorefrontCommerceMode } from './config';
-import type { MediaCarouselItem } from './sections';
-import type { CartState } from './stores/cart.store';
+import type { ProductOptionGroup, ProductOptionSelection } from '../data/product-options';
+import type { ResolvedStorefrontConfig, StorefrontCommerceMode } from '../document/config';
+import type { MediaCarouselItem } from '../blocks/sections';
+import type { CartState } from '../stores/cart.store';
+import type { ComponentOverride } from './component-override';
 export interface StorefrontComponentBaseProps {
     config: ResolvedStorefrontConfig;
     commerceMode: StorefrontCommerceMode;
@@ -17,9 +18,26 @@ export interface StorefrontActions {
     closeCart: () => void;
     createProductEnquiry: (input: CreateProductEnquiryInput) => Promise<ProductEnquiry>;
 }
+/**
+ * Which photo the CARD shows — the grid-side counterpart of
+ * {@link ProductGalleryOrder}.
+ *
+ *   primary   the first `is_primary` row, else the first row (the default;
+ *             byte-identical to what the card has always done)
+ *   position  the lowest `sortOrder`, ties broken by image id
+ *
+ * `position` exists because `is_primary` is not a unique constraint: artorious
+ * carries products with TWO primary rows, which made the card's pick depend on
+ * PostgREST's tie order — the same card could show a different photo between
+ * two loads. The gallery got `order` in M2; the card had no equivalent and a
+ * store fork was the only way to sort by position.
+ */
+export type ProductCardImageOrder = 'primary' | 'position';
 export interface ProductCardProps extends StorefrontComponentBaseProps {
     product: Product;
     actions: Pick<StorefrontActions, 'navigateTo' | 'addToCart' | 'openCart'>;
+    /** Defaults to 'primary' — see {@link ProductCardImageOrder}. */
+    imageOrder?: ProductCardImageOrder;
 }
 export interface ProductDetailProps extends StorefrontComponentBaseProps {
     product: Product;
@@ -35,10 +53,24 @@ export interface ProductDetailProps extends StorefrontComponentBaseProps {
     addToCart: () => void;
     openEnquiry: () => void;
 }
+/**
+ * Which photo leads the gallery.
+ *
+ *   primary   the merchant's pick: isPrimary first, then sortOrder ascending (default)
+ *   position  sortOrder ascending, ignoring the primary flag
+ *   newest    sortOrder descending — the most recently added photo leads
+ *
+ * `newest` exists because of a real fork: artorious reimplemented the entire
+ * 158-line gallery to change ONLY this rule (its Supabase rows carried two
+ * conflicting is_primary flags, so sort_order was the only trustworthy signal).
+ * A props-only override (`components.ProductGallery.props.order`) now does it.
+ */
+export type ProductGalleryOrder = 'primary' | 'position' | 'newest';
 export interface ProductGalleryProps extends StorefrontComponentBaseProps {
     product: Product;
     images: ProductImage[];
     primaryImage?: ProductImage;
+    order?: ProductGalleryOrder;
 }
 export interface ProductPriceProps extends StorefrontComponentBaseProps {
     product: Product;
@@ -115,24 +147,44 @@ export interface StorefrontStateProps extends StorefrontComponentBaseProps {
 export interface CartDrawerFooterExtraProps extends StorefrontComponentBaseProps {
     cart: CartState;
 }
+/**
+ * Code-level component replacements.
+ *
+ * Each entry accepts either the component (what stores write today) or
+ * `{ component?, props? }`. Passing only `props` keeps the SDK component and
+ * forces some of its props — which is what four of five customizing stores
+ * actually wanted when they replaced a whole card instead.
+ *
+ * Every field takes the union rather than only the two surfaces stores have
+ * overridden so far: "why can I pass props to ProductCard but not CategoryCard"
+ * is a worse surface than one extra type.
+ */
 export interface StorefrontComponents {
-    ProductCard?: React.ComponentType<ProductCardProps>;
-    ProductDetail?: React.ComponentType<ProductDetailProps>;
-    ProductGallery?: React.ComponentType<ProductGalleryProps>;
-    ProductPrice?: React.ComponentType<ProductPriceProps>;
-    ProductActions?: React.ComponentType<ProductActionsProps>;
-    ProductEnquiryForm?: React.ComponentType<ProductEnquiryFormContractProps>;
-    CategoryCard?: React.ComponentType<CategoryCardProps>;
-    CollectionSection?: React.ComponentType<CollectionSectionProps>;
-    HeroSection?: React.ComponentType<HeroSectionContractProps>;
-    MediaCarousel?: React.ComponentType<MediaCarouselProps>;
-    ProductSlider?: React.ComponentType<ProductSliderProps>;
-    Header?: React.ComponentType<StorefrontChromeProps>;
-    Footer?: React.ComponentType<StorefrontChromeProps>;
-    Shell?: React.ComponentType<StorefrontChromeProps>;
-    EmptyState?: React.ComponentType<StorefrontStateProps>;
-    LoadingState?: React.ComponentType<StorefrontStateProps>;
-    ErrorState?: React.ComponentType<StorefrontStateProps>;
-    CartDrawerFooterExtra?: React.ComponentType<CartDrawerFooterExtraProps>;
+    ProductCard?: ComponentOverride<ProductCardProps>;
+    ProductDetail?: ComponentOverride<ProductDetailProps>;
+    ProductGallery?: ComponentOverride<ProductGalleryProps>;
+    ProductPrice?: ComponentOverride<ProductPriceProps>;
+    ProductActions?: ComponentOverride<ProductActionsProps>;
+    ProductEnquiryForm?: ComponentOverride<ProductEnquiryFormContractProps>;
+    CategoryCard?: ComponentOverride<CategoryCardProps>;
+    CollectionSection?: ComponentOverride<CollectionSectionProps>;
+    HeroSection?: ComponentOverride<HeroSectionContractProps>;
+    MediaCarousel?: ComponentOverride<MediaCarouselProps>;
+    ProductSlider?: ComponentOverride<ProductSliderProps>;
+    Header?: ComponentOverride<StorefrontChromeProps>;
+    Footer?: ComponentOverride<StorefrontChromeProps>;
+    Shell?: ComponentOverride<StorefrontChromeProps>;
+    EmptyState?: ComponentOverride<StorefrontStateProps>;
+    LoadingState?: ComponentOverride<StorefrontStateProps>;
+    ErrorState?: ComponentOverride<StorefrontStateProps>;
+    CartDrawerFooterExtra?: ComponentOverride<CartDrawerFooterExtraProps>;
 }
+/**
+ * The override surface as a runtime value, for validators and catalogs: a
+ * store document referencing an unknown component slot must be told the valid
+ * set (I2), and a type alone cannot say it at runtime. The `satisfies` +
+ * exhaustiveness pair keeps this list impossible to leave stale when a key is
+ * added to {@link StorefrontComponents}.
+ */
+export declare const STOREFRONT_COMPONENT_KEYS: readonly ["ProductCard", "ProductDetail", "ProductGallery", "ProductPrice", "ProductActions", "ProductEnquiryForm", "CategoryCard", "CollectionSection", "HeroSection", "MediaCarousel", "ProductSlider", "Header", "Footer", "Shell", "EmptyState", "LoadingState", "ErrorState", "CartDrawerFooterExtra"];
 //# sourceMappingURL=component-contracts.d.ts.map

package/dist/extend/component-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-contracts.d.ts","sourceRoot":"","sources":["../../src/extend/component-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,EAAE,QAAQ,EAAE,yBAAyB,EAAE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACrH,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAA;AACzF,OAAO,KAAK,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAC1F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAE7D,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,wBAAwB,CAAA;IAChC,YAAY,EAAE,sBAAsB,CAAA;IACpC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,KAAK,IAAI,CAAA;IAC1F,QAAQ,EAAE,MAAM,IAAI,CAAA;IACpB,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB,oBAAoB,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;CACpF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,UAAU,CAAA;AAE1D,MAAM,WAAW,gBAAiB,SAAQ,4BAA4B;IACpE,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,YAAY,GAAG,WAAW,GAAG,UAAU,CAAC,CAAA;IACzE,iEAAiE;IACjE,UAAU,CAAC,EAAE,qBAAqB,CAAA;CACnC;AAED,MAAM,WAAW,kBAAmB,SAAQ,4BAA4B;IACtE,OAAO,EAAE,OAAO,CAAA;IAChB,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,YAAY,EAAE,kBAAkB,EAAE,CAAA;IAClC,eAAe,EAAE,sBAAsB,CAAA;IACvC,kBAAkB,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,sBAAsB,CAAC,CAAC,CAAA;IAChF,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAA;IACzD,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,WAAW,GAAG,sBAAsB,GAAG,YAAY,CAAC,CAAA;IACrF,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB,WAAW,EAAE,MAAM,IAAI,CAAA;CACxB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAA;AAEnE,MAAM,WAAW,mBAAoB,SAAQ,4BAA4B;IACvE,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,YAAY,EAAE,CAAA;IACtB,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAC5B;AAED,MAAM,WAAW,iBAAkB,SAAQ,4BAA4B;IACrE,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,MAAM,WAAW,mBAAoB,SAAQ,4BAA4B;IACvE,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAA;IACzD,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,WAAW,GAAG,sBAAsB,GAAG,YAAY,CAAC,CAAA;IACrF,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB,WAAW,EAAE,MAAM,IAAI,CAAA;CACxB;AAED,MAAM,WAAW,+BAAgC,SAAQ,4BAA4B;IACnF,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;CACvB;AAED,MAAM,WAAW,iBAAkB,SAAQ,4BAA4B;IACrE,QAAQ,EAAE,QAAQ,CAAA;IAClB,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAA;CAC/C;AAED,MAAM,WAAW,sBAAuB,SAAQ,4BAA4B;IAC1E,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED,MAAM,WAAW,wBAAyB,SAAQ,4BAA4B;IAC5E,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED,MAAM,WAAW,kBAAmB,SAAQ,4BAA4B;IACtE,KAAK,EAAE,iBAAiB,EAAE,CAAA;IAC1B,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAA;IACrC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;CACnC;AAED,MAAM,WAAW,kBAAmB,SAAQ,4BAA4B;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,CAAA;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,qBAAsB,SAAQ,4BAA4B;IACzE,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED,MAAM,WAAW,oBAAqB,SAAQ,4BAA4B;IACxE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,0BAA2B,SAAQ,4BAA4B;IAC9E,IAAI,EAAE,SAAS,CAAA;CAChB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,CAAA;IACjD,aAAa,CAAC,EAAE,iBAAiB,CAAC,kBAAkB,CAAC,CAAA;IACrD,cAAc,CAAC,EAAE,iBAAiB,CAAC,mBAAmB,CAAC,CAAA;IACvD,YAAY,CAAC,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,CAAA;IACnD,cAAc,CAAC,EAAE,iBAAiB,CAAC,mBAAmB,CAAC,CAAA;IACvD,kBAAkB,CAAC,EAAE,iBAAiB,CAAC,+BAA+B,CAAC,CAAA;IACvE,YAAY,CAAC,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,CAAA;IACnD,iBAAiB,CAAC,EAAE,iBAAiB,CAAC,sBAAsB,CAAC,CAAA;IAC7D,WAAW,CAAC,EAAE,iBAAiB,CAAC,wBAAwB,CAAC,CAAA;IACzD,aAAa,CAAC,EAAE,iBAAiB,CAAC,kBAAkB,CAAC,CAAA;IACrD,aAAa,CAAC,EAAE,iBAAiB,CAAC,kBAAkB,CAAC,CAAA;IACrD,MAAM,CAAC,EAAE,iBAAiB,CAAC,qBAAqB,CAAC,CAAA;IACjD,MAAM,CAAC,EAAE,iBAAiB,CAAC,qBAAqB,CAAC,CAAA;IACjD,KAAK,CAAC,EAAE,iBAAiB,CAAC,qBAAqB,CAAC,CAAA;IAChD,UAAU,CAAC,EAAE,iBAAiB,CAAC,oBAAoB,CAAC,CAAA;IACpD,YAAY,CAAC,EAAE,iBAAiB,CAAC,oBAAoB,CAAC,CAAA;IACtD,UAAU,CAAC,EAAE,iBAAiB,CAAC,oBAAoB,CAAC,CAAA;IACpD,qBAAqB,CAAC,EAAE,iBAAiB,CAAC,0BAA0B,CAAC,CAAA;CACtE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,6SAmBsB,CAAA"}

package/dist/extend/component-override.d.ts

@@ -0,0 +1,38 @@
+import type { ComponentType } from 'react';
+/**
+ * Either the whole component (what stores write today), or an adjustment.
+ *
+ * `{ props }` alone keeps the SDK component and forces some of its props.
+ * `{ component, props }` replaces it and pre-binds props — useful for a wrapper
+ * that needs a couple of fixed values.
+ */
+export type ComponentOverride<P> = ComponentType<P> | {
+    component?: ComponentType<P>;
+    /** Props forced on the component, overriding what the page passes. */
+    props?: Partial<P>;
+};
+export interface ResolvedOverride<P> {
+    Component: ComponentType<P>;
+    /** Props to apply last, so an override wins over what the page computed. */
+    props: Partial<P>;
+    /** True when the store replaced the component rather than adjusting it. */
+    replaced: boolean;
+}
+/**
+ * Normalize both override forms against the SDK's own component.
+ *
+ * Override props are applied AFTER the page's, deliberately: an override that
+ * could not win over a computed prop would be unable to change the thing the
+ * store is overriding it for.
+ */
+export declare function resolveOverride<P>(override: ComponentOverride<P> | undefined, fallback: ComponentType<P>): ResolvedOverride<P>;
+/**
+ * The component an override resolves to, or undefined when the store only
+ * adjusted props. Lets a page keep its existing `if (Override) …` branch, which
+ * exists because replacing a page body is structurally different from tweaking
+ * one of its props.
+ */
+export declare function overrideComponent<P>(override: ComponentOverride<P> | undefined): ComponentType<P> | undefined;
+/** The props an override forces, whether or not it also replaces the component. */
+export declare function overrideProps<P>(override: ComponentOverride<P> | undefined): Partial<P>;
+//# sourceMappingURL=component-override.d.ts.map

package/dist/extend/component-override.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-override.d.ts","sourceRoot":"","sources":["../../src/extend/component-override.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAiB1C;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC3B,aAAa,CAAC,CAAC,CAAC,GAChB;IACE,SAAS,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;IAC5B,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CACnB,CAAA;AAgBL,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;IAC3B,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACjB,2EAA2E;IAC3E,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,EAC1C,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GACzB,gBAAgB,CAAC,CAAC,CAAC,CASrB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAI7G;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAGvF"}

package/dist/extend/component-selectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-selectors.d.ts","sourceRoot":"","sources":["../../src/extend/component-selectors.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;CAK/B,CAAA;AAEV,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAY/B,CAAA;AAEV,MAAM,MAAM,4BAA4B,GAAG,OAAO,4BAA4B,CAAA;AAC9E,MAAM,MAAM,8BAA8B,GAAG,OAAO,4BAA4B,CAAC,aAAa,CAAA"}

package/dist/extend/editor-bridge.d.ts

@@ -0,0 +1,59 @@
+export interface EditorBridgeOptions {
+    /**
+     * Origins allowed to drive the picker. An activation from anywhere else is
+     * ignored. Required: there is no safe default, because the parent of an
+     * iframe is chosen by whoever embedded it.
+     */
+    allowedOrigins: readonly string[];
+    /** Test seam. Defaults to the ambient window. */
+    target?: Window;
+}
+export interface PickedBlock {
+    /** Dotted document path — what applyChange accepts and validateStore reports. */
+    path: string;
+    /** The block's registered type, so the parent can look up its schema. */
+    type: string;
+    /** Bounding rect of the block's first painted child, for the parent's overlay. */
+    rect?: {
+        top: number;
+        left: number;
+        width: number;
+        height: number;
+    };
+}
+export declare const EDITOR_MESSAGES: {
+    readonly activate: "ACTIVATE_ELEMENT_PICKER";
+    readonly deactivate: "DEACTIVATE_ELEMENT_PICKER";
+    readonly ready: "ELEMENT_PICKER_READY";
+    readonly picked: "ELEMENT_PICKED";
+    readonly cancelled: "ELEMENT_PICKER_CANCELLED";
+    readonly navigation: "NAVIGATION_CHANGE";
+};
+/**
+ * The nearest ancestor that is a block, and the element that actually paints.
+ *
+ * The stamp lives on a `display: contents` wrapper, which has no box of its
+ * own — `getBoundingClientRect()` on it returns zeros. So the rect comes from
+ * its first element child, which is the block's real root.
+ */
+export declare function blockAt(element: Element | null): {
+    path: string;
+    type: string;
+    node: Element;
+} | null;
+/**
+ * Wire the storefront to an editor parent. Returns a teardown.
+ *
+ * Inert when the page is not framed: a storefront served to a shopper has
+ * `window.parent === window`, nothing is registered, and editor mode stays off.
+ */
+export declare function connectEditorBridge(options: EditorBridgeOptions): () => void;
+/**
+ * Tell the parent the route changed, so its URL bar follows the iframe.
+ *
+ * Silent until an allowed parent has activated the bridge — the path is not
+ * sensitive, but broadcasting to '*' from every storefront is a habit worth
+ * not forming.
+ */
+export declare function reportNavigation(path: string, parentOrigin: string | null, target?: Window): void;
+//# sourceMappingURL=editor-bridge.d.ts.map

package/dist/extend/editor-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-bridge.d.ts","sourceRoot":"","sources":["../../src/extend/editor-bridge.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAA;IACZ,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,IAAI,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CACpE;AAED,eAAO,MAAM,eAAe;;;;;;;CAOlB,CAAA;AAEV;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAWrG;AAQD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,IAAI,CA8E5E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAIjG"}