@uniweb/runtime 0.12.9 → 0.12.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.12.9",
+  "version": "0.12.10",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.11.1",
+    "@uniweb/core": "^0.12.0",
     "@uniweb/theming": "^0.1.15"
   },
   "devDependencies": {
@@ -44,7 +44,7 @@
     "esbuild": "^0.21.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.27.0",
     "vite": "^7.3.1",
     "vitest": "^4.1.7",
-    "@uniweb/build": "0.25.0"
+    "@uniweb/build": "0.25.3"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/components/WebsiteRenderer.jsx

@@ -12,6 +12,7 @@ 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'
 
 /**
  * WebsiteRenderer component
@@ -41,6 +42,11 @@ export default function WebsiteRenderer() {
   // 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()
+
   if (!website) {
     return (
       <div className="website-loading" style={{ padding: '2rem', textAlign: 'center', color: '#64748b' }}>

package/src/document-tracking.js

@@ -4,10 +4,15 @@
  * ⭐ **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` alone; the next
- * emitter meeting the same condition belongs in this chunk, and one meeting a
+ * 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.
  *
+ * ⛔ **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.
+ * The grouping is about WHEN THE CHUNK LOADS, never about sharing a callback.
+ *
  * ⛔ **`section-views.js` stays separate** — its condition is narrower (a page
  * may override, so it is armed per page rather than per document). ⛔ **And
  * `script-loader.js` stays separate on a different axis entirely** — a site can
@@ -136,3 +141,115 @@ export function observeOutboundClicks(tracking) {
     document.removeEventListener('auxclick', onClick, true)
   }
 }
+
+/* ------------------------------------------------------------------ *
+ * section_click — which sections a visitor actually interacts with.
+ *
+ * ⭐ **Armed per DOCUMENT, not per page — unlike `section_view`.** That event
+ * needs `trackSections` because it emits **once per section per page view**, so
+ * a long page costs many times what a short one does and the cardinality had to
+ * be capped at the granularity the cost varies at. **A click is bounded by what
+ * a visitor does**, exactly like `outbound_click`, so the cost shape that forced
+ * the page flag does not arise here.
+ *
+ * ⇒ **And therefore no delivery projection.** A page-level flag would need the
+ * stored flag carried onto the runtime payload — a distinct item owned by
+ * another lane and invisible from this one. That gap shipped once already and
+ * cost a day of a working emitter reporting nothing.
+ *
+ * ⛔ **THE ELEMENT LOOKUP GOES THROUGH THE GRAPH, never through a selector.**
+ * There is no `data-section-id` attribute in this renderer — a section wrapper
+ * carries `id="section-<stableId>"`, written by `sectionDomId()`. And the
+ * obvious repair, `closest('[id^="section-"]')`, is also wrong: a hardcoded
+ * prefix is a second copy of a rule that already drifted once — the search
+ * extractor kept emitting `Section1` while the DOM said
+ * `section-what-is-uniweb`, every section-level result on every site pointed at
+ * a fragment that did not exist, and no test failed.
+ *
+ * ⚖️ **Both wrong versions fail the same way and it is the worst way**: a
+ * selector that matches nothing throws nothing and logs nothing. It reports
+ * zero clicks on every section of every site, with the payload internally
+ * consistent and every check green.
+ *
+ * ⭐ **Double-counting with `outbound_click` is DELIBERATE.** A link inside a
+ * section is both a section interaction and a departure; both answers are true,
+ * and deduping would under-count whichever lost the tie-break. ⛔ The constraint
+ * is a *reporting* one — the two must never be summed into a "clicks" total.
+ * ------------------------------------------------------------------ */
+
+import { sectionDomId } from '@uniweb/core/section-id'
+
+/**
+ * The rendered sections of one page, as a DOM-id → Block lookup.
+ *
+ * Derived from the graph and keyed by the same helper the renderers write the
+ * id with, so this cannot drift from what is in the document. A block whose
+ * element is absent is skipped — in split-content mode a page's sections can
+ * arrive later, and a click before then simply does not resolve.
+ *
+ * @param {object} page - the active `Page`
+ * @returns {Map<string, object>}
+ */
+function sectionsById(page) {
+  const map = new Map()
+  for (const block of page?.bodyBlocks || []) {
+    const id = sectionDomId(block)
+    if (document.getElementById(id)) map.set(id, block)
+  }
+  return map
+}
+
+/**
+ * Report clicks landing inside a section, attributed to that section.
+ *
+ * @param {() => object} getPage - reads the CURRENTLY active page. A function
+ *        rather than a value because one listener outlives every SPA
+ *        navigation; capturing a page would attribute every later click to the
+ *        page the visitor first landed on.
+ * @returns {(() => void) | null} teardown, or null when there is no DOM
+ */
+export function observeSectionClicks(getPage) {
+  if (typeof document === 'undefined' || typeof getPage !== 'function') return null
+
+  // Rebuilt when the page identity changes, not on every click. Navigation is
+  // the only thing that invalidates it, and it is the cheap moment to notice.
+  let cachedPage = null
+  let cachedMap = null
+
+  const onClick = (event) => {
+    const page = getPage()
+    if (!page) return
+    if (page !== cachedPage) {
+      cachedPage = page
+      cachedMap = sectionsById(page)
+    }
+    if (!cachedMap.size) return
+
+    // Walk up rather than `closest(selector)`: the ids come from the graph, so
+    // there is no selector to write that is not a second copy of the id rule.
+    // `id` values can also contain characters a selector would have to escape.
+    let el = event.target
+    while (el && el.nodeType === 1) {
+      const block = el.id ? cachedMap.get(el.id) : undefined
+      if (block) {
+        // Through the BLOCK, so `path`, `section` (the type) and `section_id`
+        // (this instance) are attached by the one envelope every section-scoped
+        // event shares. The consumer joins clicks to views on those fields.
+        block.track('section_click')
+        return
+      }
+      el = el.parentElement
+    }
+  }
+
+  // ⛔ CAPTURE, and `auxclick` alongside `click` — same two reasons as
+  // `outbound_click` above: a foundation may `stopPropagation()` on its own
+  // handlers, and a middle click fires only `auxclick`.
+  document.addEventListener('click', onClick, true)
+  document.addEventListener('auxclick', onClick, true)
+
+  return () => {
+    document.removeEventListener('click', onClick, true)
+    document.removeEventListener('auxclick', onClick, true)
+  }
+}

package/src/hooks/useSectionClicks.js

@@ -0,0 +1,100 @@
+/**
+ * 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