@freshjuice/zest 2.1.0 → 2.3.0

package/dist/zest.pl.js

@@ -258,10 +258,47 @@ var Zest = (function () {
 
   let patterns = { ...DEFAULT_PATTERNS };
 
+  /** Escape a string so it can be embedded in a regex literal verbatim. */
+  function escapeRegex(value) {
+    return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+
+  /**
+   * Append patterns to a single category without replacing what's already
+   * there. Used by `essentialKeys` and `essentialPatterns` config to extend
+   * the strictly-necessary category with consumer-specific entries while
+   * keeping the built-in defaults (zest_*, csrf*, xsrf*, etc.).
+   *
+   * `keys` is an array of exact storage/cookie names; each one is
+   * compiled as a fully-anchored regex via `escapeRegex`.
+   * `patternStrings` is an array of regex source strings, each validated
+   * via `safeRegExp`. Invalid entries are dropped silently.
+   */
+  function appendPatternsToCategory(category, { keys = [], patternStrings = [] } = {}) {
+    if (!patterns[category]) patterns[category] = [];
+
+    for (const key of keys) {
+      if (typeof key !== 'string' || !key) continue;
+      const re = safeRegExp(`^${escapeRegex(key)}$`);
+      if (re) patterns[category].push(re);
+    }
+
+    for (const p of patternStrings) {
+      if (typeof p !== 'string' || !p) continue;
+      const re = safeRegExp(p);
+      if (re) patterns[category].push(re);
+    }
+  }
+
   /**
    * Set custom patterns. User-supplied strings are validated with safeRegExp,
    * which rejects catastrophic-backtracking shapes and syntax errors.
    * Invalid patterns are silently dropped with a console warning.
+   *
+   * Note: this REPLACES the patterns for any category present in
+   * `customPatterns`. To extend the essential category without losing the
+   * built-in defaults, use `appendPatternsToCategory()` (or pass
+   * `essentialKeys` / `essentialPatterns` to `Zest.init()`).
    */
   function setPatterns(customPatterns) {
     patterns = { ...DEFAULT_PATTERNS };
@@ -321,19 +358,19 @@ var Zest = (function () {
   // Upper bound on the number of queued cookies awaiting consent replay.
   // An unbounded queue is a memory-exhaustion DoS vector — a hostile
   // script could flood it with document.cookie writes.
-  const MAX_QUEUE_SIZE$2 = 100;
+  const MAX_QUEUE_SIZE$3 = 100;
 
   // Queue for blocked cookies
   const cookieQueue = [];
 
   // Reference to consent checker function
-  let checkConsent$3 = () => false;
+  let checkConsent$5 = () => false;
 
   /**
    * Set the consent checker function
    */
-  function setConsentChecker$2(fn) {
-    checkConsent$3 = fn;
+  function setConsentChecker$4(fn) {
+    checkConsent$5 = fn;
   }
 
   /**
@@ -389,10 +426,10 @@ var Zest = (function () {
 
         const category = getCategoryForName(name);
 
-        if (checkConsent$3(category)) {
+        if (checkConsent$5(category)) {
           // Consent given - set cookie
           originalCookieDescriptor.set.call(document, value);
-        } else if (cookieQueue.length < MAX_QUEUE_SIZE$2) {
+        } else if (cookieQueue.length < MAX_QUEUE_SIZE$3) {
           // No consent - queue for later (capped to prevent DoS)
           cookieQueue.push({
             value,
@@ -417,7 +454,7 @@ var Zest = (function () {
 
   // Upper bound on queued operations awaiting consent replay — unbounded
   // growth would be a memory-exhaustion DoS vector.
-  const MAX_QUEUE_SIZE$1 = 200;
+  const MAX_QUEUE_SIZE$2 = 200;
 
   // Store originals
   let originalLocalStorage = null;
@@ -428,13 +465,13 @@ var Zest = (function () {
   const sessionStorageQueue = [];
 
   // Reference to consent checker function
-  let checkConsent$2 = () => false;
+  let checkConsent$4 = () => false;
 
   /**
    * Set the consent checker function
    */
-  function setConsentChecker$1(fn) {
-    checkConsent$2 = fn;
+  function setConsentChecker$3(fn) {
+    checkConsent$4 = fn;
   }
 
   /**
@@ -447,9 +484,9 @@ var Zest = (function () {
           return (key, value) => {
             const category = getCategoryForName(key);
 
-            if (checkConsent$2(category)) {
+            if (checkConsent$4(category)) {
               target.setItem(key, value);
-            } else if (queue.length < MAX_QUEUE_SIZE$1) {
+            } else if (queue.length < MAX_QUEUE_SIZE$2) {
               queue.push({
                 key,
                 value,
@@ -732,11 +769,11 @@ var Zest = (function () {
 
   // Categories the author has declared blockable. A script can self-label
   // into one of these, but not into 'essential' (a common bypass).
-  const BLOCKABLE_CATEGORIES = new Set(['functional', 'analytics', 'marketing']);
+  const BLOCKABLE_CATEGORIES$2 = new Set(['functional', 'analytics', 'marketing']);
 
   // Upper bound on queued scripts awaiting consent replay — prevents a
   // hostile page from flooding the queue with <script> nodes.
-  const MAX_QUEUE_SIZE = 500;
+  const MAX_QUEUE_SIZE$1 = 500;
 
   // Queue for blocked scripts — the authoritative source for replay,
   // snapshotting src/inline BEFORE any DOM mutation so later tampering
@@ -747,31 +784,31 @@ var Zest = (function () {
   let observer = null;
 
   // Current blocking mode
-  let blockingMode = 'safe';
+  let blockingMode$2 = 'safe';
 
   // Custom blocked domains (user-defined)
-  let customBlockedDomains = [];
+  let customBlockedDomains$2 = [];
 
   // Reference to consent checker function
-  let checkConsent$1 = () => false;
+  let checkConsent$3 = () => false;
 
   /**
    * Set the consent checker function
    */
-  function setConsentChecker(fn) {
-    checkConsent$1 = fn;
+  function setConsentChecker$2(fn) {
+    checkConsent$3 = fn;
   }
 
   /**
    * Check if script URL matches custom blocked domains
    */
-  function matchesCustomDomains(url) {
-    if (!url || customBlockedDomains.length === 0) return null;
+  function matchesCustomDomains$2(url) {
+    if (!url || customBlockedDomains$2.length === 0) return null;
 
     try {
       const hostname = new URL(url).hostname.toLowerCase();
 
-      for (const entry of customBlockedDomains) {
+      for (const entry of customBlockedDomains$2) {
         const domain = typeof entry === 'string' ? entry : entry.domain;
         const category = typeof entry === 'string' ? 'marketing' : (entry.category || 'marketing');
 
@@ -804,7 +841,7 @@ var Zest = (function () {
     // Only honor values from the blockable set; 'essential' and unknown
     // values fall through to the other checks.
     const explicitCategory = script.getAttribute('data-consent-category');
-    const explicitBlockable = explicitCategory && BLOCKABLE_CATEGORIES.has(explicitCategory)
+    const explicitBlockable = explicitCategory && BLOCKABLE_CATEGORIES$2.has(explicitCategory)
       ? explicitCategory
       : null;
 
@@ -816,17 +853,17 @@ var Zest = (function () {
     }
 
     // 2. Check custom blocked domains
-    const customCategory = matchesCustomDomains(src);
+    const customCategory = matchesCustomDomains$2(src);
 
     // 3. Mode-based blocking
     let modeCategory = null;
-    switch (blockingMode) {
+    switch (blockingMode$2) {
       case 'manual':
         break;
 
       case 'safe':
       case 'strict':
-        modeCategory = getCategoryForScript(src, blockingMode);
+        modeCategory = getCategoryForScript(src, blockingMode$2);
         break;
 
       case 'doomsday':
@@ -860,7 +897,7 @@ var Zest = (function () {
       return false;
     }
 
-    if (checkConsent$1(category)) {
+    if (checkConsent$3(category)) {
       // Consent already given - allow script
       script.setAttribute('data-zest-processed', 'allowed');
       return false;
@@ -894,7 +931,7 @@ var Zest = (function () {
       script.removeAttribute('src');
     }
 
-    if (scriptQueue.length < MAX_QUEUE_SIZE) {
+    if (scriptQueue.length < MAX_QUEUE_SIZE$1) {
       scriptQueue.push(scriptInfo);
     }
     return true;
@@ -975,8 +1012,8 @@ var Zest = (function () {
    * Start observing for new scripts
    */
   function startScriptBlocking(mode = 'safe', customDomains = []) {
-    blockingMode = mode;
-    customBlockedDomains = customDomains;
+    blockingMode$2 = mode;
+    customBlockedDomains$2 = customDomains;
 
     // Process existing scripts
     processExistingScripts();
@@ -992,6 +1029,568 @@ var Zest = (function () {
     return true;
   }
 
+  /**
+   * Network Interceptor - Intercepts fetch / XHR / sendBeacon calls
+   *
+   * Why this exists separately from the script blocker:
+   *
+   * Modern CMSes (HubSpot, Cloudflare Zaraz, server-side GTM, Shopify,
+   * Webflow) increasingly proxy their tracker code through the site's own
+   * origin to defeat ad-blockers. The <script> tag itself is first-party
+   * (e.g. /hs/scriptloader/{id}.js) so a hostname-based script blocker
+   * cannot match it. But at RUNTIME that script still phones home to the
+   * vendor's analytics endpoint via fetch / XHR / sendBeacon — and THAT
+   * URL is third-party.
+   *
+   * This interceptor sits on the network layer and uses the same
+   * customBlockedDomains + mode-based tracker list as the script blocker.
+   * Whatever the user told Zest to block (typically generated by an AI
+   * audit) gets blocked regardless of which API the tracker uses.
+   *
+   * No replay: network calls are one-shot and time-sensitive. Replaying a
+   * stale beacon after consent would create confusing / duplicated data,
+   * so blocked requests are dropped, not queued.
+   */
+
+
+  // Originals captured at install time. Stored for restoration tests and
+  // for any internal Zest network calls we may add later.
+  let originalFetch = null;
+  let originalXhrOpen = null;
+  let originalXhrSend = null;
+  let originalSendBeacon = null;
+
+  let blockingMode$1 = 'safe';
+  let customBlockedDomains$1 = [];
+  let installed$1 = false;
+
+  let checkConsent$2 = () => false;
+
+  const BLOCKABLE_CATEGORIES$1 = new Set(['functional', 'analytics', 'marketing']);
+
+  function setConsentChecker$1(fn) {
+    checkConsent$2 = fn;
+  }
+
+  /**
+   * Resolve a Request | URL | string to an absolute URL string. Returns
+   * null if the input cannot be parsed — callers treat null as "do not
+   * block" (we'd rather let an opaque request through than crash the page).
+   */
+  function resolveUrl(input) {
+    try {
+      if (typeof input === 'string') {
+        return new URL(input, location.href).href;
+      }
+      if (input && typeof input === 'object') {
+        if (typeof input.url === 'string') {
+          // Request object
+          return new URL(input.url, location.href).href;
+        }
+        if (typeof input.href === 'string') {
+          // URL object
+          return input.href;
+        }
+      }
+    } catch (e) {
+      // fallthrough
+    }
+    return null;
+  }
+
+  /**
+   * Match a URL against the user's customBlockedDomains list. Mirrors
+   * matchesCustomDomains() in script-blocker.js — kept inline rather than
+   * shared so each interceptor can be lifted independently.
+   */
+  function matchesCustomDomains$1(hostname) {
+    if (!hostname || customBlockedDomains$1.length === 0) return null;
+    const host = hostname.toLowerCase();
+    for (const entry of customBlockedDomains$1) {
+      const domain = (typeof entry === 'string' ? entry : entry?.domain || '').toLowerCase();
+      if (!domain) continue;
+      const category = typeof entry === 'string'
+        ? 'marketing'
+        : (BLOCKABLE_CATEGORIES$1.has(entry?.category) ? entry.category : 'marketing');
+      if (host === domain || host.endsWith('.' + domain)) {
+        return category;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Decide whether a URL should be blocked and return its category, or
+   * null if it should pass through. Priority: customBlockedDomains >
+   * mode-based tracker list (matching script-blocker priority).
+   */
+  function getBlockCategory$1(url) {
+    if (!url) return null;
+    let hostname;
+    try {
+      hostname = new URL(url, location.href).hostname;
+    } catch (e) {
+      return null;
+    }
+
+    const customCategory = matchesCustomDomains$1(hostname);
+    if (customCategory) return customCategory;
+
+    switch (blockingMode$1) {
+      case 'manual':
+        return null;
+      case 'safe':
+      case 'strict':
+        return getCategoryForScript(url, blockingMode$1);
+      case 'doomsday':
+        if (isThirdParty(url)) {
+          return getCategoryForScript(url, 'strict') || 'marketing';
+        }
+        return null;
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Should the request be blocked right now? Returns the category that
+   * caused the block (for logging / callbacks later) or null.
+   */
+  function shouldBlock$1(url) {
+    const category = getBlockCategory$1(url);
+    if (!category) return null;
+    if (checkConsent$2(category)) return null;
+    return category;
+  }
+
+  /**
+   * Construct an empty, successful-looking Response for a blocked fetch.
+   * Status 204 (No Content) is the most honest "we deliberately returned
+   * nothing" signal. Trackers that .then(r => r.json()) will get an empty
+   * body and typically silently move on.
+   */
+  function blockedResponse() {
+    // Some environments (older browsers, strict CSP) may not have Response
+    // — fall back to a thenable shape the most common tracker code expects.
+    if (typeof Response === 'function') {
+      return new Response(null, { status: 204, statusText: 'Blocked by Zest' });
+    }
+    const fake = {
+      ok: false,
+      status: 204,
+      statusText: 'Blocked by Zest',
+      json: () => Promise.resolve({}),
+      text: () => Promise.resolve(''),
+      arrayBuffer: () => Promise.resolve(new ArrayBuffer(0))
+    };
+    return fake;
+  }
+
+  /**
+   * Install fetch hook. Captures the original so we can both restore it
+   * later and use it for any internal Zest network calls.
+   */
+  function patchFetch() {
+    if (typeof window === 'undefined' || typeof window.fetch !== 'function') return;
+    originalFetch = window.fetch.bind(window);
+
+    window.fetch = function zestPatchedFetch(input, init) {
+      const url = resolveUrl(input);
+      if (shouldBlock$1(url)) {
+        return Promise.resolve(blockedResponse());
+      }
+      return originalFetch(input, init);
+    };
+  }
+
+  /**
+   * Install XMLHttpRequest hook. We patch .open() to capture the URL on
+   * the instance, then .send() to decide whether to abort. Using a hidden
+   * symbol on the instance avoids leaking state and survives any wrapping
+   * code that reassigns request properties.
+   */
+  const URL_KEY = Symbol('zestUrl');
+
+  function patchXhr() {
+    if (typeof XMLHttpRequest === 'undefined') return;
+    const proto = XMLHttpRequest.prototype;
+    originalXhrOpen = proto.open;
+    originalXhrSend = proto.send;
+
+    proto.open = function (method, url, ...rest) {
+      this[URL_KEY] = typeof url === 'string' ? url : (url && url.href) || '';
+      return originalXhrOpen.call(this, method, url, ...rest);
+    };
+
+    proto.send = function (body) {
+      const url = this[URL_KEY];
+      if (shouldBlock$1(url)) {
+        // Mimic the failure mode of a network error: queueMicrotask is
+        // used so consumers that synchronously attach handlers after
+        // .send() still receive the events.
+        const xhr = this;
+        queueMicrotask(() => {
+          try {
+            // Best-effort — readonly props in some environments
+            Object.defineProperty(xhr, 'readyState', { value: 4, configurable: true });
+            Object.defineProperty(xhr, 'status', { value: 0, configurable: true });
+          } catch (e) {
+            // ignore
+          }
+          try {
+            xhr.dispatchEvent(new Event('error'));
+            xhr.dispatchEvent(new Event('loadend'));
+          } catch (e) {
+            // ignore
+          }
+        });
+        return;
+      }
+      return originalXhrSend.call(this, body);
+    };
+  }
+
+  /**
+   * Install navigator.sendBeacon hook. Returning false matches the spec's
+   * "data was not queued" semantics; trackers that check the return value
+   * fall back to fetch (which we also block) or give up.
+   */
+  function patchSendBeacon() {
+    if (typeof navigator === 'undefined' || typeof navigator.sendBeacon !== 'function') return;
+    originalSendBeacon = navigator.sendBeacon.bind(navigator);
+
+    navigator.sendBeacon = function zestPatchedSendBeacon(url, data) {
+      if (shouldBlock$1(typeof url === 'string' ? url : (url && url.href) || '')) {
+        return false;
+      }
+      return originalSendBeacon(url, data);
+    };
+  }
+
+  /**
+   * Install all network hooks. Safe to call multiple times — subsequent
+   * calls just refresh mode + custom domain config without re-wrapping.
+   */
+  function interceptNetwork(mode = 'safe', customDomains = []) {
+    blockingMode$1 = mode;
+    customBlockedDomains$1 = Array.isArray(customDomains) ? customDomains : [];
+
+    if (installed$1) return true;
+    patchFetch();
+    patchXhr();
+    patchSendBeacon();
+    installed$1 = true;
+    return true;
+  }
+
+  /**
+   * Element Interceptor - Catches tracker elements BEFORE the browser fetches them.
+   *
+   * The script-blocker uses MutationObserver. That fires asynchronously
+   * (microtask after the DOM mutation), so by the time we can react the
+   * browser has already kicked off the network request for the src/href.
+   * The script may not execute (we flip type to text/plain) but the
+   * fetch already left the building — and to ConsentTheater / a privacy
+   * audit that fetch IS a pre-consent leak.
+   *
+   * This interceptor patches the prototype setters and Element.setAttribute
+   * synchronously, so when code does:
+   *
+   *   const s = document.createElement('script');
+   *   s.src = 'https://tracker.example/track.js';   // ← intercepted HERE
+   *   document.head.appendChild(s);                 // ← src is already empty,
+   *                                                 //   no fetch ever fired
+   *
+   * Covers four element types and both ways to set the URL:
+   *
+   *   - HTMLScriptElement   src
+   *   - HTMLLinkElement     href      (stylesheets, prefetch, preload, dns-prefetch)
+   *   - HTMLImageElement    src       (tracking pixels)
+   *   - HTMLIFrameElement   src       (tracking iframes)
+   *
+   * Plus the global Image() constructor used by classic pixel trackers.
+   *
+   * What this does NOT catch: inline HTML <script src=...> / <link href=...>
+   * tags parsed from the original HTML response. The browser starts those
+   * fetches as soon as it encounters the tag during parsing, BEFORE any
+   * JavaScript runs. The only complete fix for that class is server-side
+   * CSP or template-time removal.
+   */
+
+
+  // Upper bound on queued blocked elements. Unbounded growth would be a
+  // memory-exhaustion vector if a page (or a hostile script) tried to
+  // flood us with src writes.
+  const MAX_QUEUE_SIZE = 500;
+
+  // Queue of blocked element writes. Each entry remembers enough to
+  // re-apply the original URL via the ORIGINAL setter once consent
+  // arrives for its category. Without this queue, blocked scripts /
+  // stylesheets / images would be lost forever and require a page
+  // reload to come back.
+  const elementQueue = [];
+
+  let blockingMode = 'safe';
+  let customBlockedDomains = [];
+  let installed = false;
+  let checkConsent$1 = () => false;
+
+  const BLOCKABLE_CATEGORIES = new Set(['functional', 'analytics', 'marketing']);
+
+  // Map of tag name -> attribute name that carries a URL we may want to
+  // block. Lowercased on both sides; setAttribute() gating uses this.
+  const URL_ATTRS = {
+    script: 'src',
+    link: 'href',
+    img: 'src',
+    iframe: 'src'
+  };
+
+  function setConsentChecker(fn) {
+    checkConsent$1 = fn;
+  }
+
+  function matchesCustomDomains(hostname) {
+    if (!hostname || customBlockedDomains.length === 0) return null;
+    const host = hostname.toLowerCase();
+    for (const entry of customBlockedDomains) {
+      const domain = (typeof entry === 'string' ? entry : entry?.domain || '').toLowerCase();
+      if (!domain) continue;
+      const category = typeof entry === 'string'
+        ? 'marketing'
+        : (BLOCKABLE_CATEGORIES.has(entry?.category) ? entry.category : 'marketing');
+      if (host === domain || host.endsWith('.' + domain)) {
+        return category;
+      }
+    }
+    return null;
+  }
+
+  function getBlockCategory(url) {
+    if (!url) return null;
+    let hostname;
+    try {
+      hostname = new URL(url, location.href).hostname;
+    } catch (e) {
+      return null;
+    }
+
+    const customCategory = matchesCustomDomains(hostname);
+    if (customCategory) return customCategory;
+
+    switch (blockingMode) {
+      case 'manual':
+        return null;
+      case 'safe':
+      case 'strict':
+        return getCategoryForScript(url, blockingMode);
+      case 'doomsday':
+        if (isThirdParty(url)) {
+          return getCategoryForScript(url, 'strict') || 'marketing';
+        }
+        return null;
+      default:
+        return null;
+    }
+  }
+
+  function shouldBlock(url) {
+    const category = getBlockCategory(url);
+    if (!category) return null;
+    if (checkConsent$1(category)) return null;
+    return category;
+  }
+
+  /**
+   * Replace the property setter for `prop` on `ProtoCtor.prototype` with
+   * a gated version. Returns the original descriptor so we can restore.
+   */
+  function patchUrlSetter(ProtoCtor, prop) {
+    if (typeof ProtoCtor !== 'function' || !ProtoCtor.prototype) return null;
+    const proto = ProtoCtor.prototype;
+    const desc = Object.getOwnPropertyDescriptor(proto, prop);
+    if (!desc || typeof desc.set !== 'function') return null;
+
+    Object.defineProperty(proto, prop, {
+      configurable: true,
+      enumerable: desc.enumerable,
+      get: desc.get,
+      set(value) {
+        if (typeof value === 'string') {
+          const category = shouldBlock(value);
+          if (category) {
+            // Don't pass through to the original setter — the URL never
+            // touches the element. Stash the element + URL + category
+            // + original descriptor in the queue so replayElements()
+            // can reinstate it once consent arrives.
+            if (elementQueue.length < MAX_QUEUE_SIZE) {
+              elementQueue.push({
+                element: this,
+                setter: desc.set,
+                prop,
+                value,
+                category,
+                method: 'property'
+              });
+            }
+            return;
+          }
+        }
+        return desc.set.call(this, value);
+      }
+    });
+
+    return desc;
+  }
+
+  function patchSetAttribute() {
+    if (typeof Element === 'undefined' || !Element.prototype) return null;
+    const orig = Element.prototype.setAttribute;
+
+    Element.prototype.setAttribute = function patchedSetAttribute(name, value) {
+      // Fast path: bail out for anything not on our watchlist before doing
+      // any string work. setAttribute is hot — keep this cheap.
+      if (typeof name !== 'string' || typeof value !== 'string' || !this || !this.tagName) {
+        return orig.call(this, name, value);
+      }
+      const tag = this.tagName.toLowerCase();
+      const watched = URL_ATTRS[tag];
+      if (!watched) {
+        return orig.call(this, name, value);
+      }
+      const attr = name.toLowerCase();
+      if (attr !== watched) {
+        return orig.call(this, name, value);
+      }
+      const category = shouldBlock(value);
+      if (category) {
+        // Drop silently and queue for replay. The element keeps any
+        // other attributes you set before / after.
+        if (elementQueue.length < MAX_QUEUE_SIZE) {
+          elementQueue.push({
+            element: this,
+            setter: orig,            // setAttribute itself, called like orig.call(el, name, value)
+            prop: name,
+            value,
+            category,
+            method: 'attribute'
+          });
+        }
+        return;
+      }
+      return orig.call(this, name, value);
+    };
+
+    return orig;
+  }
+
+  function patchImageConstructor() {
+    if (typeof window === 'undefined' || typeof window.Image !== 'function') return null;
+    const OrigImage = window.Image;
+
+    function PatchedImage(width, height) {
+      const img = arguments.length >= 2
+        ? new OrigImage(width, height)
+        : new OrigImage();
+      // No work needed here — the .src setter patch on HTMLImageElement
+      // will catch any later assignment. PatchedImage exists mainly to
+      // expose the .src patch via this path for `new Image()` users.
+      return img;
+    }
+    PatchedImage.prototype = OrigImage.prototype;
+    // Copy any static fields just in case.
+    for (const key of Object.keys(OrigImage)) {
+      try { PatchedImage[key] = OrigImage[key]; } catch (e) { /* ignore */ }
+    }
+
+    try {
+      Object.defineProperty(window, 'Image', {
+        configurable: true,
+        writable: true,
+        value: PatchedImage
+      });
+    } catch (e) {
+      window.Image = PatchedImage;
+    }
+
+    return OrigImage;
+  }
+
+  /**
+   * Replay blocked element writes for newly-allowed categories.
+   *
+   * For each queued entry whose category is in `allowedCategories`:
+   *   - If the element is still connected to the DOM, re-apply the
+   *     URL via the ORIGINAL setter / setAttribute. The browser starts
+   *     the fetch as if nothing had been intercepted.
+   *   - If the element has since been removed (no `isConnected`), drop
+   *     the entry — calling code lost its reference and we have no
+   *     parent to attach to.
+   *
+   * Queue ordering is preserved so that scripts/stylesheets re-execute
+   * in the same order the page originally requested them.
+   */
+  function replayElements(allowedCategories) {
+    if (!Array.isArray(allowedCategories) || elementQueue.length === 0) return;
+    const remaining = [];
+
+    for (const item of elementQueue) {
+      if (!allowedCategories.includes(item.category)) {
+        remaining.push(item);
+        continue;
+      }
+
+      const el = item.element;
+      if (!el || !el.isConnected) {
+        // Element is detached or gone — nothing to re-apply against.
+        continue;
+      }
+
+      try {
+        if (item.method === 'attribute') {
+          item.setter.call(el, item.prop, item.value);
+        } else {
+          item.setter.call(el, item.value);
+        }
+      } catch (e) {
+        // Restoration failed (rare — element might be in a weird state).
+        // Don't requeue; one failure is enough.
+      }
+    }
+
+    elementQueue.length = 0;
+    elementQueue.push(...remaining);
+  }
+
+  /**
+   * Install all element-level interceptors. Idempotent — second call
+   * just refreshes mode + customDomains without rewrapping.
+   */
+  function interceptElements(mode = 'safe', customDomains = []) {
+    blockingMode = mode;
+    customBlockedDomains = Array.isArray(customDomains) ? customDomains : [];
+
+    if (installed) return true;
+
+    if (typeof HTMLScriptElement !== 'undefined') {
+      patchUrlSetter(HTMLScriptElement, 'src');
+    }
+    if (typeof HTMLLinkElement !== 'undefined') {
+      patchUrlSetter(HTMLLinkElement, 'href');
+    }
+    if (typeof HTMLImageElement !== 'undefined') {
+      patchUrlSetter(HTMLImageElement, 'src');
+    }
+    if (typeof HTMLIFrameElement !== 'undefined') {
+      patchUrlSetter(HTMLIFrameElement, 'src');
+    }
+    patchSetAttribute();
+    patchImageConstructor();
+
+    installed = true;
+    return true;
+  }
+
   /**
    * Default consent categories
    */
@@ -1292,6 +1891,33 @@ var Zest = (function () {
     // Blocking mode: 'manual' | 'safe' | 'strict' | 'doomsday'
     mode: 'safe',
 
+    // Interceptor toggles. By default Zest installs cookie + storage
+    // interceptors that route writes through the consent layer. Consumers
+    // who manage gating themselves (typically headless mode with custom
+    // analytics integrations) can opt out per channel.
+    intercept: {
+      cookies: true,
+      storage: true,
+      scripts: true,
+      network: true
+    },
+
+    // Strictly-necessary declarations. Both fields *append* to whatever
+    // the essential category already matches via the pattern matcher
+    // defaults — they do not replace.
+    //
+    // - essentialKeys:    array of exact storage / cookie names to treat
+    //                     as strictly-necessary. Easiest case.
+    // - essentialPatterns: array of regex source strings, validated via
+    //                      safeRegExp. For prefix or family matches.
+    //
+    // Use these instead of `patterns.essential` when you only want to
+    // ADD entries to the essential category without replacing the
+    // built-in patterns (zest_*, csrf*, xsrf*, session*, __host-*,
+    // __secure-*).
+    essentialKeys: [],
+    essentialPatterns: [],
+
     // Custom domains to block (in addition to mode-based blocking)
     blockedDomains: [], // days
 
@@ -1374,6 +2000,28 @@ var Zest = (function () {
       config.patterns = userConfig.patterns;
     }
 
+    // Interceptor toggles — shallow-merge so consumers can pass partial
+    // overrides like `intercept: { storage: false }` without losing the
+    // other defaults.
+    if (userConfig.intercept && typeof userConfig.intercept === 'object') {
+      config.intercept = {
+        ...DEFAULTS.intercept,
+        ...userConfig.intercept
+      };
+    }
+
+    // Strictly-necessary declarations
+    if (Array.isArray(userConfig.essentialKeys)) {
+      config.essentialKeys = userConfig.essentialKeys.filter(
+        (k) => typeof k === 'string' && k.length > 0 && k.length <= 200
+      );
+    }
+    if (Array.isArray(userConfig.essentialPatterns)) {
+      config.essentialPatterns = userConfig.essentialPatterns.filter(
+        (p) => typeof p === 'string' && p.length > 0 && p.length <= 500
+      );
+    }
+
     return config;
   }
 
@@ -1785,6 +2433,11 @@ var Zest = (function () {
     replayCookies(categories);
     replayStorage(categories);
     replayScripts(categories);
+    // Element-level replays (script/link/img/iframe URLs that were
+    // dropped at the prototype-setter / setAttribute layer). Network
+    // interceptor (fetch/XHR/sendBeacon) intentionally has no replay
+    // — beacons are one-shot and resending would duplicate analytics.
+    replayElements(categories);
   }
 
   /**
@@ -1816,13 +2469,44 @@ var Zest = (function () {
       setPatterns(currentConfig.patterns);
     }
 
+    // Append consumer-declared strictly-necessary entries on top of
+    // whatever's already in the essential category. This is the friendly
+    // alternative to overriding via `patterns.essential` directly.
+    if (
+      (Array.isArray(currentConfig.essentialKeys) && currentConfig.essentialKeys.length > 0) ||
+      (Array.isArray(currentConfig.essentialPatterns) && currentConfig.essentialPatterns.length > 0)
+    ) {
+      appendPatternsToCategory('essential', {
+        keys: currentConfig.essentialKeys,
+        patternStrings: currentConfig.essentialPatterns
+      });
+    }
+
+    setConsentChecker$4(checkConsent);
+    setConsentChecker$3(checkConsent);
     setConsentChecker$2(checkConsent);
     setConsentChecker$1(checkConsent);
     setConsentChecker(checkConsent);
 
-    interceptCookies();
-    interceptStorage();
-    startScriptBlocking(currentConfig.mode, currentConfig.blockedDomains);
+    // Interceptor toggles. By default everything is intercepted (back-compat
+    // with v2.0 / v2.1). Consumers that gate scripts and storage themselves
+    // can opt out per channel via `intercept: { storage: false, … }`.
+    const intercept = currentConfig.intercept || { cookies: true, storage: true, scripts: true, network: true };
+    if (intercept.cookies !== false) interceptCookies();
+    if (intercept.storage !== false) interceptStorage();
+    if (intercept.scripts !== false) {
+      // Element-level synchronous interception (prototype setters +
+      // setAttribute) installs BEFORE startScriptBlocking so that the
+      // moment any later script does `el.src = "https://tracker..."`,
+      // we drop the URL before the browser fetches. The MutationObserver
+      // inside startScriptBlocking remains as a defence-in-depth net for
+      // anything that slips past (e.g. nodes constructed via cloneNode).
+      interceptElements(currentConfig.mode, currentConfig.blockedDomains);
+      startScriptBlocking(currentConfig.mode, currentConfig.blockedDomains);
+    }
+    if (intercept.network !== false) {
+      interceptNetwork(currentConfig.mode, currentConfig.blockedDomains);
+    }
 
     const consent = loadConsent();
     initialized = true;
@@ -2961,18 +3645,29 @@ ${customCss}
   }
 
   /**
-   * Initialize Zest with UI.
+   * UI mount guard. We split UI mounting (which needs `<body>` and a parsed
+   * DOM) from interceptor installation (which must happen on script eval to
+   * gate any later `defer` / `async` tracker scripts). `coreInit()` is
+   * idempotent so calling init() before the DOM is ready is safe — the UI
+   * portion just gets queued.
    */
-  function init(userConfig = {}) {
-    const { alreadyInitialized, consent, hasDecision, dntApplied } = coreInit(userConfig);
-    if (alreadyInitialized) {
-      console.warn('[Zest] Already initialized');
-      return Zest;
+  let uiMounted = false;
+
+  function mountUI() {
+    if (uiMounted) return;
+
+    // Banner needs document.body to mount its host element. If body isn't
+    // there yet, requeue on DOMContentLoaded.
+    if (!document || !document.body) {
+      document.addEventListener('DOMContentLoaded', mountUI, { once: true });
+      return;
     }
 
+    uiMounted = true;
     const config = getActiveConfig();
+    const decision = hasConsentDecision();
 
-    if (!hasDecision && !dntApplied) {
+    if (!decision) {
       showBanner({
         onAcceptAll: handleAcceptAll,
         onRejectAll: handleRejectAll,
@@ -2982,7 +3677,27 @@ ${customCss}
     } else if (config?.showWidget) {
       showWidget({ onClick: handleShowSettings });
     }
+  }
 
+  /**
+   * Initialize Zest with UI.
+   *
+   * Splits into two phases:
+   *
+   *   1. `coreInit()` runs synchronously: interceptors install on the
+   *      cookie / storage / script / network channels immediately so any
+   *      `defer` or `async` script that fires later is already gated.
+   *      Critical — DOMContentLoaded fires AFTER `defer` scripts execute,
+   *      so deferring interceptor install means trackers fire first.
+   *
+   *   2. UI mount (banner / widget) is queued until `<body>` exists. If
+   *      this script runs in `<head>` while the document is still
+   *      parsing, that means waiting for DOMContentLoaded; if it runs
+   *      after, mount happens immediately.
+   */
+  function init(userConfig = {}) {
+    coreInit(userConfig);
+    mountUI();
     return Zest;
   }
 
@@ -3091,17 +3806,14 @@ ${customCss}
       window.Zest = Zest;
     }
 
-    const autoInit = () => {
-      const cfg = getConfig();
-      if (cfg.autoInit !== false) {
-        init(window.ZestConfig);
-      }
-    };
-
-    if (document.readyState === 'loading') {
-      document.addEventListener('DOMContentLoaded', autoInit);
-    } else {
-      autoInit();
+    // Run init() synchronously on script eval. init() itself splits the
+    // work — interceptors install now, UI mount waits for <body> if
+    // needed. No DOMContentLoaded wait at this layer: deferring init()
+    // would let any `defer` / `async` tracker script fire its network
+    // calls before our interceptors are in place.
+    const cfg = getConfig();
+    if (cfg.autoInit !== false) {
+      init(window.ZestConfig);
     }
   }