@coras-io/embed 0.2.0 → 0.4.0

package/dist/sdk/types.d.ts

@@ -1,4 +1,4 @@
-import type { BrandConfig } from "@coras-io/brand-tokens";
+import type { BrandConfig, BrandJson } from "@coras-io/brand-tokens";
 import type { SupportedCurrencies } from "../core/types/core/currency.js";
 import type { SupportedLocales } from "../core/types/core/locale.js";
 /**
@@ -57,12 +57,10 @@ export type CorasPageParamsByPage = {
 /** Params for a specific page, or the union when the page is not narrowed. */
 export type CorasPageParams<P extends CorasPageName = CorasPageName> = CorasPageParamsByPage[P];
 /**
- * The SDK `theme` option is the shared `BrandConfig` contract: un-prefixed
- * semantic keys (`primary`, `secondary`, …) plus chrome, `logo`, and
- * `fontFaces`. Defined once in `@coras-io/brand-tokens` and reused by the
- * microsites, emails, and the Studio.
+ * The SDK `theme` option is the shared brand contract from `@coras-io/brand-tokens`:
+ * a `brand.json` as written (grouped by surface) or the engine's flat keys.
  */
-export type CorasTheme = BrandConfig;
+export type CorasTheme = BrandConfig | BrandJson;
 /**
  * Which colour scheme the mount renders. `theme` carries the light values and
  * its `dark` block the dark overrides; this picks which side the `light-dark()`
@@ -70,11 +68,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 +156,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 +219,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 +247,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 +279,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 {};

package/dist/sdk/url.d.ts

@@ -6,6 +6,23 @@ import type { CorasPageName, CorasPageParams } from "./types.js";
  * URL; these helpers translate between a Coras state and a canonical URL so each
  * framework does not write bespoke parsing glue. See ADR 0013.
  */
+/**
+ * Pages with a URL. `suggestion-widget` is absent by design: it is a standalone
+ * embed the host mounts directly, not a page a visitor navigates to.
+ */
+export type CorasRoutablePage = Exclude<CorasPageName, "suggestion-widget">;
+/**
+ * A URL-representable state.
+ *
+ * `page` and `params` are deliberately left uncorrelated, and `page` stays the
+ * full union: a host that owns routing feeds these helpers straight from a
+ * `coras:navigate` detail or its own router, where the pair arrives as separate
+ * values no annotation can prove match. Narrowing here would buy nothing the
+ * runtime does not already check and would force every routed host to
+ * destructure per page. `buildCorasUrl` enforces the real constraints - a
+ * routable page, a details id, and an id that clears the reserved segments -
+ * and throws rather than emit a URL that parses back as something else.
+ */
 export type CorasUrlState = {
     page: CorasPageName;
     params: CorasPageParams;
@@ -23,12 +40,16 @@ export type CorasUrlStrategy = {
     currencyParam?: string;
     /**
      * Path segment for pages that use a reserved keyword. `landing` has no
-     * segment and `details` is represented by a bare id segment.
+     * segment and `details` is represented by a bare, percent-encoded id segment.
+     * Reserved segments therefore carve their words out of the details id space:
+     * an id equal to one is rejected by `buildCorasUrl` rather than silently
+     * building a URL that parses back as another page. Rename them here if they
+     * collide with real ids.
      */
-    reservedSegments?: Partial<Record<CorasPageName, string>>;
+    reservedSegments?: Partial<Record<CorasRoutablePage, string>>;
 };
 export declare const DEFAULT_URL_STRATEGY: Required<Omit<CorasUrlStrategy, "reservedSegments">> & {
-    reservedSegments: Partial<Record<CorasPageName, string>>;
+    reservedSegments: Partial<Record<CorasRoutablePage, string>>;
 };
 /** Parse a (relative or absolute) URL into a Coras state. */
 export declare function parseCorasUrl(url: string, strategy?: CorasUrlStrategy): CorasUrlState;

package/dist/sdk/url.js

@@ -1,9 +1,8 @@
-import { normalizeCurrency, normalizeLocale, PAGE_PARAM_KEYS, PAGE_PARAM_TYPES, } from "./validation.js";
+import { CorasValidationError, normalizeCurrency, normalizeLocale, PAGE_PARAM_KEYS, } from "./validation.js";
 const DEFAULT_RESERVED = {
     search: "search",
     payment: "payment",
     help: "help",
-    "suggestion-widget": "widget",
 };
 export const DEFAULT_URL_STRATEGY = {
     basePath: "",
@@ -12,14 +11,33 @@ export const DEFAULT_URL_STRATEGY = {
     currencyParam: "currency",
     reservedSegments: DEFAULT_RESERVED,
 };
+function invalidUrlState(message, field) {
+    throw new CorasValidationError("invalid_page_params", message, field);
+}
 function resolveStrategy(strategy = {}) {
+    const reservedSegments = {
+        ...DEFAULT_RESERVED,
+        ...strategy.reservedSegments,
+    };
+    // A segment holding a `/` (or nothing) would split into a path shape the
+    // parser can never invert, and two pages sharing a segment make the parse
+    // ambiguous. Both are host configuration errors: fail loudly at the call
+    // rather than emit URLs that silently round-trip to the wrong page.
+    const seen = new Map();
+    for (const [page, segment] of Object.entries(reservedSegments)) {
+        if (!segment || segment !== segment.trim() || /[/?#]/.test(segment)) {
+            invalidUrlState(`reservedSegments.${page} must be a non-empty path segment without "/", "?" or "#".`, `reservedSegments.${page}`);
+        }
+        const owner = seen.get(segment);
+        if (owner) {
+            invalidUrlState(`reservedSegments."${segment}" is used by both "${owner}" and "${page}"; each page needs its own segment.`, `reservedSegments.${page}`);
+        }
+        seen.set(segment, page);
+    }
     return {
         ...DEFAULT_URL_STRATEGY,
         ...strategy,
-        reservedSegments: {
-            ...DEFAULT_RESERVED,
-            ...strategy.reservedSegments,
-        },
+        reservedSegments,
     };
 }
 function reservedToPage(reserved) {
@@ -33,22 +51,15 @@ function reservedToPage(reserved) {
 function trimSlashes(value) {
     return value.replace(/^\/+|\/+$/g, "");
 }
-// Decode a query value into the type `mount()` validation expects. An
-// unparseable value is left as the raw string so validation reports it instead
-// of the helper silently swallowing it.
-function decodeParam(key, value) {
-    const type = PAGE_PARAM_TYPES[key];
-    if (type === "number") {
-        const n = Number(value);
-        return value.trim() !== "" && Number.isFinite(n) ? n : value;
-    }
-    if (type === "boolean") {
-        if (value === "true")
-            return true;
-        if (value === "false")
-            return false;
+// Decode a percent-encoded path segment, falling back to the raw value when it
+// holds a malformed escape (so a hand-written URL is never a hard failure).
+function safeDecodeSegment(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
     }
-    return value;
 }
 /** Parse a (relative or absolute) URL into a Coras state. */
 export function parseCorasUrl(url, strategy = {}) {
@@ -89,6 +100,7 @@ export function parseCorasUrl(url, strategy = {}) {
     }
     const reservedMap = reservedToPage(resolved.reservedSegments);
     const pageSegment = segments[index];
+    // Only ever `landing`, a reserved page, or `details` - all routable.
     let page = "landing";
     const params = {};
     if (pageSegment) {
@@ -97,8 +109,9 @@ export function parseCorasUrl(url, strategy = {}) {
             page = reservedPage;
         }
         else {
+            // Any non-reserved segment is a (percent-encoded) details id.
             page = "details";
-            params.id = pageSegment;
+            params.id = safeDecodeSegment(pageSegment);
         }
     }
     // Page-specific params come from the query string.
@@ -108,13 +121,18 @@ export function parseCorasUrl(url, strategy = {}) {
             continue; // details id is the path segment
         if (key === "metadata")
             continue; // host context, not URL state
+        // Every param a routable page accepts is a string, so the raw query value
+        // is already the type `mount()` validation expects.
         const value = parsed.searchParams.get(key);
         if (value != null)
-            params[key] = decodeParam(key, value);
+            params[key] = value;
     }
+    // `page` and `params` are built together above (a details page always got its
+    // id from the path segment), so the pairing holds even though the locals are
+    // separate values the compiler cannot correlate.
     return {
         page,
-        params: params,
+        params,
         ...(locale ? { locale } : {}),
         ...(currency ? { currency } : {}),
     };
@@ -122,6 +140,11 @@ export function parseCorasUrl(url, strategy = {}) {
 /** Build a canonical URL from a Coras state. */
 export function buildCorasUrl(state, strategy = {}) {
     const resolved = resolveStrategy(strategy);
+    // The type already excludes it; this catches JavaScript hosts, for whom a
+    // silent landing URL would be the alternative.
+    if (state.page === "suggestion-widget") {
+        invalidUrlState("suggestion-widget has no URL: it is a standalone embed the host mounts directly, not a routable page.", "page");
+    }
     const segments = [];
     const base = trimSlashes(resolved.basePath);
     if (base)
@@ -132,8 +155,22 @@ export function buildCorasUrl(state, strategy = {}) {
         segments.push(state.currency);
     const params = (state.params ?? {});
     if (state.page === "details") {
-        if (params.id != null)
-            segments.push(String(params.id));
+        const id = params.id;
+        // The id *is* the route segment, so a details state without one has no URL.
+        // Building the bare landing path instead would lose the page silently.
+        if (typeof id !== "string" || id.length === 0) {
+            invalidUrlState("A details state needs a non-empty params.id: the id is its URL segment.", "params.id");
+        }
+        // A bare id segment shares its space with the reserved words, so an id that
+        // equals one would parse back as that page. Reject it rather than emit a
+        // URL that does not round-trip; rename the segment via `reservedSegments`
+        // if a real id collides.
+        const collision = Object.entries(resolved.reservedSegments).find(([, segment]) => segment === id);
+        if (collision) {
+            invalidUrlState(`A details id of "${id}" collides with the "${collision[0]}" route segment and would parse back as that page. Rename the segment via reservedSegments.`, "params.id");
+        }
+        // Encode the id so `/`, `?`, and `#` survive the round-trip.
+        segments.push(encodeURIComponent(id));
     }
     else {
         const reserved = resolved.reservedSegments[state.page];
@@ -160,9 +197,11 @@ export function buildCorasUrl(state, strategy = {}) {
 }
 /** Normalize locale/currency aliases and ensure a params object. */
 export function normalizeCorasUrlState(input) {
+    // Only locale and currency are rewritten, so the page/params pairing the
+    // caller supplied carries through untouched.
     return {
         page: input.page,
-        params: (input.params ?? {}),
+        params: input.params ?? {},
         ...(input.locale
             ? { locale: normalizeLocale(input.locale) ?? input.locale }
             : {}),

package/dist/sdk/validation.d.ts

@@ -21,13 +21,6 @@ export declare const PUBLIC_PAGES: readonly CorasPageName[];
 export declare function assertValidPage(page: unknown): asserts page is CorasPageName;
 /** Allowed param keys per page (public names). */
 export declare const PAGE_PARAM_KEYS: Record<CorasPageName, readonly string[]>;
-/**
- * URL params whose string form decodes to a non-string type. Everything not
- * listed stays a string. Used by the URL helpers so a value round-trips through
- * a URL as the type `mount()` validation expects (e.g. `limit=3` -> `3`, not
- * `"3"`; `showExploreCard=false` -> `false`, not a truthy `"false"`).
- */
-export declare const PAGE_PARAM_TYPES: Readonly<Record<string, "number" | "boolean">>;
 /** Normalize locale casing/separators (e.g. `en_ie`, `EN-IE` -> `en-IE`). */
 export declare function normalizeLocale(value: string): SupportedLocales | undefined;
 /** Normalize currency casing (e.g. `eur` -> `EUR`). */

package/dist/sdk/validation.js

@@ -52,15 +52,31 @@ export const PAGE_PARAM_KEYS = {
     "suggestion-widget": ["limit", "showExploreCard", "country", "city"],
 };
 /**
- * URL params whose string form decodes to a non-string type. Everything not
- * listed stays a string. Used by the URL helpers so a value round-trips through
- * a URL as the type `mount()` validation expects (e.g. `limit=3` -> `3`, not
- * `"3"`; `showExploreCard=false` -> `false`, not a truthy `"false"`).
+ * The value type of every public page param. Param names mean the same thing on
+ * every page that accepts them, so one flat table drives both `mount()`
+ * validation and the URL helpers' decoding.
  */
-export const PAGE_PARAM_TYPES = {
+const PAGE_PARAM_KINDS = {
+    country: "string",
+    city: "string",
+    startDate: "date",
+    endDate: "date",
+    date: "date",
+    sort: "string",
+    duration: "string",
+    price: "string",
+    categories: "string",
+    search: "string",
+    id: "string",
+    content: "string",
+    metadata: "metadata",
     limit: "number",
     showExploreCard: "boolean",
 };
+/** Dates cross the API as plain `yyyy-MM-dd` calendar days. */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Upper bound for the suggestion widget's `limit`, guarding absurd requests. */
+const MAX_WIDGET_LIMIT = 50;
 const CONFIG_KEYS = [
     "apiUrl",
     "distributorId",
@@ -75,14 +91,14 @@ const CONFIG_KEYS = [
 ];
 const localeSet = new Set(allLocales);
 const currencySet = new Set(supportedCurrencies);
-const colorSchemes = new Set([
-    "light",
-    "dark",
-    "system",
-    "inherit",
-]);
+const colorSchemes = new Set(["light", "dark", "inherit"]);
 /** Normalize locale casing/separators (e.g. `en_ie`, `EN-IE` -> `en-IE`). */
 export function normalizeLocale(value) {
+    // Guard the type here rather than at each call site: JavaScript hosts reach
+    // this with arbitrary values, and an unsupported one is `undefined` (which
+    // callers turn into a typed error) rather than a raw TypeError from `.trim`.
+    if (typeof value !== "string")
+        return undefined;
     const parts = value.trim().replace(/_/g, "-").split("-");
     if (parts.length === 0 || !parts[0])
         return undefined;
@@ -93,6 +109,8 @@ export function normalizeLocale(value) {
 }
 /** Normalize currency casing (e.g. `eur` -> `EUR`). */
 export function normalizeCurrency(value) {
+    if (typeof value !== "string")
+        return undefined;
     const canonical = value.trim().toUpperCase();
     return currencySet.has(canonical)
         ? canonical
@@ -122,17 +140,15 @@ export function assertSecureUrl(value, field) {
         return url.href;
     throw new CorasValidationError("invalid_url", `${field} must use https (http is only allowed for localhost).`, field);
 }
-// Strict hostname: alnum labels separated by dots, optional :port.
-// Rejects protocol-relative inputs, paths, and free-form strings.
-const BARE_HOSTNAME_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?::\d{1,5})?$/i;
 /**
  * Asset URL must be one of:
- *   - an https URL (http allowed only for localhost),
- *   - a bare hostname like `assets.example.com[:port]`,
+ *   - an absolute https URL (http allowed only for localhost),
  *   - a root-relative path like `/assets`.
- * Rejected: protocol-relative URLs (`//host/x`), `javascript:` / `data:` URIs,
- * traversal-style paths. `assetsUrl` is interpolated straight into image and
- * SVG hrefs (see icon.component.ts), so a permissive validator is a foot-gun.
+ * Rejected: protocol-relative URLs (`//host/x`), bare hostnames
+ * (`assets.example.com` - the browser would resolve it against the host page's
+ * origin), `javascript:` / `data:` URIs, and traversal-style paths. `assetsUrl`
+ * is interpolated straight into image and SVG hrefs (see icon.component.ts), so
+ * a permissive validator is a foot-gun.
  */
 function validateAssetsUrl(value) {
     if (value === "") {
@@ -160,16 +176,15 @@ function validateAssetsUrl(value) {
         assertSecureUrl(value, "config.assetsUrl");
         return;
     }
-    if (!BARE_HOSTNAME_RE.test(value)) {
-        throw new CorasValidationError("invalid_url", "config.assetsUrl must be an https URL, a bare hostname, or a root-relative path.", "config.assetsUrl");
-    }
+    throw new CorasValidationError("invalid_url", "config.assetsUrl must be an absolute https URL or a root-relative path.", "config.assetsUrl");
 }
 // Field keys plus the BrandConfig meta keys validateBrandConfig understands.
 // Used only to surface unknown keys in strict mode (the schema itself strips
 // them silently, which a strict host wants flagged, not swallowed).
 const THEME_KEYS = [
     ...FIELDS.map((field) => field.key),
-    "logo",
+    ...FIELDS.map((field) => field.path.split(".")[0]),
+    "$schema",
     "fontFaces",
     "dark",
     "schemaVersion",
@@ -198,6 +213,13 @@ function validateTheme(theme, strict) {
         }
     }
 }
+// Guards a `.map()` over host-supplied config: a JavaScript caller passing a
+// bare string would otherwise throw a raw TypeError instead of a typed error.
+function assertArray(value, field) {
+    if (!Array.isArray(value)) {
+        throw new CorasValidationError("invalid_config", `${field} must be an array.`, field);
+    }
+}
 function rejectUnknownKeys(object, allowed, context) {
     for (const key of Object.keys(object)) {
         if (!allowed.includes(key)) {
@@ -244,9 +266,15 @@ export function validateConfig(config, strict) {
     }
     if (config.colorScheme != null &&
         !colorSchemes.has(config.colorScheme)) {
-        throw new CorasValidationError("invalid_color_scheme", `Unsupported colorScheme "${config.colorScheme}". Valid values: light, dark, system, inherit.`, "config.colorScheme");
+        throw new CorasValidationError("invalid_color_scheme", `Unsupported colorScheme "${config.colorScheme}". Valid values: light, dark, inherit.`, "config.colorScheme");
+    }
+    if (config.loyaltyPointsEnabled != null) {
+        if (typeof config.loyaltyPointsEnabled !== "boolean") {
+            throw new CorasValidationError("invalid_config", "config.loyaltyPointsEnabled must be a boolean.", "config.loyaltyPointsEnabled");
+        }
     }
     if (config.allowedLocales != null) {
+        assertArray(config.allowedLocales, "config.allowedLocales");
         normalized.allowedLocales = config.allowedLocales.map((value) => {
             const locale = normalizeLocale(value);
             if (!locale) {
@@ -256,6 +284,7 @@ export function validateConfig(config, strict) {
         });
     }
     if (config.allowedCurrencies != null) {
+        assertArray(config.allowedCurrencies, "config.allowedCurrencies");
         normalized.allowedCurrencies = config.allowedCurrencies.map((value) => {
             const currency = normalizeCurrency(value);
             if (!currency) {
@@ -269,40 +298,67 @@ export function validateConfig(config, strict) {
 export function validatePageParams(page, params, strict) {
     if (params == null)
         return {};
-    if (typeof params !== "object") {
+    // An array is `typeof "object"`, but it is never a valid params bag: accepting
+    // one would silently ignore every param the host meant to pass.
+    if (typeof params !== "object" || Array.isArray(params)) {
         throw new CorasValidationError("invalid_page_params", `params for page "${page}" must be an object.`, "params");
     }
     const allowed = PAGE_PARAM_KEYS[page];
     if (strict) {
         rejectUnknownKeys(params, allowed, "params");
     }
-    // `details.id` is the public id and must be a non-empty string when present.
-    if (page === "details" && "id" in params) {
-        const id = params.id;
-        if (id != null && (typeof id !== "string" || id.length === 0)) {
-            throw new CorasValidationError("invalid_page_params", "params.id must be a non-empty string.", "params.id");
-        }
+    // Type-check every param the page accepts. Outside strict mode unknown keys
+    // are ignored rather than rejected, so only `allowed` keys are checked.
+    for (const key of allowed) {
+        const value = params[key];
+        // An explicit `undefined`/`null` clears the param back to its default.
+        if (value == null)
+            continue;
+        assertParamKind(page, key, value);
     }
-    // `payment.metadata` is a free-form bag of client data; its keys are
-    // arbitrary, but every value must be a string so it can be serialized for
-    // the API forward.
-    if (page === "payment" && "metadata" in params) {
-        const metadata = params.metadata;
-        if (metadata != null) {
-            const isPlainObject = typeof metadata === "object" && !Array.isArray(metadata);
+    return params;
+}
+function assertParamKind(page, key, value) {
+    const invalid = (expected) => {
+        throw new CorasValidationError("invalid_page_params", `params.${key} for page "${page}" must be ${expected}.`, `params.${key}`);
+    };
+    switch (PAGE_PARAM_KINDS[key] ?? "string") {
+        case "number":
+            if (typeof value !== "number" || !Number.isFinite(value))
+                invalid("a number");
+            break;
+        case "boolean":
+            if (typeof value !== "boolean")
+                invalid("a boolean");
+            break;
+        case "date":
+            // Pages clear a date by emitting `""` (see the landing page's date reset),
+            // which means the same as omitting the param: reset it to its default.
+            if (typeof value !== "string" || (value !== "" && !ISO_DATE.test(value)))
+                invalid("a yyyy-MM-dd date");
+            break;
+        case "metadata": {
+            // A free-form bag of client data; its keys are arbitrary, but every value
+            // must be a string so it can be serialized for the API forward.
+            const isPlainObject = typeof value === "object" && !Array.isArray(value);
             if (!isPlainObject ||
-                !Object.values(metadata).every((value) => typeof value === "string")) {
-                throw new CorasValidationError("invalid_page_params", "params.metadata must be an object of string values.", "params.metadata");
-            }
+                !Object.values(value).every((v) => typeof v === "string"))
+                invalid("an object of string values");
+            break;
         }
+        default:
+            if (typeof value !== "string")
+                invalid("a string");
+            break;
     }
-    if (page === "suggestion-widget" && "limit" in params) {
-        const limit = params.limit;
-        if (limit != null && (typeof limit !== "number" || limit <= 0)) {
-            throw new CorasValidationError("invalid_page_params", "params.limit must be a positive number.", "params.limit");
-        }
-    }
-    return params;
+    // `id` is the public identifier and additionally carries the details route.
+    if (key === "id" && value.length === 0)
+        invalid("a non-empty string");
+    if (key === "limit" &&
+        (!Number.isInteger(value) ||
+            value <= 0 ||
+            value > MAX_WIDGET_LIMIT))
+        invalid(`a whole number between 1 and ${MAX_WIDGET_LIMIT}`);
 }
 /**
  * Validate and normalize the full mount options before anything is rendered.

package/dist/styles/contrast-fixtures.d.ts

@@ -1,9 +1,4 @@
 import type { ContrastPair } from "./contrast.js";
-/**
- * Default-theme contrast pairs validated in CI (plan F-004, P-058; pairs from
- * Appendix J). `tokens` lists the CSS variables each colour resolves from so a
- * stale check can confirm they still exist in the generated token sheet.
- */
 export type DefaultContrastPair = ContrastPair & {
     tokens: [string, string];
 };