@freshjuice/zest 2.1.0 → 2.3.0

package/dist/zest.headless.esm.js

@@ -141,10 +141,47 @@ const DEFAULT_PATTERNS = {
 
 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 };
@@ -204,19 +241,19 @@ let originalCookieDescriptor = null;
 // 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;
 }
 
 /**
@@ -272,10 +309,10 @@ function interceptCookies() {
 
       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,
@@ -300,7 +337,7 @@ function interceptCookies() {
 
 // 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;
@@ -311,13 +348,13 @@ const localStorageQueue = [];
 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;
 }
 
 /**
@@ -330,9 +367,9 @@ function createStorageProxy(storage, queue, storageName) {
         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,
@@ -615,11 +652,11 @@ function isThirdParty(url) {
 
 // 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
@@ -630,31 +667,31 @@ const scriptQueue = [];
 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');
 
@@ -687,7 +724,7 @@ function getScriptBlockCategory(script) {
   // 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;
 
@@ -699,17 +736,17 @@ function getScriptBlockCategory(script) {
   }
 
   // 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':
@@ -743,7 +780,7 @@ function blockScript(script) {
     return false;
   }
 
-  if (checkConsent$1(category)) {
+  if (checkConsent$3(category)) {
     // Consent already given - allow script
     script.setAttribute('data-zest-processed', 'allowed');
     return false;
@@ -777,7 +814,7 @@ function blockScript(script) {
     script.removeAttribute('src');
   }
 
-  if (scriptQueue.length < MAX_QUEUE_SIZE) {
+  if (scriptQueue.length < MAX_QUEUE_SIZE$1) {
     scriptQueue.push(scriptInfo);
   }
   return true;
@@ -858,8 +895,8 @@ function handleMutations(mutations) {
  * Start observing for new scripts
  */
 function startScriptBlocking(mode = 'safe', customDomains = []) {
-  blockingMode = mode;
-  customBlockedDomains = customDomains;
+  blockingMode$2 = mode;
+  customBlockedDomains$2 = customDomains;
 
   // Process existing scripts
   processExistingScripts();
@@ -875,6 +912,568 @@ function startScriptBlocking(mode = 'safe', customDomains = []) {
   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
  */
@@ -1663,6 +2262,33 @@ const DEFAULTS = {
   // 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
 
@@ -1745,6 +2371,28 @@ function mergeConfig(userConfig) {
     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;
 }
 
@@ -2053,6 +2701,11 @@ function replayAll(categories) {
   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);
 }
 
 /**
@@ -2084,13 +2737,44 @@ function coreInit(userConfig = {}) {
     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;