@kotao/storefront 0.2.0

package/dist/shop-DkQmro-Y.d.ts

@@ -0,0 +1,202 @@
+import { C as CartFormAction } from './types-Df3bGbKU.js';
+import { ReactNode } from 'react';
+
+interface CartFormProps {
+    readonly action: CartFormAction;
+}
+interface CartFormInputResult {
+    readonly action: CartFormAction | null;
+    readonly inputs: Record<string, any>;
+}
+declare function getCartFormInput(formData: FormData): CartFormInputResult;
+/**
+ * Lightweight CartForm surface marker for Hydrogen-style imports. React render integration can wrap
+ * this constant surface; the load-bearing API today is the stable ACTIONS contract used by handlers.
+ */
+declare const CartForm: ((_props: CartFormProps) => null) & {
+    ACTIONS: Readonly<{
+        readonly LinesAdd: "LinesAdd";
+        readonly LinesUpdate: "LinesUpdate";
+        readonly LinesRemove: "LinesRemove";
+        readonly DiscountCodesUpdate: "DiscountCodesUpdate";
+        readonly GiftCardCodesAdd: "GiftCardCodesAdd";
+        readonly GiftCardCodesRemove: "GiftCardCodesRemove";
+        readonly BuyerIdentityUpdate: "BuyerIdentityUpdate";
+        readonly NoteUpdate: "NoteUpdate";
+        readonly AttributesUpdate: "AttributesUpdate";
+        readonly MetafieldsSet: "MetafieldsSet";
+        readonly MetafieldsDelete: "MetafieldsDelete";
+        readonly DeliveryAddressesReplace: "DeliveryAddressesReplace";
+        readonly SelectedDeliveryOptionsUpdate: "SelectedDeliveryOptionsUpdate";
+    }>;
+    getFormInput: typeof getCartFormInput;
+};
+
+/**
+ * Legacy consent state. The visible Storefront consent UI is disabled until the replacement flow ships,
+ * so runtime analytics treats every bucket as effectively granted and ignores stale consent cookies.
+ */
+type ConsentBucket = 'analytics' | 'marketing' | 'preferences';
+type ConsentState = Readonly<Record<ConsentBucket, boolean>>;
+declare const CONSENT_BUCKETS: readonly ConsentBucket[];
+declare const DENIED_CONSENT: ConsentState;
+declare const GRANTED_CONSENT: ConsentState;
+declare const CONSENT_COOKIE = "kotao_consent";
+declare function isGranted(state: ConsentState, bucket: ConsentBucket): boolean;
+declare function mergeConsent(state: ConsentState, patch: Partial<ConsentState>): ConsentState;
+declare function serializeConsent(state: ConsentState): string;
+declare function parseConsent(value: string | null | undefined): ConsentState;
+/** The `document.cookie` string to persist consent (Secure, SameSite=Lax, Path=/, ~180d). */
+declare function buildConsentCookie(state: ConsentState): string;
+/** Read the consent cookie out of a `document.cookie`-style string. */
+declare function readConsentCookie(cookieHeader: string | null | undefined): ConsentState;
+
+type BoundNonceProvider = (props: {
+    readonly children?: ReactNode;
+}) => ReactNode;
+/** Hydrogen-compatible nonce hook. */
+declare function useNonce(): string | undefined;
+
+/**
+ * Coarse visitor geo attached to pixel events — structurally the SDK's `context.geo` (a `Geo` value is
+ * assignable here). Declared locally so the analytics surface (and its DOM/React preset) need not pull
+ * in the geo crypto module.
+ */
+interface AnalyticsGeo {
+    readonly country: string | null;
+    readonly city: string | null;
+    readonly colo: string | null;
+    readonly botScore: number | null;
+    readonly clientIp: string | null;
+}
+/** The standard storefront analytics events (Hydrogen-shaped names). */
+declare const ANALYTICS_EVENTS: {
+    readonly pageViewed: "page_viewed";
+    readonly productViewed: "product_viewed";
+    readonly collectionViewed: "collection_viewed";
+    readonly cartViewed: "cart_viewed";
+    readonly searchViewed: "search_viewed";
+    readonly productAddedToCart: "product_added_to_cart";
+};
+type AnalyticsEventName = (typeof ANALYTICS_EVENTS)[keyof typeof ANALYTICS_EVENTS];
+/** Ambient context the provider attaches to every event before it reaches the pixel. */
+interface AnalyticsContext {
+    readonly shopId?: string;
+    readonly url?: string;
+    readonly geo?: AnalyticsGeo;
+}
+interface PageViewedPayload {
+    readonly title?: string;
+}
+interface ProductViewedPayload {
+    readonly productId: string;
+    readonly handle?: string;
+}
+interface CollectionViewedPayload {
+    readonly collectionId: string;
+    readonly handle?: string;
+}
+interface CartViewedPayload {
+    readonly cartId?: string;
+}
+interface SearchViewedPayload {
+    readonly query: string;
+    readonly resultCount?: number;
+}
+interface ProductAddedToCartPayload {
+    readonly productId: string;
+    readonly variantId: string;
+    readonly quantity: number;
+}
+/** Event name → payload (the typed pub/sub surface). */
+interface AnalyticsEventMap {
+    page_viewed: PageViewedPayload;
+    product_viewed: ProductViewedPayload;
+    collection_viewed: CollectionViewedPayload;
+    cart_viewed: CartViewedPayload;
+    search_viewed: SearchViewedPayload;
+    product_added_to_cart: ProductAddedToCartPayload;
+}
+/** A pixel-bound event: the name, its payload, the ambient context, a timestamp, and consent state. */
+interface PixelEvent<E extends AnalyticsEventName = AnalyticsEventName> {
+    readonly event: E;
+    readonly payload: AnalyticsEventMap[E];
+    readonly context: AnalyticsContext;
+    readonly timestamp: string;
+    /** Whether the analytics-consent bucket was granted when this event was recorded. */
+    readonly consent: boolean;
+}
+
+type EventHandler<E extends AnalyticsEventName> = (payload: AnalyticsEventMap[E]) => void;
+/** A framework-agnostic typed pub/sub bus (Hydrogen `useAnalytics` shape, minus React). */
+interface AnalyticsEmitter {
+    subscribe<E extends AnalyticsEventName>(event: E, handler: EventHandler<E>): () => void;
+    publish<E extends AnalyticsEventName>(event: E, payload: AnalyticsEventMap[E]): void;
+}
+declare function createAnalyticsEmitter(): AnalyticsEmitter;
+
+/** The actual network send. Injectable so tests don't touch the network. */
+type PixelSend = (endpoint: string, body: string) => void;
+interface PixelTransportOptions {
+    /** Same-origin carve-out endpoint (default '/api/storefront/pixel') — never cross-origin. */
+    readonly endpoint?: string;
+    readonly batchSize?: number;
+    /**
+     * The actual network send. Required + injected: the browser sender (`sendBeacon`/keepalive `fetch`)
+     * is DOM-specific and lives in the React layer, keeping this batching core framework-agnostic and
+     * unit-testable with a spy. The provider wires the real sender.
+     */
+    readonly send: PixelSend;
+}
+interface PixelTransport {
+    record(event: PixelEvent): void;
+    flush(): void;
+}
+/**
+ * Batches pixel events and POSTs them to the same-origin carve-out. Flushes on `batchSize` or an
+ * explicit `flush()` (the provider flushes on page-hide). The endpoint is same-origin so themes need
+ * no CORS and no token is exposed in the browser.
+ */
+declare function createPixelTransport(options: PixelTransportOptions): PixelTransport;
+
+interface AnalyticsBusOptions {
+    readonly transport: PixelTransport;
+    /** Legacy consent seam retained for API compatibility while Storefront consent UI is disabled. */
+    readonly getConsent: () => ConsentState;
+    /** Ambient context (shopId, geo, url) attached to each pixel event. */
+    readonly getContext?: () => AnalyticsContext;
+    /** Clock seam for deterministic timestamps in tests. */
+    readonly now?: () => string;
+}
+interface AnalyticsBus {
+    readonly emitter: AnalyticsEmitter;
+    publish<E extends AnalyticsEventName>(event: E, payload: AnalyticsEventMap[E]): void;
+    flush(): void;
+}
+/**
+ * Wire the emitter to the pixel. Every published event reaches theme subscribers (via the emitter) and
+ * is also recorded to the pixel. Consent gating is temporarily disabled with the UI; the consent seam
+ * remains so a proper replacement can reinstate the policy without changing theme APIs.
+ */
+declare function createAnalyticsBus(options: AnalyticsBusOptions): AnalyticsBus;
+
+interface ShopAnalytics {
+    readonly acceptedLanguage?: string;
+    readonly currency?: string;
+    readonly shopId?: string;
+    readonly storefrontId?: string;
+}
+interface GetShopAnalyticsOptions {
+    readonly publicStorefrontId?: string;
+    readonly storefront?: {
+        readonly i18n?: {
+            readonly country?: string | null;
+            readonly currency?: string | null;
+            readonly language?: string | null;
+            readonly pathPrefix?: string | null;
+        } | null;
+    } | null;
+}
+declare function getShopAnalytics(options: GetShopAnalyticsOptions): ShopAnalytics;
+
+export { ANALYTICS_EVENTS as A, type BoundNonceProvider as B, type ConsentBucket as C, DENIED_CONSENT as D, type EventHandler as E, getShopAnalytics as F, GRANTED_CONSENT as G, isGranted as H, mergeConsent as I, parseConsent as J, readConsentCookie as K, serializeConsent as L, getCartFormInput as M, useNonce as N, type PageViewedPayload as P, type SearchViewedPayload as S, type ConsentState as a, type AnalyticsBus as b, type AnalyticsBusOptions as c, type AnalyticsContext as d, type AnalyticsEmitter as e, type AnalyticsEventMap as f, type AnalyticsEventName as g, type AnalyticsGeo as h, CONSENT_BUCKETS as i, CONSENT_COOKIE as j, CartForm as k, type CartFormProps as l, type CartViewedPayload as m, type CollectionViewedPayload as n, type GetShopAnalyticsOptions as o, type PixelEvent as p, type PixelSend as q, type PixelTransport as r, type PixelTransportOptions as s, type ProductAddedToCartPayload as t, type ProductViewedPayload as u, type ShopAnalytics as v, buildConsentCookie as w, createAnalyticsBus as x, createAnalyticsEmitter as y, createPixelTransport as z };

package/dist/store-DQK1nhob.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Resolved (merged) settings shapes. Deliberately free of any `@kotao/storefront-contracts` import so the
+ * React layer (typechecked under the DOM lib) can consume them without pulling the contracts' Worker-crypto
+ * (`shop-context.ts`) into a DOM typecheck — the same decoupling the analytics `AnalyticsGeo` type uses.
+ * The merge engine (merge.ts), which DOES consume contracts types, lives in the Worker-core typecheck.
+ */
+type ResolvedSettings = Record<string, unknown>;
+interface ResolvedBlock {
+    readonly id?: string;
+    readonly type: string;
+    readonly settings: ResolvedSettings;
+}
+interface ResolvedSection {
+    readonly id: string;
+    readonly type: string;
+    readonly settings: ResolvedSettings;
+    readonly blocks: readonly ResolvedBlock[];
+}
+interface ResolvedValuesDocument {
+    readonly shopId: string;
+    readonly sections: readonly ResolvedSection[];
+}
+/** The fully-merged settings a theme renders from: ordered sections + global theme tokens. */
+interface ThemeSettingsSnapshot {
+    readonly sections: readonly ResolvedSection[];
+    readonly global: ResolvedSettings;
+    readonly templates?: Readonly<Record<string, ResolvedValuesDocument>>;
+    readonly sectionGroups?: Readonly<Record<string, ResolvedValuesDocument>>;
+}
+
+/**
+ * Framework-agnostic theme-settings store (#93). Holds the merged {@link ThemeSettingsSnapshot} and lets
+ * subscribers react to live edits. In plain runtime the snapshot is the stable server-provided value and
+ * never changes; in the visual editor, postMessage-driven setting patches call `patchSection`/`patchGlobal`
+ * so the React binding (useSyncExternalStore) re-renders without a reload. `getSnapshot` returns a stable
+ * reference between patches (a new one only on change), as useSyncExternalStore requires.
+ */
+
+interface ThemeSettingsStore {
+    getSnapshot(): ThemeSettingsSnapshot;
+    subscribe(listener: () => void): () => void;
+    /** Replace a section instance's resolved settings (editor live-patch); no-op if the id is unknown. */
+    patchSection(instanceId: string, settings: ResolvedSettings): void;
+    /** Insert a fully-resolved section instance (editor live-add); reserved ids are ignored. */
+    insertSection(section: ResolvedSection, index?: number): void;
+    /** Remove one section instance (editor live-delete); no-op if unknown. */
+    removeSection(instanceId: string): void;
+    /** Move one section instance to a new position (editor live-reorder); no-op if unknown. */
+    moveSection(instanceId: string, index: number): void;
+    /** Replace the global theme tokens (editor live-patch). */
+    patchGlobal(settings: ResolvedSettings): void;
+    /** Replace a block instance's resolved settings; no-op if section/block is unknown. */
+    patchBlock(sectionId: string, blockId: string, settings: ResolvedSettings): void;
+    /** Insert a fully-resolved block instance into a section. */
+    insertBlock(sectionId: string, block: ResolvedBlock, index?: number): void;
+    /** Remove one block instance from a section. */
+    removeBlock(sectionId: string, blockId: string): void;
+    /** Move one block instance to a new position inside a section. */
+    moveBlock(sectionId: string, blockId: string, index: number): void;
+    /** Replace all preview sections from a template values document. */
+    replaceSections(sections: readonly ResolvedSection[]): void;
+    /** Replace one layout section group document, such as header or footer. */
+    replaceSectionGroup(handle: string, document: ResolvedValuesDocument): void;
+}
+declare function createThemeSettingsStore(initial: ThemeSettingsSnapshot): ThemeSettingsStore;
+
+export { type ResolvedBlock as R, type ThemeSettingsSnapshot as T, type ResolvedSection as a, type ResolvedSettings as b, type ThemeSettingsStore as c, createThemeSettingsStore as d };

package/dist/storefront-api-types.d.ts

@@ -0,0 +1,312 @@
+type Maybe<T> = T | null;
+type InputMaybe<T> = Maybe<T>;
+type Exact<T extends Record<string, unknown>> = {
+    [K in keyof T]: T[K];
+};
+interface Scalars {
+    readonly ID: {
+        readonly input: string;
+        readonly output: string;
+    };
+    readonly String: {
+        readonly input: string;
+        readonly output: string;
+    };
+    readonly Boolean: {
+        readonly input: boolean;
+        readonly output: boolean;
+    };
+    readonly Int: {
+        readonly input: number;
+        readonly output: number;
+    };
+    readonly Float: {
+        readonly input: number;
+        readonly output: number;
+    };
+    readonly Decimal: {
+        readonly input: string;
+        readonly output: string;
+    };
+    readonly DateTime: {
+        readonly input: string;
+        readonly output: string;
+    };
+    readonly HTML: {
+        readonly input: string;
+        readonly output: string;
+    };
+    readonly URL: {
+        readonly input: string;
+        readonly output: string;
+    };
+    readonly [key: string]: {
+        readonly input: any;
+        readonly output: any;
+    };
+}
+interface LooseObject {
+    [key: string]: any;
+}
+type CountryCode = string;
+type CurrencyCode = string;
+type LanguageCode = string;
+type ProductCollectionSortKeys = string;
+type ProductSortKeys = string;
+interface Seo extends LooseObject {
+    readonly description: string | null;
+    readonly title?: string | null;
+}
+interface Image extends LooseObject {
+    readonly altText?: string | null;
+    readonly height?: number | null;
+    readonly id?: string;
+    readonly url: string;
+    readonly width?: number | null;
+}
+interface MoneyV2 extends LooseObject {
+    readonly amount: string;
+    readonly currencyCode: CurrencyCode;
+}
+interface Domain extends LooseObject {
+    readonly url: string;
+}
+interface Metafield extends LooseObject {
+    readonly key: string;
+    readonly namespace: string;
+    readonly value: string;
+}
+interface ArticleAuthor extends LooseObject {
+    readonly name?: string | null;
+}
+interface Article extends LooseObject {
+    readonly author?: ArticleAuthor | null;
+    readonly contentHtml?: string;
+    readonly excerpt?: string | null;
+    readonly handle: string;
+    readonly id: string;
+    readonly image?: Image | null;
+    readonly publishedAt: string;
+    readonly seo?: Seo | null;
+    readonly title: string;
+}
+interface Blog extends LooseObject {
+    readonly handle: string;
+    readonly id: string;
+    readonly seo?: Seo | null;
+    readonly title: string;
+}
+interface Collection extends LooseObject {
+    readonly description: string;
+    readonly descriptionHtml?: string | null;
+    readonly handle: string;
+    readonly id: string;
+    readonly image?: Image | null;
+    readonly seo?: Seo | null;
+    readonly title: string;
+    readonly updatedAt?: string | null;
+}
+interface Page extends LooseObject {
+    readonly body?: string | null;
+    readonly bodySummary?: string | null;
+    readonly handle: string;
+    readonly id: string;
+    readonly seo?: Seo | null;
+    readonly title: string;
+}
+interface ExternalVideo extends LooseObject {
+    readonly alt?: string | null;
+    readonly embedUrl: string;
+    readonly host: string;
+    readonly id: string;
+    readonly mediaContentType: string;
+    readonly previewImage?: Image | null;
+}
+interface MediaImage extends LooseObject {
+    readonly alt?: string | null;
+    readonly id: string;
+    readonly image?: Image | null;
+    readonly mediaContentType: string;
+    readonly previewImage?: Image | null;
+}
+interface Model3dSource extends LooseObject {
+    readonly mimeType: string;
+    readonly url: string;
+}
+interface Model3d extends LooseObject {
+    readonly alt?: string | null;
+    readonly id: string;
+    readonly mediaContentType: string;
+    readonly previewImage?: Image | null;
+    readonly sources: readonly Model3dSource[];
+}
+interface VideoSource extends LooseObject {
+    readonly mimeType: string;
+    readonly url: string;
+}
+interface Video extends LooseObject {
+    readonly alt?: string | null;
+    readonly id: string;
+    readonly mediaContentType: string;
+    readonly previewImage?: Image | null;
+    readonly sources: readonly VideoSource[];
+}
+type Media = ExternalVideo | MediaImage | Model3d | Video;
+interface MenuItem extends LooseObject {
+    readonly id: string;
+    readonly items?: readonly MenuItem[];
+    readonly resourceId?: string | null;
+    readonly tags?: readonly string[];
+    readonly title: string;
+    readonly type?: string;
+    readonly url?: string | null;
+}
+interface Menu extends LooseObject {
+    readonly id: string;
+    readonly items: readonly MenuItem[];
+}
+interface PageInfo extends LooseObject {
+    readonly endCursor?: string | null;
+    readonly hasNextPage: boolean;
+    readonly hasPreviousPage: boolean;
+    readonly startCursor?: string | null;
+}
+interface ProductOptionValueSwatch extends LooseObject {
+    readonly color?: string | null;
+    readonly image?: Image | null;
+}
+interface ProductOptionValue extends LooseObject {
+    readonly available?: boolean;
+    readonly firstSelectableVariant?: ProductVariant | null;
+    readonly isActive?: boolean;
+    readonly name?: string;
+    readonly swatch?: ProductOptionValueSwatch | null;
+}
+interface ProductOption extends LooseObject {
+    readonly name: string;
+    readonly optionValues?: ProductOptionValue[];
+    readonly values?: string[];
+}
+interface SelectedOption extends LooseObject {
+    readonly name: string;
+    readonly value: string;
+}
+interface SelectedOptionInput extends LooseObject {
+    readonly name: string;
+    readonly value: string;
+}
+interface ProductVariant extends LooseObject {
+    readonly availableForSale?: boolean | null;
+    readonly compareAtPrice?: MoneyV2 | null;
+    readonly id: string;
+    readonly image?: Image | null;
+    readonly price: MoneyV2;
+    readonly product: Pick<Product, 'id' | 'handle' | 'title'>;
+    readonly selectedOptions: SelectedOption[];
+    readonly sku?: string | null;
+    readonly title?: string;
+}
+interface Product extends LooseObject {
+    readonly availableForSale?: boolean;
+    readonly description: string;
+    readonly descriptionHtml?: string;
+    readonly featuredImage?: Image | null;
+    readonly handle: string;
+    readonly id: string;
+    readonly media?: {
+        readonly nodes?: Media[];
+    };
+    readonly options?: ProductOption[];
+    readonly publishedAt: string;
+    readonly priceRange?: {
+        readonly maxVariantPrice?: MoneyV2;
+        readonly minVariantPrice: MoneyV2;
+    };
+    readonly seo?: Seo | null;
+    readonly title: string;
+    readonly variants: {
+        readonly nodes: ProductVariant[];
+    };
+    readonly vendor: string;
+}
+interface FilterValue extends LooseObject {
+    readonly count?: number;
+    readonly id: string;
+    readonly input?: string;
+    readonly label: string;
+}
+interface Filter extends LooseObject {
+    readonly id: string;
+    readonly label: string;
+    readonly type?: string;
+    readonly values: readonly FilterValue[];
+}
+type ProductFilter = LooseObject;
+interface ShopPolicy extends LooseObject {
+    readonly body: string;
+    readonly handle: string;
+    readonly id: string;
+    readonly title: string;
+    readonly url?: string;
+}
+interface ShopPolicyWithDefault extends ShopPolicy {
+    readonly default?: boolean;
+}
+interface Shop extends LooseObject {
+    readonly brand?: LooseObject | null;
+    readonly description?: string | null;
+    readonly id: string;
+    readonly name: string;
+    readonly primaryDomain?: Domain;
+}
+interface OrderLineItem extends LooseObject {
+    readonly title: string;
+}
+interface Order extends LooseObject {
+    readonly financialStatus?: string | null;
+    readonly fulfillmentStatus?: string | null;
+    readonly id: string;
+    readonly orderNumber?: number;
+    readonly processedAt: string;
+}
+interface CartCost extends LooseObject {
+    readonly subtotalAmount?: MoneyV2;
+    readonly totalAmount?: MoneyV2;
+    readonly totalTaxAmount?: MoneyV2 | null;
+}
+interface CartLine extends LooseObject {
+    readonly id: string;
+    readonly merchandise?: ProductVariant;
+    readonly quantity: number;
+}
+interface CartLineUpdateInput extends LooseObject {
+    readonly id: string;
+    readonly merchandiseId?: string | null;
+    readonly quantity?: number | null;
+}
+interface CartBuyerIdentityInput extends LooseObject {
+    readonly countryCode?: CountryCode | null;
+    readonly customerAccessToken?: string | null;
+    readonly email?: string | null;
+    readonly phone?: string | null;
+}
+interface CartDiscountCode extends LooseObject {
+    readonly applicable?: boolean;
+    readonly code: string;
+}
+interface CartLineConnection extends LooseObject {
+    readonly edges?: {
+        readonly node: CartLine;
+    }[];
+    readonly nodes?: CartLine[];
+}
+interface Cart extends LooseObject {
+    readonly checkoutUrl: string;
+    readonly cost: CartCost;
+    readonly discountCodes?: readonly CartDiscountCode[];
+    readonly id: string;
+    readonly lines?: CartLineConnection;
+    readonly totalQuantity: number;
+}
+
+export type { Article, ArticleAuthor, Blog, Cart, CartBuyerIdentityInput, CartCost, CartDiscountCode, CartLine, CartLineConnection, CartLineUpdateInput, Collection, CountryCode, CurrencyCode, Domain, Exact, ExternalVideo, Filter, FilterValue, Image, InputMaybe, LanguageCode, Maybe, Media, MediaImage, Menu, MenuItem, Metafield, Model3d, Model3dSource, MoneyV2, Order, OrderLineItem, Page, PageInfo, Product, ProductCollectionSortKeys, ProductFilter, ProductOption, ProductOptionValue, ProductOptionValueSwatch, ProductSortKeys, ProductVariant, Scalars, SelectedOption, SelectedOptionInput, Seo, Shop, ShopPolicy, ShopPolicyWithDefault, Video, VideoSource };

package/dist/storefront-api-types.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=storefront-api-types.js.map
+//# sourceMappingURL=storefront-api-types.js.map

package/dist/storefront-api-types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"storefront-api-types.js"}

package/dist/types-BDhHWZsP.d.ts

@@ -0,0 +1,77 @@
+/**
+ * SEO surface types for `@kotao/storefront` (ADR-0003 §SDK), Hydrogen-shaped. Framework-agnostic:
+ * `getSeoMeta` emits a flat descriptor list a theme can return from a React Router 7 `meta` export or
+ * feed to the `<Seo/>` component.
+ */
+interface OpenGraphImage {
+    readonly url: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly alt?: string;
+}
+interface OpenGraph {
+    readonly title?: string;
+    readonly description?: string;
+    /** og:type, e.g. 'website' | 'article' | 'product'. Defaults to 'website' when OG tags are emitted. */
+    readonly type?: string;
+    readonly url?: string;
+    readonly siteName?: string;
+    readonly locale?: string;
+    readonly images?: readonly OpenGraphImage[];
+}
+interface TwitterCard {
+    readonly card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+    readonly site?: string;
+    readonly creator?: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly image?: string;
+}
+/** An hreflang alternate. Design-only hook (no multi-language data ships) — emitted only when supplied. */
+interface Alternate {
+    readonly hreflang: string;
+    readonly href: string;
+}
+/** A schema.org JSON-LD object (produced by the json-ld builders, or hand-authored). */
+type JsonLd = any;
+interface RobotsOptions {
+    readonly noIndex?: boolean;
+    readonly noFollow?: boolean;
+}
+/** SEO config merged across levels (root → route → leaf); deeper/later wins per field. */
+interface SeoConfig {
+    readonly [key: string]: unknown;
+    readonly title?: string | null;
+    /** Applied to the resolved title as `titleTemplate.replace('%s', title)`. Last level wins. */
+    readonly titleTemplate?: string;
+    readonly description?: string | null;
+    /** Absolute canonical URL. */
+    readonly canonical?: string | null;
+    readonly url?: string | null;
+    /** Robots directive, e.g. 'index,follow' or 'noindex,nofollow'. */
+    readonly robots?: string | RobotsOptions;
+    readonly openGraph?: OpenGraph;
+    readonly twitter?: TwitterCard;
+    readonly alternates?: readonly Alternate[];
+    /** schema.org JSON-LD object(s); accumulated (not overridden) across levels. */
+    readonly jsonLd?: JsonLd | readonly JsonLd[];
+}
+/** A head descriptor, shaped to be React Router 7 `meta`-export compatible. */
+type SeoDescriptor = {
+    readonly title: string;
+} | {
+    readonly name: string;
+    readonly content: string;
+} | {
+    readonly property: string;
+    readonly content: string;
+} | {
+    readonly tagName: 'link';
+    readonly rel: string;
+    readonly href: string;
+    readonly hrefLang?: string;
+} | {
+    readonly 'script:ld+json': JsonLd;
+};
+
+export type { Alternate as A, JsonLd as J, OpenGraph as O, SeoConfig as S, TwitterCard as T, OpenGraphImage as a, SeoDescriptor as b };