platform-types 1.10.687 → 1.10.689

package/dist/index.d.ts

@@ -79,6 +79,8 @@ export * from './storefrontTheme.ts';
 export * from './storeNetwork.ts';
 export * from './storefrontAssets.ts';
 export * from './storefrontEvent.ts';
+export * from './storefrontSeo.ts';
+export * from './storefrontWebLiteralKeys.ts';
 export * from './subscription.ts';
 export * from './support.ts';
 export * from './terminal.ts';

package/dist/index.js

@@ -87,6 +87,8 @@ export * from "./storefrontTheme.js";
 export * from "./storeNetwork.js";
 export * from "./storefrontAssets.js";
 export * from "./storefrontEvent.js";
+export * from "./storefrontSeo.js";
+export * from "./storefrontWebLiteralKeys.js";
 export * from "./subscription.js";
 export * from "./support.js";
 export * from "./terminal.js";

package/dist/storefrontAssets.d.ts

@@ -1,4 +1,26 @@
-export declare const STOREFRONT_ASSET_VARIANTS: readonly ["original", "200x200", "400x400", "800x800", "1200x1200", "1600x1600"];
+export declare const STOREFRONT_ASSET_VARIANTS: readonly ["original", "200x200", "400x400", "800x800", "1200x1200", "1600x1600", "1200x630", "192x192", "512x512"];
+/**
+ * How each variant is rendered from the stored original. `original` is the
+ * stored image unchanged in size. `inside` is a thumbnail: it fits inside the
+ * box keeping its aspect and never enlarges, so a small original comes back at
+ * its own size. `1200x630` is `cover`: an EXACT-size crop for share images
+ * (`og:image`), enlarged when the original is smaller. `192x192` and `512x512`
+ * are `contain`: EXACT-size icons (favicon, PWA manifest), not thumbnails —
+ * the whole original is scaled to fit and the rest of the square is padded
+ * transparent, so nothing is cropped; they are always PNG, or WebP when the
+ * client accepts it, because a JPEG cannot carry the transparent padding.
+ */
+export declare const STOREFRONT_ASSET_VARIANT_FIT: {
+    readonly original: "original";
+    readonly '200x200': "inside";
+    readonly '400x400': "inside";
+    readonly '800x800': "inside";
+    readonly '1200x1200': "inside";
+    readonly '1600x1600': "inside";
+    readonly '1200x630': "cover";
+    readonly '192x192': "contain";
+    readonly '512x512': "contain";
+};
 /** The active-asset cap, the same value as `STOREFRONT_DESIGN_LIMITS.activeImages` by construction. */
 export declare const MAX_STOREFRONT_ASSETS: 200;
 declare global {

package/dist/storefrontAssets.js

@@ -6,6 +6,31 @@ export const STOREFRONT_ASSET_VARIANTS = [
     '800x800',
     '1200x1200',
     '1600x1600',
+    '1200x630',
+    '192x192',
+    '512x512',
 ];
+/**
+ * How each variant is rendered from the stored original. `original` is the
+ * stored image unchanged in size. `inside` is a thumbnail: it fits inside the
+ * box keeping its aspect and never enlarges, so a small original comes back at
+ * its own size. `1200x630` is `cover`: an EXACT-size crop for share images
+ * (`og:image`), enlarged when the original is smaller. `192x192` and `512x512`
+ * are `contain`: EXACT-size icons (favicon, PWA manifest), not thumbnails —
+ * the whole original is scaled to fit and the rest of the square is padded
+ * transparent, so nothing is cropped; they are always PNG, or WebP when the
+ * client accepts it, because a JPEG cannot carry the transparent padding.
+ */
+export const STOREFRONT_ASSET_VARIANT_FIT = {
+    original: 'original',
+    '200x200': 'inside',
+    '400x400': 'inside',
+    '800x800': 'inside',
+    '1200x1200': 'inside',
+    '1600x1600': 'inside',
+    '1200x630': 'cover',
+    '192x192': 'contain',
+    '512x512': 'contain',
+};
 /** The active-asset cap, the same value as `STOREFRONT_DESIGN_LIMITS.activeImages` by construction. */
 export const MAX_STOREFRONT_ASSETS = STOREFRONT_DESIGN_LIMITS.activeImages;

package/dist/storefrontDesign.d.ts

@@ -1,6 +1,17 @@
 import type { StorefrontThemeWarning } from './storefrontTheme.ts';
+/** The social kinds a contact may link, each to its own hosts; a contact links at most one per kind. */
+export declare const STOREFRONT_SOCIAL_HOSTS: {
+    readonly instagram: readonly ["instagram.com", "www.instagram.com"];
+    readonly facebook: readonly ["facebook.com", "www.facebook.com"];
+    readonly youtube: readonly ["youtube.com", "www.youtube.com", "youtu.be", "www.youtu.be"];
+    readonly tiktok: readonly ["tiktok.com", "www.tiktok.com"];
+    readonly linkedin: readonly ["linkedin.com", "www.linkedin.com"];
+    readonly x: readonly ["x.com", "www.x.com"];
+};
 export declare const STOREFRONT_DESIGN_LIMITS: {
     readonly customPages: 20;
+    readonly pageAliases: 20;
+    readonly pageAliasMetadataBytes: number;
     readonly sectionsPerPage: 10;
     readonly productCountMin: 4;
     readonly productCountMax: 24;
@@ -35,9 +46,17 @@ export declare const STOREFRONT_DESIGN_LIMITS: {
     readonly contactAddress: 500;
     readonly contactNote: 200;
     readonly contactHours: 14;
-    readonly contactSocials: 8;
+    /** One link per social kind, so the cap is the number of kinds. */
+    readonly contactSocials: number;
     readonly contactEmail: 254;
 };
+/**
+ * A custom page's slug: lowercase ASCII letters, digits and inner hyphens, 1 to
+ * `STOREFRONT_DESIGN_LIMITS.slug` characters, starting and ending alphanumeric. The one
+ * definition: the api's validators, its page renderer and the edge viewer request read it.
+ */
+export declare const STOREFRONT_PAGE_SLUG_RE: RegExp;
+export declare const isStorefrontPageSlug: (value: unknown) => value is string;
 export declare const STOREFRONT_SECTION_TYPES: readonly ["banner", "imageText", "products", "categories", "brands", "text", "faq", "benefits", "contact", "paymentDelivery"];
 export declare const STOREFRONT_BUILTIN_DESTINATIONS: readonly ["home", "catalogue", "offers", "new", "search", "cart", "account", "privacy"];
 /**
@@ -53,14 +72,6 @@ export declare const STOREFRONT_PROTECTED_BUILTIN_DESTINATIONS: readonly ["searc
 export declare const STOREFRONT_CONTACT_FIELDS: readonly ["email", "phone", "whatsapp", "address", "hours", "socials"];
 export declare const STOREFRONT_RESERVED_SLUGS: readonly ["home", "index", "api", "auth", "login", "logout", "account", "cart", "checkout", "orders", "search", "products", "product", "producto", "coleccion", "categories", "brands", "sale", "new", "privacy", "terms", "sitemap", "robots", "manifest", "assets", "preview", "admin", "storefront", "pagina", "basket", "profile", "favorites", "invoices", "payments", "payment-methods", "user", "mantenimiento"];
 export declare const STOREFRONT_BENEFIT_ICONS: readonly ["truck", "shield", "credit-card", "store", "heart", "check"];
-export declare const STOREFRONT_SOCIAL_HOSTS: {
-    readonly instagram: readonly ["instagram.com", "www.instagram.com"];
-    readonly facebook: readonly ["facebook.com", "www.facebook.com"];
-    readonly youtube: readonly ["youtube.com", "www.youtube.com", "youtu.be", "www.youtu.be"];
-    readonly tiktok: readonly ["tiktok.com", "www.tiktok.com"];
-    readonly linkedin: readonly ["linkedin.com", "www.linkedin.com"];
-    readonly x: readonly ["x.com", "www.x.com"];
-};
 export declare function createStorefrontDesignV1(): StorefrontDesignV1;
 declare global {
     type StorefrontDesignSectionType = (typeof STOREFRONT_SECTION_TYPES)[number];
@@ -180,7 +191,12 @@ declare global {
             content: StorefrontDesignSectionContent[K];
         };
     }[StorefrontDesignSectionType];
+    interface StorefrontDesignPublicationMetadata {
+        pageAliases: Record<string, string[]>;
+        pageSlugs: Record<string, string>;
+    }
     interface StorefrontDesignSeo {
+        noindex?: boolean;
         title?: string;
         description?: string;
         image?: StorefrontDesignImagePlacement;
@@ -213,6 +229,7 @@ declare global {
         links: StorefrontDesignMenuLink[];
     }
     interface StorefrontContactHours {
+        /** `days` are ISO 8601 weekdays, 1 = Monday … 7 = Sunday (unique per row); `opens` is before `closes`. */
         rows: {
             days: number[];
             opens: string;
@@ -264,7 +281,7 @@ declare global {
     };
     /**
      * Image placements gain `url`/`mobileUrl`: the variant-LESS base
-     * `/sf-media/{stage}/{storeId}/{publicationId}/{assetId}`, a path on the images host. Append
+     * `/media/{stage}/{storeId}/{publicationId}/{assetId}`, a path on the images host. Append
      * `/${StorefrontAssetVariant}` (one of `STOREFRONT_ASSET_VARIANTS`) to request it; the base
      * alone is not servable. Never route it through `/fit-in/`: the media path is refused there.
      * Private preview envelopes instead supply `/preview/read?operation=asset&assetId=...`; the
@@ -310,7 +327,8 @@ declare global {
         seo: StorefrontDesignSeo;
         literalOverrides: Record<string, string>;
     }
-    type StorefrontDesignFieldErrorCode = 'INVALID' | 'REQUIRED' | 'UNKNOWN_KEY' | 'DUPLICATE' | 'RESERVED_SLUG' | 'DANGLING_REFERENCE' | 'MAPPING_CONFLICT' | 'TOO_LARGE';
+    /** `TOO_LARGE` at path `''` means the whole stored draft would exceed its row budget, not one field. */
+    type StorefrontDesignFieldErrorCode = 'INVALID' | 'REQUIRED' | 'UNKNOWN_KEY' | 'DUPLICATE' | 'RESERVED_SLUG' | 'ALIAS_CONFLICT' | 'ALIAS_LIMIT' | 'DANGLING_REFERENCE' | 'MAPPING_CONFLICT' | 'TOO_LARGE';
     interface StorefrontDesignFieldError {
         path: string;
         code: StorefrontDesignFieldErrorCode;
@@ -359,6 +377,10 @@ declare global {
     interface StorefrontDesignPreviewInput {
         draftRevision: string;
     }
+    /**
+     * GET draft answers a baseline built without copying the legacy logo, while POST init copies it,
+     * so `document.branding.logo` can differ between them: clients rebase onto init's document.
+     */
     interface StorefrontDesignBaselineResult {
         draftRevision: null;
         publishedRevision: null;
@@ -387,6 +409,17 @@ declare global {
         items: StorefrontDesignHistoryEntry[];
         cursor?: string;
     }
+    /** A page of the live publication: the slug it answers at and the former slugs that 301 to it. */
+    interface StorefrontDesignPublishedPage {
+        slug: string;
+        aliases: string[];
+    }
+    /** Where a resolved setting's value came from: the registry default, a platform layer, or the document. */
+    type StorefrontDesignSettingProvenance = 'default' | 'platform' | 'design';
+    /**
+     * GET draft and every mutation that answers the draft (init, save, discard, restore) carry the
+     * same result; an idempotent replay rebuilds the four derived fields from current reads.
+     */
     interface StorefrontDesignDraftResult {
         draftRevision: string;
         publishedRevision: string | null;
@@ -394,6 +427,28 @@ declare global {
         dirty: boolean;
         mappingConflicts: StorefrontDesignMappingConflict[];
         legacySourceRevision: string;
+        /**
+         * The live publication's page addresses, keyed by page id: every page that has ever been
+         * published and still owns its slug, a since-removed or disabled page's included. Renaming
+         * an ENABLED page listed here makes its current slug a 301 alias on the next publish; a
+         * page absent here has no live address, so renaming it creates no alias. Absent when the
+         * shop has never published.
+         */
+        publishedPages?: Record<string, StorefrontDesignPublishedPage>;
+        /**
+         * What publishing this saved document would refuse today, as field errors: missing required
+         * content, a link to a disabled or missing page (`DANGLING_REFERENCE`), a slug a published
+         * page still owns (`ALIAS_CONFLICT`), a page out of aliases (`ALIAS_LIMIT`), and one
+         * `MAPPING_CONFLICT` per unresolved `mappingConflicts` entry, at that entry's path (the
+         * publish refusal itself names the single path `mappingConflicts`). Empty when publishable.
+         * Never blocks a save, and never covers asset readiness, which publish probes on its own
+         * (`STOREFRONT_ASSET_NOT_READY`).
+         */
+        publishIssues?: StorefrontDesignFieldError[];
+        /** The document's settings over the live platform layer: what the published shop would render. */
+        effectiveSettings?: StorefrontDesignSettings;
+        /** Per setting, which layer `effectiveSettings` took it from. */
+        settingsProvenance?: Record<keyof StorefrontDesignSettings, StorefrontDesignSettingProvenance>;
     }
     interface StorefrontDesignDeliveryTarget {
         /**
@@ -503,6 +558,27 @@ declare global {
         assetId: string;
         variant?: StorefrontAssetVariant;
     };
+    /**
+     * The codes `GET /preview/read` answers itself, on the common `{ message, error }` body:
+     * 400 `STOREFRONT_PREVIEW_INVALID` (a query the read schema refuses, a repeated parameter or a
+     * body), 401 `STOREFRONT_PREVIEW_INVALID` (no or a malformed bearer grant), 401 `…_EXPIRED`,
+     * 403 `…_REVOKED` / `…_FORBIDDEN` / `PLAN_UPGRADE_REQUIRED` (bare, without the editor
+     * routes' plan fields), 404 `ASSET_NOT_FOUND` (an asset the pinned draft does not reference or
+     * that is not ready), 405 `METHOD_NOT_ALLOWED` (anything but GET and OPTIONS), 413
+     * `STOREFRONT_PREVIEW_IMAGE_TOO_LARGE` (asset bytes over 4 MiB) and 503 `…_UNAVAILABLE`.
+     */
+    type StorefrontPreviewReadErrorCode = 'STOREFRONT_PREVIEW_INVALID' | 'STOREFRONT_PREVIEW_EXPIRED' | 'STOREFRONT_PREVIEW_REVOKED' | 'STOREFRONT_PREVIEW_FORBIDDEN' | 'STOREFRONT_PREVIEW_UNAVAILABLE' | 'STOREFRONT_PREVIEW_IMAGE_TOO_LARGE' | 'PLAN_UPGRADE_REQUIRED' | 'ASSET_NOT_FOUND' | 'METHOD_NOT_ALLOWED';
+    /**
+     * The codes a catalogue operation answers through its public web route's own core, as that
+     * route does: 404 `PRODUCT_NOT_FOUND` / `PRODUCT_GROUP_NOT_FOUND` / `COLLECTION_NOT_FOUND`,
+     * 400 `INVALID_CURSOR` / `INVALID_DISCOVERY_QUERY`, 409 `CURSOR_STALE` (a collection that
+     * changed between the reads bracketing a page) and 503 `PRODUCT_LOOKUP_INCOMPLETE`.
+     */
+    type StorefrontPreviewCatalogueErrorCode = 'PRODUCT_NOT_FOUND' | 'PRODUCT_GROUP_NOT_FOUND' | 'COLLECTION_NOT_FOUND' | 'INVALID_CURSOR' | 'INVALID_DISCOVERY_QUERY' | 'CURSOR_STALE' | 'PRODUCT_LOOKUP_INCOMPLETE';
+    interface StorefrontPreviewReadFailure {
+        message: string;
+        error: StorefrontPreviewReadErrorCode | StorefrontPreviewCatalogueErrorCode;
+    }
     interface StorefrontPreviewDesignResult {
         mode: 'preview';
         draftRevision: string;

package/dist/storefrontDesign.js

@@ -1,5 +1,16 @@
+/** The social kinds a contact may link, each to its own hosts; a contact links at most one per kind. */
+export const STOREFRONT_SOCIAL_HOSTS = {
+    instagram: ['instagram.com', 'www.instagram.com'],
+    facebook: ['facebook.com', 'www.facebook.com'],
+    youtube: ['youtube.com', 'www.youtube.com', 'youtu.be', 'www.youtu.be'],
+    tiktok: ['tiktok.com', 'www.tiktok.com'],
+    linkedin: ['linkedin.com', 'www.linkedin.com'],
+    x: ['x.com', 'www.x.com'],
+};
 export const STOREFRONT_DESIGN_LIMITS = {
     customPages: 20,
+    pageAliases: 20,
+    pageAliasMetadataBytes: 64 * 1024,
     sectionsPerPage: 10,
     productCountMin: 4,
     productCountMax: 24,
@@ -34,9 +45,17 @@ export const STOREFRONT_DESIGN_LIMITS = {
     contactAddress: 500,
     contactNote: 200,
     contactHours: 14,
-    contactSocials: 8,
+    /** One link per social kind, so the cap is the number of kinds. */
+    contactSocials: Object.keys(STOREFRONT_SOCIAL_HOSTS).length,
     contactEmail: 254,
 };
+/**
+ * A custom page's slug: lowercase ASCII letters, digits and inner hyphens, 1 to
+ * `STOREFRONT_DESIGN_LIMITS.slug` characters, starting and ending alphanumeric. The one
+ * definition: the api's validators, its page renderer and the edge viewer request read it.
+ */
+export const STOREFRONT_PAGE_SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,78}[a-z0-9])?$/;
+export const isStorefrontPageSlug = (value) => typeof value === 'string' && STOREFRONT_PAGE_SLUG_RE.test(value);
 export const STOREFRONT_SECTION_TYPES = [
     'banner',
     'imageText',
@@ -115,14 +134,6 @@ export const STOREFRONT_RESERVED_SLUGS = [
     'mantenimiento',
 ];
 export const STOREFRONT_BENEFIT_ICONS = ['truck', 'shield', 'credit-card', 'store', 'heart', 'check'];
-export const STOREFRONT_SOCIAL_HOSTS = {
-    instagram: ['instagram.com', 'www.instagram.com'],
-    facebook: ['facebook.com', 'www.facebook.com'],
-    youtube: ['youtube.com', 'www.youtube.com', 'youtu.be', 'www.youtu.be'],
-    tiktok: ['tiktok.com', 'www.tiktok.com'],
-    linkedin: ['linkedin.com', 'www.linkedin.com'],
-    x: ['x.com', 'www.x.com'],
-};
 export function createStorefrontDesignV1() {
     return {
         schemaVersion: 1,

package/dist/storefrontSeo.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Information-page paths and the storefront's SEO inheritance chain — one
+ * definition for the server that renders a shared link's head and the editor
+ * that previews it.
+ */
+/** Path prefix of a published information page: `/pagina/<slug>`. */
+export declare const STOREFRONT_PAGE_PATH_PREFIX = "/pagina/";
+/** The path an information page with `slug` is served at. The slug is neither validated nor encoded here. */
+export declare const storefrontPagePath: (slug: string) => string;
+/** The description a shop is shared with when neither the page nor the shop sets one. */
+export declare const storefrontDefaultSeoDescription: (storeName: string) => string;
+/**
+ * Where a resolved SEO field came from: the page itself, the shop-wide `seo`
+ * block, the shop logo (image only), or the platform default.
+ */
+export type StorefrontSeoSource = 'page' | 'shop' | 'logo' | 'default';
+/** The SEO fields a page and the shop each carry; `Placement` is the image shape of the document passed in. */
+export interface StorefrontSeoFields<Placement = StorefrontDesignImagePlacement> {
+    title?: string;
+    description?: string;
+    image?: Placement;
+    noindex?: boolean;
+}
+/**
+ * What {@link resolveStorefrontSeo} reads from a design document. A draft
+ * (`StorefrontDesignV1`), the published projection and `PublicStorefrontDesign`
+ * all satisfy it; with the last, a resolved image keeps its `url`.
+ */
+export interface StorefrontSeoDocument<Placement = StorefrontDesignImagePlacement> {
+    seo: StorefrontSeoFields<Placement>;
+    branding: {
+        logo?: Placement;
+    };
+    pages: readonly {
+        id: string;
+        title: string;
+        seo?: StorefrontSeoFields<Placement>;
+    }[];
+}
+/** The SEO a page is shared with, each field with where it came from. */
+export interface ResolvedStorefrontSeo<Placement = StorefrontDesignImagePlacement> {
+    title: string;
+    description: string;
+    /**
+     * The placement shared as `og:image` (cropped to 1200x630), or `null` for
+     * the platform's own share image (`source.image === 'default'`).
+     */
+    image: Placement | null;
+    noindex: boolean;
+    source: {
+        title: Exclude<StorefrontSeoSource, 'logo'>;
+        description: Exclude<StorefrontSeoSource, 'logo'>;
+        image: StorefrontSeoSource;
+        noindex: Exclude<StorefrontSeoSource, 'logo'>;
+    };
+}
+/**
+ * The SEO the storefront shares a page with: `'home'`, or an information page
+ * by `id`.
+ *
+ * - title: the page's `seo.title`, else its `title`, else the shop's
+ *   `seo.title`, else `storeName`. Home skips the page steps — its own `title`
+ *   is never used.
+ * - description: the page's `seo.description`, else the shop's, else
+ *   {@link storefrontDefaultSeoDescription}.
+ * - image: the page's `seo.image`, else the shop's, else the logo, else `null`
+ *   (the platform share image).
+ * - noindex: the page's `seo.noindex` when set — an explicit `false` beats a
+ *   shop-wide `true` — else the shop's, else `false`.
+ *
+ * An empty title or description counts as unset and falls through. Returns
+ * `undefined` for a page id the document does not carry; `'home'` always
+ * resolves. A shop with no published design is out of scope: its head uses
+ * the store's own name, photo and the default description.
+ */
+export declare function resolveStorefrontSeo<Placement>(document: StorefrontSeoDocument<Placement>, target: 'home', storeName: string): ResolvedStorefrontSeo<Placement>;
+export declare function resolveStorefrontSeo<Placement>(document: StorefrontSeoDocument<Placement>, target: string, storeName: string): ResolvedStorefrontSeo<Placement> | undefined;

package/dist/storefrontSeo.js

@@ -0,0 +1,58 @@
+/**
+ * Information-page paths and the storefront's SEO inheritance chain — one
+ * definition for the server that renders a shared link's head and the editor
+ * that previews it.
+ */
+/** Path prefix of a published information page: `/pagina/<slug>`. */
+export const STOREFRONT_PAGE_PATH_PREFIX = '/pagina/';
+/** The path an information page with `slug` is served at. The slug is neither validated nor encoded here. */
+export const storefrontPagePath = (slug) => `${STOREFRONT_PAGE_PATH_PREFIX}${slug}`;
+/** The description a shop is shared with when neither the page nor the shop sets one. */
+export const storefrontDefaultSeoDescription = (storeName) => `Comprá online en ${storeName}: catálogo, precios y stock actualizados.`;
+const shopImage = (document) => {
+    if (document.seo.image)
+        return { image: document.seo.image, source: 'shop' };
+    if (document.branding.logo)
+        return { image: document.branding.logo, source: 'logo' };
+    return { image: null, source: 'default' };
+};
+/** Home's SEO — and the default every information page inherits field by field. */
+const shopSeo = (document, storeName) => {
+    const { seo } = document;
+    const image = shopImage(document);
+    return {
+        title: seo.title || storeName,
+        description: seo.description || storefrontDefaultSeoDescription(storeName),
+        image: image.image,
+        noindex: seo.noindex === true,
+        source: {
+            title: seo.title ? 'shop' : 'default',
+            description: seo.description ? 'shop' : 'default',
+            image: image.source,
+            noindex: typeof seo.noindex === 'boolean' ? 'shop' : 'default',
+        },
+    };
+};
+export function resolveStorefrontSeo(document, target, storeName) {
+    const shop = shopSeo(document, storeName);
+    if (target === 'home')
+        return shop;
+    const page = document.pages.find(({ id }) => id === target);
+    if (!page)
+        return undefined;
+    const own = page.seo;
+    const pageTitle = own?.title || page.title;
+    const pageNoindex = own?.noindex;
+    return {
+        title: pageTitle || shop.title,
+        description: own?.description || shop.description,
+        image: own?.image || shop.image,
+        noindex: typeof pageNoindex === 'boolean' ? pageNoindex : shop.noindex,
+        source: {
+            title: pageTitle ? 'page' : shop.source.title,
+            description: own?.description ? 'page' : shop.source.description,
+            image: own?.image ? 'page' : shop.source.image,
+            noindex: typeof pageNoindex === 'boolean' ? 'page' : shop.source.noindex,
+        },
+    };
+}

package/dist/storefrontTheme.d.ts

@@ -1,4 +1,4 @@
-import { type StorefrontDesignSettings } from './storefrontDesignRegistry.ts';
+import { type StorefrontDesignSettings, type StorefrontDesignSettingsLayer } from './storefrontDesignRegistry.ts';
 type StorefrontThemeMode = 'light' | 'dark';
 type StorefrontThemeSurfaceId = 'page' | 'header' | 'footer';
 export interface StorefrontThemeSurface {
@@ -51,11 +51,27 @@ export interface StorefrontResolvedTheme {
 }
 export declare const storefrontContrastRatio: (foreground: string, background: string) => number;
 /**
- * The storefront theme for a design's settings overrides.
- *
- * Settings resolve from the registry defaults plus the store's own design
- * overrides ONLY — no GLOBAL or WEB layer takes part — so a consumer uses this
- * as shipped rather than merging layers of its own first.
+ * The GLOBAL design-settings layer of the platform globals row as `getPlatformGlobalsRow`
+ * returns it (`{ [key]: { value, ... } }`): each entry's `value`, kept only when it is a
+ * valid design setting, so a non-design global or a malformed value never reaches a theme.
  */
-export declare const resolveStorefrontTheme: (overrides?: Partial<StorefrontDesignSettings>) => StorefrontResolvedTheme;
+export declare const storefrontGlobalSettingsLayer: (globalsRow?: Record<string, unknown>) => StorefrontDesignSettingsLayer;
+/**
+ * The settings a storefront is served with: registry defaults, then the platform GLOBAL
+ * layer, then the design's own overrides. The one resolver behind the public envelope's
+ * `effectiveSettings`, the draft's `effectiveSettings` and the publish contrast report —
+ * a caller passes the globals row it read, never a layer stack of its own. The edge
+ * renderer's `theme-color` is design-only: its role reads no GLOBALS row.
+ */
+export declare const resolveStorefrontEffectiveSettings: (overrides?: Partial<StorefrontDesignSettings>, globalsRow?: Record<string, unknown>) => StorefrontDesignSettings;
+/**
+ * The storefront theme for a design's settings overrides, resolved through
+ * `resolveStorefrontEffectiveSettings`: the GLOBAL layer of `globalsRow` sits under the
+ * design, exactly as in the public envelope's `effectiveSettings`. Omitting `globalsRow`
+ * resolves defaults plus the design only — correct solely while no GLOBAL design setting
+ * is set, so a caller serving or reporting on a storefront passes the row (the edge
+ * renderer's `theme-color` is the one exception, design-only by its read grant). Passing
+ * already-effective settings as `overrides` rebuilds the same theme.
+ */
+export declare const resolveStorefrontTheme: (overrides?: Partial<StorefrontDesignSettings>, globalsRow?: Record<string, unknown>) => StorefrontResolvedTheme;
 export {};

package/dist/storefrontTheme.js

@@ -1,4 +1,4 @@
-import { resolveStorefrontDesignSettings } from "./storefrontDesignRegistry.js";
+import { resolveStorefrontDesignSettings, validateStorefrontDesignSetting, } from "./storefrontDesignRegistry.js";
 const channels = (color) => [
     Number.parseInt(color.slice(1, 3), 16),
     Number.parseInt(color.slice(3, 5), 16),
@@ -62,14 +62,36 @@ const surfaceTokens = (background, settings, mode, surface, warnings) => {
     };
 };
 /**
- * The storefront theme for a design's settings overrides.
- *
- * Settings resolve from the registry defaults plus the store's own design
- * overrides ONLY — no GLOBAL or WEB layer takes part — so a consumer uses this
- * as shipped rather than merging layers of its own first.
+ * The GLOBAL design-settings layer of the platform globals row as `getPlatformGlobalsRow`
+ * returns it (`{ [key]: { value, ... } }`): each entry's `value`, kept only when it is a
+ * valid design setting, so a non-design global or a malformed value never reaches a theme.
  */
-export const resolveStorefrontTheme = (overrides = {}) => {
-    const settings = resolveStorefrontDesignSettings(overrides);
+export const storefrontGlobalSettingsLayer = (globalsRow) => ({
+    layer: 'GLOBAL',
+    values: Object.fromEntries(Object.entries(globalsRow ?? {}).flatMap(([key, entry]) => {
+        const value = entry !== null && typeof entry === 'object' ? entry.value : undefined;
+        return validateStorefrontDesignSetting(key, value) ? [[key, value]] : [];
+    })),
+});
+/**
+ * The settings a storefront is served with: registry defaults, then the platform GLOBAL
+ * layer, then the design's own overrides. The one resolver behind the public envelope's
+ * `effectiveSettings`, the draft's `effectiveSettings` and the publish contrast report —
+ * a caller passes the globals row it read, never a layer stack of its own. The edge
+ * renderer's `theme-color` is design-only: its role reads no GLOBALS row.
+ */
+export const resolveStorefrontEffectiveSettings = (overrides = {}, globalsRow) => resolveStorefrontDesignSettings(overrides, [storefrontGlobalSettingsLayer(globalsRow)]);
+/**
+ * The storefront theme for a design's settings overrides, resolved through
+ * `resolveStorefrontEffectiveSettings`: the GLOBAL layer of `globalsRow` sits under the
+ * design, exactly as in the public envelope's `effectiveSettings`. Omitting `globalsRow`
+ * resolves defaults plus the design only — correct solely while no GLOBAL design setting
+ * is set, so a caller serving or reporting on a storefront passes the row (the edge
+ * renderer's `theme-color` is the one exception, design-only by its read grant). Passing
+ * already-effective settings as `overrides` rebuilds the same theme.
+ */
+export const resolveStorefrontTheme = (overrides = {}, globalsRow) => {
+    const settings = resolveStorefrontEffectiveSettings(overrides, globalsRow);
     const warnings = [];
     const makeMode = (mode) => {
         const background = (requested) => mode === 'light' ? requested.toUpperCase() : mix(requested, '#000000', 0.9);

package/dist/storefrontWebLiteralKeys.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Every storefront `WEB` literal key a shop may override, in code-unit order.
+ *
+ * This list is what the api's override validator accepts — one definition, so
+ * an editor offers exactly the keys a save will keep. A key outside it is
+ * refused as `UNKNOWN_KEY` on save and dropped on read.
+ *
+ * ⚠️ It is NOT every key the storefront renders. Withheld on purpose:
+ * - every key starting with `PRIVACY_` — privacy and terms are platform text,
+ *   the same on every shop, and the storefront ignores a shop value for them;
+ * - the keys only the not-found and unavailable screens render, which read no
+ *   shop layer;
+ * - keys whose storefront value is not a plain `{name}`-token sentence (it
+ *   branches, computes, or is not a string), which a shop string cannot
+ *   express.
+ * An editor that lists any of those offers an edit the server refuses.
+ *
+ * Interpolated values use `{name}` tokens named after the storefront's own
+ * parameters.
+ */
+export declare const STOREFRONT_WEB_LITERAL_KEYS: readonly string[];
+/** Whether a shop may override `key` — membership in {@link STOREFRONT_WEB_LITERAL_KEYS}. */
+export declare const isStorefrontLiteralKey: (key: string) => boolean;