@uniweb/core 0.9.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -9,6 +9,7 @@
     "./data-paths": "./src/data-paths.js",
     "./detail-url": "./src/detail-url.js",
     "./fetch-config": "./src/fetch-config.js",
+    "./icon-corpus": "./src/icon-corpus.js",
     "./locale-config": "./src/locale-config.js",
     "./route-match": "./src/route-match.js",
     "./section-id": "./src/section-id.js",
@@ -39,7 +40,7 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "^1.2.2",
+    "@uniweb/semantic-parser": "^1.2.3",
     "@uniweb/theming": "^0.1.15"
   },
   "scripts": {

package/src/block.js

@@ -5,8 +5,12 @@
  * child blocks, and state management. Connects to foundation components.
  */
 
-import { parseContent as parseSemanticContent } from '@uniweb/semantic-parser'
+import {
+  parseContent as parseSemanticContent,
+  resolveAssetUrl
+} from '@uniweb/semantic-parser'
 import { normalizeTokenValue } from '@uniweb/theming'
+import { sectionDomId } from './section-id.js'
 
 /**
  * Lift container fences out of a content document.
@@ -156,7 +160,7 @@ export default class Block {
     if (rawBg && !this.standardOptions.background) {
       this.standardOptions = {
         ...this.standardOptions,
-        background: Block.normalizeBackground(rawBg)
+        background: Block.normalizeBackground(rawBg, this.parseOptions())
       }
     }
 
@@ -285,6 +289,28 @@ export default class Block {
    * block already knows both — a foundation should not have to thread context
    * it was handed. Same arrangement as `useFormSubmit({ block })`.
    *
+   * ## ⭐ `section` and `section_id` answer DIFFERENT questions — both ride
+   *
+   * `section` is the component **type** (`Hero`); `section_id` is this
+   * **instance** (`section-hero`), the same string the renderers write as the
+   * DOM id, so it joins to the anchor a search result already links to.
+   *
+   * | | cardinality to a collector | survives a foundation swap | survives a content rename |
+   * |---|---|---|---|
+   * | `section` (type) | the foundation's vocabulary — bounded, small | ⛔ no | ✅ yes |
+   * | `section_id` (instance) | pages × sections — needs scoping to be storable | ✅ yes | ⛔ **no — a rename silently splits the series** |
+   *
+   * ⛔ **Both are sent, deliberately, and dropping either later is a wire
+   * break.** A consumer storing only one is free to ignore the other — the cost
+   * of carrying it is one field — whereas **collecting under an identity that is
+   * later changed throws the data away rather than merely delaying it.**
+   * *(Agreed across the producing and serving sides, 2026-08-17; the cardinality
+   * numbers that are the reason are recorded internally.)*
+   *
+   * ⚠️ Instance identity on the wire is **`(path, section_id)`** — `path` is
+   * already here, so no `path#section` composite is ever sent and neither side
+   * keeps one in sync.
+   *
    * ⛔ **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.
@@ -302,6 +328,7 @@ export default class Block {
     globalThis.uniweb?.tracking?.track(event, {
       path: this.path,
       section: this.type,
+      section_id: sectionDomId(this),
       ...data
     })
   }
@@ -377,10 +404,43 @@ export default class Block {
    * Uses @uniweb/semantic-parser for intelligent content extraction
    * Returns flat content structure
    */
+  /**
+   * Options handed to the semantic parser for this block.
+   *
+   * `assets` carries the host's asset-URL pattern (`config.assets.url`) so a
+   * node's `assetId`/`assetExt` resolve to a real URL. It is read from the
+   * published payload and passed as an explicit input rather than reached for
+   * as module state — the parser must never know a host, and a pattern is the
+   * only thing that tells it one.
+   *
+   * ⚠️ This depends on `website.config` being populated before a Block is
+   * constructed, and it is — but only because `Page.bodyBlocks` is a LAZY
+   * getter, so blocks are built at render, long after the Website constructor
+   * returns. The constructor itself assigns `this.pages` (line ~149) BEFORE
+   * `this.config` (line ~159), so an eager Block would parse against an empty
+   * config and every asset would silently fall through to `src` — working
+   * output, no error, no resolution.
+   *
+   * ⚠️ **That getter now has a SECOND consumer, in another lane.** The editor
+   * relies on it re-running: `updateParams` → `website.rebuild` → `_applyContent`
+   * → `page.bodyBlocks` constructs fresh Blocks, which is what re-normalises a
+   * section background on every live edit (traced by the frontend lane,
+   * 2026-08-17, before deleting their own duplicate normaliser). So making block
+   * construction eager breaks background editing as well as asset resolution —
+   * two failures, two lanes, one cause, and neither visible from the other side.
+   *
+   * Do not make block construction eager
+   * without moving the config assignment first.
+   */
+  parseOptions() {
+    const assets = this.website?.config?.assets
+    return assets ? { assets } : {}
+  }
+
   extractFromProseMirror(doc) {
     try {
       // Parse with semantic-parser - returns flat structure
-      const parsed = parseSemanticContent(doc)
+      const parsed = parseSemanticContent(doc, this.parseOptions())
 
       // Parsed content is now flat: { title, pretitle, paragraphs, links, items, sequence, ... }
       return parsed
@@ -678,9 +738,45 @@ export default class Block {
    * - Object without mode: mode inferred from which fields are present
    *
    * @param {string|Object} raw - Raw background value from frontmatter
+   * @param {Object} [options] - Parse options; `options.assets.url` is the host's
+   *        asset-URL pattern, used to resolve a store-held background.
    * @returns {Object} Normalized background config with mode
    */
-  static normalizeBackground(raw) {
+  static normalizeBackground(raw, options) {
+    return Block.resolveBackgroundMedia(Block.normalizeBackgroundShape(raw), options)
+  }
+
+  /**
+   * Resolve a store-held background asset (`assetId` + `assetExt`) to a `src`.
+   *
+   * ⭐ This runs HERE, at normalize time, and deliberately not at render. A
+   * background is drawn by two twinned implementations — `Background.jsx` (SPA)
+   * and `ssr-renderer.js` (SSG + edge) — which both read `background.image?.src`.
+   * Resolving at render would mean the identical change in both, and the twins
+   * drifting is this repo's standing hazard: the lane you tested keeps working
+   * while the other is wrong in production. One resolution here, and both lanes
+   * get it for free.
+   *
+   * Same precedence as the node path: a store-held asset wins WHEN IT RESOLVES,
+   * so a producer may write `assetId` beside a `src` and the `src` carries the
+   * render until a host declares a pattern.
+   */
+  static resolveBackgroundMedia(bg, options) {
+    const pattern = options?.assets?.url
+    if (!pattern || !bg || typeof bg !== 'object') return bg
+
+    let out = bg
+    for (const key of ['image', 'video']) {
+      const media = bg[key]
+      if (!media || typeof media !== 'object') continue
+      const url = resolveAssetUrl(media.assetId, media.assetExt, pattern)
+      if (url) out = { ...out, [key]: { ...media, src: url } }
+    }
+    return out
+  }
+
+  /** Shape normalization only — no resolution. See `normalizeBackground`. */
+  static normalizeBackgroundShape(raw) {
     // String shorthand — classify by content
     if (typeof raw === 'string') {
       // URL or path → image/video

package/src/icon-corpus.js

@@ -0,0 +1,80 @@
+/**
+ * The icon corpus — its default origin and its filename rule.
+ *
+ * ## Why this is one module and not five constants
+ *
+ * An icon referenced by `library` + `name` is **our own asset**, not the site's.
+ * We publish the families, we document them, and `@uniweb/icons`'
+ * `scripts/build-cdn.js` writes the files. So unlike a site asset — whose URL
+ * pattern the HOST declares because the bytes are in the host's store — the
+ * layout here is ours to name, and a default origin is the correct answer
+ * rather than a guessed one.
+ *
+ * That makes this a **writer/reader pair**, which is the part that needs a
+ * single definition:
+ *
+ *   writer   @uniweb/icons scripts/build-cdn.js   emits cdn/{family}/{family}-{name}.svg
+ *   readers  @uniweb/runtime setup.js             browser resolution
+ *            @uniweb/runtime ssr-renderer.js      prerender + Worker isolate prefetch
+ *            @uniweb/icons  src/resolver.js       local-then-CDN resolution
+ *
+ * Before 2026-08-17 the origin was spelled out in three of those and the
+ * filename rule in all four. A writer and its readers drifting is the exact
+ * defect `@uniweb/core/route-match` exists to prevent, and the one the runtime
+ * channel's bridge-filename helper prevents by construction. Same treatment
+ * here: one helper, no second spelling.
+ *
+ * ## ⛔ Keep this a LEAF — zero imports
+ *
+ * `ssr-renderer.js` is bundled into the SSR isolate that runs in a Cloudflare
+ * Worker, so anything it reaches must import nothing: no `node:*`, no DOM, no
+ * `@uniweb/core` root (which pulls semantic-parser and theming). That is the
+ * same constraint `route-match` and `locale-config` carry, and the reason this
+ * lives in core rather than in `@uniweb/icons` — a Worker cannot take a package
+ * whose value is ~3,200 icon modules behind a dynamic import, and `@uniweb/runtime`
+ * depends on core already.
+ *
+ * A host may override the ORIGIN — a mirror of this corpus is a legitimate
+ * deployment choice, and on a hosted site the base comes from the payload the
+ * host serves. It may not override the LAYOUT: a mirror mirrors. Re-deriving
+ * filenames instead of copying them is what produced two incompatible spellings
+ * of the same corpus once already.
+ *
+ * @module @uniweb/core/icon-corpus
+ */
+
+/**
+ * Where the framework publishes its own icon corpus.
+ *
+ * Not a fallback for a missing host address — it is the address of OUR artifact,
+ * and it is what makes `![](lu-house)` work in a project with no backend at all.
+ * A host that mirrors the corpus supplies its own origin on the payload.
+ */
+export const DEFAULT_ICON_BASE = 'https://uniweb.github.io/icons'
+
+/**
+ * The corpus path for one icon, relative to any origin serving it.
+ *
+ * `{family}/{family}-{name}.svg` — the family repeats deliberately: the
+ * directory groups, and the filename prefix keeps ids unique across families so
+ * a name alone is never ambiguous.
+ *
+ * @param {string} family - short family code (`lu`, `hi2`, `fa6`)
+ * @param {string} name - icon id within that family (`house`, `a-arrow-down`)
+ * @returns {string} e.g. `lu/lu-house.svg`
+ */
+export function iconPath(family, name) {
+  return `${family}/${family}-${name}.svg`
+}
+
+/**
+ * The full URL for one icon against a serving origin.
+ *
+ * @param {string} family - short family code
+ * @param {string} name - icon id within that family
+ * @param {string} [base] - serving origin; defaults to the framework's own
+ * @returns {string}
+ */
+export function iconUrl(family, name, base = DEFAULT_ICON_BASE) {
+  return `${String(base).replace(/\/+$/, '')}/${iconPath(family, name)}`
+}

package/src/locale-config.js

@@ -2,7 +2,7 @@
  * Shared locale-config helpers — the ONE home for the language rules that
  * build, sync, runtime, and the CLI all apply to a site's config.
  *
- * Contract (kb/framework/build/uwx-format.md → "Per-locale publish readiness"):
+ * Contract ("Per-locale publish readiness"):
  * - `languages` (site.yml) / `info.languages` (wire) — the DECLARED working
  *   set. A plain, strongly-validated string list.
  * - `publishLanguages` (site.yml) / `info.publish_languages` (wire) — publish

package/src/page.js

@@ -48,6 +48,14 @@ export default class Page {
     // Rewrite target (if set, this route is served by an external site)
     this.rewrite = pageData.rewrite || null
 
+    // Opt this page into section-level instrumentation (`trackSections` in
+    // page.yml). Off by default, and PAGE-LEVEL ONLY — there is deliberately no
+    // site-wide or folder-level spelling, because one event per section on every
+    // page of a site produces far more distinct values than an analytics
+    // consumer can reasonably retain. The runtime reads it to decide whether to
+    // arm an observer; it means nothing without a tracking destination.
+    this.trackSections = pageData.trackSections || false
+
     // Two orthogonal visibility axes:
     //  • `hidden` — REACHABILITY. When true the page is excluded from the published
     //    site entirely (the build prunes it and its subtree); it survives only in

package/src/services.js

@@ -180,26 +180,62 @@ export function resolveService(website, name) {
 }
 
 /**
- * Read a service's declaration object, whichever tier supplied it.
+ * 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.
- * Used by `tracking:` for `consent:`; a future service with its own options
- * reads them the same way rather than inventing a second lookup.
  *
- * The tiers are checked in the same order and for the same reason, so a site
- * that authors the object form is not silently merged with a host's.
+ * ## ⛔ 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 declaration object, or `{}` when there is none
+ * @returns {object} the effective options, or `{}` when no tier declares any
  */
 export function readServiceOptions(website, name) {
   const config = website?.config
-  const authored = config?.[name]
-  if (authored !== undefined) {
-    return authored && typeof authored === 'object' ? authored : {}
-  }
-  const hosted = config?.services?.[name]
-  return hosted && typeof hosted === 'object' ? hosted : {}
+  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

@@ -4,7 +4,7 @@
  * ⭐ **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`.
+ * path.
  *
  * ```
  * { event: 'page_view',       path: '/about', referrer?, utm_* }
@@ -71,6 +71,30 @@ const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefine
  * loudly.
  *
  * A cross-origin parent throws on `window.top` access; that also means framed.
+ *
+ * ⚠️ **The boundary condition: this checks `framed`, not `preview`.** A preview
+ * rendered in a popup or a top-level tab would be same-origin and NOT framed,
+ * `isLiveDocument()` would return true, and — like every failure in this area —
+ * it would have no symptom: the payload stays internally consistent while the
+ * owner's own edits quietly inflate their numbers.
+ *
+ * ✅ **Covered on the other side too, by a test rather than a promise**
+ * **[frontend, measured; relayed 2026-08-17]**: `preview-runtime` imports the
+ * real `setup` / `provider` / `foundation-loader` (not a fork), all five of its
+ * mounts are `<iframe>`, and the popup case is already instantiated —
+ * `DetachedPreview.jsx` is a popup *root* with the runtime in an iframe inside
+ * it, so the guard holds. A non-framed preview is not reachable by re-parenting
+ * at all: content and foundation arrive *only* over the frame-bridge, so going
+ * non-framed means replacing the transport. Their
+ * `previewFraming.smoke.test.js` pins both the iframe property and the exact set
+ * of mounting files, so a new mount fails there.
+ *
+ * ⛔ **Do not "fix" this by adding an explicit preview flag from the harness.**
+ * A suppression that depends on another lane remembering something has no
+ * symptom when forgotten, which is the whole reason this one reads the DOM
+ * instead; two suppressions where one is authoritative is how you get a stale
+ * one. The two guards now fail independently, in different repos, for the same
+ * violation.
  */
 function detectFramed() {
   if (!isBrowser) return false
@@ -160,8 +184,11 @@ export default class Tracker {
     // '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.consentRequired = !!options.consentRequired
 
     this.queue = []
     this.acquisition = null
@@ -180,11 +207,17 @@ export default class Tracker {
     // reports three times.
     this.currentPath = null
 
-    this.flushIntervalId = null
-    this.onPageHide = null
-    this.onVisibilityChange = 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
@@ -200,14 +233,30 @@ export default class Tracker {
   }
 
   /**
-   * Enabled means: a destination exists, we are in a browser, and we are not
-   * inside someone's iframe. Consent is checked separately — a consent-pending
-   * tracker is *enabled* and buffering, which is a different state from off.
+   * 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 && isBrowser && !this.framed
+    return !!this.endpoint && this.isLiveDocument()
   }
 
   /** @returns {'granted'|'denied'|'pending'} */
@@ -223,15 +272,44 @@ export default class Tracker {
    * 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) {
-    if (!this.isEnabled()) return
+    const wasGranted = this.consent === 'granted'
     this.consent = granted ? 'granted' : 'denied'
-    if (granted) {
-      this.flush()
-    } else {
+
+    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()
     }
   }
 
@@ -330,35 +408,34 @@ export default class Tracker {
     })
   }
 
-  /** @private */
+  /**
+   * 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() {
-    this.flushIntervalId = setInterval(() => this.flush(), this.flushInterval)
+    setInterval(() => this.flush(), this.flushInterval)
   }
 
   /** @private */
   armUnloadHandlers() {
-    this.onPageHide = () => this.flush(true)
-    this.onVisibilityChange = () => {
+    window.addEventListener('pagehide', () => this.flush(true))
+    window.addEventListener('visibilitychange', () => {
       if (document.visibilityState === 'hidden') this.flush(true)
-    }
-    window.addEventListener('pagehide', this.onPageHide)
-    window.addEventListener('visibilitychange', this.onVisibilityChange)
-  }
-
-  /** Stop the interval, detach listeners, and send what is left. */
-  destroy() {
-    if (this.flushIntervalId) {
-      clearInterval(this.flushIntervalId)
-      this.flushIntervalId = null
-    }
-    if (isBrowser) {
-      if (this.onPageHide) window.removeEventListener('pagehide', this.onPageHide)
-      if (this.onVisibilityChange) {
-        window.removeEventListener('visibilitychange', this.onVisibilityChange)
-      }
-    }
-    this.onPageHide = null
-    this.onVisibilityChange = null
-    this.flush(true)
+    })
   }
 }

package/src/uniweb.js

@@ -72,7 +72,7 @@ export default class Uniweb {
     // Populated by prerender before rendering, read synchronously by Icon.
     this.iconCache = new Map()
 
-    // Site tracking — one event stream (`kb/framework/plans/tracking.md`).
+    // Site tracking — one event stream.
     //
     // ⛔ Deliberately constructed DISABLED, and the runtime replaces it in L2
     // (`wire-foundation.js` → `wireTracker`). It cannot be configured here even