@uniweb/core 0.10.2 → 0.11.1

package/package.json

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

package/src/tracker.js

@@ -49,9 +49,10 @@
  * ## Field lifetime — captured once, replayed on every page view
  *
  * `document.referrer` and the landing `utm_*` params exist **at arrival and
- * nowhere afterwards**: the referrer never changes across SPA navigation, and
- * the params leave the URL on the first navigation. So they are captured once,
- * here, and attached to every `page_view` of the document.
+ * nowhere afterwards** — as does `continues`, which is derived from the same
+ * read: the referrer never changes across SPA navigation, and the params leave
+ * the URL on the first navigation. So they are captured once, here, and
+ * attached to every `page_view` of the document.
  *
  * ⇒ **Consequence worth knowing when reading the numbers:** a per-view facet
  * built on them is *derived, not observed*. `utm_source` counts "views by
@@ -113,11 +114,35 @@ function captureAcquisition() {
 
   // Same-origin referrers are dropped: internal navigation is not a referral,
   // and counting it would make a site its own top referrer on every page.
+  //
+  // ⭐ **But dropping it destroys the only thing separating two different
+  // events, so the fact that it WAS same-origin is kept as one bit.** A full
+  // document load happens either because someone arrived from outside, or
+  // because a visitor already on the site triggered a real navigation — a
+  // locale switch through kit's `<Link reload>` being the shipped case. Both
+  // reach a collector with no referrer: the first never had one, the second had
+  // it discarded here. ⇒ An "entry pages" metric built on that **invents**
+  // arrivals, counting a locale switch as somebody landing on the Spanish page.
+  //
+  // ⚖️ `continues` states the FACT, not the conclusion. Whether a continuation
+  // disqualifies an entry is the consumer's call; a field named for one metric
+  // ages badly the moment a second one wants it.
+  //
+  // ⛔ **It carries no identity and links nothing.** It says only *this document
+  // continues a visit*, never *which* — so the categorical claim in this file's
+  // header, that nothing persistent is minted, is untouched. Correlating two
+  // visits would be a session, which is exactly what is refused.
   const referrer = document.referrer
   if (referrer) {
     try {
       if (new URL(referrer).origin !== window.location.origin) {
         context.referrer = referrer
+      } else {
+        // Emitted only when true. Absent means "not a continuation" AND "an
+        // older runtime that never sent it" — indistinguishable on purpose,
+        // because that collapses to today's behaviour rather than to a wrong
+        // answer, and it keeps the common payload the size it already was.
+        context.continues = true
       }
     } catch {
       // Unparseable — treat as absent rather than forwarding a malformed value.
@@ -171,13 +196,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
 
@@ -472,7 +512,7 @@ export default class Tracker {
    * @private
    */
   armFlushInterval() {
-    setInterval(() => this.flush(), this.flushInterval)
+    setInterval(() => this.flush(), this.flushIntervalMs)
   }
 
   /** @private */