@ecomconsult/consentkit 0.5.5 → 0.5.7

package/README.md

@@ -188,13 +188,15 @@ Pass any subset to `init()`. Nested objects merge with the defaults.
 | `theme.mode` | `"auto" \| "light" \| "dark"` | `"auto"` | `auto` follows `prefers-color-scheme` |
 | `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 |
+| `texts.detailsAction` | `"policy" \| "settings" \| "hide" \| "declaration"` | see notes | v0.5.0, `declaration` in v0.5.7. What «Learn more» does. Defaults to `policy` when `policyUrl` is set, `settings` when it is not. `policy` or `declaration` without a usable URL falls back to `settings` rather than rendering a dead link |
+| `texts.declarationUrl` | `string` | — | v0.5.7. Address of the cookie declaration page, used by `detailsAction: "declaration"`. `http(s)` only. Filled by the hosted service; the client only reads it |
 | `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` |
+| `blocking.placeholders` | `boolean` | `true` | v0.5.7. Draw a card in place of an embed held back before consent — see [Placeholders for blocked embeds](#placeholders-for-blocked-embeds). `false` restores the pre-0.5.7 behaviour: the frame is still blocked, just invisible |
 | `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 |
 
@@ -267,14 +269,69 @@ resolved colours, its contrast ratio, and whether the value was adjusted.
 | `"policy"` | A link to `texts.policyUrl`, opened with `target="_blank" rel="noopener"` |
 | `"settings"` | A button that opens the preferences panel |
 | `"hide"` | Nothing at all |
+| `"declaration"` | v0.5.7. A link to `texts.declarationUrl` — the cookie declaration page — opened the same way as `policy` |
 
 The default follows `policyUrl`: `policy` when one is set, `settings` when it
-is not — so supplying only a URL does the obvious thing.
+is not — so supplying only a URL does the obvious thing. `declarationUrl`
+deliberately does *not* affect that default: a site that gains a declaration
+address keeps whatever «Learn more» already did until it asks for the change.
+
+Both link forms accept `http(s)` addresses only. A `javascript:` or `data:` URL
+in a control the visitor is invited to click is an XSS vector, so anything else
+is refused and the link degrades to `settings`.
 
 > 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.
 
+### Reopening the settings
+
+`ConsentKit.openSettings()` opens the preferences panel from anywhere on the
+page — a footer link, a menu item, a button in your own cookie policy. It is
+safe to call before the banner has mounted: a call that arrives while the UI
+file is still loading is remembered and honoured on mount, so a link clicked
+during a slow page load still works.
+
+The same panel has an address. Ссылка «Изменить выбор cookie» →
+`https://site/#ck-settings`: любая ссылка на страницу сайта с этим хвостом
+открывает окно настроек — и при загрузке страницы, и при переходе по ссылке на
+уже открытой странице. Хвост убирается из адреса через `history.replaceState`,
+поэтому перезагрузка или «назад» не открывают окно повторно. Это тот адрес, на
+который ведёт кнопка «Изменить выбор cookie» на странице декларации cookie, и
+его же удобно поставить в подвал сайта:
+
+```html
+<a href="#ck-settings">Изменить выбор cookie</a>
+```
+
+### Placeholders for blocked embeds
+
+When the engine holds back an `<iframe>` before consent — a known tracker, or
+any third-party frame in strict mode — the visitor would otherwise see an empty
+hole where a video or a map should be. Since 0.5.7 ConsentKit draws a card in
+its place: the name of the service, the category the embed is waiting for, a
+primary button «Разрешить и показать» that grants **that one category** and
+loads the embed, and a link to the full settings panel.
+
+The card is sized from the frame's own `width`/`height` (or its computed size),
+never shorter than 120px, and never wider than its container. It is rendered in
+its own Shadow DOM and takes the banner's theme — the page's font, your accent
+colour and corner radius — so it looks like part of the site rather than part of
+a third-party widget. Strings ship in ru, ro and en; every other language falls
+back to en.
+
+The button grants one category through the ordinary consent path: the decision
+is stored and journalled as `method: 'custom'`, the usual `ck:consent` /
+`ck:change` events fire, and consent the visitor had already given to *other*
+categories is preserved rather than overwritten. The frame itself is restored by
+the core's normal revival pass, which is the same code path the panel's switches
+and «Accept all» already use.
+
+Frames that are `display:none`, 1×1 tracking pixels, or outside `<body>` are
+left alone, and a frame the site allowed never gets a card at all — an allowed
+frame is never intercepted in the first place. Set `blocking.placeholders:
+false` to restore the pre-0.5.7 behaviour.
+
 ### Infrastructure
 
 Some third-party hosts are not a consent decision at all: they are where a site
@@ -310,6 +367,7 @@ All methods are safe to call at any time and never throw.
 | `rejectAll()` | `CkState` | Denies every opt-in category. `method: 'reject_all'` |
 | `withdraw()` | `CkState` | Clears storage and known cookies, sends GCM `denied`, resets to `decided: false` |
 | `show()` | `void` | Opens the preferences panel |
+| `openSettings()` | `void` | v0.5.7. Opens the preferences panel. Safe before the UI has loaded — the request is remembered and honoured as soon as the banner mounts |
 | `hide()` | `void` | Closes the panel |
 | `config` | `CkConfig` | The merged, effective config |
 | `version` | `string` | Core version string |
@@ -555,6 +613,11 @@ Removing it is a supported, first-class option — no obligation, no nag:
 node tools/build-inline.mjs --langs=en,ru --no-branding   # block without it
 ```
 
+The line is `branding.poweredBy.text`; with `language: 'auto'` supply
+`branding.poweredBy.texts` instead — `{ ru: '…', ro: '…', en: '…' }`, resolved
+against the language the banner actually picked (`texts[lang]` → base code →
+`texts.en` → `text`), so the attribution matches what the visitor is reading.
+
 If you write the config by hand, simply omit the `branding` object; nothing
 renders without it. Either way costs you ~200 bytes, not a licence: the client
 is MIT and the line is yours to drop.

package/npm/core.cjs

@@ -30,6 +30,7 @@ function createStub() {
     rejectAll: function () { return undecidedState(); },
     withdraw: function () { return undecidedState(); },
     show: function () {},
+    openSettings: function () {},
     hide: function () {},
     _categories: CATEGORIES.slice(),
     _isStub: true

package/npm/core.mjs

@@ -28,6 +28,9 @@ export const {
   rejectAll,
   withdraw,
   show,
+  // v0.5.7: the public name for «open the cookie settings», safe to call
+  // before the UI has loaded.
+  openSettings,
   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.

package/npm/index.cjs

@@ -33,6 +33,7 @@ function createStub() {
     rejectAll: function () { return undecidedState(); },
     withdraw: function () { return undecidedState(); },
     show: function () {},
+    openSettings: function () {},
     hide: function () {},
     _categories: CATEGORIES.slice(),
     _isStub: true

package/npm/index.d.ts

@@ -136,8 +136,17 @@ export interface CkTextsConfig {
    * 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.
+   * v0.5.7 adds `'declaration'`: a link to {@link CkTextsConfig.declarationUrl},
+   * the cookie declaration page, which likewise degrades to `'settings'`
+   * without a usable URL.
    */
-  detailsAction?: 'policy' | 'settings' | 'hide';
+  detailsAction?: 'policy' | 'settings' | 'hide' | 'declaration';
+  /**
+   * v0.5.7. Address of the cookie declaration page, used by
+   * `detailsAction: 'declaration'`. `http(s)` only. Supplied by the hosted
+   * service; the client only reads it.
+   */
+  declarationUrl?: string;
 }
 
 /** Whether a category is offered in the preferences panel at all. */
@@ -170,6 +179,12 @@ export interface CkBlockingConfig {
   mode?: 'known' | 'strict';
   /** Hosts strict mode must never intercept. Suffix match: `p.com` covers `cdn.p.com`. */
   allow?: string[];
+  /**
+   * v0.5.7. Draw a card in place of an `<iframe>` held back before consent,
+   * offering «Разрешить и показать» for that one category. Default `true`;
+   * `false` restores the pre-0.5.7 behaviour (still blocked, just invisible).
+   */
+  placeholders?: boolean;
 }
 
 /** One declared cookie, shown under its category in the preferences panel. */
@@ -234,6 +249,12 @@ export interface ConsentKitApi {
   withdraw(): CkState;
   /** Dispatches `ck:ui:open-preferences`. */
   show(): void;
+  /**
+   * v0.5.7. Opens the preferences panel. Unlike {@link show}, a call made
+   * before the UI has loaded is remembered and honoured once the banner
+   * mounts, so a footer link clicked during a slow load still works.
+   */
+  openSettings(): void;
   /** Dispatches `ck:ui:close`. */
   hide(): void;
 
@@ -380,6 +401,7 @@ export declare function accept(choice?: CkAcceptArg): CkState;
 export declare function rejectAll(): CkState;
 export declare function withdraw(): CkState;
 export declare function show(): void;
+export declare function openSettings(): void;
 export declare function hide(): void;
 export declare function _extendHostDb(map: Record<string, CkCategory>): number;
 
@@ -410,6 +432,7 @@ declare module '@ecomconsult/consentkit' {
   export function rejectAll(): CkState;
   export function withdraw(): CkState;
   export function show(): void;
+  export function openSettings(): void;
   export function hide(): void;
 }
 
@@ -424,6 +447,7 @@ declare module '@ecomconsult/consentkit/core' {
   export function rejectAll(): CkState;
   export function withdraw(): CkState;
   export function show(): void;
+  export function openSettings(): void;
   export function hide(): void;
 }
 

package/npm/index.mjs

@@ -51,6 +51,9 @@ export const {
   rejectAll,
   withdraw,
   show,
+  // v0.5.7: the public name for «open the cookie settings», safe to call
+  // before the UI has loaded.
+  openSettings,
   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.

package/npm/internal-stub.mjs

@@ -28,7 +28,7 @@ export function undecidedState() {
  */
 export function createStub() {
   const stub = {
-    version: '0.5.5',
+    version: '0.5.7',
     config: {},
     init: function () { return undecidedState(); },
     allowed: function (cat) { return cat === 'necessary'; },
@@ -37,6 +37,7 @@ export function createStub() {
     rejectAll: function () { return undecidedState(); },
     withdraw: function () { return undecidedState(); },
     show: function () {},
+    openSettings: function () {},
     hide: function () {},
     _categories: CATEGORIES.slice(),
     // v0.4.0: the stub mirrors the real surface, so consumer code that calls

package/package.json

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

package/src/ck-core.js

@@ -1537,7 +1537,7 @@
   // Public API
   // ---------------------------------------------------------------------------
   var ConsentKit = {
-    version: '0.5.5',
+    version: '0.5.7',
     config: config,
 
     init: function (userConfig) {
@@ -1597,6 +1597,28 @@
     show: function () { dispatch('ck:ui:open-preferences', { state: publicState(), config: config }); },
     hide: function () { dispatch('ck:ui:close', { state: publicState() }); },
 
+    /* SPEC V1.10 §1 — the public name for «открыть настройки cookie». A site
+       puts it behind a footer link, and the declaration page links to
+       `https://site/#ck-settings`, which ck-ui turns into the same call.
+
+       Deliberately not just an alias of show(): the event is a broadcast, and a
+       page that calls openSettings() before ck-ui.js has been PARSED has no
+       listener to receive it — the request would be silently lost, which is the
+       one case a footer link hits (a click during a slow load). So the request
+       is latched here as well as dispatched, and ck-ui's mount() consumes the
+       latch at the end of its first render. ck-ui already writes to this object
+       (_contrast, _resolvePageFont), so the coupling direction is established.
+
+       `_pendingOpen` is read-and-cleared by ck-ui; nothing else touches it. */
+    openSettings: function () {
+      try { ConsentKit._pendingOpen = true; } catch (e) { /* noop */ }
+      dispatch('ck:ui:open-preferences', { state: publicState(), config: config });
+    },
+
+    // Set by openSettings() when the UI may not be listening yet; cleared by
+    // ck-ui.js the moment it can honour it. Underscored: not a public API.
+    _pendingOpen: false,
+
     // Introspection helpers for the demo status panel (read-only).
     _categoryForUrl: categoryForUrl,
     _categories: CATEGORIES.slice(),

package/src/ck-locales.js

@@ -572,6 +572,12 @@
     colPurpose: 'Pentru ce',
     colExpiry: 'Expiră',
     floating: 'Setări cookie-uri',
+    // SPEC V1.10 §2 — заглушка встраивания. Only ro carries these here: en and
+    // ru are builtin in ck-ui.js, and every other locale falls back to en.
+    phText: 'Aici este conținut de la {host}. Se va încărca după acordul pentru «{cat}».',
+    phAllow: 'Permite și arată',
+    phSettings: 'Setări cookie-uri',
+    phLabel: 'Conținut blocat',
     cat: {
       necessary: { title: 'Necesare', desc: 'Sunt necesare pentru funcționarea site-ului: autentificare, securitate, reținerea alegerii dumneavoastră. Nu pot fi dezactivate.' },
       functional: { title: 'Funcționale', desc: 'Rețin alegerile dumneavoastră: limba, coșul, chatul.' },

package/src/ck-ui-branding.js

@@ -348,6 +348,34 @@
     return out.join('\n');
   }
 
+  /* Pick the attribution line for the language the banner actually resolved to.
+
+     A SaaS server renders one config per site but cannot know the visitor's
+     language: with `language: 'auto'` the code that decides is ck-ui's
+     resolveLang(), in the browser, long after the config was serialised. So a
+     single `poweredBy.text` produced "Made by E-COM Consult" under a fully
+     Russian banner. `poweredBy.texts` lets the server send every line it has
+     and leaves the choice here, where the resolved language is known.
+
+     host.lang is the code ck-ui resolved ('ru', 'pt-br', ...). It is optional
+     on purpose: a page still running an older cached ck-ui.js passes no lang,
+     and that must degrade to the English/`text` line rather than throw. */
+  function pickPoweredByText(texts, lang, str) {
+    if (!texts || typeof texts !== 'object' || Array.isArray(texts)) return null;
+    var code = (typeof lang === 'string') ? lang.toLowerCase() : '';
+    // Own keys only. ck-ui's resolveLang() can only return a real locale key or
+    // 'en', so 'constructor' never arrives through the normal path — but `host`
+    // is caller-supplied on a published extension entry point, and reading an
+    // inherited key would hand str() a function instead of a missing line.
+    // Values go through str() as well, so anything non-string falls through.
+    function own(k) {
+      return (k && Object.prototype.hasOwnProperty.call(texts, k)) ? str(texts[k]) : null;
+    }
+    var hit = own(code);
+    if (!hit && code.length > 2) hit = own(code.slice(0, 2));          // ru-RU -> ru
+    return hit || own('en');
+  }
+
   /* Powered-by line. true -> localised default; object -> caller's text/url.
      Rendered after the actions in DOM order and styled quiet on purpose. */
   function buildPoweredBy(cfg, host) {
@@ -361,7 +389,8 @@
     if (pb === true) {
       text = T.poweredBy;                          // en fallback guaranteed by STR_KEYS
     } else if (typeof pb === 'object' && !Array.isArray(pb)) {
-      text = str(pb.text) || T.poweredBy;
+      // texts[lang] -> texts[base] -> texts.en -> text -> T.poweredBy
+      text = pickPoweredByText(pb.texts, host.lang, str) || str(pb.text) || T.poweredBy;
       url = safeLinkUrl(pb.url);
     } else {
       return null;
@@ -467,12 +496,26 @@
      styling, so a config that gains a logo after the first ck:init has to
      rebuild rather than restyle. Returns '-' when there is no branding config,
      which is what keeps an unbranded page's signature stable. */
+  function textsSig(texts) {
+    if (!texts || typeof texts !== 'object' || Array.isArray(texts)) return '-';
+    var keys = [], k;
+    for (k in texts) {
+      if (Object.prototype.hasOwnProperty.call(texts, k) && str(texts[k])) keys.push(k);
+    }
+    keys.sort();
+    var out = [];
+    for (var i = 0; i < keys.length; i++) out.push(keys[i] + '=' + str(texts[keys[i]]));
+    return out.join(',');
+  }
+
   function brandSignature(cfg) {
     var b = brandingCfg(cfg);
     if (!b) return '-';
     var pb = b.poweredBy;
+    // texts is folded in with sorted keys so the signature is stable across key
+    // order — without it a server swapping only `texts` would not remount.
     var pbSig = (pb && typeof pb === 'object')
-      ? 'o:' + String(pb.text || '') + ':' + String(pb.url || '')
+      ? 'o:' + String(pb.text || '') + ':' + String(pb.url || '') + ':' + textsSig(pb.texts)
       : String(!!pb);
     // Logos are hashed by length + head so a long data: URI does not bloat the key.
     function tag(v) {

package/src/ck-ui.js

@@ -32,6 +32,14 @@
       colExpiry: 'Expires',
       floating: 'Cookie settings',
       poweredBy: 'Powered by ConsentKit',
+      // SPEC V1.10 §2 — the blocked-embed placeholder. {host} is the vendor
+      // label when the database knows one and the bare host otherwise; {cat} is
+      // the localized category title, taken from cat.<name>.title below, so the
+      // name in the placeholder is the name on the switch in the panel.
+      phText: 'Content from {host} goes here. It will load once you allow «{cat}».',
+      phAllow: 'Allow and show',
+      phSettings: 'Cookie settings',
+      phLabel: 'Blocked content',
       cat: {
         necessary: {
           title: 'Necessary',
@@ -72,6 +80,10 @@
       colExpiry: 'Срок',
       floating: 'Настройки cookie',
       poweredBy: 'Работает на ConsentKit',
+      phText: 'Здесь содержимое от {host}. Оно загрузится после согласия на «{cat}».',
+      phAllow: 'Разрешить и показать',
+      phSettings: 'Настроить cookie',
+      phLabel: 'Заблокированное содержимое',
       cat: {
         necessary: {
           title: 'Необходимые',
@@ -103,7 +115,11 @@
     'bannerTitle', 'bannerText', 'more', 'acceptAll', 'rejectAll', 'customize',
     'bannerLabel', 'panelTitle', 'panelIntro', 'save', 'close', 'alwaysOn',
     'cookiesIn', 'noCookies', 'colName', 'colVendor', 'colPurpose', 'colExpiry', 'floating',
-    'poweredBy'
+    'poweredBy',
+    // SPEC V1.10 §2. Present in ck-locales.js for ro only; every other external
+    // locale falls back to DICT.en through buildStrings(), which is what §2
+    // asks for («остальные языки — en»).
+    'phText', 'phAllow', 'phSettings', 'phLabel'
   ];
 
   // builtin(en,ru) <- window.__ckLocales, read at render time so the locales
@@ -161,6 +177,47 @@
     return out;
   }
 
+  /* ------------------------------------------- blocked-embed placeholder (§2) */
+
+  /* The one piece of the placeholder that is worth testing without a DOM: which
+     sentence a visitor reads. PURE — takes a host (or vendor label), a category
+     name and a language, returns the finished string.
+
+     `host` is used verbatim: the core has no vendor-label table (only the SaaS
+     scanner's VENDOR_DB does, server-side), so §2's «ярлык хоста; без ярлыка —
+     содержимое с <host>» collapses to the host here. When a label lookup is
+     added to the core later, this signature already accepts it — pass the label
+     instead of the host and nothing else changes.
+
+     The category name is resolved through the SAME buildStrings() the panel
+     uses, so «Маркетинг» in the placeholder is «Маркетинг» on the switch. An
+     unknown language falls back to en, an unknown category to marketing — the
+     category a strict-mode interception is filed under. */
+  function placeholderText(host, category, lang) {
+    var table = localeTable();
+    var T2 = buildStrings(resolveLang(lang, table), table);
+    var cat = (category && T2.cat[category]) ? category : 'marketing';
+    var name = String(host || '').trim();
+    return T2.phText
+      .replace('{host}', name || T2.phLabel)
+      .replace('{cat}', T2.cat[cat].title);
+  }
+
+  /* Hostname of a blocked frame's real address, for the sentence above. The
+     data-src is whatever the page asked for, which may be protocol-relative or
+     relative, so it is resolved against the page like the core does it. */
+  function hostOf(src) {
+    var s = String(src || '');
+    try {
+      var base = (typeof location !== 'undefined' && location.href) || 'http://localhost/';
+      var h = new URL(s, base).hostname || '';
+      return h.toLowerCase().replace(/^www\./, '');
+    } catch (e) {
+      var m = /^(?:[a-z]+:)?\/\/([^/?#]+)/i.exec(s);
+      return m ? m[1].toLowerCase().replace(/:\d+$/, '').replace(/^www\./, '') : '';
+    }
+  }
+
   /* --------------------------------------------------------------- styles */
 
   var CSS = [
@@ -370,8 +427,12 @@
     return (b && typeof b === 'object') ? b : null;
   }
 
+  /* LANG travels with T: an extension that renders language-dependent text of
+     its own (branding.poweredBy.texts) needs the code the banner resolved to,
+     which only this file knows — the config may say 'auto' and the answer then
+     comes from the visitor's browser at mount time. */
   function extHost() {
-    return { el: el, str: str, T: T };
+    return { el: el, str: str, T: T, lang: LANG };
   }
 
   function buildBrandLogo(cfg) {
@@ -427,6 +488,7 @@
   var mountedSig = null;
   var host = null, root = null;
   var T = DICT.en;
+  var LANG = 'en';             // the code T was built from, reassigned per mount
   var nodes = {};              // banner/panel/fab refs
   var switches = {};           // category -> button
   var panelOpen = false;
@@ -1283,12 +1345,30 @@
     var url = str(texts.policyUrl);
     if (url && !/^https?:\/\//i.test(url)) url = null;
 
+    /* SPEC V1.10 §1 — the third destination: our own cookie declaration page.
+       `declarationUrl` is server-owned (the SaaS config injects it, like
+       `branding`); the client only reads it and never invents one. It is
+       validated exactly like policyUrl — http(s) only, because a link the
+       visitor is invited to click must not be able to carry javascript: — and
+       it deliberately does NOT influence the default action: the URL-sensitive
+       default above stays policyUrl-driven, so a site that gains a declaration
+       address does not silently lose its «Подробнее» → политика link. */
+    var decl = str(texts.declarationUrl);
+    if (decl && !/^https?:\/\//i.test(decl)) decl = null;
+
     var action = texts.detailsAction;
-    if (action !== 'policy' && action !== 'settings' && action !== 'hide') {
+    if (action !== 'policy' && action !== 'settings' && action !== 'hide' && action !== 'declaration') {
       action = url ? 'policy' : 'settings';
     }
     if (action === 'policy' && !url) action = 'settings';
-    return { kind: action, href: action === 'policy' ? url : null };
+    // Asked for the declaration with no address to send anyone to: fall back to
+    // opening the settings rather than rendering a dead link.
+    if (action === 'declaration' && !decl) action = 'settings';
+
+    var href = null;
+    if (action === 'policy') href = url;
+    else if (action === 'declaration') href = decl;
+    return { kind: action, href: href };
   }
 
   // Unknown type -> bar/bottom. Known type with an unrecognized position ->
@@ -1330,11 +1410,15 @@
       p.appendChild(document.createTextNode(T.bannerText));
     } else {
       p.appendChild(document.createTextNode(T.bannerText + ' '));
-      if (det.kind === 'policy') {
+      // 'policy' and 'declaration' are the same DOM shape — an outbound link in
+      // a new tab — and differ only in where they point (resolveDetails picked
+      // the address). Both must be listed here: a missing branch would silently
+      // render 'declaration' as the settings BUTTON instead of the link.
+      if (det.kind === 'policy' || det.kind === 'declaration') {
         var link = el('a', 'ck-banner__more', T.more);
         link.href = det.href;
         link.target = '_blank';
-        link.rel = 'noopener';          // never hand the policy page window.opener
+        link.rel = 'noopener';          // never hand the linked page window.opener
         p.appendChild(link);
       } else {
         // A control that changes what is on screen is a button, not a link:
@@ -1602,6 +1686,290 @@
     if (nodes.scrim) nodes.scrim.classList.toggle('ck-hidden', decided || !nodes.bannerModal);
     if (nodes.fab) nodes.fab.classList.toggle('ck-hidden', !decided);
     if (!panelOpen) syncSwitches(s);
+
+    /* §2 — a consent change is exactly when a card must go: the core's
+       applyConsentToDom() has already put the frame's src back by the time
+       ck:change reaches us (commit() revives before it dispatches), so the
+       sweep sees a frame with a src and retires its placeholder. It runs on
+       every sync, which also catches a category the visitor turned back OFF —
+       though a frame that already loaded cannot be un-loaded, so that direction
+       only matters for frames still held back. */
+    try { sweepPlaceholders(); } catch (e) { /* noop */ }
+  }
+
+  /* ------------------------------------------- blocked-embed placeholders (§2) */
+
+  /* SPEC V1.10 §2. When the core holds an <iframe> back — a known tracker, or
+     any third-party frame in strict mode — it leaves it in one shape:
+     `data-ck` + `data-src` and NO src (markBlockedIframe in ck-core.js). This
+     module draws a block of the same size in its place, offering the visitor
+     the one decision that would make the embed appear.
+
+     WHY A SIBLING, NOT A WRAPPER: sites style embeds through the parent
+     (`.video-wrap > iframe`, grid children, aspect-ratio boxes). Wrapping the
+     frame inserts a node into that relationship and breaks the layout it was
+     meant to preserve. A sibling inserted before the frame inherits the same
+     parent context, and removing it later restores the DOM exactly.
+
+     WHO RESTORES THE FRAME: not this file. `Element.prototype.setAttribute` is
+     patched by the core, and only applyConsentToDom() may write a blocked
+     frame's src — under `bypass`, through the native setter it captured before
+     patching. So «Разрешить и показать» grants the category through the normal
+     consent path and the CORE brings the frame back; the next sweep sees a
+     frame that has a src again and drops the placeholder. One code path for
+     the button, the panel's switches and «Принять всё» alike. */
+
+  var PH_ATTR = 'data-ck-ph';            // marks a frame this file hid
+  var PH_DISPLAY = 'data-ck-ph-display'; // its previous inline display value
+  var placeholders = [];                 // [{ frame, node }]
+
+  function placeholdersEnabled(cfg) {
+    // No default in the core's DEFAULT_CONFIG, exactly like detailsAction:
+    // absent means on, and only an explicit false opts out.
+    try {
+      var b = cfg && cfg.blocking;
+      return !(b && b.placeholders === false);
+    } catch (e) { return true; }
+  }
+
+  /* §2: «Не трогать фреймы display:none, 1×1, и те, что не в <body>.»
+     Order matters — a frame this file has already hidden reads as display:none,
+     which would make it skip its own placeholder and leave it stranded forever.
+     Frames we marked are therefore exempted before the display test runs. */
+  function frameEligible(frame) {
+    try {
+      if (!frame || !document.body) return false;
+      if (!document.body.contains(frame)) return false;
+      if (frame.getAttribute(PH_ATTR)) return true;   // ours: already measured
+      var cs = null;
+      try { cs = window.getComputedStyle(frame); } catch (e) { cs = null; }
+      if (cs && (cs.display === 'none' || cs.visibility === 'hidden')) return false;
+      var r = null;
+      try { r = frame.getBoundingClientRect(); } catch (e) { r = null; }
+      // A 1×1 (or 0×0) frame is a tracking pixel dressed as an embed: there is
+      // nothing for a visitor to watch and a card in its place would be noise.
+      if (r && r.width <= 1 && r.height <= 1) {
+        // Zero-sized because it is not laid out YET (a lazy tab, a collapsed
+        // section) is indistinguishable here from a real pixel except via the
+        // attributes, which a pixel sets to 1 and a video does not.
+        var aw = parseInt(frame.getAttribute('width') || '0', 10);
+        var ah = parseInt(frame.getAttribute('height') || '0', 10);
+        if (!(aw > 1 || ah > 1)) return false;
+      }
+      return true;
+    } catch (e) { return false; }
+  }
+
+  /* Size the card to the hole the frame left. Attributes first (an embed is
+     nearly always `width="560" height="315"`), computed size second. Read
+     BEFORE the frame is hidden — getComputedStyle on a display:none element
+     reports nothing worth copying. */
+  function frameSize(frame) {
+    var w = '', h = '';
+    try {
+      var aw = frame.getAttribute('width');
+      var ah = frame.getAttribute('height');
+      if (aw && /^\d+$/.test(String(aw).trim())) w = String(aw).trim() + 'px';
+      if (ah && /^\d+$/.test(String(ah).trim())) h = String(ah).trim() + 'px';
+      if (!w || !h) {
+        var cs = window.getComputedStyle(frame);
+        if (!w && cs && cs.width && cs.width !== 'auto' && cs.width !== '0px') w = cs.width;
+        if (!h && cs && cs.height && cs.height !== 'auto' && cs.height !== '0px') h = cs.height;
+      }
+    } catch (e) { /* fall through to the defaults in PH_CSS */ }
+    return { width: w, height: h };
+  }
+
+  var PLAY_ICON =
+    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" ' +
+    'stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">' +
+    '<rect x="2.5" y="4.5" width="19" height="15" rx="2.5"/>' +
+    '<path d="M10.5 9.2v5.6l4.6-2.8-4.6-2.8Z"/></svg>';
+
+  // Own sheet: a placeholder is its own shadow root, so it cannot borrow the
+  // banner's. Tokens come from buildThemeCss() (theme.accent, radius, font),
+  // which is why a placeholder repaints with the banner.
+  var PH_CSS = [
+    ':host{all:initial;display:block;max-width:100%}',
+    '*,*::before,*::after{box-sizing:border-box}',
+    '.ck-ph{width:100%;height:100%;min-height:120px;max-width:100%;',
+    'display:flex;flex-direction:column;align-items:center;justify-content:center;',
+    'gap:10px;padding:20px;text-align:center;',
+    'font-family:var(--ck-font);font-size:14px;line-height:1.5;color:var(--ck-ink);',
+    'background:var(--ck-soft);border:1px solid var(--ck-line);',
+    'border-radius:var(--ck-radius-card)}',
+    '.ck-ph svg{width:32px;height:32px;display:block;color:var(--ck-muted);flex:none}',
+    '.ck-ph p{margin:0;color:var(--ck-muted);max-width:44ch}',
+    '.ck-ph__row{display:flex;flex-wrap:wrap;gap:8px;align-items:center;justify-content:center}',
+    '.ck-ph__btn{font:inherit;font-weight:600;cursor:pointer;padding:9px 16px;',
+    'border-radius:var(--ck-radius-btn);border:1px solid var(--ck-accent);',
+    'background:var(--ck-accent);color:var(--ck-on-accent)}',
+    '.ck-ph__link{font:inherit;background:none;border:0;padding:4px;cursor:pointer;',
+    'color:var(--ck-link);text-decoration:underline}',
+    ':focus-visible{outline:2px solid var(--ck-accent);outline-offset:2px;border-radius:4px}'
+  ].join('\n');
+
+  function categoryEnabled(cfg, cat) {
+    try {
+      if (cat === 'necessary') return false;         // nothing to grant
+      var c = cfg && cfg.categories && cfg.categories[cat];
+      return !c || c.enabled !== false;
+    } catch (e) { return true; }
+  }
+
+  function buildPlaceholder(frame, cat, cfg) {
+    var mountEl = document.createElement('div');
+    mountEl.setAttribute('data-ck-placeholder', '1');
+    var size = frameSize(frame);
+    var st = mountEl.style;
+    st.setProperty('max-width', '100%');
+    if (size.width) st.setProperty('width', size.width);
+    if (size.height) st.setProperty('min-height', size.height);
+
+    var sr = mountEl.attachShadow({ mode: 'open' });
+    var sheet = document.createElement('style');
+    /* buildThemeCss writes :host tokens — the same tokens, in this root, which
+       is what makes a placeholder repaint with the banner.
+
+       The font gets applyTheme()'s treatment for the same reason it needs it
+       there: `:host{all:initial}` resets the family, so a bare `inherit` in
+       this root resolves to the UA default (Times), not to the page's type.
+       The probed page font when it can be read, the system stack when it
+       cannot — never a bare `inherit`. */
+    var built = buildThemeCss(cfg);
+    var phFont = '';
+    if (built.font === 'inherit') {
+      phFont = '\n:host{--ck-font:' + (resolvePageFont() || SYSTEM_FONT) + '}';
+    }
+    sheet.textContent = PH_CSS + '\n' + built.css + phFont;
+    sr.appendChild(sheet);
+
+    var card = el('div', 'ck-ph');
+    card.setAttribute('role', 'group');
+    card.setAttribute('aria-label', T.phLabel);
+
+    var icon = document.createElement('div');
+    icon.innerHTML = PLAY_ICON;
+    card.appendChild(icon);
+
+    var label = hostOf(frame.getAttribute('data-src'));
+    card.appendChild(el('p', null, placeholderText(label, cat, LANG)));
+
+    var row = el('div', 'ck-ph__row');
+    /* Only offer the grant when it can actually take effect: the core's
+       filterByConfig() drops a category the site disabled in config, so the
+       button would consume the click and change nothing. The panel link stays
+       either way — it is always an honest answer. */
+    if (categoryEnabled(cfg, cat)) {
+      var allow = el('button', 'ck-ph__btn', T.phAllow);
+      allow.type = 'button';
+      allow.addEventListener('click', function () { grantCategory(cat); });
+      row.appendChild(allow);
+    }
+    var settings = el('button', 'ck-ph__link', T.phSettings);
+    settings.type = 'button';
+    settings.addEventListener('click', function () { openPanel(settings); });
+    row.appendChild(settings);
+    card.appendChild(row);
+
+    sr.appendChild(card);
+    return mountEl;
+  }
+
+  /* «Разрешить и показать» — one category, through the normal consent path.
+
+     MERGE, DO NOT REPLACE: ConsentKit.accept({...}) SETS the whole opt-in set
+     from the object it is given, so passing `{marketing:true}` alone would
+     silently switch OFF an analytics consent the visitor had already given.
+     The current state is read first and only the one category is flipped.
+
+     accept(object) files the decision as method 'custom', which is what §2 asks
+     the journal to record, and ck-saas.js logs it off the ck:consent/ck:change
+     the core dispatches — so there is no logging code here. The core's
+     applyConsentToDom() restores the frame; sweepPlaceholders() then removes
+     this card, driven by the ck:change that same commit dispatches. */
+  function grantCategory(cat) {
+    var ck = api();
+    if (!ck || typeof ck.accept !== 'function') return;
+    var cur = safeState().categories || {};
+    var next = {
+      functional: cur.functional === true,
+      analytics: cur.analytics === true,
+      marketing: cur.marketing === true
+    };
+    if (cat === 'functional' || cat === 'analytics' || cat === 'marketing') next[cat] = true;
+    try { ck.accept(next); } catch (e) { /* noop */ }
+    syncFromState();
+  }
+
+  function hideFrame(frame) {
+    try {
+      frame.setAttribute(PH_DISPLAY, frame.style.display || '');
+      frame.setAttribute(PH_ATTR, '1');
+      frame.style.display = 'none';
+    } catch (e) { /* noop */ }
+  }
+
+  function restoreFrame(frame) {
+    try {
+      var prev = frame.getAttribute(PH_DISPLAY);
+      frame.style.display = prev || '';
+      frame.removeAttribute(PH_DISPLAY);
+      frame.removeAttribute(PH_ATTR);
+    } catch (e) { /* noop */ }
+  }
+
+  function dropPlaceholder(entry) {
+    try {
+      if (entry.node && entry.node.parentNode) entry.node.parentNode.removeChild(entry.node);
+    } catch (e) { /* noop */ }
+    restoreFrame(entry.frame);
+  }
+
+  function clearPlaceholders() {
+    for (var i = 0; i < placeholders.length; i++) dropPlaceholder(placeholders[i]);
+    placeholders = [];
+  }
+
+  /* Idempotent: called from mount() and from every consent change. Adds cards
+     for frames still held back, removes them from frames the core revived. */
+  function sweepPlaceholders(cfg) {
+    if (typeof document === 'undefined' || !document.body) return;
+    var c = cfg || safeConfig();
+
+    // Placeholders turned off after some were drawn: take them all down.
+    if (!placeholdersEnabled(c)) { clearPlaceholders(); return; }
+
+    // 1. Retire cards whose frame came back (or left the document).
+    var kept = [];
+    for (var i = 0; i < placeholders.length; i++) {
+      var e = placeholders[i];
+      var revived = false;
+      try {
+        revived = !document.body.contains(e.frame) || !!e.frame.getAttribute('src');
+      } catch (e2) { revived = true; }
+      if (revived) dropPlaceholder(e); else kept.push(e);
+    }
+    placeholders = kept;
+
+    // 2. Draw cards for frames the core is holding back. The selector is the
+    //    core's own revival selector, which is why a frame the SITE allowed can
+    //    never match: an allowed frame keeps its src and is never marked.
+    var list;
+    try { list = document.querySelectorAll('iframe[data-ck][data-src]'); } catch (e3) { return; }
+    for (var j = 0; j < list.length; j++) {
+      var frame = list[j];
+      try {
+        if (frame.getAttribute('src')) continue;              // already revived
+        if (frame.getAttribute(PH_ATTR)) continue;            // already carded
+        if (!frameEligible(frame)) continue;
+        var cat = frame.getAttribute('data-ck') || 'marketing';
+        var node = buildPlaceholder(frame, cat, c);
+        if (frame.parentNode) frame.parentNode.insertBefore(node, frame);
+        hideFrame(frame);
+        placeholders.push({ frame: frame, node: node });
+      } catch (e4) { /* one bad frame must not stop the sweep */ }
+    }
   }
 
   /* ----------------------------------------------------------------- mount */
@@ -1632,6 +2000,10 @@
     mounted = false;
     panelOpen = false;
     lastFocus = null;
+    // The cards belong to the render about to be replaced: their listeners close
+    // over the old T and the old shadow root. mount() sweeps again and draws
+    // fresh ones in the new language and theme.
+    clearPlaceholders();
     // The pending schedule belongs to the shadow root about to be rebuilt; the
     // fresh mount() starts its own ladder from a clean count.
     clearFontTimers();
@@ -1649,7 +2021,8 @@
     }
 
     var table = localeTable();                       // read at render time
-    T = buildStrings(resolveLang(cfg && cfg.language, table), table);
+    LANG = resolveLang(cfg && cfg.language, table);
+    T = buildStrings(LANG, table);
 
     host = document.getElementById('ck-root');
     if (!host) {
@@ -1686,6 +2059,55 @@
     // Only now: scheduleFontProbes() re-applies the theme from a timer, and
     // applyTheme() is a no-op until there is a host and a themeStyle to write.
     scheduleFontProbes(cfg);
+
+    // SPEC V1.10 §2 — заглушки вместо задержанных встраиваний. After the shadow
+    // root exists, because a placeholder's «Настроить cookie» calls openPanel().
+    sweepPlaceholders(cfg);
+
+    /* SPEC V1.10 §1 — honour a settings request that arrived before there was
+       anything to open: either ConsentKit.openSettings() called while this file
+       was still loading (the core latches it), or a page opened directly on
+       `#ck-settings`. Both end in the same panel. */
+    consumePendingOpen();
+    openFromHash();
+  }
+
+  /* ---------------------------------------------------- settings deep link */
+
+  var SETTINGS_HASH = '#ck-settings';
+
+  // The core latches openSettings() calls made before ck-ui.js was parsed, so a
+  // footer link clicked during a slow load still opens the panel once we exist.
+  function consumePendingOpen() {
+    var ck = api();
+    if (!ck || !ck._pendingOpen) return;
+    try { ck._pendingOpen = false; } catch (e) { /* noop */ }
+    openPanel(null);
+  }
+
+  /* `https://site/#ck-settings` — the address the cookie declaration page links
+     «Изменить выбор cookie» to. The hash is removed again via replaceState so a
+     reload, a shared link or a back-navigation does not re-open the panel, and
+     so the address bar does not keep a control fragment in it.
+
+     replaceState is fed pathname+search rather than '' — an empty URL argument
+     is a no-op in some engines, which would leave the hash in place and re-open
+     the panel on the next hashchange. Everything is guarded: a sandboxed iframe
+     throws on replaceState, and a panel that opened is worth more than a tidy
+     address bar. */
+  function openFromHash() {
+    try {
+      if (typeof location === 'undefined' || location.hash !== SETTINGS_HASH) return;
+    } catch (e) { return; }
+    clearSettingsHash();
+    openPanel(null);
+  }
+
+  function clearSettingsHash() {
+    try {
+      if (typeof history === 'undefined' || typeof history.replaceState !== 'function') return;
+      history.replaceState(null, '', location.pathname + location.search);
+    } catch (e) { /* noop */ }
   }
 
   /* ---------------------------------------------------------------- events */
@@ -1716,7 +2138,11 @@
       nextProbeDelay: nextProbeDelay,
       shouldReprobe: shouldReprobe,
       resolveDetails: resolveDetails,
-      buildThemeCss: buildThemeCss
+      buildThemeCss: buildThemeCss,
+      // SPEC V1.10 §2: which sentence a blocked embed shows. Pure, so the
+      // wording is testable (and quotable by the cabinet) without a DOM.
+      placeholderText: placeholderText,
+      placeholdersEnabled: placeholdersEnabled
     };
     // The page-font probe reads the DOM, so it is not part of the pure block —
     // but the debug panel must be able to quote the family the banner painted
@@ -1762,9 +2188,29 @@
 
   document.addEventListener('ck:ui:open-preferences', function () {
     if (!mounted) mount(safeConfig());
+    // mount() consumes the core's latch itself; clear it here too so a call
+    // made while we were already mounted cannot leave a stale flag behind for
+    // a later remount to act on.
+    var ck = api();
+    if (ck && ck._pendingOpen) { try { ck._pendingOpen = false; } catch (e) { /* noop */ } }
     openPanel(null);
   });
 
+  /* SPEC V1.10 §1 — navigating to `#ck-settings` on a page that is already
+     loaded (a footer link, or the declaration page opened in the same tab).
+     mount() covers the other half: a page ENTERED on that hash.
+
+     Feature-checked rather than assumed: the SSR guard above only proves there
+     is a `document`, and the branding suite evaluates this file against a stub
+     window that has none of the event plumbing. A missing hashchange costs the
+     deep link, not the banner. */
+  if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+    window.addEventListener('hashchange', function () {
+      if (!mounted) mount(safeConfig());
+      openFromHash();
+    });
+  }
+
   document.addEventListener('ck:ui:close', function () {
     closePanel();
   });