uniweb 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "^0.8.5",
-    "@uniweb/kit": "^0.12.0",
-    "@uniweb/runtime": "^0.11.7"
+    "@uniweb/core": "^0.10.0",
+    "@uniweb/kit": "^0.12.2",
+    "@uniweb/runtime": "^0.12.0"
   },
   "peerDependencies": {
-    "@uniweb/content-reader": "^1.2.2",
-    "@uniweb/build": "^0.22.0",
-    "@uniweb/semantic-parser": "^1.2.2"
+    "@uniweb/build": "^0.24.0",
+    "@uniweb/semantic-parser": "^1.2.2",
+    "@uniweb/content-reader": "^1.2.2"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -1954,6 +1954,108 @@ from. `values` keeps the `File` so your input can show its selection.
 
 Full reference: `development/receiving-form-submissions.md`.
 
+### Tracking (`tracking:`)
+
+A site may declare one **tracking destination**, and everything worth counting
+goes there as an event on a single stream. A page visit is just the event the
+runtime emits by itself.
+
+```yaml
+# site.yml — your own collector, on any host
+tracking: https://collector.example.com/events
+
+# or, when it needs more than an address
+tracking:
+  endpoint: /collect
+  consent: required
+```
+
+A host may also supply one under `services.tracking`, and the usual precedence
+applies: yours wins, then the host's, then neither.
+
+⚠️ **The endpoint has to accept the framework's own format** — a batched
+`{ "events": [ … ] }` POST, documented in `reference/site-configuration.md`. It
+is not a third-party analytics product's public API, which expects that
+product's own shape.
+
+A site may also name a vendor's own script under `tracking.scripts`, which the
+runtime loads once, after consent when a gate is declared, and never in a frame
+or during prerender. That is a **separate path with no connection to the stream
+below** — the vendor measures its own way, and nothing you `track()` reaches it.
+
+**The runtime reports `page_view` on every route change, including the first.**
+That is the only thing it emits on its own — everything else is yours to report:
+
+```jsx
+// In a section type, the block is already in your props.
+block.track('video_milestone', { milestone: 50 })
+```
+
+`block.track` attaches the page path and the section type for you. For an event
+with no block in hand, use the hook:
+
+```jsx
+import { useTracker } from '@uniweb/kit'
+
+const { track } = useTracker()
+<button onClick={() => track('brochure_download', { file: 'specs.pdf' })}>…</button>
+```
+
+The event name is yours — there is no list of permitted names. Three are already
+in use, so reach for these rather than inventing a synonym: **`page_view`** (the
+runtime), **`scroll_depth`** (kit's `useScrollDepth()`, with a `depth` of 25 /
+50 / 75 / 100) and **`video_milestone`** (kit's `<Media>`, with `milestone` and
+`src`). Put the varying part in a **field**, never in the name — four names for
+one event turn a collector's event dimension into a cardinality problem.
+
+⛔ **Never guard a `track()` call.** A site with **no** tracking destination is
+the default and the majority: the call returns having done nothing, opened no
+connection, and thrown nothing. Absent is the normal state, not an error — so
+don't check whether tracking is on, and never render differently because of it.
+There is no "is tracking enabled" question a component should be asking.
+
+⚠️ **If a site asks for consent**, tracking holds everything until a visitor
+answers; granting sends what was buffered, denying discards it. A consent banner
+is an ordinary component:
+
+```jsx
+import { useTrackingConsent } from '@uniweb/kit'
+
+const { status, grant, deny } = useTrackingConsent()
+if (status !== 'pending') return null
+return <CookieBanner onAccept={grant} onReject={deny} />
+```
+
+Without `consent: required`, tracking starts immediately — declaring a
+destination is the site owner's decision to make, not the framework's.
+
+Every event carries a **`visit`** key on the envelope — opaque, generated at page
+load, the same for every event of that page load — so a collector can order what
+happened into a journey.
+
+> **What is never sent:** no visitor id, no fingerprint, no session spanning days
+> or tabs, and **nothing is written to the visitor's device** — no cookie, no
+> local storage. The `visit` key lives in memory and dies with the document, so
+> it identifies one page load rather than a person. A `page_view` carries the
+> path, and — captured once when the page first loads, then replayed on each view
+> — the external referrer and any `utm_*` the visitor arrived with. Nothing else.
+
+### ⛔ Use kit. Never touch the `uniweb` global
+
+Everything above reaches the runtime through `@uniweb/kit` or through something
+handed to your component as a prop. That is the rule, not a stylistic preference:
+
+- ✅ `useWebsite()`, `useTracker()`, `resolveService(website, …)` — kit hooks and
+  utilities.
+- ✅ `block.track(…)`, `block.page`, `block.website` — the block **arrives in your
+  props**, so calling methods on it is not reaching for a global.
+- ⛔ `globalThis.uniweb`, `window.uniweb` — never, in a foundation.
+
+The singleton is framework internals: its shape is not part of the contract with
+foundations, and code that reads it directly breaks on changes that were never
+breaking changes. If you need something kit does not expose yet, that is worth
+reporting — not worth reaching around.
+
 <!-- template:loom -->
 ### Content handlers
 

package/src/commands/doctor.js

@@ -307,7 +307,7 @@ export function checkAgentsBlock({ siteName, siteYml, issues }) {
       .join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not recognized.`
   )
   for (const key of unknown) {
-    const near = nearestAgentsKey(key, known)
+    const near = nearestKnownKey(key, known)
     if (near) log(`    ${colors.dim}'${key}' — did you mean ${colors.reset}${colors.green}${near}${colors.reset}${colors.dim}?${colors.reset}`)
   }
   log(
@@ -326,7 +326,7 @@ export function checkAgentsBlock({ siteName, siteYml, issues }) {
  * for `origins`, and a wrong suggestion is worse than none — it sends the
  * author to change a line that was not their mistake.
  */
-function nearestAgentsKey(input, known) {
+function nearestKnownKey(input, known) {
   let best = null
   let bestScore = Infinity
   for (const candidate of known) {
@@ -339,6 +339,148 @@ function nearestAgentsKey(input, known) {
   return bestScore <= 3 ? best : null
 }
 
+/**
+ * The options `tracking:` actually has a reader.
+ *
+ * ⚠️ **Kept here rather than imported, because nothing at runtime enumerates
+ * them** — `wireTracker` reads named properties off the resolved declaration, it
+ * does not iterate a list. So there is no existing array to import and this
+ * duplicates nothing. It does mean the list can drift: the readers are
+ * `runtime/src/wire-foundation.js::wireTracker` (`consent`, `scripts`, `debug`)
+ * and `core/src/services.js::readEndpoint` (`endpoint`). Add a key there, add it
+ * here.
+ */
+const TRACKING_KEYS = ['endpoint', 'consent', 'scripts', 'debug']
+
+/**
+ * Spellings that read as an ATTEMPT to require consent but do not require it.
+ *
+ * `consentRequired` is `options.consent === 'required'` — an exact match — so
+ * every one of these silently means *no gate*. That is the one field in this
+ * block where a silent no-op has a consequence beyond a missing metric.
+ *
+ * ⚖️ Deliberately not "anything that is not `required`": `consent: none` is a
+ * documented, useful value — it is how a site overrides a gate its **host**
+ * declared, under the per-key tier fill. Flagging that would flag correct code.
+ */
+const CONSENT_NEAR_MISSES = new Set(['require', 'requires', 'required.', 'true', 'yes', 'on', '1'])
+
+/**
+ * `tracking:` — flag the keys and values that are carried and never acted on.
+ *
+ * The block is forwarded to the host as opaque data and resolved at render, so
+ * nothing downstream rejects a mistake in it. Every error here therefore fails
+ * the same way: **silently, at a visitor's browser, as an absence** — which is
+ * also exactly what a site that configured nothing looks like. There is no
+ * symptom to notice and nothing to grep for.
+ *
+ * ⭐ That is the whole argument for checking it at `doctor` time: it is the only
+ * moment in the chain where a person who can fix it is looking at it.
+ *
+ * A bare `tracking: <url>` string is the documented shorthand and carries no
+ * options — there is nothing in it to be wrong.
+ */
+export function checkTrackingBlock({ siteName, siteYml, issues }) {
+  const tracking = siteYml?.tracking
+  if (tracking === undefined || tracking === null) return
+  if (typeof tracking === 'string') return
+
+  if (typeof tracking !== 'object' || Array.isArray(tracking)) {
+    const id = 'tracking-not-an-object'
+    issues.push({
+      id,
+      type: 'warning',
+      site: siteName,
+      message: `site.yml: \`tracking:\` should be an endpoint string, or a map of options`
+    })
+    warn(`[${id}] ${siteName}: \`tracking:\` is neither an endpoint string nor a map of options.`)
+    return
+  }
+
+  const known = new Set(TRACKING_KEYS)
+  const unknown = Object.keys(tracking).filter((k) => !known.has(k))
+  if (unknown.length > 0) {
+    const id = 'tracking-unknown-key'
+    issues.push({
+      id,
+      type: 'warning',
+      site: siteName,
+      message: `site.yml: \`tracking:\` has ${unknown.length === 1 ? 'an unknown key' : 'unknown keys'}: ${unknown.join(', ')}`
+    })
+    warn(
+      `[${id}] ${siteName}: \`tracking:\` ${unknown.length === 1 ? 'key' : 'keys'} ${unknown
+        .map((k) => `'${k}'`)
+        .join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not recognized.`
+    )
+    for (const key of unknown) {
+      const near = nearestKnownKey(key, known)
+      if (near) log(`    ${colors.dim}'${key}' — did you mean ${colors.reset}${colors.green}${near}${colors.reset}${colors.dim}?${colors.reset}`)
+    }
+    log(
+      `    ${colors.dim}Carried to the host as opaque data and never read. Known: ${TRACKING_KEYS.join(', ')}.${colors.reset}`
+    )
+  }
+
+  // `consent` is exact-matched against 'required'. A near miss is not a typo
+  // with a cosmetic cost — it is a consent gate the author believes they asked
+  // for and did not get.
+  if ('consent' in tracking) {
+    const value = tracking.consent
+    const spelling = value === null || value === undefined ? '' : String(value).trim().toLowerCase()
+
+    // ⛔ The gate test is against the RAW value, because the runtime's is:
+    // `options.consent === 'required'`, exact and case-sensitive. Lowercasing
+    // before this comparison made `Required` look correct to the checker — the
+    // check stopped testing the thing it was written to catch. The normalized
+    // spelling is only for deciding whether a wrong value reads as an ATTEMPT.
+    const gateIsOn = value === 'required'
+    const looksIntended =
+      spelling === '' || spelling === 'required' || CONSENT_NEAR_MISSES.has(spelling)
+
+    if (!gateIsOn && looksIntended) {
+      const id = 'tracking-consent-not-required'
+      const shown = spelling === '' ? 'an empty value' : `\`${String(value)}\``
+      issues.push({
+        id,
+        type: 'warning',
+        site: siteName,
+        message: `site.yml: \`tracking.consent:\` is ${shown} — only the exact value \`required\` turns the gate on`
+      })
+      warn(`[${id}] ${siteName}: \`tracking.consent:\` is ${shown}; the gate is OFF.`)
+      log(
+        `    ${colors.dim}Only \`consent: required\` holds events until a visitor answers. Anything else${colors.reset}`
+      )
+      log(
+        `    ${colors.dim}sends immediately — including a blank value, which YAML reads as null.${colors.reset}`
+      )
+    }
+  }
+
+  // An entry that yields no URL is dropped by the loader without a sound.
+  const declared = tracking.scripts
+  if (declared !== undefined) {
+    const list = Array.isArray(declared) ? declared : [declared]
+    const bad = list.filter(
+      (e) => !(typeof e === 'string' ? e.trim() : typeof e?.src === 'string' && e.src.trim())
+    )
+    if (bad.length > 0) {
+      const id = 'tracking-script-without-url'
+      issues.push({
+        id,
+        type: 'warning',
+        site: siteName,
+        message: `site.yml: \`tracking.scripts:\` has ${bad.length} ${bad.length === 1 ? 'entry' : 'entries'} with no URL`
+      })
+      warn(
+        `[${id}] ${siteName}: ${bad.length} \`tracking.scripts:\` ${bad.length === 1 ? 'entry has' : 'entries have'} no URL and will not load.`
+      )
+      log(
+        `    ${colors.dim}An entry is a URL, or an object with a \`src\`. Anything else is dropped silently.${colors.reset}`
+      )
+    }
+  }
+}
+
 /** Levenshtein distance, iterative two-row form. */
 function editDistance(a, b) {
   if (a === b) return 0
@@ -760,6 +902,7 @@ export async function doctor(args = []) {
     // Forms need a destination, and having none is only visible on the page.
     await checkFormSubmitTarget({ sitePath, siteName, siteYml, issues })
     checkAgentsBlock({ siteName, siteYml, issues })
+    checkTrackingBlock({ siteName, siteYml, issues })
 
     checkGeneratedDataDir({
       sitePath,

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-13T20:52:45.396Z",
+  "generatedAt": "2026-08-16T05:48:07.516Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.22.0",
+      "version": "0.24.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -28,7 +28,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.8.5",
+      "version": "0.10.0",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -46,7 +46,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.12.0",
+      "version": "0.12.2",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -65,7 +65,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.3.1",
+      "version": "0.3.3",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -73,7 +73,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.11.7",
+      "version": "0.12.0",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -111,7 +111,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.7",
+      "version": "0.8.9",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",