@fayz-ai/storefront 0.9.0 → 0.11.0

package/README.md

@@ -9,7 +9,7 @@
 
 `@fayz-ai/storefront` is the customer-facing surface of the Fayz SDK: a storefront scaffold that renders a page as a tree of **blocks** (hero, products, manifesto, cart, …) defined in the app manifest. Two completely different brands come out of the same template with zero custom components — the storefront is *data*, not a fork.
 
-It reads commerce from `@fayz-ai/shop`, so the same engine powering an admin also powers the public store. Customize from labels to a fully bespoke section via the [customization ladder](../../docs/CUSTOMIZATION.md) — never by editing this package.
+It reads commerce from `@fayz-ai/shop`, so the same engine powering an admin also powers the public store. Customize from labels to a fully bespoke section via the [customization ladder](../../docs/saas/CUSTOMIZATION.md) — never by editing this package.
 
 ## What's inside
 - **Scaffold** — `defineStorefront(config)` + `StorefrontScaffold` rendered by `renderApp`
@@ -35,7 +35,7 @@ export function App() {
 ```
 
 ## Part of the Fayz SDK
-The storefront surface over `@fayz-ai/shop`. The admin counterpart is built with `@fayz-ai/saas`; both are surfaces of one manifest.
+The storefront surface over `@fayz-ai/shop`. The admin counterpart is built with `@fayz-ai/admin`; both are surfaces of one manifest.
 
 ## Roadmap & contributing
-Built and evolving in the open. See the [Fayz SDK roadmap](../../docs/ROADMAP.md).
+Built and evolving in the open. See the [Fayz SDK roadmap](../../docs/platform/ROADMAP.md).

package/dist/app/createStorefrontApp.d.ts

@@ -0,0 +1,65 @@
+import React from 'react';
+import type { ShopProvider } from '@fayz-ai/shop/provider';
+import type { StorefrontConfig } from '../document/config';
+import type { StorefrontComponents } from '../extend/component-contracts';
+import type { StorefrontSection } from '../blocks/sections';
+import type { RouterAdapter } from '@fayz-ai/core';
+/**
+ * Register the config's declared entities.
+ *
+ * They register BEFORE the provider exists: the mock provider's entity stores
+ * validate their seed against these declarations, and the `entity.*` loaders
+ * resolve them at read time (I2 for unknown keys). Shared with the headless
+ * renderer so a preview of an entity-backed page reads the same declarations
+ * the live store does.
+ */
+export declare function registerStorefrontEntities(config: StorefrontConfig): void;
+/**
+ * The shop provider a config implies: its explicit provider, or a mock seeded
+ * from its catalog, discounts and declared promotions.
+ *
+ * Extracted so `renderStore` binds the SAME provider the browser runtime would
+ * — a headless render that invented its own data source would preview a store
+ * nobody ships.
+ */
+export declare function resolveStorefrontProvider(config: StorefrontConfig): ShopProvider;
+export declare function initStorefrontRuntime(config: StorefrontConfig): void;
+export interface StorefrontShellProps {
+    /**
+     * Addressing scheme and history owner. Omitted → hash addressing in a
+     * browser, or a static adapter bound to `path` when one is given. Supply one
+     * to serve the store at real URLs, or to hand history to a host router.
+     */
+    router?: RouterAdapter;
+    /**
+     * Render this path instead of the live hash location.
+     *
+     * The headless seam (spine M8): `renderStore` and the preview server drive
+     * the shell by path, so a static render never depends on a global
+     * `window.location` and one process can render many paths — including
+     * concurrently, which a location-mutating renderer could not.
+     */
+    path?: string;
+}
+/** The inner storefront UI. Reads everything from the config context, so it is
+ *  shared by createStorefrontApp and the manifest-driven StorefrontScaffold. */
+export declare function StorefrontShell({ path: pathOverride, router }?: StorefrontShellProps): React.JSX.Element;
+/**
+ * Declarative storefront factory — the customer-facing counterpart of
+ * createSaasApp. Sugar over the manifest path: it is equivalent to
+ * renderApp(defineStorefront(config)), sharing initStorefrontRuntime +
+ * StorefrontShell with the scaffold.
+ *
+ *   const App = createStorefrontApp({ name: 'Aurora Goods', currency: 'BRL' })
+ */
+export declare function createStorefrontApp(config: StorefrontConfig): React.ComponentType;
+export interface CreateStorefrontOptions {
+    config: StorefrontConfig;
+    provider?: ShopProvider;
+    components?: StorefrontComponents;
+    routes?: StorefrontConfig['routes'];
+    pages?: StorefrontConfig['routes'];
+    sections?: readonly StorefrontSection[];
+}
+export declare function createStorefront(options: CreateStorefrontOptions): React.ComponentType;
+//# sourceMappingURL=createStorefrontApp.d.ts.map

package/dist/app/createStorefrontApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createStorefrontApp.d.ts","sourceRoot":"","sources":["../../src/app/createStorefrontApp.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAMzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAM1D,OAAO,KAAK,EAAE,gBAAgB,EAA4B,MAAM,oBAAoB,CAAA;AACpF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAU3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAiIlD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAIzE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,GAAG,YAAY,CAEhF;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CA8CpE;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;gFACgF;AAChF,wBAAgB,eAAe,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,GAAE,oBAAyB,qBAcxF;AA6CD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,KAAK,CAAC,aAAa,CAiBjF;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,gBAAgB,CAAA;IACxB,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,UAAU,CAAC,EAAE,oBAAoB,CAAA;IACjC,MAAM,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAA;IACnC,KAAK,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAA;IAClC,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;CACxC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,KAAK,CAAC,aAAa,CAgBtF"}

package/dist/{define.d.ts → app/define.d.ts}

@@ -1,6 +1,6 @@
-import type { StorefrontConfig, StorefrontRouteDefinition } from './config';
-import type { StorefrontComponents } from './component-contracts';
-import type { StorefrontSection } from './sections';
+import type { StorefrontConfig, StorefrontRouteDefinition } from '../document/config';
+import type { StorefrontComponents } from '../extend/component-contracts';
+import type { StorefrontSection } from '../blocks/sections';
 import type { CreateStorefrontOptions } from './createStorefrontApp';
 /**
  * Identity helpers for generated/custom storefronts.

package/dist/app/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/app/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,yBAAyB,EAC1B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAEpE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,CAAC,CAAC,SAAS,gBAAgB,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAErF;AAED,wBAAgB,0BAA0B,CAAC,KAAK,CAAC,CAAC,SAAS,oBAAoB,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,CAEjG;AAED,wBAAgB,sBAAsB,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,yBAAyB,EAAE,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAEzG;AAED,wBAAgB,wBAAwB,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,iBAAiB,EAAE,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAErG;AAED,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,CAAC,SAAS,uBAAuB,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAE1F"}

package/dist/app/hydration.d.ts

@@ -0,0 +1,37 @@
+import type { PageDataEntry } from '../blocks/page-data';
+/** Where the payload lives in the document. */
+export declare const PAGE_DATA_SCRIPT_ID = "__fayz_page_data__";
+export interface HydrationPayload {
+    /** Resolved page data, keyed by `dataNeedKey`. */
+    entries: Record<string, PageDataEntry>;
+    /** The path the server rendered, so a mismatch is detectable rather than silent. */
+    path: string;
+}
+/**
+ * The `<script>` tag carrying `payload`, for a renderer to place in the body.
+ *
+ * Only `ready` entries are carried. An entry that errored server-side is
+ * deliberately dropped so the browser retries it: a transient provider failure
+ * during a prerender would otherwise be baked into the page for as long as the
+ * HTML is cached.
+ */
+export declare function serializePageData(payload: HydrationPayload): string;
+/**
+ * The payload this document was rendered with, or null.
+ *
+ * Read once and memoised: the tag describes the FIRST render only. After a
+ * client-side navigation the document still contains it, and re-reading would
+ * seed a new page with the previous one's data.
+ */
+export declare function readHydratedPageData(): HydrationPayload | null;
+/**
+ * Entries to seed a page at `path`, or undefined.
+ *
+ * Path-guarded: the payload belongs to the document the server rendered, so
+ * handing it to a different route would seed that route with another page's
+ * answers. Query strings are ignored — they address state within a page.
+ */
+export declare function hydratedEntriesFor(path: string): Record<string, PageDataEntry> | undefined;
+/** Test seam: forget the memoised read. */
+export declare function resetHydratedPageData(): void;
+//# sourceMappingURL=hydration.d.ts.map

package/dist/app/hydration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration.d.ts","sourceRoot":"","sources":["../../src/app/hydration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAexD,+CAA+C;AAC/C,eAAO,MAAM,mBAAmB,uBAAuB,CAAA;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACtC,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAA;CACb;AAiBD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAOnE;AAKD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,GAAG,IAAI,CAc9D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,SAAS,CAK1F;AAED,2CAA2C;AAC3C,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C"}

package/dist/app/prerender.d.ts

@@ -0,0 +1,57 @@
+import { historyRouterAdapter } from '@fayz-ai/core';
+import type { ShopProvider } from '@fayz-ai/shop/provider';
+import type { RenderStoreOptions } from '../document/render';
+import type { StoreDocument } from '../document/sections';
+export interface PrerenderPage {
+    path: string;
+    html: string;
+    /** Where a file-writing host should put it: `/product/x` → `product/x/index.html`. */
+    outputPath: string;
+    title: string;
+    /** False when the path rendered the not-found page — excluded from `pages`. */
+    found: boolean;
+    ok: boolean;
+}
+export interface PrerenderResult {
+    pages: PrerenderPage[];
+    /** Paths that rendered not-found or errored, with the reason. */
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
+    sitemapXml: string;
+    robotsTxt: string;
+}
+export interface PrerenderOptions extends Omit<RenderStoreOptions, 'path' | 'router' | 'html'> {
+    provider: ShopProvider;
+    /** Absolute origin. Required for a sitemap — its URLs must be absolute. */
+    origin: string;
+    /** Defaults to every public path the store has. */
+    paths?: readonly string[];
+    /** Bounded so a large catalogue does not open one connection per product. */
+    concurrency?: number;
+    /** Reported per page, so a long run is observable rather than silent. */
+    onPage?: (page: PrerenderPage) => void;
+}
+/** `/` → `index.html`; `/product/x` → `product/x/index.html`. */
+export declare function outputPathFor(path: string): string;
+export declare function buildSitemapXml(origin: string, paths: readonly string[]): string;
+/**
+ * Disallows the per-shopper routes explicitly.
+ *
+ * They are not linked from anywhere crawlable, but a crawler that finds one
+ * anyway would index a checkout — and crawl budget spent there is budget not
+ * spent on products.
+ */
+export declare function buildRobotsTxt(origin: string): string;
+/**
+ * Render every public page of a store.
+ *
+ * The router is fixed to real-URL addressing: prerendering a hash-addressed
+ * store would write files no URL can reach, which is the whole reason the
+ * addressing seam exists.
+ */
+export declare function prerenderStore(document: StoreDocument | Record<string, unknown>, options: PrerenderOptions): Promise<PrerenderResult>;
+/** The adapter a browser app should use to serve a prerendered store. */
+export declare const prerenderClientRouter: typeof historyRouterAdapter;
+//# sourceMappingURL=prerender.d.ts.map

package/dist/app/prerender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prerender.d.ts","sourceRoot":"","sources":["../../src/app/prerender.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAuB,MAAM,eAAe,CAAA;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAE1D,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,oBAAoB,CAAA;AAI/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAezD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,+EAA+E;IAC/E,KAAK,EAAE,OAAO,CAAA;IACd,EAAE,EAAE,OAAO,CAAA;CACZ;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,EAAE,CAAA;IACtB,iEAAiE;IACjE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAChD,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,gBACf,SAAQ,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5D,QAAQ,EAAE,YAAY,CAAA;IACtB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAA;IACd,mDAAmD;IACnD,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAA;CACvC;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGlD;AAUD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMhF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAYrD;AAoBD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjD,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAmD1B;AAED,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,6BAAuB,CAAA"}

package/dist/{router.d.ts → app/router.d.ts}

@@ -1,128 +1,153 @@
 import React from 'react';
+import { type RouterAdapter } from '@fayz-ai/core';
+export declare const StorefrontRouterProvider: React.Provider<RouterAdapter | null>;
+export declare function useRouterAdapter(): RouterAdapter;
+/** The current in-app path, re-rendering on every navigation. */
+export declare function useRoutePath(): string;
+/** Scroll to top on route change. Separate from path tracking so a host that
+ *  manages its own scroll restoration can simply not call it. */
+export declare function useScrollToTopOnNavigate(path: string): void;
+export declare function useNavigate(): (to: string) => void;
+/** @deprecated Use `useRoutePath()`. Kept so existing imports keep compiling. */
+export declare const useHashPath: typeof useRoutePath;
+/** Imperative navigation from an event handler. See `_activeAdapter` above. */
 export declare function navigateTo(to: string): void;
-export declare function useHashPath(): string;
+/**
+ * The adapter a shell should install for a given render.
+ *
+ * A `path` override means a static render (`renderStore`, the preview server, a
+ * node test): there is no history to own, but anchors must still carry real,
+ * crawlable hrefs — which is the whole point of rendering headlessly.
+ */
+export declare function shellRouterAdapter(pathOverride: string | undefined, live: RouterAdapter): RouterAdapter;
 /** Match '/product/:slug' against '/product/leather-backpack' → { slug: 'leather-backpack' } */
 export declare function matchPath(pattern: string, path: string): Record<string, string> | null;
-export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
     to: string;
 }
-/** Real anchor (#/path) — middle-click/cmd-click friendly, Playwright friendly. */
-export declare function Link({ to, children, ...rest }: LinkProps): React.DetailedReactHTMLElement<{
+/**
+ * A real anchor, always — middle-click, cmd-click, "copy link address" and
+ * Playwright all keep working, and a crawler sees a real href.
+ *
+ * Under hash addressing the browser handles the fragment itself, so the click
+ * is left alone. Under real-URL addressing a plain left-click must be
+ * intercepted or the browser would do a full document load; modified clicks and
+ * explicit targets are still handed to the browser.
+ */
+export declare function Link({ to, children, onClick, target, ...rest }: LinkProps): React.DetailedReactHTMLElement<{
+    style?: React.CSSProperties | undefined;
+    prefix?: string | undefined | undefined;
+    slot?: string | undefined | undefined;
+    title?: string | undefined | undefined;
     download?: any;
-    href: string;
-    hrefLang?: string | undefined;
-    media?: string | undefined;
-    ping?: string | undefined;
-    target?: React.HTMLAttributeAnchorTarget | undefined;
-    type?: string | undefined;
+    hrefLang?: string | undefined | undefined;
+    media?: string | undefined | undefined;
+    ping?: string | undefined | undefined;
+    type?: string | undefined | undefined;
     referrerPolicy?: React.HTMLAttributeReferrerPolicy | undefined;
-    defaultChecked?: boolean | undefined;
+    defaultChecked?: boolean | undefined | undefined;
     defaultValue?: string | number | readonly string[] | undefined;
-    suppressContentEditableWarning?: boolean | undefined;
-    suppressHydrationWarning?: boolean | undefined;
-    accessKey?: string | undefined;
-    autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters" | undefined | (string & {});
-    autoFocus?: boolean | undefined;
-    className?: string | undefined;
-    contentEditable?: (boolean | "false" | "true") | "inherit" | "plaintext-only" | undefined;
-    contextMenu?: string | undefined;
-    dir?: string | undefined;
-    draggable?: (boolean | "false" | "true") | undefined;
-    enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined;
-    hidden?: boolean | undefined;
-    id?: string | undefined;
-    lang?: string | undefined;
-    nonce?: string | undefined;
-    slot?: string | undefined;
-    spellCheck?: (boolean | "false" | "true") | undefined;
-    style?: React.CSSProperties | undefined;
-    tabIndex?: number | undefined;
-    title?: string | undefined;
-    translate?: "yes" | "no" | undefined;
-    radioGroup?: string | undefined;
+    suppressContentEditableWarning?: boolean | undefined | undefined;
+    suppressHydrationWarning?: boolean | undefined | undefined;
+    accessKey?: string | undefined | undefined;
+    autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters" | undefined | (string & {}) | undefined;
+    autoFocus?: boolean | undefined | undefined;
+    className?: string | undefined | undefined;
+    contentEditable?: (boolean | "true" | "false") | "inherit" | "plaintext-only" | undefined;
+    contextMenu?: string | undefined | undefined;
+    dir?: string | undefined | undefined;
+    draggable?: (boolean | "true" | "false") | undefined;
+    enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined | undefined;
+    hidden?: boolean | undefined | undefined;
+    id?: string | undefined | undefined;
+    lang?: string | undefined | undefined;
+    nonce?: string | undefined | undefined;
+    spellCheck?: (boolean | "true" | "false") | undefined;
+    tabIndex?: number | undefined | undefined;
+    translate?: "yes" | "no" | undefined | undefined;
+    radioGroup?: string | undefined | undefined;
     role?: React.AriaRole | undefined;
-    about?: string | undefined;
-    content?: string | undefined;
-    datatype?: string | undefined;
+    about?: string | undefined | undefined;
+    content?: string | undefined | undefined;
+    datatype?: string | undefined | undefined;
     inlist?: any;
-    prefix?: string | undefined;
-    property?: string | undefined;
-    rel?: string | undefined;
-    resource?: string | undefined;
-    rev?: string | undefined;
-    typeof?: string | undefined;
-    vocab?: string | undefined;
-    autoCorrect?: string | undefined;
-    autoSave?: string | undefined;
-    color?: string | undefined;
-    itemProp?: string | undefined;
-    itemScope?: boolean | undefined;
-    itemType?: string | undefined;
-    itemID?: string | undefined;
-    itemRef?: string | undefined;
-    results?: number | undefined;
-    security?: string | undefined;
-    unselectable?: "on" | "off" | undefined;
-    inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
-    is?: string | undefined;
-    exportparts?: string | undefined;
-    part?: string | undefined;
-    "aria-activedescendant"?: string | undefined;
-    "aria-atomic"?: (boolean | "false" | "true") | undefined;
-    "aria-autocomplete"?: "none" | "inline" | "list" | "both" | undefined;
-    "aria-braillelabel"?: string | undefined;
-    "aria-brailleroledescription"?: string | undefined;
-    "aria-busy"?: (boolean | "false" | "true") | undefined;
-    "aria-checked"?: boolean | "false" | "mixed" | "true" | undefined;
-    "aria-colcount"?: number | undefined;
-    "aria-colindex"?: number | undefined;
-    "aria-colindextext"?: string | undefined;
-    "aria-colspan"?: number | undefined;
-    "aria-controls"?: string | undefined;
-    "aria-current"?: boolean | "false" | "true" | "page" | "step" | "location" | "date" | "time" | undefined;
-    "aria-describedby"?: string | undefined;
-    "aria-description"?: string | undefined;
-    "aria-details"?: string | undefined;
-    "aria-disabled"?: (boolean | "false" | "true") | undefined;
-    "aria-dropeffect"?: "none" | "copy" | "execute" | "link" | "move" | "popup" | undefined;
-    "aria-errormessage"?: string | undefined;
-    "aria-expanded"?: (boolean | "false" | "true") | undefined;
-    "aria-flowto"?: string | undefined;
-    "aria-grabbed"?: (boolean | "false" | "true") | undefined;
-    "aria-haspopup"?: boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog" | undefined;
-    "aria-hidden"?: (boolean | "false" | "true") | undefined;
-    "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling" | undefined;
-    "aria-keyshortcuts"?: string | undefined;
-    "aria-label"?: string | undefined;
-    "aria-labelledby"?: string | undefined;
-    "aria-level"?: number | undefined;
-    "aria-live"?: "off" | "assertive" | "polite" | undefined;
-    "aria-modal"?: (boolean | "false" | "true") | undefined;
-    "aria-multiline"?: (boolean | "false" | "true") | undefined;
-    "aria-multiselectable"?: (boolean | "false" | "true") | undefined;
-    "aria-orientation"?: "horizontal" | "vertical" | undefined;
-    "aria-owns"?: string | undefined;
-    "aria-placeholder"?: string | undefined;
-    "aria-posinset"?: number | undefined;
-    "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined;
-    "aria-readonly"?: (boolean | "false" | "true") | undefined;
-    "aria-relevant"?: "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text" | "text additions" | "text removals" | undefined;
-    "aria-required"?: (boolean | "false" | "true") | undefined;
-    "aria-roledescription"?: string | undefined;
-    "aria-rowcount"?: number | undefined;
-    "aria-rowindex"?: number | undefined;
-    "aria-rowindextext"?: string | undefined;
-    "aria-rowspan"?: number | undefined;
-    "aria-selected"?: (boolean | "false" | "true") | undefined;
-    "aria-setsize"?: number | undefined;
-    "aria-sort"?: "none" | "ascending" | "descending" | "other" | undefined;
-    "aria-valuemax"?: number | undefined;
-    "aria-valuemin"?: number | undefined;
-    "aria-valuenow"?: number | undefined;
-    "aria-valuetext"?: string | undefined;
+    property?: string | undefined | undefined;
+    rel?: string | undefined | undefined;
+    resource?: string | undefined | undefined;
+    rev?: string | undefined | undefined;
+    typeof?: string | undefined | undefined;
+    vocab?: string | undefined | undefined;
+    autoCorrect?: string | undefined | undefined;
+    autoSave?: string | undefined | undefined;
+    color?: string | undefined | undefined;
+    itemProp?: string | undefined | undefined;
+    itemScope?: boolean | undefined | undefined;
+    itemType?: string | undefined | undefined;
+    itemID?: string | undefined | undefined;
+    itemRef?: string | undefined | undefined;
+    results?: number | undefined | undefined;
+    security?: string | undefined | undefined;
+    unselectable?: "on" | "off" | undefined | undefined;
+    inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined | undefined;
+    is?: string | undefined | undefined;
+    exportparts?: string | undefined | undefined;
+    part?: string | undefined | undefined;
+    "aria-activedescendant"?: string | undefined | undefined;
+    "aria-atomic"?: (boolean | "true" | "false") | undefined;
+    "aria-autocomplete"?: "none" | "inline" | "list" | "both" | undefined | undefined;
+    "aria-braillelabel"?: string | undefined | undefined;
+    "aria-brailleroledescription"?: string | undefined | undefined;
+    "aria-busy"?: (boolean | "true" | "false") | undefined;
+    "aria-checked"?: boolean | "false" | "mixed" | "true" | undefined | undefined;
+    "aria-colcount"?: number | undefined | undefined;
+    "aria-colindex"?: number | undefined | undefined;
+    "aria-colindextext"?: string | undefined | undefined;
+    "aria-colspan"?: number | undefined | undefined;
+    "aria-controls"?: string | undefined | undefined;
+    "aria-current"?: boolean | "false" | "true" | "page" | "step" | "location" | "date" | "time" | undefined | undefined;
+    "aria-describedby"?: string | undefined | undefined;
+    "aria-description"?: string | undefined | undefined;
+    "aria-details"?: string | undefined | undefined;
+    "aria-disabled"?: (boolean | "true" | "false") | undefined;
+    "aria-dropeffect"?: "none" | "copy" | "execute" | "link" | "move" | "popup" | undefined | undefined;
+    "aria-errormessage"?: string | undefined | undefined;
+    "aria-expanded"?: (boolean | "true" | "false") | undefined;
+    "aria-flowto"?: string | undefined | undefined;
+    "aria-grabbed"?: (boolean | "true" | "false") | undefined;
+    "aria-haspopup"?: boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog" | undefined | undefined;
+    "aria-hidden"?: (boolean | "true" | "false") | undefined;
+    "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling" | undefined | undefined;
+    "aria-keyshortcuts"?: string | undefined | undefined;
+    "aria-label"?: string | undefined | undefined;
+    "aria-labelledby"?: string | undefined | undefined;
+    "aria-level"?: number | undefined | undefined;
+    "aria-live"?: "off" | "assertive" | "polite" | undefined | undefined;
+    "aria-modal"?: (boolean | "true" | "false") | undefined;
+    "aria-multiline"?: (boolean | "true" | "false") | undefined;
+    "aria-multiselectable"?: (boolean | "true" | "false") | undefined;
+    "aria-orientation"?: "horizontal" | "vertical" | undefined | undefined;
+    "aria-owns"?: string | undefined | undefined;
+    "aria-placeholder"?: string | undefined | undefined;
+    "aria-posinset"?: number | undefined | undefined;
+    "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined | undefined;
+    "aria-readonly"?: (boolean | "true" | "false") | undefined;
+    "aria-relevant"?: "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text" | "text additions" | "text removals" | undefined | undefined;
+    "aria-required"?: (boolean | "true" | "false") | undefined;
+    "aria-roledescription"?: string | undefined | undefined;
+    "aria-rowcount"?: number | undefined | undefined;
+    "aria-rowindex"?: number | undefined | undefined;
+    "aria-rowindextext"?: string | undefined | undefined;
+    "aria-rowspan"?: number | undefined | undefined;
+    "aria-selected"?: (boolean | "true" | "false") | undefined;
+    "aria-setsize"?: number | undefined | undefined;
+    "aria-sort"?: "none" | "ascending" | "descending" | "other" | undefined | undefined;
+    "aria-valuemax"?: number | undefined | undefined;
+    "aria-valuemin"?: number | undefined | undefined;
+    "aria-valuenow"?: number | undefined | undefined;
+    "aria-valuetext"?: string | undefined | undefined;
     dangerouslySetInnerHTML?: {
         __html: string | TrustedHTML;
-    } | undefined;
+    } | undefined | undefined;
     onCopy?: React.ClipboardEventHandler<HTMLAnchorElement> | undefined;
     onCopyCapture?: React.ClipboardEventHandler<HTMLAnchorElement> | undefined;
     onCut?: React.ClipboardEventHandler<HTMLAnchorElement> | undefined;
@@ -207,7 +232,6 @@ export declare function Link({ to, children, ...rest }: LinkProps): React.Detail
     onWaitingCapture?: React.ReactEventHandler<HTMLAnchorElement> | undefined;
     onAuxClick?: React.MouseEventHandler<HTMLAnchorElement> | undefined;
     onAuxClickCapture?: React.MouseEventHandler<HTMLAnchorElement> | undefined;
-    onClick?: React.MouseEventHandler<HTMLAnchorElement> | undefined;
     onClickCapture?: React.MouseEventHandler<HTMLAnchorElement> | undefined;
     onContextMenu?: React.MouseEventHandler<HTMLAnchorElement> | undefined;
     onContextMenuCapture?: React.MouseEventHandler<HTMLAnchorElement> | undefined;
@@ -281,5 +305,8 @@ export declare function Link({ to, children, ...rest }: LinkProps): React.Detail
     onAnimationIterationCapture?: React.AnimationEventHandler<HTMLAnchorElement> | undefined;
     onTransitionEnd?: React.TransitionEventHandler<HTMLAnchorElement> | undefined;
     onTransitionEndCapture?: React.TransitionEventHandler<HTMLAnchorElement> | undefined;
+    href: string;
+    onClick: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+    target: React.HTMLAttributeAnchorTarget | undefined;
 }, HTMLElement>;
 //# sourceMappingURL=router.d.ts.map

package/dist/app/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/app/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAqE,MAAM,OAAO,CAAA;AACzF,OAAO,EAA6C,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AAwB7F,eAAO,MAAM,wBAAwB,sCAAgC,CAAA;AAuBrE,wBAAgB,gBAAgB,IAAI,aAAa,CAOhD;AAED,iEAAiE;AACjE,wBAAgB,YAAY,IAAI,MAAM,CAOrC;AAED;iEACiE;AACjE,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAI3D;AAED,wBAAgB,WAAW,IAAI,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAGlD;AAED,iFAAiF;AACjF,eAAO,MAAM,WAAW,qBAAe,CAAA;AAEvC,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,aAAa,GAAG,aAAa,CAOvG;AAED,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAatF;AAED,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC5F,EAAE,EAAE,MAAM,CAAA;CACX;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,EAAE,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAG5C,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC;;gBAgBhE"}

package/dist/{scaffold.d.ts → app/scaffold.d.ts}

@@ -1,7 +1,7 @@
 import React from 'react';
 import type { AppManifest } from '@fayz-ai/core';
-import type { StorefrontConfig } from './config';
-import './blocks';
+import type { StorefrontConfig } from '../document/config';
+import '../blocks/registry';
 /** StorefrontConfig → AppManifest (the sugar-to-data direction). */
 export declare function defineStorefront(config: StorefrontConfig): AppManifest;
 export declare function StorefrontScaffold({ manifest, surface }: {

package/dist/app/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/app/scaffold.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,eAAe,CAAA;AAGjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAK1D,OAAO,oBAAoB,CAAA;AAgB3B,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,CA6BtE;AA4CD,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE;IAAE,QAAQ,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,qBAanG;yBAbe,kBAAkB;;;AAoBlC,wBAAgB,0BAA0B,IAAI,IAAI,CAIjD"}

package/dist/app/serving.d.ts

@@ -0,0 +1,70 @@
+import type { ShopProvider } from '@fayz-ai/shop/provider';
+import type { StorefrontConfig, ResolvedStorefrontConfig } from '../document/config';
+export type StorefrontRouteMatch = {
+    kind: 'custom';
+    route: NonNullable<ResolvedStorefrontConfig['routes']>[number];
+    params: Record<string, string>;
+} | {
+    kind: 'product';
+    params: Record<string, string>;
+} | {
+    kind: 'order';
+    params: Record<string, string>;
+} | {
+    kind: 'checkout';
+} | {
+    kind: 'account';
+} | {
+    kind: 'catalog';
+} | {
+    kind: 'searchResults';
+} | {
+    kind: 'policy';
+    policy: 'privacy' | 'terms' | 'returns';
+} | {
+    kind: 'content';
+    slug: string;
+    params: Record<string, string>;
+} | {
+    kind: 'home';
+} | {
+    kind: 'notFound';
+};
+/**
+ * What a path means, resolved once.
+ *
+ * The shell renders from this, cacheability is derived from it, and a host
+ * framework asks it whether a URL exists at all before choosing a status code.
+ * Those three answering separately is how a page ends up rendered as one thing
+ * and cached or statused as another.
+ *
+ * The query string is stripped first: it addresses state WITHIN a page, so
+ * `/?utm_source=instagram` is the home page — the single most common shape of
+ * inbound marketing link, and a 404 for it is a silent, expensive bug.
+ */
+export declare function resolveStorefrontRoute(config: StorefrontConfig | ResolvedStorefrontConfig, rawPath: string): StorefrontRouteMatch;
+/** Whether a URL exists at all — what a host needs before choosing a status. */
+export declare function isKnownPath(config: StorefrontConfig | ResolvedStorefrontConfig, path: string): boolean;
+/**
+ * Whether `path`'s HTML is identical for every visitor.
+ *
+ * Conservative by construction: a store's own route is private unless it says
+ * otherwise, because guessing "public" is the direction that leaks one
+ * shopper's page to another.
+ */
+export declare function isPublicPath(config: StorefrontConfig | ResolvedStorefrontConfig, path: string): boolean;
+/**
+ * Every path worth prerendering, and the same list a sitemap should carry.
+ *
+ * Product URLs come from the catalogue rather than the route table, so the
+ * provider is asked rather than guessed at. Custom routes with parameters are
+ * skipped: the SDK cannot know what values a store's own route accepts, and
+ * emitting `/colecao/:slug` into a sitemap is worse than omitting it.
+ */
+export declare function storefrontPaths(input: {
+    config: StorefrontConfig | ResolvedStorefrontConfig;
+    provider: ShopProvider;
+    /** Include per-shopper routes. Off by default — they are not prerenderable. */
+    includePrivate?: boolean;
+}): Promise<string[]>;
+//# sourceMappingURL=serving.d.ts.map

package/dist/app/serving.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serving.d.ts","sourceRoot":"","sources":["../../src/app/serving.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAI1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA;AAcpF,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,WAAW,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAClH;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAA;AAExB;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,gBAAgB,GAAG,wBAAwB,EACnD,OAAO,EAAE,MAAM,GACd,oBAAoB,CAgCtB;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CACzB,MAAM,EAAE,gBAAgB,GAAG,wBAAwB,EACnD,IAAI,EAAE,MAAM,GACX,OAAO,CAET;AAcD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,GAAG,wBAAwB,EACnD,IAAI,EAAE,MAAM,GACX,OAAO,CAgBT;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE;IAC3C,MAAM,EAAE,gBAAgB,GAAG,wBAAwB,CAAA;IACnD,QAAQ,EAAE,YAAY,CAAA;IACtB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAapB"}