@fayz-ai/storefront 0.9.0 → 0.10.0

package/dist/app/static-render.d.ts

@@ -0,0 +1,46 @@
+import type { BlockNode } from '@fayz-ai/core';
+import type { PageDataEntry, PageDataNeed } from '../blocks/page-data';
+/**
+ * What a route declared for the document head during a static render.
+ *
+ * Title and description are the client-rendered baseline. The rest is what a
+ * page needs to be worth anything once it HAS its own URL: a canonical so the
+ * engine knows which address is authoritative, an image and type so a share in
+ * a messaging app is not a grey rectangle, and JSON-LD so a product is eligible
+ * for a rich result instead of a plain blue link.
+ */
+export interface StaticHeadInput {
+    title?: string;
+    description?: string | null;
+    /** Absolute URL. A relative canonical is ignored by search engines. */
+    canonical?: string;
+    /** Absolute URL of the image a share should show. */
+    image?: string;
+    /** OpenGraph type — 'website', 'article', 'product'. */
+    type?: string;
+    /** schema.org objects, emitted as <script type="application/ld+json">. */
+    jsonLd?: Array<Record<string, unknown>>;
+}
+export interface StaticRenderPass {
+    /** Called once per scope, so a page plus its slots report the whole rendered
+     *  composition — including forced-layout repairs (I7). */
+    tree(nodes: readonly BlockNode[]): void;
+    needs(needs: readonly PageDataNeed[]): void;
+    head(input: StaticHeadInput): void;
+    /** Resolved by an earlier pass, keyed by `dataNeedKey`. A key present here is
+     *  served instead of being fetched. */
+    entries: Readonly<Record<string, PageDataEntry>>;
+    /**
+     * Absolute origin the rendered page will be served from, when the caller
+     * knows it. Pages need it to declare a canonical or an og:image, and a static
+     * render has no `window.location` to infer one from — so it travels with the
+     * pass rather than being guessed per page.
+     */
+    origin?: string;
+}
+/** The pass currently rendering, or null — which is every browser render. */
+export declare function currentStaticRenderPass(): StaticRenderPass | null;
+/** Run one synchronous render with `pass` installed. Nesting restores the
+ *  previous pass, so a renderer inside a renderer cannot strand the global. */
+export declare function withStaticRenderPass<T>(pass: StaticRenderPass, render: () => T): T;
+//# sourceMappingURL=static-render.d.ts.map

package/dist/app/static-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-render.d.ts","sourceRoot":"","sources":["../../src/app/static-render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAYtE;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B;8DAC0D;IAC1D,IAAI,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,CAAA;IACvC,KAAK,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI,CAAA;IAC3C,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAA;IAClC;2CACuC;IACvC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAA;IAChD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAID,6EAA6E;AAC7E,wBAAgB,uBAAuB,IAAI,gBAAgB,GAAG,IAAI,CAEjE;AAED;+EAC+E;AAC/E,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAQlF"}

package/dist/blocks/block-at-path.d.ts

@@ -0,0 +1,59 @@
+import type { BlockDescriptor } from '@fayz-ai/core';
+import type { StoreDocument } from '../document/sections';
+export interface BlockAtPath {
+    /** The path as given, echoed so a caller can key state by it. */
+    path: string;
+    /** The block's registered type. */
+    type: string;
+    /**
+     * Where this block's settings live: `<path>.props` for the nested form,
+     * `<path>` itself for the flat one. Both forms MIX inside one array, so a
+     * caller appending `.props` by hand is right about some blocks and silently
+     * wrong about the rest. Pass this to `settingChange` and it cannot happen.
+     */
+    settingsPath: string;
+    /** Current values, whichever form they took — the form's initial state. */
+    props: Record<string, unknown>;
+    /** Empty when the block declares no settings, which is itself the answer. */
+    settings: BlockDescriptor['settings'];
+    /** For a caller that wants labels, help text or presets. */
+    descriptor: BlockDescriptor | null;
+}
+export type BlockAtPathError = {
+    code: 'unparseable-path';
+    message: string;
+} | {
+    code: 'no-block-at-path';
+    message: string;
+} | {
+    code: 'unknown-block';
+    message: string;
+    valid: string[];
+};
+/**
+ * Resolve a picked path against a Store Document.
+ *
+ * Every failure names what went wrong and, for an unknown block, the valid set
+ * (I2) — an editor that silently renders an empty panel teaches a merchant that
+ * the editor is broken.
+ */
+export declare function blockAtPath(document: StoreDocument | Record<string, unknown>, path: string): {
+    ok: true;
+    block: BlockAtPath;
+} | {
+    ok: false;
+    error: BlockAtPathError;
+};
+/**
+ * The change that saves one edited setting.
+ *
+ * Takes `settingsPath`, not the block's path: only `blockAtPath` has seen the
+ * node and knows which form it took. Hardcoding `.props.` here wrote an ignored
+ * key on every flat block — a save that reported success and changed nothing.
+ */
+export declare function settingChange(settingsPath: string, settingId: string, value: unknown): {
+    op: 'set' | 'remove';
+    path: string;
+    value?: unknown;
+};
+//# sourceMappingURL=block-at-path.d.ts.map

package/dist/blocks/block-at-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-at-path.d.ts","sourceRoot":"","sources":["../../src/blocks/block-at-path.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAIpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAUzD,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAA;IACZ,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,6EAA6E;IAC7E,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,CAAA;IACrC,4DAA4D;IAC5D,UAAU,EAAE,eAAe,GAAG,IAAI,CAAA;CACnC;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AA0B/D;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjD,IAAI,EAAE,MAAM,GACX;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,CAmD3E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG;IACtF,EAAE,EAAE,KAAK,GAAG,QAAQ,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAMA"}

package/dist/blocks/page-blocks.d.ts

@@ -0,0 +1,163 @@
+import type { BlockDataNeeds, BlockNode } from '@fayz-ai/core';
+import type { StorefrontSection } from './sections';
+import type { StorefrontTheme } from '../lib/theme';
+/** Pages that are composed from blocks, and the `enabledOn` vocabulary.
+ *  `content` is the editorial kind: a titled page that is nothing but blocks —
+ *  no commerce body, no catalog assumptions. */
+export type StorefrontPageKind = 'home' | 'catalog' | 'product' | 'collection' | 'content';
+/**
+ * A block instance in a page tree — the general form.
+ *
+ * `id` matters more than it looks: two product rails on one page are
+ * indistinguishable without it, so an external editor cannot target one of them
+ * and an AI-generated diff cannot say which it changed. VTEX solved the same
+ * problem with `rich-text#hero`; this is the same idea spelled as a field.
+ */
+export interface StorefrontBlockRef {
+    /** Registered block id — an SDK section, a plugin block, or an app's own. */
+    type: string;
+    id?: string;
+    props?: Record<string, unknown>;
+    children?: readonly StorefrontBlockRef[];
+    /**
+     * Instance-level data needs, merged over the block meta's `data` declaration
+     * by need name — how a document points a block's loader at a route param
+     * (`{ products: { loader: 'products.list', params: { category: { $param:
+     * 'slug' } } } }`). Resolved once per page by the page-data scope.
+     */
+    data?: BlockDataNeeds;
+}
+/**
+ * What a page's block list accepts.
+ *
+ * The typed union keeps checking SDK sections (a bad `variant` is still a type
+ * error); the open ref form is what lets an app place its own registered block
+ * without casting.
+ */
+export type StorefrontBlockLike = StorefrontSection | StorefrontBlockRef;
+export interface StorefrontPageConfig {
+    blocks: readonly StorefrontBlockLike[];
+}
+/**
+ * An editorial page, expressible entirely in the document: a slug, a title, a
+ * route, and blocks. This is the page kind that absorbs the "brand site half"
+ * of a store — biography, philosophy, press, collections — which today lives
+ * as hand-written custom routes (cristinarotondaro carries ~240 lines of them).
+ *
+ * The store chrome (header, footer, cart) still frames the page; what a
+ * content page does NOT get is a commerce body block or any catalog
+ * assumption. It is blocks all the way down.
+ */
+export interface StorefrontContentPageConfig extends StorefrontPageConfig {
+    /** Document/page title (`<title>` gets "<title> — <store>"). Defaults to the slug. */
+    title?: string;
+    /**
+     * Route path. Defaults to `/<slug>`. May declare params (`/categoria/:slug`)
+     * — one page then serves every match, and its blocks read the params through
+     * `$param` loader bindings (M3). validateStore checks that every binding
+     * names a param the path declares.
+     */
+    path?: string;
+    /**
+     * Theme overlay applied ONLY inside this page, merged over the store theme.
+     *
+     * This is what makes a campaign page — a licensed line, a seasonal drop, a
+     * collab — expressible as a content page instead of a microsite. Stores
+     * routinely build those elsewhere and lose the funnel with them: the "buy"
+     * CTA leaves for another domain and the cart, the session and the
+     * attribution go with it.
+     *
+     * The overlay is emitted scoped to `[data-page="<slug>"]`, so a hot-pink
+     * summer drop cannot repaint the header, the cart drawer or any other route.
+     * It merges key by key, so a page that sets only `colors.primary` keeps the
+     * store's typography and every other token.
+     */
+    theme?: Partial<StorefrontTheme>;
+}
+/**
+ * Merge a page's theme overlay over the store theme.
+ *
+ * Nested groups merge rather than replace: a page declaring one colour must not
+ * silently drop the store's fonts, radii and brand tokens back to SDK defaults.
+ */
+export declare function mergePageTheme(base: StorefrontTheme | undefined, overlay: Partial<StorefrontTheme> | undefined): StorefrontTheme | undefined;
+/** The wrapper attribute + selector a page's scoped theme is emitted under. */
+export declare function pageThemeSelector(slug: string): string;
+/** The params a route path pattern declares ('/categoria/:slug' → ['slug']). */
+export declare function routePathParams(path: string): string[];
+export interface StorefrontPagesConfig {
+    home?: StorefrontPageConfig;
+    catalog?: StorefrontPageConfig;
+    product?: StorefrontPageConfig;
+    collection?: StorefrontPageConfig;
+    /** Editorial pages, keyed by slug. */
+    content?: Record<string, StorefrontContentPageConfig>;
+}
+/** Route path of one content page (explicit `path`, or `/<slug>`). */
+export declare function contentPagePath(slug: string, page: StorefrontContentPageConfig): string;
+export interface ContentPageMatch {
+    slug: string;
+    page: StorefrontContentPageConfig;
+    /** Params extracted from the page's path pattern, when it declares any. */
+    params: Record<string, string>;
+}
+/** The content page a path resolves to, if the store declared one. Paths are
+ *  patterns (`/categoria/:slug`), so one declared page can serve a family of
+ *  URLs and hand the matched params to its blocks' `$param` bindings. */
+export declare function matchContentPage(pages: StorefrontPagesConfig | undefined, path: string): ContentPageMatch | null;
+/** Block ids for the native page bodies — Shopify's `main` section, by another name. */
+export declare const CATALOG_BODY_BLOCK = "catalogBody";
+export declare const PRODUCT_BODY_BLOCK = "productBody";
+/**
+ * Keys that are block identity rather than props, in the nested form.
+ *
+ * Exported for the same reason `blockInstanceId` is: it must be ONE rule.
+ * Whoever asks "where do this block's settings live" — the renderer here, the
+ * editor via `blockAtPath`, the overlay's settings/structure guard — has to get
+ * the same answer, or an edit an editor accepts is one the renderer ignores.
+ */
+export declare const BLOCK_STRUCTURAL_KEYS: ReadonlySet<string>;
+/**
+ * Does this entry keep its settings under `props` (nested form) or inline on
+ * the entry itself (flat form)?
+ *
+ * Both forms are first-class and they MIX inside one array — artorious's home
+ * page is 3 nested and 5 flat — so nothing may assume the shape from the path
+ * it took to get here.
+ */
+export declare function isNestedBlockRef(entry: unknown): boolean;
+/**
+ * The id a block instance is known by: the authored `id`, or `<type>-<index>`
+ * when it has none.
+ *
+ * Exported because it must be ONE rule. A block with no authored id still
+ * reaches the outside world under its synthesized id — `renderStore` reports
+ * it, an editor targets it, a generated diff names it — so `applyChange` has
+ * to resolve `blocks[#banner-0]` to the same entry the renderer called
+ * `banner-0`. Two implementations of this rule would make the id an agent is
+ * handed by one ability unusable by another.
+ */
+export declare function blockInstanceId(entry: unknown, index: number): string;
+/** Normalize an authored block list into the block tree the renderer consumes. */
+export declare function toBlockNodes(blocks: readonly StorefrontBlockLike[]): BlockNode[];
+/**
+ * The default tree for a page kind — what the SDK renders when a store has not
+ * composed the page. For catalog and product that is the native body alone,
+ * which is why adopting `pages` is a no-op until a store adds something.
+ */
+export declare function defaultPageBlocks(kind: StorefrontPageKind): BlockNode[];
+export interface PageBlockDiagnostic {
+    level: 'error' | 'warning';
+    rule: string;
+    detail: string;
+}
+/**
+ * Diagnostics for one composed page.
+ *
+ * These are reported, not enforced. A store in production must not go blank
+ * because a block was placed on a page its author did not anticipate — so the
+ * hard stop belongs in the editor (which reads the same `enabledOn` through
+ * `describeBlocks`), and this is the development-time equivalent.
+ */
+export declare function checkPageBlocks(kind: StorefrontPageKind, nodes: readonly BlockNode[]): PageBlockDiagnostic[];
+//# sourceMappingURL=page-blocks.d.ts.map

package/dist/blocks/page-blocks.d.ts.map

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

package/dist/blocks/page-data.d.ts

@@ -0,0 +1,105 @@
+import React from 'react';
+import type { BlockDataNeed, BlockNode } from '@fayz-ai/core';
+export type PageDataStatus = 'idle' | 'loading' | 'ready' | 'error';
+export interface PageDataEntry {
+    status: 'loading' | 'ready' | 'error';
+    data?: unknown;
+    error?: string;
+}
+/** One collected, binding-resolved, deduped need. */
+export interface PageDataNeed {
+    key: string;
+    loader: string;
+    params: Record<string, unknown>;
+}
+/**
+ * Resolve a declared need's param bindings against the page's route params and
+ * the declaring block's props (setting defaults filled in, so the declaration
+ * and the rendered block agree on unset props). A binding that resolves to
+ * `undefined` drops its param — dataNeedKey drops undefined anyway, so the
+ * declared need and a hook asking with explicit `undefined`s share a key.
+ */
+export declare function resolveDataParams(need: BlockDataNeed, context: {
+    params: Record<string, string>;
+    props: Record<string, unknown>;
+}): Record<string, unknown>;
+/**
+ * Walk a block tree (children included) and collect every declared need,
+ * bindings resolved, deduped by canonical (loader, params) key.
+ */
+export declare function collectDataNeeds(nodes: readonly BlockNode[], routeParams?: Record<string, string>): PageDataNeed[];
+/** Resolve ONE need through the provider port. Never throws: an unknown
+ *  loader or a failing read becomes an 'error' entry for that need alone. */
+export declare function resolvePageDataNeed(need: Pick<PageDataNeed, 'loader' | 'params'>): Promise<PageDataEntry>;
+/** Resolve a set of needs concurrently, isolated per need. Test seam and the
+ *  future server-side entry point — the scope component uses the same calls. */
+export declare function resolvePageData(needs: readonly PageDataNeed[]): Promise<Record<string, PageDataEntry>>;
+export interface PageDataScopeProps {
+    nodes: readonly BlockNode[];
+    /** Route params the tree's `$param` bindings resolve against. */
+    params?: Record<string, string>;
+    /**
+     * Pre-resolved entries, keyed by dataNeedKey — the server-side/static-render
+     * seam (L4): `resolvePageData(collectDataNeeds(nodes))` ahead of render,
+     * then hand the results in. Keys already 'ready' here are never re-fetched;
+     * anything missing resolves client-side as usual.
+     */
+    initial?: Record<string, PageDataEntry>;
+    children: React.ReactNode;
+}
+/**
+ * Collects and resolves the data needs of one block tree, and provides the
+ * results. Scopes nest (a slot inside a page): a child scope reuses every
+ * entry an ancestor already resolved and only fetches its own remainder, so
+ * dedupe holds across the whole rendered page, not per tree.
+ */
+export declare function PageDataScope({ nodes, params, initial, children }: PageDataScopeProps): React.JSX.Element;
+export interface UseLoaderResult<T> {
+    status: PageDataStatus;
+    data: T | null;
+    error: string | null;
+    /** Re-run the read (bypasses the page-resolved entry from then on). */
+    reload: () => void;
+}
+/**
+ * A block's (or page's) read: `useLoader('products.list', { filter, limit })`.
+ *
+ * When a PageDataScope above already resolved the same (loader, params) pair —
+ * because this block, or ANY block on the page, declared it — the resolved
+ * entry is returned and no request is made. Otherwise the hook resolves the
+ * loader itself, through the same provider port, so a component used outside a
+ * composed page (a store's hand-written route) keeps working identically.
+ * Pass `null` params to disable the read.
+ */
+export declare function useLoader<T>(loader: string, params: Record<string, unknown> | null): UseLoaderResult<T>;
+/**
+ * A BLOCK's named data need: `useBlockData(node, 'products', fallback)`.
+ *
+ * Reads the block's effective declaration — meta `data` with the document
+ * instance's `data` merged over it — and resolves its bindings with the SAME
+ * inputs the page resolver used (scope route params, node props over setting
+ * defaults), so the two always compute the same key. That is what makes a
+ * document able to rebind a param (`category: { $param: 'slug' }`) and have
+ * the rendered block follow: the block asks for its declared need, not for a
+ * hardcoded one.
+ *
+ * `fallback` covers the component being used directly as JSX (a store's
+ * hand-written route), where there is no node and no declaration to read.
+ */
+export declare function useBlockData<T>(node: BlockNode | undefined, name: string, fallback: {
+    loader: string;
+    params: Record<string, unknown>;
+}): UseLoaderResult<T> & {
+    loader: string;
+};
+/**
+ * What a block renders when its declared data failed: nothing for shoppers, a
+ * visible card for builders — the same visibility rule as a crashed block
+ * (M2's per-block error boundary, WooCommerce's `CURRENT_USER_IS_ADMIN ?
+ * onError : () => null`).
+ */
+export declare function BlockDataError({ loader, message }: {
+    loader: string;
+    message?: string | null;
+}): React.JSX.Element | null;
+//# sourceMappingURL=page-data.d.ts.map

package/dist/blocks/page-data.d.ts.map

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

package/dist/{blocks.d.ts → blocks/registry.d.ts}

@@ -3,4 +3,4 @@ import type { StorefrontSection } from './sections';
 export declare function registerStorefrontBlocks(): void;
 /** Convert the typed storefront section blueprint into a generic block tree. */
 export declare function sectionsToBlocks(sections: readonly StorefrontSection[]): BlockNode[];
-//# sourceMappingURL=blocks.d.ts.map
+//# sourceMappingURL=registry.d.ts.map

package/dist/blocks/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/blocks/registry.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAkEnD,wBAAgB,wBAAwB,IAAI,IAAI,CA4C/C;AAKD,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,GAAG,SAAS,EAAE,CAKpF"}

package/dist/{sections.d.ts → blocks/sections.d.ts}

@@ -1,4 +1,5 @@
-import type { HeroVariant } from './theme';
+import type { HeroVariant } from '../lib/theme';
+import type { StorefrontBlockLike } from './page-blocks';
 import type React from 'react';
 export interface HeroSlide {
     title: string;
@@ -93,7 +94,20 @@ export type StorefrontSection = {
 /** @deprecated Use StorefrontSection. Kept for existing generated stores. */
 export type HomeSection = StorefrontSection;
 export interface HomeConfig {
-    sections: readonly StorefrontSection[];
+    /**
+     * Accepts an app's own registered block, not just the SDK's typed sections.
+     *
+     * `home` and `pages.home` are the same page written two ways, and
+     * `pages.home.blocks` has taken `StorefrontBlockLike` since the page-tree
+     * work — so the short form five of seven live stores actually write was the
+     * one that still could not name a block the union has never heard of. That
+     * asymmetry is what forced `sections: mySections as never`, which throws away
+     * type checking on the whole array to place one custom block.
+     *
+     * The typed union is still first in the union, so a bad `variant` on an SDK
+     * section remains a type error.
+     */
+    sections: readonly StorefrontBlockLike[];
 }
 export interface NavLink {
     label: string;
@@ -124,4 +138,28 @@ export interface FooterConfig {
 }
 /** Wide gradient SVG data-URI — deterministic hero/banner art, no network. */
 export declare function bannerPlaceholder(label: string, hueA: number, hueB: number, w?: number, h?: number): string;
+/**
+ * The aspect ratios the SDK's layouts are built around. A replacement image
+ * that honours these drops in; one that does not will letterbox or crop.
+ *
+ *   product   3:4 portrait   (cards, gallery)   750 × 1000
+ *   banner   ~21:9 wide      (promo strips)    1600 ×  700
+ *   category  4:5 portrait   (showcase tiles)   480 ×  600
+ *
+ * `product` is 3:4 because that is what ProductCard's `imageAspect: 'portrait'`
+ * actually renders (`aspect-[3/4]`). Amboras's placeholder README prescribes
+ * "3:4 portrait (800x1000px)" — 800 × 1000 is 4:5, so following their pixels
+ * would letterbox every card by 5%. Ratios are worth copying; arithmetic is
+ * worth checking.
+ */
+export declare const PLACEHOLDER_ASPECTS: {
+    readonly product: readonly [750, 1000];
+    readonly banner: readonly [1600, 700];
+    readonly category: readonly [480, 600];
+};
+/**
+ * Portrait product placeholder as an SVG data-URI — deterministic per product
+ * name, no network. Defaults to the prescribed 3:4.
+ */
+export declare function productPlaceholder(label: string, w?: number, h?: number): string;
 //# sourceMappingURL=sections.d.ts.map

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

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