@uniweb/core 0.10.1 → 0.11.0

package/package.json

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

package/src/page.js

@@ -48,13 +48,24 @@ export default class Page {
     // Rewrite target (if set, this route is served by an external site)
     this.rewrite = pageData.rewrite || null
 
-    // Opt this page into section-level instrumentation (`trackSections` in
-    // page.yml). Off by default, and PAGE-LEVEL ONLY — there is deliberately no
-    // site-wide or folder-level spelling, because one event per section on every
-    // page of a site produces far more distinct values than an analytics
-    // consumer can reasonably retain. The runtime reads it to decide whether to
-    // arm an observer; it means nothing without a tracking destination.
-    this.trackSections = pageData.trackSections || false
+    // This page's answer on section-level instrumentation (`trackSections` in
+    // page.yml) — an OVERRIDE, not a switch.
+    //
+    // ⭐ **Three states, and the third is the point.** `undefined` means the page
+    // said nothing and the site's own `tracking.emit` decides; `true` and
+    // `false` override it in either direction, so an owner can instrument one
+    // page of a quiet site or exempt a noisy page of a loud one.
+    //
+    // ⛔ **`|| false` was wrong here and collapsed the tri-state**, which made
+    // page-level the ONLY spelling and forced every owner to tick pages
+    // individually. The wire already carried all three — `content-collector`
+    // emits the key only when it is `!= null` — so nothing but this line had to
+    // change. ⇒ Read `?? undefined`, never a boolean coercion.
+    //
+    // The runtime passes it to `Tracker.arms('section_view', …)`, which is where
+    // the precedence against the host's own list is resolved. It means nothing
+    // without a tracking destination.
+    this.trackSections = pageData.trackSections ?? undefined
 
     // Two orthogonal visibility axes:
     //  • `hidden` — REACHABILITY. When true the page is excluded from the published

package/src/tracker.js

@@ -171,13 +171,28 @@ export default class Tracker {
    * @param {Object} options
    * @param {string} [options.endpoint] - destination; **required to enable**
    * @param {boolean} [options.consentRequired=false] - hold everything until granted
-   * @param {number} [options.flushInterval=5000]
+   * @param {number} [options.flushIntervalMs=5000] - batch window, MILLISECONDS
    * @param {number} [options.maxQueueSize=10]
    * @param {boolean} [options.debug=false]
    */
   constructor(options = {}) {
     this.endpoint = options.endpoint || null
-    this.flushInterval = options.flushInterval || 5000
+    // ⭐ **`Ms` is in the name because the unit cannot be inferred from the
+    // value, and the failure is silent and inverted.** A bare `flushInterval:
+    // 30` meaning *thirty seconds* reads here as 30 **milliseconds** — flushing
+    // ~33x a second, the opposite of the intent, indistinguishable from working
+    // config, and paid for by the host rather than by whoever typed it. The wire
+    // field the host emits is `flushIntervalMs` for the same reason; this option
+    // is spelled to match so nothing has to translate between them.
+    //
+    // ⛔ **No floor is imposed, deliberately.** A minimum here would be a second
+    // copy of a policy the host already owns, able only to disagree with theirs —
+    // the same reason this framework never co-owns a serve location. What is
+    // rejected is not a *small* value but an *invalid* one: anything non-finite
+    // or <= 0 would arm a spinning or never-firing timer, so it falls back to the
+    // default rather than being honoured.
+    const interval = options.flushIntervalMs
+    this.flushIntervalMs = Number.isFinite(interval) && interval > 0 ? interval : 5000
     this.maxQueueSize = options.maxQueueSize || 10
     this.debug = options.debug || false
 
@@ -207,6 +222,17 @@ export default class Tracker {
     // reports three times.
     this.currentPath = null
 
+    // What the runtime may ARM, as two independent narrowings. Both are `null`
+    // when nothing narrows, which is the common case and the cheap one.
+    //
+    // ⛔ **Neither ever filters `track()`.** The registry is open by design, and
+    // a client-side allowlist over a foundation's own events would export one
+    // host's policy onto every host — including hosts that sent no list, whose
+    // sites would silently drop everything their foundation emits. These gate
+    // the runtime's OWN emissions and nothing else. See `arms()`.
+    this.hostEvents = options.hostEvents ? new Set(options.hostEvents) : null
+    this.siteEmit = options.siteEmit ? new Set(options.siteEmit) : null
+
     this.framed = detectFramed()
 
     // Called once when consent moves to granted, and never otherwise. The
@@ -259,6 +285,39 @@ export default class Tracker {
     return !!this.endpoint && this.isLiveDocument()
   }
 
+  /**
+   * Whether the runtime should ARM one of its own automatic emitters.
+   *
+   * ⭐ **Three questions, in the order that makes each one's absence safe:**
+   *
+   * 1. **Is there anywhere to send, in a live document?** — `isEnabled()`.
+   * 2. **Will the host consume this?** `hostEvents` is the host's cost switch:
+   *    no point arming an observer for a row nobody stores. ⛔ **Absent means NO
+   *    NARROWING, never an empty set** — a host that sends no list is an older
+   *    or simpler one, and reading absence as "consume nothing" would take
+   *    every site on that host dark with every gate reading yes.
+   * 3. **Did the site ask for it?** `siteEmit` is the operator's own selection.
+   *    Absent means everything.
+   *
+   * `override` is the per-page answer where one exists (`page.trackSections`).
+   * It replaces the SITE's answer and cannot escape the host's: a page may
+   * widen what its own site configured, and may not conjure a row the host
+   * declined to store.
+   *
+   * ⛔ **Not consulted by `track()`.** A foundation's events are never gated —
+   * see the constructor.
+   *
+   * @param {string} event
+   * @param {boolean} [override] - the per-page decision, when the caller has one
+   * @returns {boolean}
+   */
+  arms(event, override) {
+    if (!this.isEnabled()) return false
+    if (this.hostEvents && !this.hostEvents.has(event)) return false
+    if (override != null) return !!override
+    return !this.siteEmit || this.siteEmit.has(event)
+  }
+
   /** @returns {'granted'|'denied'|'pending'} */
   consentStatus() {
     return this.consent
@@ -333,7 +392,7 @@ export default class Tracker {
    * @param {string} path
    */
   trackPageView(path) {
-    if (!this.isEnabled() || !path) return
+    if (!this.arms('page_view') || !path) return
     if (path === this.currentPath) return
     this.currentPath = path
     // Promptly, rather than waiting out the batch window: a page view is the
@@ -428,7 +487,7 @@ export default class Tracker {
    * @private
    */
   armFlushInterval() {
-    setInterval(() => this.flush(), this.flushInterval)
+    setInterval(() => this.flush(), this.flushIntervalMs)
   }
 
   /** @private */