npm - @ecomconsult/consentkit - Versions diffs - 0.3.5 → 0.5.0 - Mend

@ecomconsult/consentkit 0.3.5 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md CHANGED Viewed

@@ -44,7 +44,7 @@ Four ways to add ConsentKit to a site, from simplest to most integrated.
 |---|---|---|---|
 | 1 | **Script tags** — copy `src/` to your server, three `<script>` tags in `<head>` | Any site you control | [Quickstart below](#quickstart--script-tags) |
 | 2 | **npm** — `npm install @ecomconsult/consentkit` | Bundled apps, React | [Quickstart below](#quickstart--npm) |
-| 3 | **WordPress plugin** — copy the plugin folder to `wp-content/plugins/` | WordPress / WooCommerce | [`plugins/wordpress/consentkit/`](plugins/wordpress/consentkit/) |
+| 3 | **WordPress plugin** — copy the plugin folder to `wp-content/plugins/`; rewrites static tracker tags server-side | WordPress / WooCommerce | [`plugins/wordpress/consentkit/`](plugins/wordpress/consentkit/) |
 | 4 | **Google Tag Manager** — import the container, trigger tags on consent events | Sites already running GTM | [`integrations/gtm/README.md`](integrations/gtm/README.md) |
 ```sh
@@ -66,6 +66,7 @@ must come first and should not be deferred.
 ```html
 <script src="/consentkit/src/ck-core.js"></script>
 <script src="/consentkit/src/ck-locales.js"></script><!-- optional: extra languages -->
+<script src="/consentkit/src/ck-ui-branding.js"></script><!-- optional: logo / attribution -->
 <script src="/consentkit/src/ck-ui.js"></script>
 <script>
   ConsentKit.init({
@@ -178,16 +179,23 @@ 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 |
 | `integrations.gtmDataLayer` | `boolean` | `true` | Push consent events to `window.dataLayer` |
+| `blocking.mode` | `"known" \| "strict"` | `"known"` | `strict` also holds back unknown third-party scripts and iframes — see [Strict mode](#strict-mode) |
+| `blocking.allow` | `string[]` | `[]` | Hosts strict mode must never intercept. Matched by suffix, so `partner.com` also covers `cdn.partner.com` |
+| `hostdb` | `Record<string, Category>` | — | Extra `host: category` pairs merged into the tracker database, applied before the initial scan. SaaS mode fills this from the service; `ConsentKit._extendHostDb()` does the same at any later point |
 | `cookieTable` | `CkCookieTableEntry[]` | `[]` | Declared cookies, listed per category in the panel |
 `cookieTable` entries:
@@ -196,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.
@@ -279,6 +379,11 @@ Iframes use `data-src`, which is applied once the category is allowed:
 `data-ck` accepts any category name: `functional`, `analytics`, `marketing`.
+> On WordPress this markup is applied **automatically, server-side**, for every
+> tracker in the built-in database — see "Server-side markup" below. Manual
+> markup is still needed for trackers the database does not know (your own
+> domain, an unlisted vendor) and for inline snippets.
 ### Automatic blocking
 Scripts injected at runtime are intercepted without any markup. ConsentKit
@@ -301,6 +406,129 @@ and DoubleClick.
 Because the patches install at parse time, `ck-core.js` must load before any
 tracker — put it first in `<head>` and do not add `defer`.
+`<iframe src>` is covered by the same three patches, and a blocked frame keeps
+its URL in `data-src` until its category is granted.
+### Extending the tracker database
+The built-in host list is a snapshot, not an oracle. `_extendHostDb()` merges
+extra `host: category` pairs into it at runtime:
+```js
+ConsentKit._extendHostDb({
+  'analytics.vendor.example': 'analytics',
+  'pixel.partner.example': 'marketing'
+});
+```
+Matching is the same as for built-in entries — a bare domain also covers its
+subdomains — and an override wins over the shipped classification for the same
+host. Categories outside `necessary | functional | analytics | marketing` and
+malformed hostnames are ignored; the call returns how many pairs were accepted.
+It works both **before and after** `init()`. Calling it afterwards does not
+re-examine anything already inserted (a script that has loaded cannot be
+unloaded), but every later insertion is classified against the extended map.
+In SaaS mode this is automatic: `ck-saas.js` applies `config.hostdb` from the
+service *before* it calls `init()`, and again when a background revalidation
+brings a changed table. At release time `node tools/sync-hostdb.mjs` bakes the
+same public table into `src/ck-core.js`, so inline blocks, the npm package and
+the WordPress plugin get it too.
+### Strict mode
+By default ConsentKit blocks what it **recognises**. `blocking.mode: 'strict'`
+inverts that for third parties: before consent, any `<script src>` or
+`<iframe src>` pointing at a host that is not same-site is intercepted, whether
+or not the tracker database has ever heard of it.
+```js
+ConsentKit.init({
+  blocking: { mode: 'strict', allow: ['widgets.partner.example'] }
+});
+```
+Four things are never intercepted:
+1. **Same-site URLs** — the page's own host, its subdomains, and anything
+   sharing its registrable domain. The check is deliberately conservative: when
+   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`. 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.
+Anything else is filed under **`marketing`** — the strictest category — and
+comes back only when the visitor accepts marketing.
+**Read this before switching it on.** Strict mode will block third-party code
+your site needs and that ConsentKit has no way to recognise as necessary: a
+booking widget, a map, a review embed, a payment provider that is not on the
+list. Turn it on, load the site with `?ck_debug=1`, and read the "Blocked until
+consent" list in the panel — entries the engine held back only because of strict
+mode are labelled `strict`. Everything there that the page genuinely needs
+belongs in `blocking.allow`.
+Two limits are worth stating plainly:
+* **Dynamic insertions only**, exactly as for known trackers. A tag written
+  straight into the HTML starts its request before ConsentKit runs (see below).
+  The WordPress plugin's server-side rewrite currently marks up *known* trackers
+  only; extending it to strict mode is recorded as a follow-up in SPEC.md.
+* **Strict starts when the config does.** The mode is read from `config`, so in
+  SaaS mode nothing is blocked strictly until the config has arrived. Blocking
+  of *known* trackers still begins at parse time, as always.
+### Static tags: what the browser cannot catch
+Runtime injection is covered by the patches above. A tracker tag written
+**directly into the HTML** is not: the parser starts that request before the
+first line of `ck-core.js` runs. The gap was measured (debt Д9: request at
+14 ms, our script at 18 ms) and it is negative — no client-side technique
+closes it. Such tags need either manual markup, or a server that rewrites them
+before the page is sent.
+### Server-side markup (WordPress plugin)
+The WordPress plugin does exactly that, and it is **on by default** since 0.3.5.
+While the page is generated, it rewrites tracker tags in the finished HTML:
+```html
+<!-- what the theme wrote -->
+<script src="https://mc.yandex.ru/metrika/tag.js"></script>
+<!-- what the browser receives -->
+<script type="text/plain" data-ck="analytics"
+        data-ck-src="https://mc.yandex.ru/metrika/tag.js"></script>
+```
+`<iframe src>` of a known host becomes `data-ck` + `data-src` with `src`
+removed. The categories come from the same HOST_DB/PATH_DB as the browser
+engine: `tools/export-hostdb.mjs` generates
+`plugins/wordpress/consentkit/includes/hostdb.php` from `src/ck-core.js`, and
+`test/hostdb.test.mjs` fails if the two drift.
+What it skips: ConsentKit's own assets, tags carrying `data-ck-ignore`, tags
+already marked up by hand, inline scripts (there is no URL to defer), the GTM
+container, and anything inside comments, `<pre>` or `<textarea>`. On any error
+the page is returned unchanged.
+The `<pre>` / `<textarea>` skip keeps the *source text* byte-identical, which is
+what a page documenting a tracker snippet needs. It does not keep such a tag
+alive: the browser parses `<pre><script src=…>` as a real script element
+whatever the server did, so the runtime engine may still intercept it. Caching plugins are compatible and get the
+already-rewritten HTML, because the rewrite happens at the PHP level before the
+page is cached.
+Outside WordPress the same idea applies to any server-side template: emit the
+`type="text/plain" data-ck` form directly, as in "Manual markup" above.
 ## Google Consent Mode v2
 With `integrations.gcm` (default), the core pushes `consent: default` with every
@@ -348,18 +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.3.5, rebuilt 2026-09-04, uncompressed — gzip on the server cuts
-this roughly three- to fourfold. Every block includes the attribution line;
-`--no-branding` takes ~200 bytes back off:
-| Block | Languages | Bytes |
-|---|---|---|
-| `ready/en-bar.txt` | en | 111,664 |
-| `ready/ru-bar.txt` | ru, ro, en | 113,285 |
-| `ready/ru-box.txt` | ru, ro, en | 113,300 |
-| `ready/ru-box-right.txt` | ru, ro, en | 113,309 |
-| `ready/ru-modal.txt` | ru, ro, en | 113,293 |
-| `ready/eu-bar.txt` | 34 languages | 161,939 |
+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 | 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
@@ -540,13 +776,19 @@ has been verified and what has not.
 - `dataLayer` event trace for consent restore, upgrade and withdrawal.
 - npm entry points and TypeScript types: syntax and import smoke tests in Node
   without a DOM.
-- PHP files of the WordPress plugin pass `php -l` on 7.4 and 8.5.
+- PHP files of the WordPress plugin pass `php -l` on 7.4, 8.3 and 8.5.
+- The server-side rewriting engine has its own suite of 61 cases
+  (`plugins/wordpress/consentkit/tests/rewrite.test.php`), green on PHP 7.4,
+  8.3 and 8.5. It is a plain PHP CLI script, so it runs outside `npm test`.
 ### Not verified — read before production use
-- **The WordPress plugin has never run on a live WordPress install.** It passes
-  linting and review, but no activation, settings round-trip, theme conflict or
-  multisite behaviour has been observed in a real installation.
+- **The WordPress plugin has been verified on a live install, but only one.**
+  It was run on WordPress 7.1 / PHP 8.3 in Docker (activation, settings
+  round-trip, shortcode, uninstall, server-side markup end to end). The declared
+  floor of WordPress 6.0 / PHP 7.4 has not been exercised live — the PHP files
+  pass `php -l` and the rewriting test suite on 7.4, 8.3 and 8.5 — and no theme
+  conflict or multisite behaviour has been observed.
 - **The GTM container has never been through a real import.** The JSON is valid
   and structurally modelled on the documented export format, but Tag Manager has
   not accepted it in practice; some field names (notably GA4 config

package/npm/core.mjs CHANGED Viewed

@@ -28,6 +28,9 @@ export const {
   rejectAll,
   withdraw,
   show,
-  hide
+  hide,
+  // v0.4.0 (§1.3): merging service overrides into the tracker database is part
+  // of the public surface, so it must be reachable as a named import too.
+  _extendHostDb
 } = ConsentKit;
 export { ConsentKit };

package/npm/index.cjs CHANGED Viewed

@@ -69,7 +69,10 @@ var hasDom = typeof document !== 'undefined' && typeof window !== 'undefined';
 if (hasDom) {
   // 2. Locales — optional language packs.
   try { require('../src/ck-locales.js'); } catch (e) { /* optional */ }
-  // 3. UI — touches `document` at module scope, browser only.
+  // 3. Branding — optional, and before the UI: it registers itself on
+  //    ConsentKit._uiExtensions and must be there before the first mount().
+  try { require('../src/ck-ui-branding.js'); } catch (e) { /* optional */ }
+  // 4. UI — touches `document` at module scope, browser only.
   try { require('../src/ck-ui.js'); } catch (e) { /* best effort */ }
 }

package/npm/index.d.ts CHANGED Viewed

@@ -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;
@@ -88,6 +158,20 @@ export interface CkIntegrationsConfig {
   gtmDataLayer?: boolean;
 }
+/** v0.4.0 (§2). How much the blocking engine holds back before consent. */
+export interface CkBlockingConfig {
+  /**
+   * `'known'` (default) blocks what the tracker database recognises.
+   * `'strict'` additionally intercepts EVERY third-party `<script src>` and
+   * `<iframe src>` that is not same-site, not in `allow`, not in the built-in
+   * allowlist (`ConsentKit._baseAllow`) and not an already-granted
+   * necessary/functional host. Interceptions are filed under `marketing`.
+   */
+  mode?: 'known' | 'strict';
+  /** Hosts strict mode must never intercept. Suffix match: `p.com` covers `cdn.p.com`. */
+  allow?: string[];
+}
 /** One declared cookie, shown under its category in the preferences panel. */
 export interface CkCookieTableEntry {
   name: string;
@@ -105,10 +189,21 @@ 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;
   integrations?: CkIntegrationsConfig;
+  /** v0.4.0. Default `{ mode: 'known', allow: [] }`. */
+  blocking?: CkBlockingConfig;
+  /**
+   * v0.4.0 (§1.3). Extra `host: category` pairs merged into the tracker
+   * database. `init()` applies them before its initial scan, so scripts
+   * already in the markup are classified against them. In SaaS mode the
+   * service supplies this; `_extendHostDb()` does the same at any later point.
+   */
+  hostdb?: Record<string, CkCategory>;
   cookieTable?: CkCookieTableEntry[];
 }
@@ -141,6 +236,136 @@ export interface ConsentKitApi {
   show(): void;
   /** Dispatches `ck:ui:close`. */
   hide(): void;
+  /**
+   * v0.4.0 (§1.3). Merges `{ host: category }` into the runtime tracker
+   * database and returns how many pairs were accepted. Matching follows the
+   * built-in table: a bare domain also covers its subdomains, and an override
+   * wins over the shipped classification for the same host.
+   *
+   * Safe before AND after `init()`. Afterwards, nothing already inserted is
+   * re-examined — a script that has loaded cannot be unloaded — but every
+   * later insertion is classified against the extended map.
+   */
+  _extendHostDb(map: Record<string, CkCategory>): number;
+  /**
+   * 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()`. */
+export interface CkBlockedEntry {
+  host: string;
+  path: string;
+  /** `'script'`, `'iframe'`, … */
+  kind: string;
+  category: CkCategory | null;
+  /** `'engine'` — intercepted by the patches; `'markup'` — marked up by hand. */
+  origin: 'engine' | 'markup';
+  /** v0.4.0. True when strict mode held this back, i.e. the host is unknown. */
+  strict: boolean;
+  /**
+   * v0.4.0. `false` when the category was granted but the element still never
+   * loaded — typically a script created and given a `src` without ever being
+   * appended, which `applyConsentToDom()` cannot reach. Such entries stay in
+   * the report after consent precisely so they can be diagnosed.
+   */
+  revived: boolean;
 }
 declare const ConsentKit: ConsentKitApi;
@@ -156,6 +381,7 @@ export declare function rejectAll(): CkState;
 export declare function withdraw(): CkState;
 export declare function show(): void;
 export declare function hide(): void;
+export declare function _extendHostDb(map: Record<string, CkCategory>): number;
 declare global {
   interface Window {