@uniweb/runtime 1.3.9 → 1.3.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "1.3.9",
+  "version": "1.3.10",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@uniweb/core": "~1.6.0",
+    "@uniweb/core": "~1.6.1",
     "@uniweb/theming": "~1.2.1"
   },
   "devDependencies": {
@@ -44,7 +44,7 @@
     "esbuild": "^0.21.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.27.0 || ^0.28.0",
     "vite": "^7.3.1",
     "vitest": "^4.1.7",
-    "@uniweb/build": "1.13.11"
+    "@uniweb/build": "1.14.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/components/WebsiteRenderer.jsx

@@ -11,8 +11,7 @@ import ThemeProvider from './ThemeProvider.jsx'
 import { useRememberScroll } from '../hooks/useRememberScroll.js'
 import { useLinkInterceptor } from '../hooks/useLinkInterceptor.js'
 import { usePageView } from '../hooks/usePageView.js'
-import { useOutboundClicks } from '../hooks/useOutboundClicks.js'
-import { useSectionClicks } from '../hooks/useSectionClicks.js'
+import { useDocumentEvents } from '../hooks/useDocumentEvents.js'
 
 /**
  * WebsiteRenderer component
@@ -37,15 +36,12 @@ export default function WebsiteRenderer() {
   // is disabled and this does nothing at all.
   usePageView()
 
-  // Report where visitors go when they leave. Same unconditional-call contract
-  // as usePageView, and armed once for the document rather than per route — the
-  // listener is delegated on `document` and outlives SPA navigation.
-  useOutboundClicks()
-
-  // Which sections visitors interact with. Same contract and the same arming
-  // condition, so it shares the chunk — but a separate `arms()` call, because a
-  // host may consume one of the two and not the other.
-  useSectionClicks()
+  // Report what a visitor does that the document's own listeners can see: where
+  // they go when they leave, which sections they interact with, what counts as a
+  // conversion. Same unconditional-call contract as usePageView, and armed once for
+  // the document rather than per route — the listeners are delegated on `document`
+  // and outlive SPA navigation.
+  useDocumentEvents()
 
   if (!website) {
     return (

package/src/document-tracking.js

@@ -4,13 +4,13 @@
  * ⭐ **The grouping rule, which is what this file is really for.** Everything
  * here needs exactly `tracking.arms(<event>)` with no further condition: a
  * destination exists, this is a live document, and neither the host nor the site
- * narrowed the event away. Today that is `outbound_click` and `section_click`;
- * an emitter meeting the same condition belongs in this chunk, and one meeting a
- * different condition does not.
+ * narrowed the event away. Today that is `outbound_click`, `section_click` and
+ * `conversion`; an emitter meeting the same condition belongs in this chunk, and
+ * one meeting a different condition does not.
  *
- * ⛔ **Two events, two independent arming calls, two listeners — deliberately.**
- * A host may name one and not the other, so they cannot share a registration:
- * folding them into one listener would arm both whenever either was selected.
+ * ⛔ **Three events, three independent arming calls, three listeners — deliberately.**
+ * A host may name one and not the others, so they cannot share a registration:
+ * folding them into one listener would arm all of them whenever one was selected.
  * The grouping is about WHEN THE CHUNK LOADS, never about sharing a callback.
  *
  * ⛔ **`section-views.js` stays separate** — its condition is narrower (a page
@@ -70,8 +70,7 @@
  *
  * ⛔ `mailto:` and `tel:` are deliberately absent. They are contact intents, not
  * navigations, and folding them in would put `mail` beside real destinations in
- * a chart about where traffic goes. They are worth their own event if anyone
- * asks for one; they are not worth corrupting this one.
+ * a chart about where traffic goes. They are `conversion` events instead, below.
  */
 const REPORTED_PROTOCOLS = new Set(['http:', 'https:'])
 
@@ -105,6 +104,16 @@ export function outboundHostname(href, here) {
   return url.hostname || null
 }
 
+/**
+ * A right click, which fires `auxclick` as a middle click does, and opens a menu rather
+ * than the link: "copy link address" is not a visit. Measured 2026-11-01, Chromium and
+ * WebKit. ⛔ Until then `outbound_click` and `section_click` counted it.
+ *
+ * @param {{ button?: number }} event
+ * @returns {boolean}
+ */
+const opensMenu = (event) => event.button > 1
+
 /**
  * Listen for clicks that leave the site and report the destination host.
  *
@@ -115,6 +124,7 @@ export function observeOutboundClicks(tracking) {
   if (typeof document === 'undefined' || !tracking?.track) return null
 
   const onClick = (event) => {
+    if (opensMenu(event)) return
     // `closest` rather than the target itself: the click almost always lands on
     // a child of the anchor — an icon, a span, the text node's element.
     const anchor = event.target?.closest?.('a[href]')
@@ -133,7 +143,8 @@ export function observeOutboundClicks(tracking) {
   document.addEventListener('click', onClick, true)
   // A middle click fires `auxclick`, not `click`. Opening a link in a new tab
   // is a real outbound visit, and omitting it would undercount silently and
-  // unevenly — power users do it far more than average visitors.
+  // unevenly — power users do it far more than average visitors. A right click
+  // fires it too, which `opensMenu` leaves out.
   document.addEventListener('auxclick', onClick, true)
 
   return () => {
@@ -217,6 +228,7 @@ export function observeSectionClicks(getPage) {
   let cachedMap = null
 
   const onClick = (event) => {
+    if (opensMenu(event)) return
     const page = getPage()
     if (!page) return
     if (page !== cachedPage) {
@@ -253,3 +265,139 @@ export function observeSectionClicks(getPage) {
     document.removeEventListener('auxclick', onClick, true)
   }
 }
+
+/* ------------------------------------------------------------------ *
+ * conversion — what the site counts, with no foundation code.
+ *
+ * Only the name crosses the wire. A phone number, an email address, a link and a
+ * page all stay here, so *"the path and query string never leave the page"* holds
+ * for this event as it does for `outbound_click`.
+ *
+ * ⭐ **Two sources, and the second needs someone to say what counts.** A `tel:` or
+ * `mailto:` tap is one by itself. A link or a page counts only when the site lists
+ * it (`services.tracking.conversions`), because nothing here can tell that this
+ * link is the sign-up and that one is the sign-in.
+ *
+ * ⚖️ **A listed conversion arms itself, and it still cannot escape the host.** A
+ * site with its own endpoint on `emit: standard` gets no automatic conversions, as
+ * that preset promises, and writing a list is that site asking for those. `arms`'
+ * override replaces the site's answer and never the host's.
+ *
+ * ⛔ **Once per name per document load.** A double tap is one contact, and so is a
+ * visitor coming back to a thank-you page within a visit. A reload is a new document
+ * and counts again, as it does for every event here.
+ *
+ * ⚖️ **`section_click` double-counts with this too, deliberately,** for the reason
+ * it does with `outbound_click`: a phone link in a section is both.
+ * ------------------------------------------------------------------ */
+
+/** The name a tap on these reports. */
+const CONTACT_NAMES = { 'tel:': 'phone', 'mailto:': 'email' }
+
+const withoutTrailingSlash = (path) => path.replace(/\/+$/, '')
+
+/** The same address, whatever query or fragment either carries. */
+function sameLink(a, b) {
+  return a.origin === b.origin && withoutTrailingSlash(a.pathname) === withoutTrailingSlash(b.pathname)
+}
+
+/**
+ * Listen for what the site counts as a conversion, and report its name.
+ *
+ * @param {{ arms: Function, track: Function, currentPath?: string|null, onPage?: Function|null }} tracking
+ * @param {() => object} getWebsite - reads the active Website: its list, and the rule
+ *        that makes a page's route the same in every language
+ * @returns {(() => void) | null} teardown, or null when there is nothing to report
+ */
+export function observeConversions(tracking, getWebsite) {
+  if (typeof document === 'undefined') return null
+
+  const declared = getWebsite()?.config?.tracking?.conversions
+  const list = Array.isArray(declared) ? declared : []
+  const automatic = tracking.arms('conversion')
+  const listed = list.length > 0 && tracking.arms('conversion', true)
+  if (!automatic && !listed) return null
+
+  const seen = new Set()
+  const once = (name) => {
+    if (seen.has(name)) return
+    seen.add(name)
+    tracking.track('conversion', { name })
+  }
+
+  const links = []
+  const pages = []
+  if (listed) {
+    for (const { name, link, page } of list) {
+      if (page) pages.push({ name, page })
+      else if (link) {
+        try {
+          links.push({ name, url: new URL(link) })
+        } catch {
+          // The build refuses one of these; a host's copy may still hold it.
+        }
+      }
+    }
+  }
+
+  // `normalizeRoute` takes the locale off and translates a localized route back, so
+  // `/thanks` is also `/es/gracias`. A fresh read each time: the language can change.
+  const routeOf = (path) => getWebsite()?.normalizeRoute?.(path) ?? path
+  const atPage = (path) => {
+    if (!path) return
+    for (const { name, page } of pages) if (routeOf(page) === routeOf(path)) once(name)
+  }
+
+  const onClick = (event) => {
+    if (opensMenu(event)) return
+    const href = event.target?.closest?.('a[href]')?.getAttribute('href')
+    if (!href) return
+    let url
+    try {
+      url = new URL(href, document.location.href)
+    } catch {
+      return
+    }
+    // The site's own name first, so it can tell one phone number from another.
+    for (const { name, url: listedUrl } of links) if (sameLink(listedUrl, url)) return once(name)
+    if (automatic && CONTACT_NAMES[url.protocol]) once(CONTACT_NAMES[url.protocol])
+  }
+
+  // ⛔ CAPTURE, and `auxclick` alongside `click` — same two reasons as `outbound_click`.
+  document.addEventListener('click', onClick, true)
+  document.addEventListener('auxclick', onClick, true)
+
+  if (pages.length) {
+    // This chunk arrives after the first page view, which may be the page that counts.
+    atPage(tracking.currentPath)
+    tracking.onPage = atPage
+  }
+
+  return () => {
+    document.removeEventListener('click', onClick, true)
+    document.removeEventListener('auxclick', onClick, true)
+    if (tracking.onPage === atPage) tracking.onPage = null
+  }
+}
+
+/**
+ * Arm each event this chunk holds, by its own `arms()` question.
+ *
+ * ⭐ Everything reads the website at the moment it needs it, through the current
+ * singleton: one listener spans every navigation, and capturing a page here would
+ * attribute every later click to the page the visitor first landed on.
+ *
+ * @param {object} tracking - the document's Tracker
+ * @returns {() => void} teardown
+ */
+export function observeDocument(tracking) {
+  const website = () => globalThis.uniweb?.activeWebsite
+  const stops = [
+    tracking.arms('outbound_click') && observeOutboundClicks(tracking),
+    tracking.arms('section_click') && observeSectionClicks(() => website()?.activePage),
+    observeConversions(tracking, website)
+  ]
+  return () => {
+    for (const stop of stops) if (stop) stop()
+  }
+}

package/src/hooks/useDocumentEvents.js

@@ -0,0 +1,64 @@
+/**
+ * useDocumentEvents — arm what a tracked document reports from its own listeners:
+ * where a visitor goes when they leave, which sections they interact with, and what
+ * the site counts as a conversion. Each is `document-tracking.js`'s to arm.
+ *
+ * ⭐ **This file is the only part always loaded.** The listeners live behind a dynamic
+ * import, so a site with no tracking destination downloads none of them. It is one hook
+ * rather than one per event because every site carries it: two copies of this effect
+ * cost every site more than a third event's whole listener costs a tracked one.
+ *
+ * ⚖️ **The condition is `isEnabled()`, not each event's `arms()`,** which is that same
+ * trade: a site narrowed to `emit: minimal` downloads the chunk and arms nothing in it,
+ * and no site pays to ask the question three times here.
+ *
+ * ## Armed ONCE for the document, not per page
+ *
+ * ⭐ **This is the difference from `useSectionViews` and it decides where the hook is
+ * mounted.** Sections are elements, so their observer must re-arm when the page's
+ * elements change. These are delegated listeners on `document`, which outlive every SPA
+ * navigation — re-arming per route would tear down and rebuild the same listeners for no
+ * reason, and a click landing mid-swap would be lost. ⇒ It belongs in `WebsiteRenderer`
+ * beside `usePageView`, keyed on nothing.
+ *
+ * ## SSR
+ *
+ * There is no SSR twin, and that IS the suppression — the same as `usePageView`. Effects
+ * do not run under `renderToString` and a Worker isolate has no `document`. Nothing to
+ * remember to switch off.
+ */
+
+import { useEffect } from 'react'
+
+/**
+ * Safe to call unconditionally: it decides *when*, never *whether*.
+ */
+export function useDocumentEvents() {
+  useEffect(() => {
+    const tracking = globalThis.uniweb?.tracking
+    // Somewhere to send, in a live document — so a framed authoring preview arms nothing.
+    if (!tracking?.isEnabled?.()) return
+
+    // `cancelled` guards the gap between asking for the module and getting it —
+    // a fast unmount would otherwise install listeners nothing ever removes.
+    let cancelled = false
+    let stop = null
+
+    import('../document-tracking.js')
+      .then((m) => {
+        if (cancelled) return
+        stop = m.observeDocument(tracking)
+      })
+      .catch(() => {
+        // Telemetry must never surface to a visitor. A chunk that fails to load
+        // costs some counts; nothing else about the page is affected.
+      })
+
+    return () => {
+      cancelled = true
+      if (stop) stop()
+    }
+  }, [])
+}
+
+export default useDocumentEvents

package/src/wire-foundation.js

@@ -302,11 +302,11 @@ export function ensureThemeCss(uniweb, foundation) {
  * site republishing. A literal list would freeze `all` at the moment the site
  * was built and quietly stop meaning "all".
  *
- * ⚖️ **`standard` and `all` select the same events today, and that is not a
- * reason to drop one.** They diverge the moment a new automatic event ships:
- * `standard` is a curated set that a release cannot grow behind an operator's
- * back, `all` is the standing yes. The volume surprise is the thing being
- * avoided — a site that never changed should not start sending more.
+ * ⚖️ **`standard` and `all` differ, and a new automatic event only ever widens
+ * the gap.** `standard` is a curated set that a release cannot grow behind an
+ * operator's back, `all` is the standing yes: `section_click`, `time_on_page` and
+ * `conversion` are `all`'s and not `standard`'s. The volume surprise is the thing
+ * being avoided — a site that never changed should not start sending more.
  *
  * ⛔ **The curated set is the answer for a site that CONFIGURED ITS OWN
  * DESTINATION. It is NOT the answer for a site whose host supplies one** — see

package/src/hooks/useOutboundClicks.js

@@ -1,64 +0,0 @@
-/**
- * useOutboundClicks — arm outbound-link reporting for the document.
- *
- * ⭐ **This file is the only part always loaded.** The listener lives behind a
- * dynamic import, so a site with no tracking destination downloads none of it —
- * the same arrangement as `useSectionViews`.
- *
- * ⛔ **One call, three questions.** `tracking.arms('outbound_click')` asks all of
- * them: is there somewhere to send in a live document (so a framed authoring
- * preview arms nothing), will the host consume this row, and did the site
- * select it. Unlike `useSectionViews` there is no per-page override to pass — see the section header
- * in `document-tracking.js` for why a page-level opt-in would cost a delivery
- * projection and buy nothing.
- *
- * ## Armed ONCE for the document, not per page
- *
- * ⭐ **This is the difference from `useSectionViews` and it decides where the
- * hook is mounted.** Sections are elements, so their observer must re-arm when
- * the page's elements change. This is a single delegated listener on
- * `document`, which outlives every SPA navigation — re-arming it per route
- * would tear down and rebuild the same listener for no reason, and a click
- * landing mid-swap would be lost. ⇒ It belongs in `WebsiteRenderer` beside
- * `usePageView`, keyed on nothing.
- *
- * ## SSR
- *
- * There is no SSR twin, and that IS the suppression — the same as
- * `usePageView`. Effects do not run under `renderToString` and a Worker isolate
- * has no `document`. Nothing to remember to switch off.
- */
-
-import { useEffect } from 'react'
-
-/**
- * Safe to call unconditionally: it decides *when*, never *whether*.
- */
-export function useOutboundClicks() {
-  useEffect(() => {
-    const tracking = globalThis.uniweb?.tracking
-    if (!tracking?.arms?.('outbound_click')) return
-
-    // `cancelled` guards the gap between asking for the module and getting it —
-    // a fast unmount would otherwise install a listener nothing ever removes.
-    let cancelled = false
-    let stop = null
-
-    import('../document-tracking.js')
-      .then((m) => {
-        if (cancelled) return
-        stop = m.observeOutboundClicks(tracking)
-      })
-      .catch(() => {
-        // Telemetry must never surface to a visitor. A chunk that fails to load
-        // costs some counts; nothing else about the page is affected.
-      })
-
-    return () => {
-      cancelled = true
-      if (stop) stop()
-    }
-  }, [])
-}
-
-export default useOutboundClicks

package/src/hooks/useSectionClicks.js

@@ -1,100 +0,0 @@
-/**
- * useSectionClicks — arm section-click reporting for the document.
- *
- * ⭐ **This file is the only part always loaded.** The listener lives behind a
- * dynamic import into `document-tracking.js` — the same chunk `outbound_click`
- * uses, because the two arm on the same condition — so a site with no tracking
- * destination downloads none of it.
- *
- * ⛔ **One call, three questions.** `tracking.arms('section_click')` asks all of
- * them: is there somewhere to send in a live document (so a framed authoring
- * preview arms nothing), will the host consume this row, and did the site select
- * it.
- *
- * ## ⛔ THIS IS NOT IN THE `standard` PRESET, and that is deliberate
- *
- * ⭐ **`section_click` is the FIRST event where `standard` and `all` diverge** —
- * the divergence `wire-foundation.js`'s `EMIT_PRESETS` was written in
- * anticipation of. `standard` is a **curated** set that a framework release must
- * not grow behind an operator's back; `all` is the standing yes. So:
- *
- * ```
- * emit: (absent) / standard   ->  does NOT arm      <- the DEFAULT
- * emit: all                   ->  arms
- * emit: [ ..., section_click] ->  arms
- * ```
- *
- * ⛔ **Do NOT "fix" this by adding the name to `standard`.** That would make a
- * site which changed nothing start sending more, which is the exact surprise the
- * two presets exist to prevent — and it is a promise the docs already make to
- * operators.
- *
- * ⚠️ **The consequence a consumer must be told, because nothing surfaces it:** a
- * host may declare this event and a collector may store it, and **a default site
- * still emits none of it**. Every gate reads yes and the series is flat. That is
- * correct behaviour, not a fault, but it is indistinguishable from a broken
- * emitter unless someone says so first.
- *
- * ⛔ **NO `trackSections` override is passed, and that is deliberate.** That
- * flag exists because `section_view` emits **once per section per page view**,
- * so its cost scales with page length and had to be capped where the cost
- * varies. A click is bounded by what a visitor does, so the same control would
- * buy nothing here — and it would cost a delivery projection to carry.
- *
- * ⚠️ **Consequence worth knowing when reading the numbers:** on a page with
- * `trackSections: false` this still reports clicks, so the click population is
- * strictly larger than the view population and **a click can exist with no view
- * row to divide by.** A per-section CTR is therefore only sound on sections
- * present in both. *(Named here because it is the emitter's doing, not the
- * collector's.)*
- *
- * ## Armed ONCE for the document, not per page
- *
- * ⭐ Same as `useOutboundClicks`, and for the same reason: this is a single
- * delegated listener on `document`, which outlives every SPA navigation.
- * Re-arming per route would tear down and rebuild the same listener for no
- * reason, and a click landing mid-swap would be lost. The *page* it attributes
- * to is read at click time instead — see `observeSectionClicks`.
- *
- * ## SSR
- *
- * There is no SSR twin, and that IS the suppression — effects do not run under
- * `renderToString` and a Worker isolate has no `document`.
- */
-
-import { useEffect } from 'react'
-
-/**
- * Safe to call unconditionally: it decides *when*, never *whether*.
- */
-export function useSectionClicks() {
-  useEffect(() => {
-    const tracking = globalThis.uniweb?.tracking
-    if (!tracking?.arms?.('section_click')) return
-
-    // `cancelled` guards the gap between asking for the module and getting it —
-    // a fast unmount would otherwise install a listener nothing ever removes.
-    let cancelled = false
-    let stop = null
-
-    import('../document-tracking.js')
-      .then((m) => {
-        if (cancelled) return
-        // Read the active page at CLICK time, not now: one listener spans every
-        // navigation, and capturing the page here would attribute every later
-        // click to whichever page the visitor first landed on.
-        stop = m.observeSectionClicks(() => globalThis.uniweb?.activeWebsite?.activePage)
-      })
-      .catch(() => {
-        // Telemetry must never surface to a visitor. A chunk that fails to load
-        // costs some counts; nothing else about the page is affected.
-      })
-
-    return () => {
-      cancelled = true
-      if (stop) stop()
-    }
-  }, [])
-}
-
-export default useSectionClicks