@ecomconsult/consentkit 0.4.0 → 0.5.1

package/README.md

@@ -179,12 +179,16 @@ Pass any subset to `init()`. Nested objects merge with the defaults.
 |---|---|---|---|
 | `policyVersion` | `string \| number` | `"1"` | Bump to invalidate stored consent and re-show the banner |
 | `language` | `string` | `"auto"` | `"auto"` reads `navigator.language`. Falls back `pt-BR` → `pt` → `en` |
-| `layout.type` | `"bar" \| "modal" \| "box"` | `"bar"` | `box` is a compact ~360px card |
+| `layout.type` | `"bar" \| "modal" \| "box"` | `"bar"` | `box` is a corner card, up to 540px wide |
 | `layout.position` | `string` | per type | `bar`: `bottom` (default) / `top`. `box`: `bottom-left` (default) / `bottom-right`. `modal` is always centred. A position that does not belong to the chosen type falls back to that type's default; the type itself is unaffected |
 | `theme.accent` | `string` | `"#2B50D8"` | Exposed as `--ck-accent` |
-| `theme.radius` | `string` | `"10px"` | Exposed as `--ck-radius` |
+| `theme.font` | `"inherit" \| "system"` | `"inherit"` | v0.5.0. `inherit` takes the host page's font family; `system` restores the pre-0.5.0 system stack. Font *sizes* are fixed either way |
+| `theme.radius` | `{ card, button }` | `{ card: 16, button: 8 }` | v0.5.0. px, clamped 0–32. A bare string or number is the pre-0.5.0 form and still sets the card radius |
+| `theme.buttons` | `{ accept, reject, settings }` | see below | v0.5.0. Per-button appearance. **Contrast is enforced automatically** — see [Button appearance](#button-appearance) |
 | `theme.mode` | `"auto" \| "light" \| "dark"` | `"auto"` | `auto` follows `prefers-color-scheme` |
-| `theme.dark` | `{ bg, ink, accent }` | built-in | Overrides the dark palette |
+| `theme.dark` | `{ bg, ink, accent, onAccent }` | built-in | Overrides the dark palette |
+| `texts.policyUrl` | `string` | — | v0.5.0. Cookie policy address. `http(s)` only; anything else is ignored |
+| `texts.detailsAction` | `"policy" \| "settings" \| "hide"` | see notes | v0.5.0. What «Learn more» does. Defaults to `policy` when `policyUrl` is set, `settings` when it is not. `policy` without a usable URL falls back to `settings` rather than rendering a dead link |
 | `categories.*.enabled` | `boolean` | `true` | Per category: `functional`, `analytics`, `marketing`. Hides the toggle when `false` |
 | `consentTtlDays` | `number` | `365` | Lifetime of the stored decision |
 | `integrations.gcm` | `boolean` | `true` | Google Consent Mode v2 signals |
@@ -200,6 +204,98 @@ Pass any subset to `init()`. Nested objects merge with the defaults.
 { name: '_ga', category: 'analytics', vendor: 'Google', purpose: 'Visit statistics', expiry: '2 years' }
 ```
 
+### Button appearance
+
+Each of the three banner buttons can be styled independently:
+
+```js
+theme: {
+  accent: '#2B50D8',
+  font: 'inherit',
+  radius: { card: 16, button: 8 },
+  buttons: {
+    accept:   { variant: 'filled' },                        // accent fill
+    reject:   { variant: 'filled' },                        // always matches accept
+    settings: { variant: 'outline', borderWidth: 1 }        // accent border
+  }
+}
+```
+
+Each entry takes `variant` (`"filled"` or `"outline"`), and optionally `bg`,
+`fg`, `border` and `borderWidth` (`1` or `2`). Omitted colours come from
+`theme.accent`.
+
+**Accept and reject are always equal.** They render at the same size and weight,
+and they always share one variant — if the two disagree in the config,
+`accept.variant` is used for both. A reject button that looks weaker than
+accept is a dark pattern, and consent collected through one is not freely
+given, so the config simply cannot express it. `settings` is independent and
+may itself be filled.
+
+**Contrast is enforced automatically and cannot be switched off.** A colour
+combination that would be unreadable is corrected before it reaches the
+stylesheet:
+
+- button text keeps the colour you set only when it clears **4.5:1** against
+  the fill it sits on; otherwise it becomes white or `#161616`, whichever
+  contrasts more;
+- an `outline` border is darkened (light card) or lightened (dark card) in
+  small steps until it clears **3:1** against the card, so it stays
+  recognisably your colour rather than jumping to black or white;
+- that resolved border colour is then the outline button's text colour,
+  subject to the same 4.5:1 rule.
+
+The card is `#ffffff` in light mode and `#1c1c1e` in dark. A colour the
+arithmetic cannot read — a CSS colour name, an `rgb()` string — is left exactly
+as you wrote it rather than being silently replaced.
+
+The same arithmetic is exposed as pure functions on `ConsentKit._contrast`
+(`relativeLuminance`, `contrastRatio`, `ensureContrast`, `stepToContrast`,
+`resolveButtonStyles`, `resolveRadius`, `resolveFont`, `resolveDetails`,
+`buildThemeCss`) so a theme editor can show the same numbers the banner paints
+instead of reimplementing them. It is present whenever `src/ck-ui.js` is loaded,
+and it is safe to call in Node — nothing in it touches the DOM. The debug
+panel's **Appearance** section reads it directly and reports each button's
+resolved colours, its contrast ratio, and whether the value was adjusted.
+
+### The «Learn more» link
+
+`texts.detailsAction` decides what the link at the end of the banner copy does:
+
+| Value | Renders |
+|---|---|
+| `"policy"` | A link to `texts.policyUrl`, opened with `target="_blank" rel="noopener"` |
+| `"settings"` | A button that opens the preferences panel |
+| `"hide"` | Nothing at all |
+
+The default follows `policyUrl`: `policy` when one is set, `settings` when it
+is not — so supplying only a URL does the obvious thing.
+
+> Before 0.5.0 this control was rendered as `<a href="#">` with no handler at
+> all: clicking it jumped to the top of the page and nothing else. Any site
+> running 0.4.x or earlier has a dead «Learn more» link.
+
+### Infrastructure
+
+Some third-party hosts are not a consent decision at all: they are where a site
+builder or hosting platform serves the site's **own** markup, styles and
+scripts from. A Tilda page loads its layout from `tildacdn.com`, a Wix page
+loads its from `parastorage.com`, and a page using Google Fonts loads its
+typefaces from `fonts.gstatic.com`. ConsentKit ships these as a separate class
+of host — readable as `ConsentKit._infra()`, tested per URL or hostname with
+`ConsentKit._isInfra(url)` — covering the CDNs of Tilda, Wix, Shopify,
+Squarespace and Webflow, the general asset CDNs (`cdn.jsdelivr.net`,
+`unpkg.com`, `cdnjs.cloudflare.com`, `code.jquery.com`, `ajax.googleapis.com`),
+Google Fonts and hCaptcha. Strict mode never intercepts them, because blocking a
+builder's own CDN breaks the page without protecting anyone; the hosted service
+also leaves them out of scan reports, since there is nothing for a site owner to
+decide. Membership is a claim that a host delivers the site's own assets, not
+that it is harmless in general — anything that *measures* keeps a real consent
+category instead, which is why `static.cloudflareinsights.com` (Cloudflare Web
+Analytics) is classified as `analytics` and blocked before consent even though
+the rest of Cloudflare's CDN is infrastructure. Both lists are matched by suffix
+and returned as copies, so reading them cannot widen what strict mode allows.
+
 ## API
 
 All methods are safe to call at any time and never throw.
@@ -360,11 +456,10 @@ Four things are never intercepted:
    the answer is unclear it says same-site, because wrongly blocking a
    first-party asset breaks the site.
 2. **`blocking.allow`** — your own list, matched by suffix.
-3. **The built-in allowlist**, readable as `ConsentKit._baseAllow`: asset CDNs
-   (`cdn.jsdelivr.net`, `unpkg.com`, `cdnjs.cloudflare.com`, `code.jquery.com`,
-   `fonts.googleapis.com`, `fonts.gstatic.com`) and things a page is unusable
-   without (`js.stripe.com`, `pay.google.com`, `checkout.creem.io`,
-   `hcaptcha.com`, and reCAPTCHA — scoped to `www.google.com/recaptcha` and
+3. **The built-in allowlist**, readable as `ConsentKit._baseAllow`. Two parts:
+   **infrastructure** (`ConsentKit._infra()`, see below) and things a page is
+   unusable without (`js.stripe.com`, `pay.google.com`, `checkout.creem.io`,
+   and reCAPTCHA — scoped to `www.google.com/recaptcha` and
    `www.gstatic.com/recaptcha`, not to those hosts at large).
 4. **Known `necessary` / `functional` hosts** already granted, which keep their
    real category rather than being swept up as marketing.
@@ -481,23 +576,26 @@ external requests. Rebuild them with `tools/build-inline.mjs` (see
 [`tools/README.md`](tools/README.md)); each block's header records the exact
 command that produced it.
 
-ConsentKit 0.4.0, rebuilt 2026-09-05, uncompressed — gzip on the server cuts
+ConsentKit 0.5.0, rebuilt 2026-09-05, uncompressed — gzip on the server cuts
 this roughly three- to fourfold. Every block includes the branding extension
 and the attribution line; `--no-branding` drops both the code and the config
 and takes **~24 KB** back off:
 
 | Block | Languages | Bytes | gzip | `--no-branding` |
 |---|---|---|---|---|
-| `ready/en-bar.txt` | en | 134,969 | 40,519 | 110,907 |
-| `ready/ru-bar.txt` | ru, ro, en | 136,590 | 41,315 | 112,508 |
-| `ready/ru-box.txt` | ru, ro, en | 136,605 | 41,320 | 112,523 |
-| `ready/ru-box-right.txt` | ru, ro, en | 136,614 | 41,326 | 112,526 |
-| `ready/ru-modal.txt` | ru, ro, en | 136,598 | 41,318 | 112,514 |
-| `ready/eu-bar.txt` | 34 languages | 185,244 | 59,665 | 161,182 |
-
-0.4.0 adds roughly 16.1 KB over 0.3.6: iframe interception, strict mode
-(same-site detection, the allowlists, the public-suffix table) and the
-extensible tracker database.
+| `ready/en-bar.txt` | en | 160,388 | 48,950 | 136,326 |
+| `ready/ru-bar.txt` | ru, ro, en | 162,009 | 49,711 | 137,927 |
+| `ready/ru-box.txt` | ru, ro, en | 162,024 | 49,718 | 137,942 |
+| `ready/ru-box-right.txt` | ru, ro, en | 162,033 | 49,718 | 137,945 |
+| `ready/ru-modal.txt` | ru, ro, en | 162,017 | 49,713 | 137,933 |
+| `ready/eu-bar.txt` | 34 languages | 210,663 | 68,094 | 186,601 |
+
+0.5.0 adds roughly 18.5 KB over 0.4.1 (about 6.1 KB gzipped): the contrast
+engine, the per-button token resolution, the new stylesheet rules and the
+comments explaining the rules the arithmetic implements. 0.4.1 had added
+roughly 6.3 KB over 0.4.0 (the infrastructure list), and 0.4.0 roughly 16.1 KB
+over 0.3.6: iframe interception, strict mode (same-site detection, the
+allowlists, the public-suffix table) and the extensible tracker database.
 
 Size is driven almost entirely by the bundled languages: `en` and `ru` are
 built into the UI and cost nothing extra, while layout, position, theme and

package/npm/index.d.ts

@@ -59,17 +59,87 @@ export interface CkDarkTheme {
   accent?: string;
 }
 
+/** v0.5.0 (SPEC V1.6 §1). Corner radii in px, clamped to 0–32. */
+export interface CkRadiusConfig {
+  /** Banner, panel and table corners. Default `16`. */
+  card?: number;
+  /** Button corners. Default `8`. */
+  button?: number;
+}
+
+/**
+ * v0.5.0 (SPEC V1.6 §1). One button's appearance.
+ *
+ * Contrast is enforced automatically and cannot be switched off: `fg` is kept
+ * only when it clears 4.5:1 against the fill it sits on, otherwise it becomes
+ * white or `#161616`, whichever wins. An `outline` `border` is darkened or
+ * lightened in steps until it clears 3:1 against the card, and that resolved
+ * border colour is then the text colour, subject to the same 4.5:1 rule.
+ * `ConsentKit._contrast` exposes the arithmetic.
+ */
+export interface CkButtonStyle {
+  variant?: 'filled' | 'outline';
+  /** Fill. `filled` defaults to the accent; `outline` is transparent. */
+  bg?: string;
+  /** Text. Computed from the contrast rules when omitted. */
+  fg?: string;
+  /** Border. Defaults to the accent. */
+  border?: string;
+  /** `1` (default) or `2`. */
+  borderWidth?: 1 | 2;
+}
+
+/**
+ * v0.5.0 (SPEC V1.6 §1). Per-button appearance.
+ *
+ * `accept` and `reject` are held to the equal-buttons invariant: they always
+ * render at the same size and weight, and they always share one variant. If
+ * the two disagree, `accept.variant` is used for both.
+ */
+export interface CkButtonsConfig {
+  /** Default `{ variant: 'filled' }` with the accent as the fill. */
+  accept?: CkButtonStyle;
+  /** Default `{ variant: 'filled' }`; always follows `accept.variant`. */
+  reject?: CkButtonStyle;
+  /** Default `{ variant: 'outline' }` with the accent as the border. */
+  settings?: CkButtonStyle;
+}
+
 export interface CkThemeConfig {
   /** Accent colour, exposed as `--ck-accent`. Default `'#2B50D8'`. */
   accent?: string;
-  /** Corner radius, exposed as `--ck-radius`. Default `'10px'`. */
-  radius?: string;
+  /**
+   * v0.5.0. `{ card, button }` in px, 0–32. Default `{ card: 16, button: 8 }`.
+   *
+   * A bare string or number is the pre-0.5.0 form and still works: it sets the
+   * card radius and leaves the button radius at its default.
+   */
+  radius?: CkRadiusConfig | string | number;
+  /**
+   * v0.5.0. `'inherit'` (default) takes the host page's font family — sizes
+   * stay fixed either way. `'system'` restores the pre-0.5.0 system stack.
+   */
+  font?: 'inherit' | 'system';
+  /** v0.5.0. Per-button appearance; contrast is enforced automatically. */
+  buttons?: CkButtonsConfig;
   /** v0.2. Default `'auto'` — follows `prefers-color-scheme`. */
   mode?: 'auto' | 'light' | 'dark';
   /** v0.2. Overrides the built-in dark palette. */
   dark?: CkDarkTheme;
 }
 
+/** v0.5.0 (SPEC V1.6 §2). Copy and the «Learn more» control. */
+export interface CkTextsConfig {
+  /** Cookie policy address. `http(s)` only; anything else is ignored. */
+  policyUrl?: string;
+  /**
+   * What «Learn more» does. Defaults to `'policy'` when `policyUrl` is set and
+   * `'settings'` when it is not. `'policy'` without a usable URL falls back to
+   * `'settings'` rather than rendering a dead link. `'hide'` renders nothing.
+   */
+  detailsAction?: 'policy' | 'settings' | 'hide';
+}
+
 /** Whether a category is offered in the preferences panel at all. */
 export interface CkCategoryConfig {
   enabled?: boolean;
@@ -119,6 +189,8 @@ export interface CkConfig {
   language?: string;
   layout?: CkLayoutConfig;
   theme?: CkThemeConfig;
+  /** v0.5.0. */
+  texts?: CkTextsConfig;
   categories?: CkCategoriesConfig;
   /** Lifetime of the stored decision, in days. Default `365`. */
   consentTtlDays?: number;
@@ -180,14 +252,100 @@ export interface ConsentKitApi {
   /**
    * v0.4.0 (§2). The built-in strict-mode allowlist, as hosts plus a few
    * `host/path` entries (reCAPTCHA). A copy: mutating it changes nothing.
+   *
+   * Since v0.4.1 this includes the whole of `_infra()`.
    */
   readonly _baseAllow: string[];
 
+  /**
+   * v0.4.1 (§8). The infrastructure list: CDNs and static hosts of site
+   * builders and hosting platforms, general asset CDNs, fonts and captcha.
+   *
+   * A CLASS of host, not a consent category — these serve the site's own
+   * assets, so there is no consent decision to make about them. Strict mode
+   * never intercepts them, and the SaaS scanner keeps them out of the report.
+   * A copy: mutating it changes nothing.
+   */
+  _infra(): string[];
+
+  /**
+   * v0.4.1 (§8). Whether a URL — or a bare hostname — is infrastructure.
+   */
+  _isInfra(url: string): boolean;
+
   /** The category the engine would assign to a URL, or `null` if unknown. */
   _categoryForUrl(url: string): CkCategory | null;
 
   /** What is currently held back, host+path only — never a query string. */
   _blocked(): CkBlockedEntry[];
+
+  /**
+   * v0.5.0 (SPEC V1.6 §1). The contrast and theme arithmetic the banner
+   * actually paints with, as pure functions — so a theme editor quotes the
+   * same numbers rather than reimplementing them and drifting.
+   *
+   * Present only when `src/ck-ui.js` is loaded (the core alone does not draw).
+   * Colour arguments are hex; anything unmeasurable (a colour name, an `rgb()`
+   * string) yields `null` from the ratio functions and is returned untouched,
+   * with `adjusted: false`, by the rest.
+   */
+  readonly _contrast?: CkContrastApi;
+}
+
+/** One resolved button, as `ConsentKit._contrast.resolveButtonStyles()` returns it. */
+export interface CkResolvedButton {
+  variant: 'filled' | 'outline';
+  bg: string;
+  fg: string;
+  border: string;
+  borderWidth: 1 | 2;
+  /** Text contrast against `against`. `null` when it could not be measured. */
+  ratio: number | null;
+  /** `true` when the contrast rules overrode what the config asked for. */
+  adjusted: boolean;
+  /** Border contrast against the card (`outline` only). */
+  borderRatio?: number | null;
+  borderAdjusted?: boolean;
+  /** What `ratio` was measured against: the button's own fill, or the card. */
+  against: string;
+}
+
+export interface CkResolvedButtons {
+  mode: 'light' | 'dark';
+  cardBg: string;
+  accent: string;
+  buttons: { accept: CkResolvedButton; reject: CkResolvedButton; settings: CkResolvedButton };
+}
+
+/** v0.5.0. `ConsentKit._contrast` — pure, DOM-free, safe to call in Node. */
+export interface CkContrastApi {
+  /** WCAG 2.1 relative luminance, 0–1. `null` for an unmeasurable colour. */
+  relativeLuminance(hex: string): number | null;
+  /** WCAG 2.1 contrast ratio, 1–21. `null` when either side is unmeasurable. */
+  contrastRatio(a: string, b: string): number | null;
+  /** Keeps `fg` when it clears `min`, else white or `#161616` — whichever wins. */
+  ensureContrast(fg: string, bg: string, min?: number):
+    { color: string; adjusted: boolean; ratio: number | null };
+  /** Darkens or lightens `color` in steps until it clears `min` against `bg`. */
+  stepToContrast(color: string, bg: string, min?: number):
+    { color: string; adjusted: boolean; ratio: number | null };
+  /** The three buttons resolved for one palette, contrast already applied. */
+  resolveButtonStyles(theme: CkThemeConfig, mode: 'light' | 'dark',
+    palette?: Record<string, string>): CkResolvedButtons;
+  resolveRadius(theme: CkThemeConfig): { card: number; button: number };
+  resolveFont(theme: CkThemeConfig): string;
+  /** Takes the whole config, not just `texts`. */
+  resolveDetails(config: CkConfig):
+    { kind: 'policy' | 'settings' | 'hide'; href: string | null };
+  /** Takes the whole config. Returns the generated stylesheet and both palettes. */
+  buildThemeCss(config: CkConfig): {
+    css: string;
+    mode: 'auto' | 'light' | 'dark';
+    radius: { card: number; button: number };
+    font: string;
+    light: CkResolvedButtons;
+    dark: CkResolvedButtons;
+  };
 }
 
 /** One entry of `ConsentKit._blocked()`. */

package/npm/internal-stub.mjs

@@ -28,7 +28,7 @@ export function undecidedState() {
  */
 export function createStub() {
   const stub = {
-    version: '0.4.0',
+    version: '0.5.1',
     config: {},
     init: function () { return undecidedState(); },
     allowed: function (cat) { return cat === 'necessary'; },
@@ -44,6 +44,11 @@ export function createStub() {
     _extendHostDb: function () { return 0; },
     _baseAllow: [],
     _categoryForUrl: function () { return null; },
+    // v0.4.1 (§8): the infrastructure list. Empty here for the same reason
+    // _baseAllow is — a stub means the engine never attached, so it is not
+    // letting anything through and must not claim a list it does not enforce.
+    _infra: function () { return []; },
+    _isInfra: function () { return false; },
     _blocked: function () { return []; },
     _isStub: true
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecomconsult/consentkit",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "GDPR cookie consent core with blocking engine, Shadow DOM UI and Google Consent Mode v2. Zero dependencies, no build step.",
   "repository": {
     "type": "git",