@uniweb/core 0.11.2 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -40,7 +40,7 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "^1.3.0",
+    "@uniweb/semantic-parser": "^1.3.1",
     "@uniweb/theming": "^0.1.15"
   },
   "scripts": {

package/src/services.js

@@ -175,7 +175,32 @@ export function resolveService(website, name) {
   // no stake in it. See the entitlement note above.
   if (hostDeclaration !== undefined) return { url: null, source: 'host' }
 
-  // 3 — nobody supplied one.
+  // ⭐ A HOST THAT EMITTED A SERVICES BLOCK IS ANSWERING — for every service,
+  // not only the ones it named. The block is the host's statement of what it
+  // offers, so a name ABSENT from it carries the same answer as a name present
+  // with no address: this host does not offer that service.
+  //
+  // Without this, "the host offers tracking and not search" and "there is no
+  // host at all" are the same value, and a caller with a fallback takes it. A
+  // caller with no fallback cannot tell the difference and never could, which
+  // is why this was invisible until search — the one service with a legacy
+  // zero-config default to fall through to — started 404ing on hosted sites.
+  //
+  // ⇒ The rule this implements: **a control for a service the site does not
+  // have must not be drawn** — uniformly, for every service, and without any
+  // explanation offered to a visitor. Not-provisioned is not an error and not a
+  // thing to apologise for; it is simply a feature the site does not have, the
+  // same way it has no contact form when `submit` is absent.
+  //
+  // ⚠️ This deliberately reads the SITE CONFIG the runtime already holds rather
+  // than asking a host for a new signal. The payload states what is on and what
+  // is off; the renderer's job is to not draw what cannot be used.
+  if (config?.services && typeof config.services === 'object' && !Array.isArray(config.services)) {
+    return { url: null, source: 'host' }
+  }
+
+  // 3 — nobody supplied one. No host is speaking, so a caller's own default
+  // (search's local index, say) is still correct — that is the static-host path.
   return { url: null, source: null }
 }
 

package/src/tracker.js

@@ -247,6 +247,24 @@ export default class Tracker {
     // reports three times.
     this.currentPath = null
 
+    // ── time_on_page ─────────────────────────────────────────────────────
+    // ⛔ Declared here because the instance is SEALED below — an assignment to
+    // an undeclared property throws in module code. Same reason `onGranted` and
+    // `Uniweb.defaultInsets` are pre-declared.
+    //
+    // ⭐ No new listener is needed for any of this: `armUnloadHandlers` already
+    // registers `pagehide` and `visibilitychange`, and `trackPageView` already
+    // knows the SPA route boundary. This is arithmetic inside handlers that
+    // already run.
+    /** When the current path became active. */
+    this.pageEnteredAt = null
+    /** Hidden time accrued on the current path, in ms. */
+    this.hiddenMs = 0
+    /** When the document last became hidden, or `null` while visible. */
+    this.hiddenSince = null
+    /** Guards against a second report for one page visit — see `reportTimeOnPage`. */
+    this.pageReported = false
+
     // What the runtime may ARM, as two independent narrowings. Both are `null`
     // when nothing narrows, which is the common case and the cheap one.
     //
@@ -414,15 +432,88 @@ export default class Tracker {
    * Report a page view. Framework-owned: it carries the acquisition context and
    * dedupes consecutive reports of the same path.
    *
+   * ⭐ **`first_of_load` marks the one view that opened this document**, and it
+   * is computed here rather than living in `acquisition` — precisely because
+   * everything in `acquisition` is *replayed* onto every view, and this must
+   * not be. Exactly one emission per `Tracker` can carry it: `currentPath` is
+   * `null` only before the first report and is never reset.
+   *
+   * ⛔ **Why it exists at all, since a consumer holding the events can derive
+   * it from `visit`.** Not every consumer holds the events. A counter store
+   * that keeps no per-event rows cannot ask *"was this the first `page_view`
+   * with this `visit`?"* without remembering which `visit` values it has seen —
+   * which is retaining `visit`, arrived at by the back door. This bit makes the
+   * document-scoped question answerable with **no collector state at all**, and
+   * a store that deliberately retains nothing is a supported consumer, not an
+   * unusual one.
+   *
+   * ⛔ **The name carries the unit on purpose.** Bare `first` reads as *the
+   * visitor's first ever view*, which is a claim this file refuses to make and
+   * could not make — nothing here survives the document. The unit is **one
+   * document load**, so a panel built on it counts loads, never people and
+   * never sessions. *(`lane-chain.md` §4a: when a misread name is paid by
+   * another lane, put the constraint in the name.)*
+   *
+   * ⛔ **IT MUST NEVER SHIP IN A RELEASE THAT LACKS `continues`, and that is a
+   * standing contract rather than an accident of ordering.** A consumer uses
+   * its *presence* as proof that this emitter is new enough to have sent
+   * `continues` had the referrer been same-origin — which is what lets an
+   * entry-page metric drop the "runtime too old to say" case entirely instead
+   * of caveating it. Backport `first_of_load` to a line without `continues`
+   * and every such consumer starts counting continuations as arrivals, with
+   * nothing anywhere reporting an error. *(The dependency is one-way:
+   * `continues` without `first_of_load` is fine and shipped that way.)*
+   *
+   * ⚖️ **It states a FACT, not a metric** — the same discipline as `continues`.
+   * Whether a first-of-load view is an "entry page" also depends on
+   * `continues`, and that combination is the consumer's to make; a field named
+   * `entry` would age badly the moment a second metric wanted this bit.
+   *
    * @param {string} path
    */
   trackPageView(path) {
-    if (!this.arms('page_view') || !path) return
+    if (!path) return
     if (path === this.currentPath) return
+
+    // ⛔ **EVERYTHING DOWN TO THE `arms` CHECK IS PAGE-BOUNDARY BOOKKEEPING, NOT
+    // AN EMISSION.** It must not sit behind `arms('page_view')`, because two
+    // other things read it and neither is `page_view`:
+    //
+    //   - `currentPath` is the default `path` for EVERY event `track()` sends —
+    //     a foundation's own events and `outbound_click` among them. Gated, a
+    //     site that selects `outbound_click` without `page_view` reports every
+    //     event with `path: undefined`, silently.
+    //   - `time_on_page` is armed independently, so gating its clock behind a
+    //     different event's selection means a site that asks for it gets
+    //     nothing at all.
+    //
+    // ⚖️ Both failures are invisible: no error, no warning, a plausible payload
+    // with a field quietly missing. The bookkeeping is cheap and unconditional;
+    // only the EMISSION below is a decision.
+    //
+    // The OUTGOING path's dwell closes before `currentPath` moves — the SPA
+    // boundary an unload-only implementation misses, which would report one
+    // duration per document and silently attribute it to the last page seen.
+    this.reportTimeOnPage()
+    const firstOfLoad = this.currentPath === null
     this.currentPath = path
+    this.startTimeOnPage()
+
+    if (!this.arms('page_view')) return
     // Promptly, rather than waiting out the batch window: a page view is the
     // event most likely to be the only one of a short visit.
-    this.enqueue({ event: 'page_view', path, ...(this.acquisition || {}) }, true)
+    //
+    // Emitted only when true, like `continues` — absent is the negative, and it
+    // keeps every later view the size it already was.
+    this.enqueue(
+      {
+        event: 'page_view',
+        path,
+        ...(this.acquisition || {}),
+        ...(firstOfLoad ? { first_of_load: true } : {})
+      },
+      true
+    )
   }
 
   /**
@@ -511,15 +602,85 @@ export default class Tracker {
    *
    * @private
    */
+  /**
+   * Begin measuring dwell on the path that just became active.
+   *
+   * @private
+   */
+  startTimeOnPage() {
+    this.pageEnteredAt = Date.now()
+    this.hiddenMs = 0
+    this.hiddenSince = null
+    this.pageReported = false
+  }
+
+  /**
+   * Report how long the visitor spent on the current path, once.
+   *
+   * ⭐ **A RAW scalar, with no floor and no clamp.** Both belong to the
+   * collector: a threshold baked in here is frozen at the speed of framework
+   * release → foundation rebuild → site republish, where the same threshold
+   * applied at write time changes when the host deploys. Dwell is also violently
+   * skewed — a tab left open overnight sits in the same mean as forty readers —
+   * so a clamp is genuinely needed; it is just not needed *here*.
+   *
+   * ⛔ **Hidden time is subtracted**, or this measures tab-open rather than
+   * reading. A backgrounded tab accrues nothing.
+   *
+   * ⛔ **Reported at a route change and at `pagehide` — NOT when the document
+   * merely becomes hidden.** Visibility is a *pause*, not an end: someone who
+   * switches tabs to look something up and comes back is still reading. Emitting
+   * on hidden would truncate exactly the engaged readers this metric exists to
+   * find, and — because the consumer derives a mean from a sum and a count —
+   * emitting more than once per page visit would inflate the count and make
+   * every mean wrong. Hence `pageReported`: **at most one per page visit.**
+   *
+   * ⚠️ **The cost of that choice, stated rather than hidden:** a page discarded
+   * while hidden, without `pagehide`, is never reported. That is an
+   * under-count, it is bounded, and it fails in the direction that does not
+   * corrupt the statistic.
+   *
+   * @private
+   */
+  reportTimeOnPage() {
+    if (this.pageReported || this.pageEnteredAt === null || !this.currentPath) return
+    if (!this.arms('time_on_page')) return
+
+    const now = Date.now()
+    // A tab hidden at this instant has not yet had its span folded in.
+    const openHidden = this.hiddenSince === null ? 0 : now - this.hiddenSince
+    const durationMs = now - this.pageEnteredAt - this.hiddenMs - openHidden
+
+    this.pageReported = true
+    // Negative is not reachable by arithmetic, but a clock adjustment mid-visit
+    // would produce one, and a negative duration poisons a sum the consumer
+    // cannot repair.
+    if (durationMs < 0) return
+    this.enqueue({ event: 'time_on_page', path: this.currentPath, durationMs })
+  }
+
+  /** @private */
   armFlushInterval() {
     setInterval(() => this.flush(), this.flushIntervalMs)
   }
 
   /** @private */
   armUnloadHandlers() {
-    window.addEventListener('pagehide', () => this.flush(true))
+    window.addEventListener('pagehide', () => {
+      // Order matters: the report must be QUEUED before the beacon goes, or it
+      // rides the next flush — and for a page being unloaded there is no next.
+      this.reportTimeOnPage()
+      this.flush(true)
+    })
     window.addEventListener('visibilitychange', () => {
-      if (document.visibilityState === 'hidden') this.flush(true)
+      if (document.visibilityState === 'hidden') {
+        // A pause, not an end — see `reportTimeOnPage`. Only the clock stops.
+        if (this.hiddenSince === null) this.hiddenSince = Date.now()
+        this.flush(true)
+      } else if (this.hiddenSince !== null) {
+        this.hiddenMs += Date.now() - this.hiddenSince
+        this.hiddenSince = null
+      }
     })
   }
 }

package/src/website.js

@@ -1016,12 +1016,34 @@ export default class Website {
   // ─────────────────────────────────────────────────────────────────
 
   /**
-   * Check if search is enabled for this site
+   * Check if search is enabled for this site.
+   *
+   * ⛔ `search: false` USED TO LEAVE SEARCH ON. The predicate was
+   * `config?.search?.enabled !== false`, and optional chaining short-circuits
+   * on `null`/`undefined` only — so `false?.enabled` evaluates `false.enabled`
+   * to `undefined`, and `undefined !== false` is `true`. An author writing the
+   * natural shorthand for "off" got search **on**, silently.
+   *
+   * ⚠️ Measured on a live hosted payload 2026-08-25: the boolean form is what
+   * actually arrives — that site carried `config.search === true`, which
+   * worked only by
+   * the same accident. Only the object form is documented, so the boolean is
+   * either authored or synthesized upstream; either way it reaches here.
+   *
+   * ⭐ Why this mattered more than its size: on a backend-hosted site the
+   * search index is not emitted (see `getSearchIndexUrl` below), so an operator
+   * whose search box is failing reaches for exactly this switch — and it was
+   * the one input that did nothing.
+   *
+   * Both forms now work, and absent still means enabled.
+   *
    * @returns {boolean}
    */
   isSearchEnabled() {
-    // Search is enabled by default unless explicitly disabled
-    return this.config?.search?.enabled !== false
+    const search = this.config?.search
+    if (typeof search === 'boolean') return search
+    // Enabled by default unless explicitly disabled.
+    return search?.enabled !== false
   }
 
   /**
@@ -1029,7 +1051,12 @@ export default class Website {
    * @returns {Object} Search configuration
    */
   getSearchConfig() {
-    const config = this.config?.search || {}
+    // A boolean `search:` carries no options — normalize it away so every
+    // read below (`config.provider`, `config.include?.…`) sees an object.
+    // `true || {}` would otherwise yield `true` and every option read would
+    // land on a boolean.
+    const raw = this.config?.search
+    const config = (raw && typeof raw === 'object') ? raw : {}
 
     return {
       enabled: this.isSearchEnabled(),