@uniweb/core 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {

package/src/services.js

@@ -180,26 +180,62 @@ export function resolveService(website, name) {
 }
 
 /**
- * Read a service's declaration object, whichever tier supplied it.
+ * Read a service's options, filling each key from the first tier that declares
+ * it — **the site's value wins per key, and the host fills the gaps.**
  *
  * `resolveService` answers *where*; this answers *with what options*. Only the
  * object form carries any — a shorthand string is an address and nothing else.
- * Used by `tracking:` for `consent:`; a future service with its own options
- * reads them the same way rather than inventing a second lookup.
  *
- * The tiers are checked in the same order and for the same reason, so a site
- * that authors the object form is not silently merged with a host's.
+ * ## ⛔ Why per-key rather than all-or-nothing
+ *
+ * This used to return the site's object whole whenever the site declared
+ * *anything*, so a single authored key hid every option the host offered. That
+ * put the two readers in this file on different rules, and the disagreement was
+ * not cosmetic:
+ *
+ *   - `resolveService` already falls through **per key** — a site declaration
+ *     carrying no `endpoint` lets the host's endpoint answer.
+ *   - `readServiceOptions` fell through **not at all**.
+ *
+ * ⇒ A site declaring only `tracking: { tags: [...] }` therefore kept sending to
+ * the **host's** endpoint while discarding the **host's** `consent` setting —
+ * using someone's collector while ignoring their gate. Not a corner case: it is
+ * what an operator gets by turning on a third-party tag while their host
+ * supplies the collector.
+ *
+ * One rule now covers both readers, and it is the one a reader of two-tier
+ * config already expects: the more specific tier wins where it speaks, and says
+ * nothing where it is silent.
+ *
+ * ⚖️ **Consequence worth stating, because it decides a question that would
+ * otherwise need its own rule:** a host's `consent` applies only when the site
+ * declared none. That is the host *filling a gap*, never overriding an
+ * operator's decision — so there is no "most restrictive wins" special case,
+ * and an operator who wants no gate on a host that asks for one writes
+ * `consent: none` and is done.
+ *
+ * ⚠️ **The merge is shallow and deliberately so.** Keys replace, they do not
+ * combine: a site's `tags` replaces a host's rather than concatenating with it.
+ * Combining would make the result depend on what a host happens to offer, which
+ * is precisely the unpredictability a site's own config should not have.
  *
  * @param {object} website
  * @param {string} name
- * @returns {object} the declaration object, or `{}` when there is none
+ * @returns {object} the effective options, or `{}` when no tier declares any
  */
 export function readServiceOptions(website, name) {
   const config = website?.config
-  const authored = config?.[name]
-  if (authored !== undefined) {
-    return authored && typeof authored === 'object' ? authored : {}
-  }
-  const hosted = config?.services?.[name]
-  return hosted && typeof hosted === 'object' ? hosted : {}
+  return { ...asOptions(config?.services?.[name]), ...asOptions(config?.[name]) }
+}
+
+/**
+ * A declaration contributes options only in its object form. A string is an
+ * address, an array is malformed, and neither carries a key worth spreading.
+ *
+ * @param {*} declaration
+ * @returns {object}
+ */
+function asOptions(declaration) {
+  if (!declaration || typeof declaration !== 'object' || Array.isArray(declaration)) return {}
+  return declaration
 }

package/src/tracker.js

@@ -160,8 +160,11 @@ export default class Tracker {
     // 'granted' | 'denied' | 'pending'. Without a consent requirement the
     // operator's act of declaring a destination IS the decision, and the
     // framework does not presume a jurisdiction on their behalf.
+    // ⛔ The requirement is consumed HERE and not stored. A `consentRequired`
+    // field was kept alongside and read by nothing — dead instance state in a
+    // class every site loads, which is what `destroy()` and its three fields
+    // were removed for. The starting status is the whole of what the flag means.
     this.consent = options.consentRequired ? 'pending' : 'granted'
-    this.consentRequired = !!options.consentRequired
 
     this.queue = []
     this.acquisition = null
@@ -180,11 +183,17 @@ export default class Tracker {
     // reports three times.
     this.currentPath = null
 
-    this.flushIntervalId = null
-    this.onPageHide = null
-    this.onVisibilityChange = null
     this.framed = detectFramed()
 
+    // Called once when consent moves to granted, and never otherwise. The
+    // runtime uses it to load a site's declared third-party tags at the moment
+    // they become permitted; nothing in core knows or cares what it does.
+    //
+    // ⛔ Declared HERE because the instance is sealed below — an assignment to
+    // an undeclared property throws in module code, and the caller assigns this
+    // after construction. Same reason `Uniweb.defaultInsets` is pre-declared.
+    this.onGranted = null
+
     if (isBrowser && this.isEnabled()) {
       this.acquisition = captureAcquisition()
       // Minted even when consent is pending: events buffered before the visitor
@@ -200,14 +209,30 @@ export default class Tracker {
   }
 
   /**
-   * Enabled means: a destination exists, we are in a browser, and we are not
-   * inside someone's iframe. Consent is checked separately — a consent-pending
-   * tracker is *enabled* and buffering, which is a different state from off.
+   * Whether this document is one where the site's telemetry should run at all —
+   * a real visit in a browser, rather than a server render or a framed
+   * authoring preview. Says nothing about whether anything is *configured*.
+   *
+   * Split out from `isEnabled()` because a second consumer needs exactly this
+   * half: the runtime loads a site's declared third-party tags, which have no
+   * endpoint of ours to check but must be suppressed in the same contexts and
+   * for the same reason. One predicate, so the two cannot drift.
+   *
+   * @returns {boolean}
+   */
+  isLiveDocument() {
+    return isBrowser && !this.framed
+  }
+
+  /**
+   * Enabled means: a destination exists, and this is a live document. Consent
+   * is checked separately — a consent-pending tracker is *enabled* and
+   * buffering, which is a different state from off.
    *
    * @returns {boolean}
    */
   isEnabled() {
-    return !!this.endpoint && isBrowser && !this.framed
+    return !!this.endpoint && this.isLiveDocument()
   }
 
   /** @returns {'granted'|'denied'|'pending'} */
@@ -223,15 +248,44 @@ export default class Tracker {
    * decision, and the views that preceded the click are not lost. Denying
    * discards the buffer and stops accepting.
    *
+   * ⛔ **Recording the decision is NOT gated on `isEnabled()`, deliberately.**
+   * Consent is *the visitor's answer*; enablement is *whether we have anywhere
+   * to send*. Two different questions, and conflating them meant a decision
+   * could not be recorded **when no destination resolved** — benign while our
+   * own queue is the only thing gated on consent, a correctness bug the moment
+   * anything else is.
+   *
+   * The same conflation suppressed recording inside a framed document. That
+   * suppression exists so an authoring session cannot inflate a site's own
+   * numbers (see `detectFramed`), and it belongs on the *sending*: with
+   * `consentRequired` the status starts `'pending'` and could not move at all,
+   * so a banner following the documented pattern would render and then never
+   * dismiss.
+   *
+   * Nothing is sent as a result: `flush()` keeps its own `isEnabled()` guard,
+   * so a disabled tracker still transmits nothing no matter what is recorded
+   * here. This changes what the tracker *remembers*, never what it *emits*.
+   *
    * @param {boolean} granted
    */
   setConsent(granted) {
-    if (!this.isEnabled()) return
+    const wasGranted = this.consent === 'granted'
     this.consent = granted ? 'granted' : 'denied'
-    if (granted) {
-      this.flush()
-    } else {
+
+    if (!granted) {
       this.queue = []
+      return
+    }
+
+    this.flush()
+
+    // Fires on the TRANSITION only, so a component calling grant() twice does
+    // not load a site's tags twice. The callback is cleared as it runs: this is
+    // a one-time permission, not a subscription.
+    if (!wasGranted && this.onGranted) {
+      const notify = this.onGranted
+      this.onGranted = null
+      notify()
     }
   }
 
@@ -330,35 +384,34 @@ export default class Tracker {
     })
   }
 
-  /** @private */
+  /**
+   * Both of these are armed once, for the life of the document, and are never
+   * detached — so neither the interval id nor the handler references are kept.
+   *
+   * ⛔ **There is deliberately no `destroy()`.** One shipped, was called by
+   * nothing, and cost 334 bytes minified in a package **every site loads
+   * whether it tracks or not** (`@uniweb/core` is not tree-shaken — the
+   * singleton's constructor holds a `Tracker`, so the class can never be
+   * dropped). Removing it took three instance fields with it, since they
+   * existed only to serve it.
+   *
+   * ⭐ The precedent is the thing this class replaced: `analytics.js` was dead
+   * code that shipped to every site for months because nobody deleted it.
+   * Adding a never-called teardown method would have been the same mistake at
+   * smaller scale. If a lifecycle that needs teardown ever appears, it arrives
+   * *with* its call site — which is the order that keeps this honest.
+   *
+   * @private
+   */
   armFlushInterval() {
-    this.flushIntervalId = setInterval(() => this.flush(), this.flushInterval)
+    setInterval(() => this.flush(), this.flushInterval)
   }
 
   /** @private */
   armUnloadHandlers() {
-    this.onPageHide = () => this.flush(true)
-    this.onVisibilityChange = () => {
+    window.addEventListener('pagehide', () => this.flush(true))
+    window.addEventListener('visibilitychange', () => {
       if (document.visibilityState === 'hidden') this.flush(true)
-    }
-    window.addEventListener('pagehide', this.onPageHide)
-    window.addEventListener('visibilitychange', this.onVisibilityChange)
-  }
-
-  /** Stop the interval, detach listeners, and send what is left. */
-  destroy() {
-    if (this.flushIntervalId) {
-      clearInterval(this.flushIntervalId)
-      this.flushIntervalId = null
-    }
-    if (isBrowser) {
-      if (this.onPageHide) window.removeEventListener('pagehide', this.onPageHide)
-      if (this.onVisibilityChange) {
-        window.removeEventListener('visibilitychange', this.onVisibilityChange)
-      }
-    }
-    this.onPageHide = null
-    this.onVisibilityChange = null
-    this.flush(true)
+    })
   }
 }