@coras-io/embed 0.2.0 → 0.3.0

package/dist/sdk/mount.js

@@ -3,7 +3,7 @@ import { DEFAULT_CURRENCY, DEFAULT_LOCALE } from "../views/constants.js";
 import { createDiagnostics, themeHasNoColours } from "./diagnostics.js";
 import { attachCallbackBridge, } from "./element-adapter.js";
 import { createChrome } from "./chrome.js";
-import { applyConfig, applyParams, captureParamDefaults, defaultPageRegistry, } from "./page-registry.js";
+import { applyConfig, applyParams, captureConfigDefaults, captureParamDefaults, defaultPageRegistry, } from "./page-registry.js";
 import { applyColorScheme, applyTheme, clearTheme } from "./theme.js";
 import { safeUrl } from "@coras-io/brand-tokens";
 import { ensureTokensInjected } from "../styles/tokens.js";
@@ -14,6 +14,23 @@ function isThenable(value) {
         value !== null &&
         typeof value.then === "function");
 }
+// `apiUrl` and `distributorId` fix the mount's identity: the API client is
+// built once around them (base.mixin), so an update cannot change them. The
+// public type already omits them; this guards JavaScript callers.
+const IMMUTABLE_CONFIG_KEYS = ["apiUrl", "distributorId"];
+// Reject an update only when it would actually change an identity key, not when
+// it merely restates the mounted value. Hosts commonly rebuild one config object
+// and pass it to both `mount()` and `update()` (every framework wrapper does),
+// so re-sending the unchanged `apiUrl`/`distributorId` must be a no-op rather
+// than an error; only a genuinely different value is rejected.
+function assertIdentityUnchanged(patch, current) {
+    const provided = patch;
+    for (const key of IMMUTABLE_CONFIG_KEYS) {
+        if (key in provided && provided[key] !== current[key]) {
+            throw new CorasValidationError("invalid_config", `config.${key} cannot be changed after mount; unmount and mount again to switch ${key === "apiUrl" ? "the API endpoint" : "distributor"}.`, `config.${key}`);
+        }
+    }
+}
 /**
  * Create a `mount` function bound to a page registry. The public `mount` uses
  * the real registry; tests inject a lightweight registry so lifecycle behavior
@@ -38,9 +55,15 @@ export function createMountWith(registry) {
         const root = document.createElement("div");
         root.setAttribute("data-coras-root", "");
         // Token system is defined on the container scope and inherits into every
-        // nested Web Component's shadow tree (plan F-004). Adopting into the
-        // document is idempotent and shared across mounts.
-        ensureTokensInjected(container.ownerDocument ?? document);
+        // nested Web Component's shadow tree (plan F-004). Adopt into the container's
+        // root node, which is its host ShadowRoot when mounted inside one - adopting
+        // into ownerDocument would leave a shadow-hosted mount with only the
+        // @property initials, losing the entire token system. `ensureTokensInjected`
+        // already accepts a ShadowRoot; give it the real root.
+        const containerRoot = container.getRootNode();
+        ensureTokensInjected(containerRoot instanceof ShadowRoot
+            ? containerRoot
+            : (container.ownerDocument ?? document));
         let currentPage = validated.page;
         let currentConfig = validated.config;
         let currentParams = validated.params;
@@ -53,8 +76,10 @@ export function createMountWith(registry) {
         container.appendChild(root);
         let destroyed = false;
         let generation = 0;
+        let chromeGeneration = 0;
         let pageElement = null;
         let pageParamDefaults = {};
+        let pageConfigDefaults = {};
         let chromeElements = [];
         let readySettled = false;
         let resolveReady;
@@ -93,7 +118,9 @@ export function createMountWith(registry) {
             const detail = toPublicErrorDetail(error, currentPage);
             // Per-mount logging only; the SDK never writes unconditional console output.
             options.logger?.error?.(error);
-            options.onError?.(detail);
+            // Deliver to `onError` via the `coras:error` event only: the callback
+            // bridge routes it to `onError`, so calling `onError` here as well would
+            // fire it twice for one error.
             fireEvent(root, "coras:error", detail);
             emitObservability("coras.error", { code: detail.code });
         }
@@ -103,13 +130,31 @@ export function createMountWith(registry) {
             }
             chromeElements = [];
         }
+        // Push `currentConfig.theme` onto the root and any live navbar. Chrome is
+        // not rebuilt on a theme-only update, so the default logo (light + dark)
+        // goes straight to the navbar.
+        function syncThemeToRoot() {
+            clearTheme(root);
+            applyTheme(root, currentConfig.theme);
+            for (const element of chromeElements) {
+                if (element.tagName === "CORAS-NAVBAR") {
+                    const nav = element;
+                    nav.logo = safeUrl(currentConfig.theme?.logo);
+                    nav.logoDark = safeUrl(currentConfig.theme?.logoDark);
+                    nav.navbarLogo = safeUrl(currentConfig.theme?.navbarLogo);
+                }
+            }
+        }
         async function renderPage(targetPage, generationToken) {
             const entry = registry[targetPage];
             await entry.load();
             if (destroyed || generationToken !== generation)
                 return;
             const element = document.createElement(entry.tagName);
-            applyConfig(element, currentConfig);
+            // Capture element defaults before applyConfig writes to them, so a later
+            // update that clears an optional config value can restore the default.
+            const configDefaults = captureConfigDefaults(element);
+            applyConfig(element, currentConfig, configDefaults);
             // Preview is a mount-time rendering mode, not config or a param, so it is
             // set directly on the element; pages that honor it read their own property.
             element.preview = preview;
@@ -120,6 +165,8 @@ export function createMountWith(registry) {
             // context consumer across providers leaves those bindings stale.
             const chrome = await createChrome(currentChrome, {
                 logo: currentConfig.theme?.logo,
+                logoDark: currentConfig.theme?.logoDark,
+                navbarLogo: currentConfig.theme?.navbarLogo,
             });
             if (destroyed || generationToken !== generation)
                 return;
@@ -131,6 +178,7 @@ export function createMountWith(registry) {
             }
             pageElement = element;
             pageParamDefaults = paramDefaults;
+            pageConfigDefaults = configDefaults;
             chromeElements = chrome;
             root.appendChild(element);
             root.dataset.corasPage = targetPage;
@@ -138,28 +186,49 @@ export function createMountWith(registry) {
                 try {
                     await element.updateComplete;
                 }
-                catch {
-                    // Page render errors are surfaced through the page's own error paths.
+                catch (error) {
+                    if (destroyed || generationToken !== generation)
+                        return;
+                    // A rejected first render must not resolve `ready` as a success or
+                    // emit `coras:ready`; surface the failure instead.
+                    reportError(error);
+                    if (!readySettled) {
+                        readySettled = true;
+                        rejectReady(error);
+                    }
+                    return;
                 }
             }
             if (destroyed || generationToken !== generation)
                 return;
             root.dataset.corasMounted = "true";
+            // `coras:ready` is the first-completed-render signal, so emit it (and
+            // resolve `ready`) exactly once; later navigations re-render without
+            // re-firing it.
             if (!readySettled) {
                 readySettled = true;
                 resolveReady();
+                fireEvent(root, "coras:ready", { page: targetPage });
             }
-            fireEvent(root, "coras:ready", { page: targetPage });
             emitObservability("coras.page-loaded", { page: targetPage });
         }
         const bridge = attachCallbackBridge(root, options, {
             onListenerError: (error) => options.logger?.error?.(error),
         });
-        function startRender(targetPage) {
+        function startRender(targetPage, rollback) {
             const token = ++generation;
+            // A fresh render owns chrome from here on; invalidate any in-flight
+            // chrome-only update so its late resolve can't append to the new page.
+            chromeGeneration += 1;
             renderPage(targetPage, token).catch((error) => {
                 if (destroyed || token !== generation)
                     return;
+                // `renderPage` only throws before it swaps the DOM (the page chunk or
+                // the chrome never loaded), so the previous page is still on screen.
+                // Restore the state that describes it, or `app.state` would report a
+                // page that never rendered. Roll back before reporting, so the error
+                // and any state read from its handler agree.
+                rollback?.();
                 reportError(error);
                 if (!readySettled) {
                     readySettled = true;
@@ -201,61 +270,98 @@ export function createMountWith(registry) {
         function applyUpdate(patch) {
             if (destroyed)
                 return;
-            // Reject an unknown page before mutating any state, so a bad update or
-            // navigate can't leave currentPage pointing at a page the registry lacks.
+            // Phase 1 - validate the whole patch before mutating any state, so a
+            // failure (unknown page, invalid params/config, immutable field) leaves
+            // the mount's state and DOM exactly as they were.
             if (patch.page != null)
                 assertValidPage(patch.page);
+            let nextConfig = currentConfig;
             if (patch.config) {
-                currentConfig = validateConfig({ ...currentConfig, ...patch.config }, strict);
-                if ("theme" in patch.config) {
-                    clearTheme(root);
-                    applyTheme(root, currentConfig.theme);
-                    // Chrome is not rebuilt on a theme-only update, so push the (possibly
-                    // changed) default logo to the live navbar directly.
-                    for (const element of chromeElements) {
-                        if (element.tagName === "CORAS-NAVBAR") {
-                            element.logo = safeUrl(currentConfig.theme?.logo);
-                        }
-                    }
-                }
-                // A colour-scheme flip is just the root's `color-scheme`; the
-                // `light-dark()` pairs already carry both modes.
-                if ("colorScheme" in patch.config) {
-                    applyColorScheme(root, currentConfig.colorScheme);
-                }
+                assertIdentityUnchanged(patch.config, currentConfig);
+                nextConfig = validateConfig({ ...currentConfig, ...patch.config }, strict);
             }
             const pageChanged = patch.page != null && patch.page !== currentPage;
-            const chromeChanged = patch.chrome !== undefined;
-            if (chromeChanged)
-                currentChrome = patch.chrome;
+            const targetPage = pageChanged
+                ? patch.page
+                : currentPage;
+            let nextParams = currentParams;
             if (pageChanged) {
-                currentPage = patch.page;
-                currentParams = validatePageParams(currentPage, patch.params, strict);
-                startRender(currentPage);
-                return;
+                nextParams = validatePageParams(targetPage, patch.params, strict);
             }
-            if (patch.params) {
+            else if (patch.params) {
                 // Params are the full desired state for the page: replace rather than
                 // merge so params the host dropped (cleared) are reset to defaults by
                 // applyParams instead of lingering.
-                currentParams = validatePageParams(currentPage, patch.params, strict);
+                nextParams = validatePageParams(currentPage, patch.params, strict);
+            }
+            // Phase 2 - commit. Nothing below throws on invalid input.
+            const themeChanged = patch.config != null && "theme" in patch.config;
+            const colorSchemeChanged = patch.config != null && "colorScheme" in patch.config;
+            const chromeChanged = patch.chrome !== undefined;
+            const previous = {
+                page: currentPage,
+                params: currentParams,
+                config: currentConfig,
+                chrome: currentChrome,
+            };
+            currentConfig = nextConfig;
+            currentParams = nextParams;
+            if (chromeChanged)
+                currentChrome = patch.chrome;
+            if (themeChanged)
+                syncThemeToRoot();
+            // A colour-scheme flip is just the root's `color-scheme`; the
+            // `light-dark()` pairs already carry both modes.
+            if (colorSchemeChanged) {
+                applyColorScheme(root, currentConfig.colorScheme);
+            }
+            if (pageChanged) {
+                currentPage = targetPage;
+                // A page change renders asynchronously, so the rest of the patch is not
+                // durable until it lands: the new config reaches the DOM only through
+                // the new page element. If the render fails, undo the whole patch so an
+                // `update()` stays all-or-nothing rather than half-applied.
+                startRender(currentPage, () => {
+                    currentPage = previous.page;
+                    currentParams = previous.params;
+                    currentConfig = previous.config;
+                    currentChrome = previous.chrome;
+                    if (themeChanged)
+                        syncThemeToRoot();
+                    if (colorSchemeChanged) {
+                        applyColorScheme(root, currentConfig.colorScheme);
+                    }
+                });
+                return;
             }
             // No page change: update the existing element in place when possible.
             if (pageElement) {
-                applyConfig(pageElement, currentConfig);
+                applyConfig(pageElement, currentConfig, pageConfigDefaults);
                 applyParams(pageElement, registry[currentPage], currentParams, pageParamDefaults);
                 if (chromeChanged) {
                     removeChrome();
+                    const chromeToken = ++chromeGeneration;
                     void createChrome(currentChrome, {
                         logo: currentConfig.theme?.logo,
-                    }).then((chrome) => {
-                        if (destroyed || !pageElement)
+                        logoDark: currentConfig.theme?.logoDark,
+                        navbarLogo: currentConfig.theme?.navbarLogo,
+                    })
+                        .then((chrome) => {
+                        // A newer chrome update or a page render has superseded this one;
+                        // discard the stale chrome instead of appending it.
+                        if (destroyed ||
+                            !pageElement ||
+                            chromeToken !== chromeGeneration) {
+                            for (const chromeElement of chrome)
+                                chromeElement.remove();
                             return;
+                        }
                         for (const chromeElement of chrome) {
                             pageElement.appendChild(chromeElement);
                         }
                         chromeElements = chrome;
-                    });
+                    })
+                        .catch(reportError);
                 }
             }
             else if (chromeChanged) {
@@ -283,6 +389,8 @@ export function createMountWith(registry) {
                 if (navigateOptions?.emitNavigate) {
                     // Programmatic navigation is tagged `host` so onNavigate handlers can
                     // avoid re-driving the host router (loop prevention, ADR 0014).
+                    // `page` and `params` are correlated by this method's own signature;
+                    // the cast only re-states that for the un-narrowed event map.
                     fireEvent(root, "coras:navigate", {
                         page,
                         params,

package/dist/sdk/navigation-intent.js

@@ -3,6 +3,9 @@ export function classifyPageUpdate(input, context) {
     const currency = input.currency ?? context.currency;
     const isNavigate = (input.page != null && input.page !== context.currentPage) ||
         input.href != null;
+    // The public details correlate `page` with `params`; here the two arrive as
+    // separate values whose pairing was already established by `validatePageParams`
+    // upstream, so the cast re-states an invariant rather than assuming one.
     if (isNavigate) {
         return {
             kind: "navigate",

package/dist/sdk/page-registry.d.ts

@@ -14,8 +14,20 @@ export type PageEntry = {
 };
 export type PageRegistry = Record<CorasPageName, PageEntry>;
 export declare const defaultPageRegistry: PageRegistry;
-/** Apply normalized SDK config to a page (or chrome) element's properties. */
-export declare function applyConfig(element: ConfigurableElement, config: CorasConfig): void;
+/**
+ * Snapshot the element's default values for every property an optional config
+ * field drives. Taken right after creation (before `applyConfig`) so a later
+ * update that drops an optional value resets the property to its default - i.e.
+ * "clears" it - instead of leaving the stale value in place. Mirrors
+ * `captureParamDefaults` for params.
+ */
+export declare function captureConfigDefaults(element: ConfigurableElement): Record<string, unknown>;
+/**
+ * Apply normalized SDK config to a page (or chrome) element's properties. An
+ * optional field the config omits resets its property to the captured default,
+ * so clearing `locale`/`currency`/etc. on an update actually takes effect.
+ */
+export declare function applyConfig(element: ConfigurableElement, config: CorasConfig, defaults: Record<string, unknown>): void;
 /**
  * Snapshot the element's default values for every param the page exposes. Taken
  * right after creation (before any params are applied) so a later update can

package/dist/sdk/page-registry.js

@@ -40,22 +40,42 @@ export const defaultPageRegistry = {
         paramToProperty: identity("limit", "showExploreCard", "country", "city"),
     },
 };
-/** Apply normalized SDK config to a page (or chrome) element's properties. */
-export function applyConfig(element, config) {
+/** Element properties driven by an optional config field, in config -> property form. */
+const OPTIONAL_CONFIG_PROPERTIES = [
+    "locale",
+    "locales",
+    "currency",
+    "currencies",
+    "loyaltyPoints",
+];
+/**
+ * Snapshot the element's default values for every property an optional config
+ * field drives. Taken right after creation (before `applyConfig`) so a later
+ * update that drops an optional value resets the property to its default - i.e.
+ * "clears" it - instead of leaving the stale value in place. Mirrors
+ * `captureParamDefaults` for params.
+ */
+export function captureConfigDefaults(element) {
+    const defaults = {};
+    for (const property of OPTIONAL_CONFIG_PROPERTIES) {
+        defaults[property] = element[property];
+    }
+    return defaults;
+}
+/**
+ * Apply normalized SDK config to a page (or chrome) element's properties. An
+ * optional field the config omits resets its property to the captured default,
+ * so clearing `locale`/`currency`/etc. on an update actually takes effect.
+ */
+export function applyConfig(element, config, defaults) {
     element.apiHost = config.apiUrl;
     element.distributorID = config.distributorId;
     element.assetsURL = config.assetsUrl;
-    if (config.locale != null)
-        element.locale = config.locale;
-    if (config.allowedLocales != null)
-        element.locales = config.allowedLocales;
-    if (config.currency != null)
-        element.currency = config.currency;
-    if (config.allowedCurrencies != null)
-        element.currencies = config.allowedCurrencies;
-    if (config.loyaltyPointsEnabled != null) {
-        element.loyaltyPoints = config.loyaltyPointsEnabled;
-    }
+    element.locale = config.locale ?? defaults.locale;
+    element.locales = config.allowedLocales ?? defaults.locales;
+    element.currency = config.currency ?? defaults.currency;
+    element.currencies = config.allowedCurrencies ?? defaults.currencies;
+    element.loyaltyPoints = config.loyaltyPointsEnabled ?? defaults.loyaltyPoints;
 }
 /**
  * Snapshot the element's default values for every param the page exposes. Taken

package/dist/sdk/theme.d.ts

@@ -1,19 +1,5 @@
 import type { CorasColorScheme, CorasTheme } from "./types.js";
-/**
- * The brand `theme` keys that map 1:1 to a public `--coras-brand-*` custom
- * property. Sourced from the shared engine so the SDK, plugin, and Studio agree.
- * `navbarShadow`, `logo`, and `fontFaces` are applied specially (below).
- */
-export declare const THEME_CSS_VARS: Record<"primary" | "secondary" | "background" | "surface" | "text" | "textMuted" | "radius" | "font" | "textButton" | "bodyIcon" | "buttonRadius" | "chipRadius" | "navbar" | "navbarText" | "navbarIcon" | "navbarBorder" | "footer" | "footerText" | "footerLink" | "error" | "success" | "warning" | "info", string>;
-/**
- * Set the mount root's colour scheme so the token sheet's `light-dark()` pairs
- * resolve correctly. `"system"` maps to `light dark` (follows the OS via
- * `prefers-color-scheme`); `"inherit"` overrides the sheet's default `light` so
- * the root inherits the host page's `color-scheme`. Cheap enough to call on its
- * own for a mode flip.
- */
+export declare const THEME_CSS_VARS: Record<"primary" | "secondary" | "pageBackground" | "text" | "textMuted" | "link" | "bodyIcon" | "focusRing" | "scrim" | "cardBackground" | "cardBorder" | "fieldBackground" | "fieldBorder" | "menuBackground" | "menuBorder" | "divider" | "cardShadow" | "softShadow" | "mainButton" | "mainButtonText" | "mainButtonHover" | "mainButtonPressed" | "secondaryButton" | "secondaryButtonText" | "secondaryButtonHover" | "secondaryButtonPressed" | "textButton" | "mainButtonBorder" | "secondaryButtonBorder" | "disabled" | "buttonShadow" | "buttonHoverLight" | "buttonHoverDark" | "radius" | "buttonRadius" | "chipRadius" | "fieldRadius" | "searchRadius" | "font" | "headingFont" | "headingScale" | "logoHeight" | "navbarBackground" | "navbarText" | "navbarIcon" | "navbarBorder" | "navbarShadow" | "footerBackground" | "footerText" | "footerLink" | "footerBorder" | "footerPaddingBottom" | "error" | "errorBackground" | "success" | "successBackground" | "warning" | "warningBackground" | "info" | "infoBackground" | "primaryTint" | "secondaryTint" | "neutral50" | "neutral100" | "neutral200" | "neutral300" | "neutral400" | "neutral500" | "neutral600" | "neutral700" | "neutral800" | "neutral900", string>;
 export declare function applyColorScheme(element: HTMLElement, scheme: CorasColorScheme | undefined): void;
-/** Apply a brand to an element as scoped `--coras-*` variables (P-052/P-061). */
 export declare function applyTheme(element: HTMLElement, theme: CorasTheme | undefined): void;
-/** Remove any brand variables/fonts previously set on an element. */
 export declare function clearTheme(element: HTMLElement): void;

package/dist/sdk/theme.js

@@ -1,37 +1,13 @@
-import { BRAND_CSS_VARS, brandVarValue, fontFacesToCSS, sanitizeBrandValue, } from "@coras-io/brand-tokens";
-/**
- * The brand `theme` keys that map 1:1 to a public `--coras-brand-*` custom
- * property. Sourced from the shared engine so the SDK, plugin, and Studio agree.
- * `navbarShadow`, `logo`, and `fontFaces` are applied specially (below).
- */
+import { BRAND_CSS_VARS, brandVarValue, fontFacesToCSS, } from "@coras-io/brand-tokens";
 export const THEME_CSS_VARS = BRAND_CSS_VARS;
 const THEME_KEYS = Object.keys(THEME_CSS_VARS);
-/**
- * Set the mount root's colour scheme so the token sheet's `light-dark()` pairs
- * resolve correctly. `"system"` maps to `light dark` (follows the OS via
- * `prefers-color-scheme`); `"inherit"` overrides the sheet's default `light` so
- * the root inherits the host page's `color-scheme`. Cheap enough to call on its
- * own for a mode flip.
- */
 export function applyColorScheme(element, scheme) {
     element.style.colorScheme =
-        scheme === "dark"
-            ? "dark"
-            : scheme === "system"
-                ? "light dark"
-                : scheme === "inherit"
-                    ? "inherit"
-                    : "light";
+        scheme === "dark" ? "dark" : scheme === "inherit" ? "inherit" : "light";
 }
-/** Apply a brand to an element as scoped `--coras-*` variables (P-052/P-061). */
 export function applyTheme(element, theme) {
     if (!theme)
         return;
-    // Each themeable var is emitted as a `light-dark()` pair (or a single value
-    // when the field has no dark variant) via the shared engine, which sanitizes
-    // both sides - an invalid value yields "" and is skipped, so the Coras default
-    // (itself a light-dark pair) shows through. The dark side falls back to the
-    // Coras dark default when the brand sets only the light value.
     const dark = (theme.dark ?? {});
     for (const key of THEME_KEYS) {
         if (theme[key] == null && dark[key] == null)
@@ -40,17 +16,8 @@ export function applyTheme(element, theme) {
         if (value)
             element.style.setProperty(THEME_CSS_VARS[key], value);
     }
-    if (theme.navbarShadow != null) {
-        const shadow = sanitizeBrandValue("navbarShadow", theme.navbarShadow);
-        if (shadow) {
-            element.style.setProperty("--coras-brand-navbar-shadow", shadow);
-        }
-    }
-    // The page background is opt-in (see the root rule in tokens.css): only an
-    // explicit `background` paints the embed surface, so the embed otherwise
-    // adopts the host page's background.
-    if (theme.background != null || dark.background != null) {
-        const pageBg = brandVarValue("background", theme.background, dark.background);
+    if (theme.pageBackground != null || dark.pageBackground != null) {
+        const pageBg = brandVarValue("pageBackground", theme.pageBackground, dark.pageBackground);
         if (pageBg)
             element.style.setProperty("--coras-page-background", pageBg);
     }
@@ -62,12 +29,10 @@ export function applyTheme(element, theme) {
         element.appendChild(style);
     }
 }
-/** Remove any brand variables/fonts previously set on an element. */
 export function clearTheme(element) {
     for (const key of THEME_KEYS) {
         element.style.removeProperty(THEME_CSS_VARS[key]);
     }
-    element.style.removeProperty("--coras-brand-navbar-shadow");
     element.style.removeProperty("--coras-page-background");
     element
         .querySelectorAll(":scope > [data-coras-fontfaces]")

package/dist/sdk/types.d.ts

@@ -70,11 +70,12 @@ export type CorasTheme = BrandConfig;
  *
  * - `"light"` (default) - always light, ignoring the host page.
  * - `"dark"` - always dark.
- * - `"system"` - follows the OS via `prefers-color-scheme`.
  * - `"inherit"` - follows the host page's own `color-scheme` (the SDK sets none),
- *   so the embed behaves like a native element on a light or dark site.
+ *   so the embed behaves like a native element on a light or dark site. A page
+ *   that declares `color-scheme: light dark` hands the embed the visitor's OS
+ *   preference through the same route.
  */
-export type CorasColorScheme = "light" | "dark" | "system" | "inherit";
+export type CorasColorScheme = "light" | "dark" | "inherit";
 export type CorasConfig = {
     apiUrl: string;
     distributorId: string;
@@ -157,21 +158,33 @@ export type CorasNavigationSource = "embed" | "host";
 export type CorasReadyDetail = {
     page: CorasPageName;
 };
-export type CorasNavigateDetail = {
-    page: CorasPageName;
-    params?: CorasPageParams;
+type NavigateDetailFor<P extends CorasPageName> = {
+    page: P;
+    params?: CorasPageParamsByPage[P];
     locale?: SupportedLocales;
     currency?: SupportedCurrencies;
     href?: string;
     source: CorasNavigationSource;
 };
-export type CorasStateChangeDetail = {
-    page: CorasPageName;
-    params: CorasPageParams;
+/**
+ * Distributes over the page union, so narrowing on `detail.page` narrows
+ * `detail.params` with it and a handler cannot read a param the page never has.
+ */
+export type CorasNavigateDetail<P extends CorasPageName = CorasPageName> = P extends CorasPageName ? NavigateDetailFor<P> : never;
+type StateChangeDetailFor<P extends CorasPageName> = {
+    page: P;
+    params: CorasPageParamsByPage[P];
     locale?: SupportedLocales;
     currency?: SupportedCurrencies;
 };
-export type CorasPaymentStatus = "pending" | "succeeded" | "failed" | "cancelled";
+/** Distributes over the page union (see `CorasNavigateDetail`). */
+export type CorasStateChangeDetail<P extends CorasPageName = CorasPageName> = P extends CorasPageName ? StateChangeDetailFor<P> : never;
+/**
+ * Terminal payment outcomes the SDK emits. Only settled results are surfaced:
+ * a `pending` in-flight state is internal, and a user cancellation returns the
+ * form to its editable state rather than emitting a distinct status.
+ */
+export type CorasPaymentStatus = "succeeded" | "failed";
 export type CorasPaymentStatusDetail = {
     status: CorasPaymentStatus;
     /** Public reference only; never provider secrets or card data. */
@@ -208,6 +221,16 @@ export type CorasCallbacks = {
     onError?: (detail: CorasErrorDetail) => void;
     onObservability?: (event: CorasObservabilityEvent) => void;
 };
+/**
+ * `mount()` is generic over `P`, so a call passing a literal page gets its own
+ * params checked against it. The alias is deliberately *not* distributed over
+ * the page union: a host that owns routing reads `page` and `params` out of a
+ * URL as separate values, and no annotation can prove that pair correlates.
+ * Distributing here would force every routed host to cast - the SDK's primary
+ * integration - to buy a check the call site already makes. The read-side types
+ * (`CorasState`, `CorasNavigateDetail`, `CorasStateChangeDetail`) do distribute,
+ * because narrowing there is free.
+ */
 export type CorasMountOptions<P extends CorasPageName = CorasPageName> = {
     container: HTMLElement;
     page: P;
@@ -226,17 +249,29 @@ export type CorasMountOptions<P extends CorasPageName = CorasPageName> = {
      */
     preview?: boolean;
 } & CorasCallbacks;
-/** Frozen snapshot of the mount's current public state. */
-export type CorasState = {
-    readonly page: CorasPageName;
-    readonly params: CorasPageParams;
+type StateFor<P extends CorasPageName> = {
+    readonly page: P;
+    readonly params: CorasPageParamsByPage[P];
     readonly locale: SupportedLocales;
     readonly currency: SupportedCurrencies;
 };
-export type CorasUpdate = {
-    page?: CorasPageName;
-    params?: CorasPageParams;
-    config?: Partial<CorasConfig>;
+/**
+ * Frozen snapshot of the mount's current public state. Distributes over the
+ * page union, so `state.page` narrows `state.params` with it.
+ */
+export type CorasState<P extends CorasPageName = CorasPageName> = P extends CorasPageName ? StateFor<P> : never;
+/**
+ * Config an update may change. `apiUrl` and `distributorId` are the mount's
+ * fixed identity (the API client is built once around them), so they are not
+ * updatable; unmount and mount again to point at a different endpoint or
+ * distributor.
+ */
+export type CorasConfigUpdate = Partial<Omit<CorasConfig, "apiUrl" | "distributorId">>;
+/** Generic over `P`, not distributed - see `CorasMountOptions` for why. */
+export type CorasUpdate<P extends CorasPageName = CorasPageName> = {
+    page?: P;
+    params?: CorasPageParamsByPage[P];
+    config?: CorasConfigUpdate;
     chrome?: CorasChrome;
 };
 export type CorasNavigateOptions = {
@@ -246,13 +281,9 @@ export type CorasNavigateOptions = {
 export type CorasApp = {
     readonly ready: Promise<void>;
     readonly state: CorasState;
-    update(patch: CorasUpdate): void;
+    update<P extends CorasPageName = CorasPageName>(patch: CorasUpdate<P>): void;
     navigate<P extends CorasPageName>(page: P, params?: CorasPageParamsByPage[P], options?: CorasNavigateOptions): void;
     prefetch(page: CorasPageName): Promise<void>;
     unmount(): void;
 };
-export type CorasPageMeta = {
-    page: CorasPageName;
-    /** Internal custom-element tag used to render the page. */
-    tagName: string;
-};
+export {};