@uniweb/core 0.8.6 → 0.10.0

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@uniweb/core",
-  "version": "0.8.6",
+  "version": "0.10.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
+    "./base-path": "./src/base-path.js",
     "./data-paths": "./src/data-paths.js",
+    "./detail-url": "./src/detail-url.js",
     "./fetch-config": "./src/fetch-config.js",
     "./locale-config": "./src/locale-config.js",
     "./route-match": "./src/route-match.js",
-    "./section-id": "./src/section-id.js"
+    "./section-id": "./src/section-id.js",
+    "./services": "./src/services.js",
+    "./tracker": "./src/tracker.js"
   },
   "files": [
     "src"

package/src/base-path.js

@@ -0,0 +1,48 @@
+/**
+ * Base-path joining — a zero-dependency leaf.
+ *
+ * A site deployed under a subdirectory (`base: /docs/` in site.yml) serves
+ * every root-relative path under that prefix. This is the one function that
+ * applies it, and it is idempotent: an already-based path is not based twice.
+ *
+ * WHY IT LIVES IN CORE
+ * It began in `@uniweb/kit/utils/href`, which is where most callers are. But
+ * `@uniweb/core/services` needs it too, and **`@uniweb/runtime` does not depend
+ * on kit** — so a service address resolved in the runtime could not reach it.
+ * Rather than grow a second copy (the failure `@uniweb/core/route-match` was
+ * created to end, after one matcher was implemented twice and the copies
+ * diverged), it moved down to the layer both sides already depend on. Kit
+ * re-exports it, so no existing call site moved.
+ *
+ * Kept separate from `resolveRoute` deliberately: React Router supplies the
+ * base itself through its `basename`, so a Router-rendered link must not have
+ * it applied twice.
+ *
+ * @module @uniweb/core/base-path
+ */
+
+/**
+ * Prefix a site-root-relative href with the deployment base path.
+ *
+ * The invariant this encodes — a base is only ever joined to a path that
+ * starts at the site root — is the whole point of routing every caller
+ * through here. A bare `basePath + href` concatenation produces garbage the
+ * moment href turns out to be absolute (`/basehttps://example.com/x`), and
+ * whether it is absolute depends on a classification that has been wrong
+ * before. Guarding at the join makes the failure impossible rather than
+ * unlikely.
+ *
+ * Passed through untouched when: there is no base, the href is empty, the href
+ * is not root-relative (a bare relative path, or any absolute/scheme URL), the
+ * href is protocol-relative (`//host/…`), or the base is already applied.
+ *
+ * @param {string} href - Href to prefix
+ * @param {string} basePath - Deployment base (no trailing slash), '' for root
+ * @returns {string} Href with the base applied, or unchanged if not applicable
+ */
+export function applyBasePath(href, basePath) {
+  if (!href || typeof href !== 'string' || !basePath) return href
+  if (!href.startsWith('/') || href.startsWith('//')) return href
+  if (href === basePath || href.startsWith(basePath + '/')) return href // already based
+  return basePath + href
+}

package/src/block.js

@@ -273,6 +273,39 @@ export default class Block {
     return `${this.path}-${this.id}`
   }
 
+  /**
+   * Report an event from this section — a video milestone, a download, an
+   * expand, anything the foundation considers worth counting.
+   *
+   * ```js
+   * block.track('video_milestone', { milestone: 50 })
+   * ```
+   *
+   * The section type and the page path are attached automatically, because a
+   * block already knows both — a foundation should not have to thread context
+   * it was handed. Same arrangement as `useFormSubmit({ block })`.
+   *
+   * ⛔ **No guard is needed at the call site.** A site with no tracking
+   * destination is the default: the call returns having done nothing, opened no
+   * connection and thrown nothing. Absent is the normal state, not an error.
+   *
+   * ⭐ **This is the one tracking entry point that is not behind kit**, and that
+   * is deliberate rather than an exception: the block **arrives as a prop**
+   * (`{ content, params, block }`), so calling a method on it is not reaching
+   * for the `uniweb` global — which foundations must never do. For an event
+   * with no block in hand, use kit's `useTracker()`.
+   *
+   * @param {string} event - event name; the registry is open
+   * @param {Object} [data] - the caller's own fields
+   */
+  track(event, data = {}) {
+    globalThis.uniweb?.tracking?.track(event, {
+      path: this.path,
+      section: this.type,
+      ...data
+    })
+  }
+
   /**
    * The parent page's URL path, one level up from the current page.
    * Use this for "Back" links in detail pages: /blog/1 → /blog

package/src/detail-url.js

@@ -0,0 +1,102 @@
+/**
+ * Detail-record resolution — the ONE home for turning a collection's `detail:`
+ * declaration plus a dynamic route's params into a fetch config.
+ *
+ * Why this is a subpath rather than an EntityStore internal. A host that
+ * renders a detail page server-side has to fetch *the same record* the browser
+ * will fetch when it hydrates over that render. The four `detail:` forms below
+ * each decide a different URL, so a host that resolves them even slightly
+ * differently prerenders record A and hydrates record B — silently, and only on
+ * the routes that have a pattern. That is the same failure `./route-match.js`
+ * was extracted to end, on the fetch side instead of the routing side.
+ *
+ * Zero-dependency leaf, like `./route-match.js`, `./data-paths.js` and
+ * `./fetch-config.js`: it imports one sibling that itself imports nothing, so a
+ * consumer that must not pull core's object graph — an edge worker, a build
+ * step — can import `@uniweb/core/detail-url` directly. No `node:*`, no DOM.
+ *
+ * ## What this module does NOT decide
+ *
+ * It builds a *request*, not a result. Whether the record exists, whether the
+ * fetch is cached, and what happens when it 404s are the caller's, exactly as
+ * a matched route pattern says nothing about the record behind it.
+ */
+
+import { substitutePlaceholders } from './substitute-placeholders.js'
+
+/**
+ * Build a detail-URL fetch config from a collection config + dynamic context.
+ *
+ * Four forms of `detail:`:
+ *   - `'rest'`                — append paramValue as a path segment.
+ *   - `'query'`               — append `?paramName=paramValue`.
+ *   - `'/articles/{slug}'`    — custom URL pattern with {paramName} placeholders.
+ *   - `{ body, envelope }`    — object form. Reuses the collection's url /
+ *                               method / headers / auth; adds per-detail
+ *                               body (with placeholder substitution) and
+ *                               per-detail envelope.
+ *
+ * Returns `null` — never throws — when the collection declares no `detail:`,
+ * when the dynamic context carries no param, or when the collection has
+ * neither `url:` nor `path:` to build from. A caller treats `null` as "this
+ * collection has no separate detail fetch", which is the common case.
+ *
+ * @param {Object} collectionConfig - A resolved fetch config for the collection
+ *   (post-`resolveFetchConfigs`, so `detail` may have been auto-injected for a
+ *   `deferred:` collection — see `./fetch-config.js`).
+ * @param {{ paramName: string, paramValue: string }} dynamicContext
+ * @returns {Object|null} A fetch config carrying `url` or `path`, or null.
+ */
+export function buildDetailConfig(collectionConfig, dynamicContext) {
+  const { detail } = collectionConfig
+  if (!detail) return null
+  const { paramName, paramValue } = dynamicContext
+  if (!paramName || paramValue === undefined) return null
+
+  const baseUrl = collectionConfig.url || collectionConfig.path
+  if (!baseUrl) return null
+  const isLocalPath = !!collectionConfig.path && !collectionConfig.url
+
+  // Object form: `detail: { body, envelope }`. Reuses collection's URL +
+  // method + headers + auth. The body is placeholder-substituted against
+  // the dynamic context so `body: { variables: { slug: "{slug}" } }` works.
+  if (detail && typeof detail === 'object') {
+    const out = {
+      ...(isLocalPath ? { path: baseUrl } : { url: baseUrl }),
+      schema: collectionConfig.schema,
+      transform: collectionConfig.transform,
+    }
+    if (collectionConfig.method) out.method = collectionConfig.method
+    if (detail.body !== undefined) {
+      out.body = substitutePlaceholders(detail.body, { [paramName]: paramValue }, { encode: false })
+    } else if (collectionConfig.body !== undefined) {
+      out.body = substitutePlaceholders(collectionConfig.body, { [paramName]: paramValue }, { encode: false })
+    }
+    if (detail.envelope) out.envelope = detail.envelope
+    return out
+  }
+
+  // String-form: URL-based conventions.
+  let detailUrl
+  if (detail === 'rest') {
+    const [basePath, queryString] = baseUrl.split('?')
+    const cleanBase = basePath.replace(/\/$/, '')
+    detailUrl = queryString
+      ? `${cleanBase}/${encodeURIComponent(paramValue)}?${queryString}`
+      : `${cleanBase}/${encodeURIComponent(paramValue)}`
+  } else if (detail === 'query') {
+    const sep = baseUrl.includes('?') ? '&' : '?'
+    detailUrl = `${baseUrl}${sep}${paramName}=${encodeURIComponent(paramValue)}`
+  } else {
+    // Custom pattern like '/articles/{slug}' — substitute placeholders
+    // from the dynamic-route context. Only placeholders matching the
+    // active paramName resolve; others pass through as literal `{name}`.
+    detailUrl = substitutePlaceholders(detail, { [paramName]: paramValue })
+  }
+
+  return {
+    ...(isLocalPath ? { path: detailUrl } : { url: detailUrl }),
+    schema: collectionConfig.schema,
+    transform: collectionConfig.transform,
+  }
+}

package/src/entity-store.js

@@ -14,8 +14,8 @@
  * and in-flight dedup.
  */
 
-import { substitutePlaceholders } from './substitute-placeholders.js'
 import { isFetchRefinement, resolveFetchConfigs } from './fetch-config.js'
+import { buildDetailConfig } from './detail-url.js'
 
 /**
  * Is `block.fetch` a per-instance refinement of the ancestor's fetch config
@@ -157,67 +157,12 @@ export default class EntityStore {
   /**
    * Build a detail-URL fetch config from a collection config + dynamic context.
    *
-   * Three forms of `detail:`:
-   *   - `'rest'`                — append paramValue as a path segment.
-   *   - `'query'`               — append `?paramName=paramValue`.
-   *   - `'/articles/{slug}'`    — custom URL pattern with {paramName} placeholders.
-   *   - `{ body, envelope }`    — object form. Reuses the collection's url /
-   *                               method / headers / auth; adds per-detail
-   *                               body (with placeholder substitution) and
-   *                               per-detail envelope.
+   * Delegates to the exported resolver so a host fetching this record
+   * server-side reaches the identical rule — see `./detail-url.js` for why the
+   * four `detail:` forms are a contract rather than an implementation detail.
    */
   _buildDetailConfig(collectionConfig, dynamicContext) {
-    const { detail } = collectionConfig
-    if (!detail) return null
-    const { paramName, paramValue } = dynamicContext
-    if (!paramName || paramValue === undefined) return null
-
-    const baseUrl = collectionConfig.url || collectionConfig.path
-    if (!baseUrl) return null
-    const isLocalPath = !!collectionConfig.path && !collectionConfig.url
-
-    // Object form: `detail: { body, envelope }`. Reuses collection's URL +
-    // method + headers + auth. The body is placeholder-substituted against
-    // the dynamic context so `body: { variables: { slug: "{slug}" } }` works.
-    if (detail && typeof detail === 'object') {
-      const out = {
-        ...(isLocalPath ? { path: baseUrl } : { url: baseUrl }),
-        schema: collectionConfig.schema,
-        transform: collectionConfig.transform,
-      }
-      if (collectionConfig.method) out.method = collectionConfig.method
-      if (detail.body !== undefined) {
-        out.body = substitutePlaceholders(detail.body, { [paramName]: paramValue }, { encode: false })
-      } else if (collectionConfig.body !== undefined) {
-        out.body = substitutePlaceholders(collectionConfig.body, { [paramName]: paramValue }, { encode: false })
-      }
-      if (detail.envelope) out.envelope = detail.envelope
-      return out
-    }
-
-    // String-form: URL-based conventions.
-    let detailUrl
-    if (detail === 'rest') {
-      const [basePath, queryString] = baseUrl.split('?')
-      const cleanBase = basePath.replace(/\/$/, '')
-      detailUrl = queryString
-        ? `${cleanBase}/${encodeURIComponent(paramValue)}?${queryString}`
-        : `${cleanBase}/${encodeURIComponent(paramValue)}`
-    } else if (detail === 'query') {
-      const sep = baseUrl.includes('?') ? '&' : '?'
-      detailUrl = `${baseUrl}${sep}${paramName}=${encodeURIComponent(paramValue)}`
-    } else {
-      // Custom pattern like '/articles/{slug}' — substitute placeholders
-      // from the dynamic-route context. Only placeholders matching the
-      // active paramName resolve; others pass through as literal `{name}`.
-      detailUrl = substitutePlaceholders(detail, { [paramName]: paramValue })
-    }
-
-    return {
-      ...(isLocalPath ? { path: detailUrl } : { url: detailUrl }),
-      schema: collectionConfig.schema,
-      transform: collectionConfig.transform,
-    }
+    return buildDetailConfig(collectionConfig, dynamicContext)
   }
 
   /**

package/src/index.js

@@ -37,6 +37,12 @@ export {
 } from './data-paths.js'
 export { evaluate as evaluateWhere, match as matchWhere } from './where.js'
 export { isRichSchema, normalizeSchema } from './schemas.js'
+export { default as Tracker } from './tracker.js'
+// Also available as the zero-dependency leaves `@uniweb/core/services` and
+// `@uniweb/core/base-path` — which is how `@uniweb/runtime` reaches them,
+// since it must not pull the package root into an SSR/Worker bundle.
+export { resolveService, resolveServiceUrl, readServiceOptions } from './services.js'
+export { applyBasePath } from './base-path.js'
 export {
   resolveStyle as resolveRequestStyle,
   listStyleNames as listRequestStyleNames

package/src/services.js

@@ -0,0 +1,241 @@
+import { applyBasePath } from './base-path.js'
+
+/**
+ * Site services — where a site's search, form submissions, assistant, tracking,
+ * or anything else of that shape actually go.
+ *
+ * ## The one idea
+ *
+ * A component must never name a host. Whether this site's search is answered by
+ * a prebuilt index, a server endpoint, or a vendor API is a *deployment* fact,
+ * and a foundation that hardcodes it is coupled to one deployment. So the
+ * address comes from configuration, and there are exactly two places it can
+ * come from:
+ *
+ *   1. **The site**, authored — `search:`, `submit:`, `assistant:`, `tracking:`
+ *      in site.yml. The operator's own declaration, and it wins.
+ *   2. **The host**, served — `config.services.<name>` in the payload. What the
+ *      deployment offers, which the site never had to know about.
+ *
+ * Absent from both means the site has no such service, and the caller acts on
+ * that rather than guessing an address. That is the same rule for every service,
+ * and it is why this module exists: it was previously implemented three times —
+ * the search provider, the submit resolver, and a hand-rolled copy inside a
+ * foundation — with three slightly different base-joining rules between them.
+ *
+ * ## The registry is open, not an enum
+ *
+ * `resolveService(website, name)` takes a *name*, and the framework has no list
+ * of permitted ones. It ships **clients** only for what it already implements
+ * (search, form submission, tracking); it ships **resolution** for anything. A
+ * foundation that invents `booking` or `translate` gets the same precedence, the
+ * same base handling and the same absent-means-absent behaviour, and a host can
+ * fill the slot without a framework change.
+ *
+ * This is deliberate and it is the same shape as `fetcher.transports`: the
+ * framework owns the seam, not the catalogue.
+ *
+ * ## ⛔ WHY THIS IS IN CORE AND NOT IN KIT
+ *
+ * It began in `@uniweb/kit/utils/services.js`, and every foundation still
+ * reaches it there — kit re-exports this module unchanged, so no call site
+ * moved. It had to come down one layer because **`@uniweb/runtime` does not
+ * depend on `@uniweb/kit`** (only on core and theming), and the runtime resolves
+ * a service address itself for `tracking`. The alternative was a second resolver
+ * with the same job, which is the defect `@uniweb/core/route-match` exists to
+ * prevent.
+ *
+ * ⇒ **Foundations import from `@uniweb/kit`.** This path is the framework's own.
+ *
+ * ## What this deliberately does not model
+ *
+ * **Entitlement.** A host that will not serve a service omits it, or declares
+ * the name with no address. The framework never learns why — no plan names, no
+ * tiers, no "paid" anywhere. That is not squeamishness: this package is public,
+ * and a framework that encodes which capabilities cost money ships the business
+ * model into open source.
+ *
+ * ⛔ **There is deliberately no explanatory string, and there was one — it was
+ * a mistake.** Until 2026-08-13 a declining host could supply a `reason` that
+ * this module relayed "to the UI verbatim", with an English default when nothing
+ * did. Removed, on two counts:
+ *
+ *   1. **Wrong audience.** A visitor has no stake in which services an operator
+ *      provisioned. "Submissions are not enabled for this site" reports someone's
+ *      billing state to the public and reads like a breakage. It is neither — it
+ *      is a service that was not bought, and **a generic component is supposed to
+ *      be smart about that.**
+ *   2. **Wrong language, unfixably.** Sites here are multilingual, or unilingual
+ *      and not English. A host-supplied sentence bypasses the site's entire
+ *      localization pipeline, and a canned constant in a public package cannot
+ *      be translated at all. Any text a visitor should read is *site content*,
+ *      which is authored and localized — never a string a service layer invents.
+ *
+ * ⇒ **`url` is the whole answer, and absence is a behavioural decision rather
+ * than a message.** No submit endpoint → render no form, or degrade to something
+ * that still serves the visitor. No tracking endpoint → report nothing, silently.
+ *
+ * **The site's own base.** `config.base` is where the site *lives*, not a
+ * service it consumes — it is load-bearing for routing and asset URLs too. It
+ * stays where it is and is an input here, not an entry.
+ *
+ * @module @uniweb/core/services
+ */
+
+/** Anything with a scheme, or protocol-relative — never joined to a base. */
+const ABSOLUTE_URL_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i
+
+/**
+ * Read an endpoint out of either declaration form.
+ *
+ * A site may write the shorthand (`submit: /forms`) or the object
+ * (`submit: { endpoint: /forms }`); a host emits JSON and normally writes the
+ * object. Both are accepted from both sides — one reader, no per-side rules to
+ * remember.
+ *
+ * @param {*} declaration
+ * @returns {string} the endpoint, or '' when there is none
+ */
+function readEndpoint(declaration) {
+  if (typeof declaration === 'string') return declaration.trim()
+  if (typeof declaration?.endpoint === 'string') return declaration.endpoint.trim()
+  return ''
+}
+
+/**
+ * Join a service endpoint to the site's base path.
+ *
+ * Three cases, and the middle one is why this is not simply `applyBasePath`:
+ *
+ *   - **Absolute** (`https://…`, `//host/…`, any scheme) — passed through. A
+ *     service on another origin is not the site's to relocate.
+ *   - **Bare relative** (`_search`) — rooted first. This spelling is documented
+ *     and in use, and `applyBasePath` alone would leave it untouched, silently
+ *     producing a request relative to whatever page the visitor is on.
+ *   - **Root-relative** (`/forms`) — the ordinary case.
+ *
+ * The join itself goes through `applyBasePath` rather than concatenation,
+ * because that is where the invariant "a base is only ever joined to a path that
+ * starts at the site root" is enforced, and it is idempotent — an
+ * already-based path is not based twice.
+ *
+ * @param {string} endpoint
+ * @param {string} [basePath] - `website.basePath`
+ * @returns {string}
+ */
+export function resolveServiceUrl(endpoint, basePath = '') {
+  if (!endpoint) return ''
+  if (ABSOLUTE_URL_RE.test(endpoint)) return endpoint
+
+  const rooted = endpoint.startsWith('/') ? endpoint : `/${endpoint}`
+  // `applyBasePath` concatenates and documents its input as carrying no
+  // trailing slash, so normalizing is the caller's job — skip it and
+  // `base: /docs/` yields `/docs//forms`.
+  const base = (basePath || '').replace(/\/+$/, '')
+  return applyBasePath(rooted, base)
+}
+
+/**
+ * Resolve where a named service lives for this site.
+ *
+ * ```js
+ * const { url } = resolveService(website, 'submit')
+ * if (!url) return null          // no endpoint — render no form, or degrade
+ * ```
+ *
+ * @param {object} website - the active Website
+ * @param {string} name - service name, e.g. 'submit' · 'search' · 'tracking'
+ * @returns {{ url: string|null, source: 'site'|'host'|null }}
+ *   `url` is the whole answer for acting. `source` says which declaration
+ *   answered — a diagnostic, and the thing to check when a host's value appears
+ *   not to be taking effect. `'host'` with a null `url` means the host answered
+ *   and offered no address; `null` means nothing declared the service at all.
+ */
+export function resolveService(website, name) {
+  const config = website?.config
+  const basePath = website?.basePath
+
+  // 1 — the site's own declaration wins. An operator who named an endpoint
+  // means it, including on a host that offers one.
+  const authored = readEndpoint(config?.[name])
+  if (authored) {
+    return { url: resolveServiceUrl(authored, basePath), source: 'site' }
+  }
+
+  // 2 — what the host says it offers.
+  const hostDeclaration = config?.services?.[name]
+  const hostEndpoint = readEndpoint(hostDeclaration)
+  if (hostEndpoint) {
+    return { url: resolveServiceUrl(hostEndpoint, basePath), source: 'host' }
+  }
+
+  // A host may declare the name while offering no address — a decline. It is
+  // still the host answering, which is all a caller can use: any *wording* for
+  // that state would be ours to invent, in one language, for a visitor who has
+  // no stake in it. See the entitlement note above.
+  if (hostDeclaration !== undefined) return { url: null, source: 'host' }
+
+  // 3 — nobody supplied one.
+  return { url: null, source: null }
+}
+
+/**
+ * Read a service's options, filling each key from the first tier that declares
+ * it — **the site's value wins per key, and the host fills the gaps.**
+ *
+ * `resolveService` answers *where*; this answers *with what options*. Only the
+ * object form carries any — a shorthand string is an address and nothing else.
+ *
+ * ## ⛔ Why per-key rather than all-or-nothing
+ *
+ * This used to return the site's object whole whenever the site declared
+ * *anything*, so a single authored key hid every option the host offered. That
+ * put the two readers in this file on different rules, and the disagreement was
+ * not cosmetic:
+ *
+ *   - `resolveService` already falls through **per key** — a site declaration
+ *     carrying no `endpoint` lets the host's endpoint answer.
+ *   - `readServiceOptions` fell through **not at all**.
+ *
+ * ⇒ A site declaring only `tracking: { tags: [...] }` therefore kept sending to
+ * the **host's** endpoint while discarding the **host's** `consent` setting —
+ * using someone's collector while ignoring their gate. Not a corner case: it is
+ * what an operator gets by turning on a third-party tag while their host
+ * supplies the collector.
+ *
+ * One rule now covers both readers, and it is the one a reader of two-tier
+ * config already expects: the more specific tier wins where it speaks, and says
+ * nothing where it is silent.
+ *
+ * ⚖️ **Consequence worth stating, because it decides a question that would
+ * otherwise need its own rule:** a host's `consent` applies only when the site
+ * declared none. That is the host *filling a gap*, never overriding an
+ * operator's decision — so there is no "most restrictive wins" special case,
+ * and an operator who wants no gate on a host that asks for one writes
+ * `consent: none` and is done.
+ *
+ * ⚠️ **The merge is shallow and deliberately so.** Keys replace, they do not
+ * combine: a site's `tags` replaces a host's rather than concatenating with it.
+ * Combining would make the result depend on what a host happens to offer, which
+ * is precisely the unpredictability a site's own config should not have.
+ *
+ * @param {object} website
+ * @param {string} name
+ * @returns {object} the effective options, or `{}` when no tier declares any
+ */
+export function readServiceOptions(website, name) {
+  const config = website?.config
+  return { ...asOptions(config?.services?.[name]), ...asOptions(config?.[name]) }
+}
+
+/**
+ * A declaration contributes options only in its object form. A string is an
+ * address, an array is malformed, and neither carries a key worth spreading.
+ *
+ * @param {*} declaration
+ * @returns {object}
+ */
+function asOptions(declaration) {
+  if (!declaration || typeof declaration !== 'object' || Array.isArray(declaration)) return {}
+  return declaration
+}

package/src/tracker.js

@@ -0,0 +1,417 @@
+/**
+ * Tracker — one event stream for a site.
+ *
+ * ⭐ **A page visit is a trackable event.** That sentence is the design. There is
+ * one destination, one envelope, and one queue; the runtime emits `page_view`
+ * automatically and a foundation emits whatever else it likes, through the same
+ * path. Design doc: `kb/framework/plans/tracking.md`.
+ *
+ * ```
+ * { event: 'page_view',       path: '/about', referrer?, utm_* }
+ * { event: 'video_milestone', path: '/about', section: 'Hero', milestone: 50 }
+ * ```
+ *
+ * ## ⛔ Absent means NO-OP, at every entry point
+ *
+ * A site with no tracking destination is the DEFAULT and the majority. So with
+ * no endpoint: nothing is queued, no interval is armed, no listener is
+ * registered, and every method returns immediately. **A caller never needs a
+ * guard** — `block.track(…)` on an unconfigured site is normal, not an error.
+ * Nothing here throws, rejects, or logs unless `debug` is on.
+ *
+ * ## ⛔ Nothing PERSISTENT is ever minted here
+ *
+ * No session id, no visitor id, no fingerprint, and **nothing written to any
+ * browser storage** — no cookie, no `localStorage`, no `sessionStorage`, no
+ * IndexedDB. The privacy hazard of an identifier is *persistence and
+ * cross-context linkage*, not existence, and that is the line this class holds.
+ * `tests/tracker.test.js` asserts it mechanically rather than by promise.
+ *
+ * ✅ **The one thing it does mint is `visit`** — an opaque key generated at
+ * construction, held only in this instance, sent on every event so a consumer
+ * can tell that these events came from the same page load. It **dies with the
+ * document**: a refresh, a new tab, or tomorrow all produce a different one, and
+ * nothing links them. It is a correlation token, not an identity — closer to a
+ * trace id than to a cookie, and strictly less linkable than the IP-and-UA
+ * derivations a collector can already compute for itself.
+ *
+ * ⚖️ **Why the framework mints it rather than a host supplying one.** A host
+ * that renders per request would have to embed the value in the document it
+ * serves — and that document is cacheable, so every visitor of one cached
+ * render would share a single key and collapse into one visitor, silently, with
+ * the numbers staying plausible. Generating it in the browser does not solve
+ * that problem, it removes it.
+ *
+ * *(The ported `Analytics` class this replaces stamped `sessionId` and
+ * `sessionDuration` on every payload — a day-scoped identity and a duration.
+ * Both are gone deliberately; `visit` is neither.)*
+ *
+ * ## 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.
+ *
+ * ⇒ **Consequence worth knowing when reading the numbers:** a per-view facet
+ * built on them is *derived, not observed*. `utm_source` counts "views by
+ * visitors who **arrived** via X", never "views that **carried** X".
+ *
+ * @module @uniweb/core/tracker
+ */
+
+const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined'
+
+/**
+ * A framed document is the editor's live-preview iframe far more often than it
+ * is a legitimately embedded site, and the failure modes are asymmetric: an
+ * embedded site going uncounted is an undercount — visible and complainable —
+ * while a site owner's authoring session inflating their own numbers is a silent
+ * overcount that corrupts what the data means. Default to the side that fails
+ * loudly.
+ *
+ * A cross-origin parent throws on `window.top` access; that also means framed.
+ */
+function detectFramed() {
+  if (!isBrowser) return false
+  try {
+    return window.top !== window.self
+  } catch {
+    return true
+  }
+}
+
+/** Acquisition context, read once at construction. See "Field lifetime" above. */
+function captureAcquisition() {
+  if (!isBrowser) return null
+
+  const context = {}
+
+  // 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.
+  const referrer = document.referrer
+  if (referrer) {
+    try {
+      if (new URL(referrer).origin !== window.location.origin) {
+        context.referrer = referrer
+      }
+    } catch {
+      // Unparseable — treat as absent rather than forwarding a malformed value.
+    }
+  }
+
+  try {
+    const params = new URLSearchParams(window.location.search)
+    for (const key of ['utm_source', 'utm_medium', 'utm_campaign']) {
+      const value = params.get(key)
+      if (value) context[key] = value
+    }
+  } catch {
+    // No parseable query string — nothing to attach.
+  }
+
+  return Object.keys(context).length > 0 ? context : null
+}
+
+/**
+ * An opaque key for one document lifetime. Never stored, never persisted.
+ *
+ * `crypto.randomUUID` needs a secure context, so a site served over plain HTTP
+ * falls through to a non-cryptographic value — which is correct rather than a
+ * compromise: this is a correlation token with no security property to preserve,
+ * and a collision only merges two visits in one site's own numbers.
+ */
+function mintVisitKey() {
+  try {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+      return crypto.randomUUID()
+    }
+  } catch {
+    // Secure-context restrictions throw rather than return undefined in places.
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+}
+
+/**
+ * How many events may accumulate while consent is pending.
+ *
+ * The ordinary `maxQueueSize` triggers a *flush*, which is a no-op while
+ * pending — so without a hard cap a site that never answers the consent
+ * question would grow the queue for the whole session. Newest are dropped
+ * rather than oldest: the first `page_view` is the one worth keeping.
+ */
+const MAX_PENDING = 50
+
+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.maxQueueSize=10]
+   * @param {boolean} [options.debug=false]
+   */
+  constructor(options = {}) {
+    this.endpoint = options.endpoint || null
+    this.flushInterval = options.flushInterval || 5000
+    this.maxQueueSize = options.maxQueueSize || 10
+    this.debug = options.debug || false
+
+    // 'granted' | 'denied' | 'pending'. Without a consent requirement the
+    // operator's act of declaring a destination IS the decision, and the
+    // framework does not presume a jurisdiction on their behalf.
+    // ⛔ The requirement is consumed HERE and not stored. A `consentRequired`
+    // field was kept alongside and read by nothing — dead instance state in a
+    // class every site loads, which is what `destroy()` and its three fields
+    // were removed for. The starting status is the whole of what the flag means.
+    this.consent = options.consentRequired ? 'pending' : 'granted'
+
+    this.queue = []
+    this.acquisition = null
+
+    // One key per document, minted only when there is somewhere to send it.
+    // Rides the ENVELOPE beside `event` rather than inside a payload, because
+    // every event needs it for the same reason `event` itself is there — and
+    // because `page_view`'s payload is closed at `{ path, referrer?, utm_* }`
+    // and this must not widen it.
+    this.visit = null
+
+    // The last path a `page_view` reported. Guards consecutive duplicates —
+    // React StrictMode double-invokes effects, and this makes "one report per
+    // path change" true here rather than contingent on every caller's
+    // dependency array. NOT revisit-dedupe: it is overwritten, so A→B→A
+    // reports three times.
+    this.currentPath = null
+
+    this.framed = detectFramed()
+
+    // Called once when consent moves to granted, and never otherwise. The
+    // runtime uses it to load a site's declared third-party tags at the moment
+    // they become permitted; nothing in core knows or cares what it does.
+    //
+    // ⛔ Declared HERE because the instance is sealed below — an assignment to
+    // an undeclared property throws in module code, and the caller assigns this
+    // after construction. Same reason `Uniweb.defaultInsets` is pre-declared.
+    this.onGranted = null
+
+    if (isBrowser && this.isEnabled()) {
+      this.acquisition = captureAcquisition()
+      // Minted even when consent is pending: events buffered before the visitor
+      // answers must carry the SAME key as those after it, or granting consent
+      // would split one visit in two. It never leaves the device until the
+      // buffer flushes, so minting early costs nothing.
+      this.visit = mintVisitKey()
+      this.armFlushInterval()
+      this.armUnloadHandlers()
+    }
+
+    Object.seal(this)
+  }
+
+  /**
+   * Whether this document is one where the site's telemetry should run at all —
+   * a real visit in a browser, rather than a server render or a framed
+   * authoring preview. Says nothing about whether anything is *configured*.
+   *
+   * Split out from `isEnabled()` because a second consumer needs exactly this
+   * half: the runtime loads a site's declared third-party tags, which have no
+   * endpoint of ours to check but must be suppressed in the same contexts and
+   * for the same reason. One predicate, so the two cannot drift.
+   *
+   * @returns {boolean}
+   */
+  isLiveDocument() {
+    return isBrowser && !this.framed
+  }
+
+  /**
+   * Enabled means: a destination exists, and this is a live document. Consent
+   * is checked separately — a consent-pending tracker is *enabled* and
+   * buffering, which is a different state from off.
+   *
+   * @returns {boolean}
+   */
+  isEnabled() {
+    return !!this.endpoint && this.isLiveDocument()
+  }
+
+  /** @returns {'granted'|'denied'|'pending'} */
+  consentStatus() {
+    return this.consent
+  }
+
+  /**
+   * Record the visitor's decision. A consent component calls this through
+   * kit's `useTrackingConsent()`; foundations never touch this object.
+   *
+   * Granting flushes what was buffered — nothing left the device before the
+   * decision, and the views that preceded the click are not lost. Denying
+   * discards the buffer and stops accepting.
+   *
+   * ⛔ **Recording the decision is NOT gated on `isEnabled()`, deliberately.**
+   * Consent is *the visitor's answer*; enablement is *whether we have anywhere
+   * to send*. Two different questions, and conflating them meant a decision
+   * could not be recorded **when no destination resolved** — benign while our
+   * own queue is the only thing gated on consent, a correctness bug the moment
+   * anything else is.
+   *
+   * The same conflation suppressed recording inside a framed document. That
+   * suppression exists so an authoring session cannot inflate a site's own
+   * numbers (see `detectFramed`), and it belongs on the *sending*: with
+   * `consentRequired` the status starts `'pending'` and could not move at all,
+   * so a banner following the documented pattern would render and then never
+   * dismiss.
+   *
+   * Nothing is sent as a result: `flush()` keeps its own `isEnabled()` guard,
+   * so a disabled tracker still transmits nothing no matter what is recorded
+   * here. This changes what the tracker *remembers*, never what it *emits*.
+   *
+   * @param {boolean} granted
+   */
+  setConsent(granted) {
+    const wasGranted = this.consent === 'granted'
+    this.consent = granted ? 'granted' : 'denied'
+
+    if (!granted) {
+      this.queue = []
+      return
+    }
+
+    this.flush()
+
+    // Fires on the TRANSITION only, so a component calling grant() twice does
+    // not load a site's tags twice. The callback is cleared as it runs: this is
+    // a one-time permission, not a subscription.
+    if (!wasGranted && this.onGranted) {
+      const notify = this.onGranted
+      this.onGranted = null
+      notify()
+    }
+  }
+
+  /**
+   * Report an event.
+   *
+   * @param {string} event - event name, e.g. 'video_milestone'. Open registry.
+   * @param {Object} [data] - the caller's own fields; `path` overrides the
+   *        current route, which is what block-scoped callers supply.
+   */
+  track(event, data = {}) {
+    if (!this.isEnabled() || !event) return
+    const { path, ...rest } = data
+    this.enqueue({ event, path: path || this.currentPath || undefined, ...rest })
+  }
+
+  /**
+   * Report a page view. Framework-owned: it carries the acquisition context and
+   * dedupes consecutive reports of the same path.
+   *
+   * @param {string} path
+   */
+  trackPageView(path) {
+    if (!this.isEnabled() || !path) return
+    if (path === this.currentPath) return
+    this.currentPath = path
+    // 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)
+  }
+
+  /**
+   * @param {Object} event
+   * @param {boolean} [immediate=false]
+   * @private
+   */
+  enqueue(event, immediate = false) {
+    if (this.consent === 'denied') return
+
+    // Envelope: the visit key is stamped here, at the one choke point every
+    // event passes through, so no caller can forget it or override it.
+    const envelope = { ...event, visit: this.visit }
+
+    if (this.consent === 'pending') {
+      if (this.queue.length >= MAX_PENDING) return
+      this.queue.push(envelope)
+      if (this.debug) console.log('[Tracker] Buffered pending consent:', envelope)
+      return
+    }
+
+    this.queue.push(envelope)
+    if (this.debug) console.log('[Tracker] Queued:', envelope)
+
+    if (immediate || this.queue.length >= this.maxQueueSize) this.flush()
+  }
+
+  /**
+   * Send whatever is queued.
+   *
+   * ⛔ **A failed send is dropped, not retried.** The class this replaced put
+   * the events back with `queue.unshift(...)`, which left the queue at or above
+   * `maxQueueSize` so the *next* event flushed immediately — a tight loop
+   * against a dead endpoint, with `maxQueueSize` triggering a flush but never
+   * bounding the queue. Best-effort delivery is the norm for this shape, and
+   * `sendBeacon` is fire-and-forget regardless.
+   *
+   * @param {boolean} [useBeacon=false] - force `sendBeacon` (unload)
+   */
+  flush(useBeacon = false) {
+    if (!this.isEnabled() || this.consent !== 'granted' || this.queue.length === 0) return
+
+    const events = this.queue
+    this.queue = []
+
+    const payload = JSON.stringify({ events })
+    if (this.debug) console.log('[Tracker] Flushing', events.length, 'event(s)')
+
+    if (useBeacon && typeof navigator !== 'undefined' && navigator.sendBeacon) {
+      const blob = new Blob([payload], { type: 'application/json' })
+      const sent = navigator.sendBeacon(this.endpoint, blob)
+      if (!sent && this.debug) console.warn('[Tracker] sendBeacon refused the payload')
+      return
+    }
+
+    // The response is ignored entirely — no retry, no branch, no surfaced
+    // error. A host's 204, 403, 503 and a network failure are indistinguishable
+    // here by construction, which is what lets a host put its own preconditions
+    // in front of the collector without the client needing to know.
+    fetch(this.endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: payload,
+      keepalive: true
+    }).catch((error) => {
+      if (this.debug) console.warn('[Tracker] Flush failed:', error.message)
+    })
+  }
+
+  /**
+   * Both of these are armed once, for the life of the document, and are never
+   * detached — so neither the interval id nor the handler references are kept.
+   *
+   * ⛔ **There is deliberately no `destroy()`.** One shipped, was called by
+   * nothing, and cost 334 bytes minified in a package **every site loads
+   * whether it tracks or not** (`@uniweb/core` is not tree-shaken — the
+   * singleton's constructor holds a `Tracker`, so the class can never be
+   * dropped). Removing it took three instance fields with it, since they
+   * existed only to serve it.
+   *
+   * ⭐ The precedent is the thing this class replaced: `analytics.js` was dead
+   * code that shipped to every site for months because nobody deleted it.
+   * Adding a never-called teardown method would have been the same mistake at
+   * smaller scale. If a lifecycle that needs teardown ever appears, it arrives
+   * *with* its call site — which is the order that keeps this honest.
+   *
+   * @private
+   */
+  armFlushInterval() {
+    setInterval(() => this.flush(), this.flushInterval)
+  }
+
+  /** @private */
+  armUnloadHandlers() {
+    window.addEventListener('pagehide', () => this.flush(true))
+    window.addEventListener('visibilitychange', () => {
+      if (document.visibilityState === 'hidden') this.flush(true)
+    })
+  }
+}

package/src/uniweb.js

@@ -12,7 +12,7 @@
  */
 
 import Website from './website.js'
-import Analytics from './analytics.js'
+import Tracker from './tracker.js'
 
 export default class Uniweb {
   /**
@@ -72,7 +72,21 @@ export default class Uniweb {
     // Populated by prerender before rendering, read synchronously by Icon.
     this.iconCache = new Map()
 
-    this.analytics = new Analytics(content?.analytics || content?.config?.analytics || {})
+    // Site tracking — one event stream (`kb/framework/plans/tracking.md`).
+    //
+    // ⛔ Deliberately constructed DISABLED, and the runtime replaces it in L2
+    // (`wire-foundation.js` → `wireTracker`). It cannot be configured here even
+    // though `activeWebsite` already exists two lines up, because the address is
+    // resolved against `website.basePath` and **that is still `''` at this
+    // point** — `setBasePath()` runs later, from the runtime. Resolving here
+    // would silently drop the base prefix on every subdirectory deployment.
+    //
+    // The disabled instance is not a placeholder to null-check: it is a working
+    // no-op, so `uniweb.tracking.track(…)` is safe in every lane — press,
+    // unipress, an SSR isolate, or before wiring — with no guard at the call
+    // site. Same slot-declared-here-so-seal-permits-assignment pattern as
+    // `defaultInsets` above.
+    this.tracking = new Tracker()
 
     Object.seal(this)
   }

package/src/analytics.js

@@ -1,237 +0,0 @@
-/**
- * Analytics
- *
- * Lightweight analytics class for tracking page views, events, and scroll depth.
- * Uses batched sending with sendBeacon for reliable delivery.
- *
- * Features:
- * - Batched event queue with periodic flush
- * - Page view tracking
- * - Custom event tracking
- * - Scroll depth tracking (25%, 50%, 75%, 100%)
- * - sendBeacon for reliable unload delivery
- * - Optional - silently ignores if not configured
- *
- * Usage via uniweb singleton:
- * ```js
- * // Track events (no-op if analytics not configured)
- * uniweb.analytics.trackPageView('/about', 'About Us')
- * uniweb.analytics.trackEvent('button_click', { buttonId: 'cta' })
- * uniweb.analytics.trackScrollDepth(50)
- * ```
- */
-
-// Check if running in browser environment
-const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined'
-
-export default class Analytics {
-  /**
-   * @param {Object} options
-   * @param {string} options.endpoint - Analytics endpoint URL (required to enable)
-   * @param {number} options.flushInterval - Interval to flush queue in ms (default: 5000)
-   * @param {number} options.maxQueueSize - Max events before auto-flush (default: 10)
-   * @param {boolean} options.debug - Enable debug logging (default: false)
-   */
-  constructor(options = {}) {
-    this.endpoint = options.endpoint || null
-    this.flushInterval = options.flushInterval || 5000
-    this.maxQueueSize = options.maxQueueSize || 10
-    this.debug = options.debug || false
-
-    // Event queue
-    this.queue = []
-
-    // Track scroll depth milestones already sent (to avoid duplicates)
-    this.scrollMilestones = new Set()
-
-    // Session info
-    this.sessionId = this.generateSessionId()
-    this.sessionStart = Date.now()
-
-    // Flush interval ID (for cleanup)
-    this.flushIntervalId = null
-
-    // Only set up browser handlers if in browser and configured
-    if (isBrowser && this.isEnabled()) {
-      this.setupFlushInterval()
-      this.setupUnloadHandler()
-    }
-
-    Object.seal(this)
-  }
-
-  /**
-   * Check if analytics is enabled
-   * @returns {boolean}
-   */
-  isEnabled() {
-    return !!this.endpoint
-  }
-
-  /**
-   * Generate a simple session ID
-   * @returns {string}
-   */
-  generateSessionId() {
-    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
-  }
-
-  /**
-   * Set up periodic flush interval
-   */
-  setupFlushInterval() {
-    this.flushIntervalId = setInterval(() => {
-      this.flush()
-    }, this.flushInterval)
-  }
-
-  /**
-   * Set up unload handler for final flush
-   */
-  setupUnloadHandler() {
-    const handleUnload = () => {
-      this.flush(true) // Force beacon
-    }
-
-    window.addEventListener('visibilitychange', () => {
-      if (document.visibilityState === 'hidden') {
-        handleUnload()
-      }
-    })
-
-    window.addEventListener('pagehide', handleUnload)
-  }
-
-  /**
-   * Add event to queue
-   * @param {string} type - Event type
-   * @param {Object} data - Event data
-   */
-  addToQueue(type, data) {
-    if (!this.isEnabled() || !isBrowser) return
-
-    const event = {
-      type,
-      data,
-      timestamp: Date.now(),
-      sessionId: this.sessionId,
-      url: window.location.href,
-      referrer: document.referrer || null
-    }
-
-    this.queue.push(event)
-
-    if (this.debug) {
-      console.log('[Analytics] Event queued:', event)
-    }
-
-    // Auto-flush if queue is full
-    if (this.queue.length >= this.maxQueueSize) {
-      this.flush()
-    }
-  }
-
-  /**
-   * Track a page view
-   * @param {string} path - Page path
-   * @param {string} title - Page title
-   * @param {Object} meta - Additional metadata
-   */
-  trackPageView(path, title, meta = {}) {
-    // Reset scroll milestones for new page
-    this.scrollMilestones.clear()
-
-    this.addToQueue('pageview', {
-      path,
-      title,
-      ...meta
-    })
-  }
-
-  /**
-   * Track a custom event
-   * @param {string} name - Event name
-   * @param {Object} data - Event data
-   */
-  trackEvent(name, data = {}) {
-    this.addToQueue('event', {
-      name,
-      ...data
-    })
-  }
-
-  /**
-   * Track scroll depth milestone
-   * @param {number} percentage - Scroll depth percentage (25, 50, 75, 100)
-   */
-  trackScrollDepth(percentage) {
-    // Only track standard milestones
-    const milestones = [25, 50, 75, 100]
-    if (!milestones.includes(percentage)) return
-
-    // Don't track the same milestone twice per page
-    if (this.scrollMilestones.has(percentage)) return
-
-    this.scrollMilestones.add(percentage)
-
-    this.addToQueue('scroll_depth', {
-      depth: percentage
-    })
-  }
-
-  /**
-   * Flush the event queue
-   * @param {boolean} useBeacon - Force use of sendBeacon (for unload)
-   */
-  flush(useBeacon = false) {
-    if (!this.isEnabled() || !isBrowser || this.queue.length === 0) return
-
-    const events = [...this.queue]
-    this.queue = []
-
-    const payload = JSON.stringify({
-      events,
-      sessionId: this.sessionId,
-      sessionDuration: Date.now() - this.sessionStart
-    })
-
-    if (this.debug) {
-      console.log('[Analytics] Flushing', events.length, 'events')
-    }
-
-    // Use sendBeacon for reliable delivery on page unload
-    if (useBeacon && navigator.sendBeacon) {
-      const blob = new Blob([payload], { type: 'application/json' })
-      const sent = navigator.sendBeacon(this.endpoint, blob)
-
-      if (!sent && this.debug) {
-        console.warn('[Analytics] sendBeacon failed, events may be lost')
-      }
-      return
-    }
-
-    // Use fetch for normal flush
-    fetch(this.endpoint, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: payload,
-      keepalive: true // Allows request to outlive page
-    }).catch((error) => {
-      if (this.debug) {
-        console.warn('[Analytics] Flush failed:', error)
-      }
-      // Put events back in queue for retry
-      this.queue.unshift(...events)
-    })
-  }
-
-  /**
-   * Clean up (stop interval, flush remaining events)
-   */
-  destroy() {
-    if (this.flushIntervalId) {
-      clearInterval(this.flushIntervalId)
-    }
-    this.flush(true)
-  }
-}