@coras-io/embed 0.2.0 → 0.3.0

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,9 +176,7 @@ 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
@@ -170,6 +184,9 @@ function validateAssetsUrl(value) {
 const THEME_KEYS = [
     ...FIELDS.map((field) => field.key),
     "logo",
+    "logoDark",
+    "navbarLogo",
+    "footerLogo",
     "fontFaces",
     "dark",
     "schemaVersion",
@@ -198,6 +215,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 +268,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 +286,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 +300,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];
 };

package/dist/styles/contrast-fixtures.js

@@ -17,17 +17,17 @@ export const DEFAULT_CONTRAST_PAIRS = [
         tokens: ["--coras-color-text", "--coras-color-background"],
     },
     {
-        label: "Secondary text on page background",
-        foreground: "#666666",
+        label: "Muted/label text on page background",
+        foreground: "#888888",
         background: "#ffffff",
-        threshold: "AA-normal",
-        tokens: ["--coras-color-text-secondary", "--coras-color-background"],
+        threshold: "AA-large",
+        tokens: ["--coras-color-text-muted", "--coras-color-background"],
     },
     {
-        label: "Heading/secondary brand text on background",
+        label: "Brand accent on background",
         foreground: "#161c44",
         background: "#ffffff",
-        threshold: "AA-normal",
+        threshold: "AA-large",
         tokens: ["--coras-brand-secondary", "--coras-color-background"],
     },
     {
@@ -35,14 +35,14 @@ export const DEFAULT_CONTRAST_PAIRS = [
         foreground: "#888888",
         background: "#fcfcff",
         threshold: "AA-large",
-        tokens: ["--coras-color-text-muted", "--coras-color-surface"],
+        tokens: ["--coras-color-text-muted", "--coras-color-card"],
     },
     {
         label: "Error alert text on error alert background",
         foreground: "#c9224a",
-        background: "#fae9ed",
+        background: "#fae8ec",
         threshold: "AA-normal",
-        tokens: ["--coras-color-error", "--coras-color-error-surface"],
+        tokens: ["--coras-color-error", "--coras-color-error-background"],
     },
     {
         label: "Focus ring on background",
@@ -58,4 +58,74 @@ export const DEFAULT_CONTRAST_PAIRS = [
         threshold: "AA-normal",
         tokens: ["--coras-navbar-text-color", "--coras-navbar-background"],
     },
+    {
+        label: "Body text on page background (dark)",
+        foreground: "#ffffff",
+        background: "#101216",
+        threshold: "AA-normal",
+        tokens: ["--coras-color-text", "--coras-color-background"],
+    },
+    {
+        label: "Muted/label text on page background (dark)",
+        foreground: "#cccccc",
+        background: "#101216",
+        threshold: "AA-large",
+        tokens: ["--coras-color-text-muted", "--coras-color-background"],
+    },
+    {
+        label: "Muted/placeholder text on surface (dark)",
+        foreground: "#cccccc",
+        background: "#191c22",
+        threshold: "AA-large",
+        tokens: ["--coras-color-text-muted", "--coras-color-card"],
+    },
+    {
+        label: "Focus ring on background (dark)",
+        foreground: "#4657d4",
+        background: "#101216",
+        threshold: "AA-large",
+        tokens: ["--coras-color-focus-ring", "--coras-color-background"],
+    },
+    {
+        label: "Navbar text on navbar background (dark)",
+        foreground: "#ffffff",
+        background: "#101216",
+        threshold: "AA-normal",
+        tokens: ["--coras-navbar-text-color", "--coras-navbar-background"],
+    },
+    {
+        label: "Footer text on footer background (dark)",
+        foreground: "#ffffff",
+        background: "#191c22",
+        threshold: "AA-normal",
+        tokens: ["--coras-footer-text-color", "--coras-footer-background-color"],
+    },
+    {
+        label: "Text button on surface (dark)",
+        foreground: "#6279f9",
+        background: "#191c22",
+        threshold: "AA-normal",
+        tokens: ["--coras-color-text-button", "--coras-color-card"],
+    },
+    {
+        label: "Link on page background (dark)",
+        foreground: "#6279f9",
+        background: "#101216",
+        threshold: "AA-normal",
+        tokens: ["--coras-color-link", "--coras-color-background"],
+    },
+    {
+        label: "Error alert text on error alert background (dark)",
+        foreground: "#f5748a",
+        background: "#442e36",
+        threshold: "AA-normal",
+        tokens: ["--coras-color-error", "--coras-color-error-background"],
+    },
+    {
+        label: "Info alert text on info alert background (dark)",
+        foreground: "#ba86e1",
+        background: "#373045",
+        threshold: "AA-normal",
+        tokens: ["--coras-color-info", "--coras-color-info-background"],
+    },
 ];

package/dist/styles/contrast.js

@@ -1,6 +1,7 @@
-// WCAG contrast utilities (plan F-004, P-058). Pure functions reused by the
-// default-theme CI check and Coras Studio's live contrast panel (exposed via
-// the `@coras-io/embed/contrast` entry).
+// WCAG contrast utilities (plan F-004, P-058). Internal to the embed: they back
+// the default-theme CI check, which needs a browser to resolve any CSS colour
+// (`oklch()`, named colours) by rasterizing it. `@coras-io/brand-tokens` carries
+// the portable, parser-based equivalents for hosts and the Studio.
 const MIN_RATIO = {
     // AA normal text and AA UI/large both per WCAG 1.4.3 / 1.4.11.
     "AA-normal": 4.5,

package/dist/styles/defaults/component.js

@@ -17,6 +17,22 @@ export default css `
     box-sizing: inherit;
   }
 
+  :host button,
+  :host input,
+  :host select,
+  :host textarea {
+    font-family: inherit;
+  }
+
+  :host h1,
+  :host h2,
+  :host h3,
+  :host h4,
+  :host h5,
+  :host h6 {
+    font-family: var(--coras-font-family-heading);
+  }
+
   [hidden] {
     display: none !important;
   }
@@ -26,6 +42,6 @@ export default css `
   :host a:active {
     text-decoration: none;
     font-weight: 600;
-    color: var(--coras-color-primary-500);
+    color: var(--coras-color-primary);
   }
 `;

package/dist/styles/primitives.d.ts

@@ -1,14 +1,4 @@
-/**
- * Shared CSS primitives (plan F-004, P-063). Components compose these instead
- * of re-authoring focus rings, screen-reader helpers, or skeleton shimmer, so
- * accessibility and branding stay consistent. All values resolve from the
- * semantic token tier.
- */
-/** Visible focus ring using the brand focus token. */
 export declare const focusRing: import("lit").CSSResult;
-/** Accessible "visually hidden" helper that remains in the accessibility tree. */
 export declare const visuallyHidden: import("lit").CSSResult;
-/** Loading skeleton shimmer; respects reduced-motion. */
 export declare const skeleton: import("lit").CSSResult;
-/** Reset for native controls used as branded buttons/fields. */
 export declare const controlReset: import("lit").CSSResult;