@uniweb/core 0.10.1 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -40,8 +40,8 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "^1.2.3",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/semantic-parser": "^1.2.3"
   },
   "scripts": {
     "test": "vitest run"

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

@@ -207,6 +207,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 +270,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 +377,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