@uniweb/core 0.10.0 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "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,8 +40,8 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "^1.2.2",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/semantic-parser": "^1.2.3"
   },
   "scripts": {
     "test": "vitest run"

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,25 @@ export default class Page {
     // Rewrite target (if set, this route is served by an external site)
     this.rewrite = pageData.rewrite || null
 
+    // This page's answer on section-level instrumentation (`trackSections` in
+    // page.yml) — an OVERRIDE, not a switch.
+    //
+    // ⭐ **Three states, and the third is the point.** `undefined` means the page
+    // said nothing and the site's own `tracking.emit` decides; `true` and
+    // `false` override it in either direction, so an owner can instrument one
+    // page of a quiet site or exempt a noisy page of a loud one.
+    //
+    // ⛔ **`|| false` was wrong here and collapsed the tri-state**, which made
+    // page-level the ONLY spelling and forced every owner to tick pages
+    // individually. The wire already carried all three — `content-collector`
+    // emits the key only when it is `!= null` — so nothing but this line had to
+    // change. ⇒ Read `?? undefined`, never a boolean coercion.
+    //
+    // The runtime passes it to `Tracker.arms('section_view', …)`, which is where
+    // the precedence against the host's own list is resolved. It means nothing
+    // without a tracking destination.
+    this.trackSections = pageData.trackSections ?? undefined
+
     // 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/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
@@ -183,6 +207,17 @@ export default class Tracker {
     // reports three times.
     this.currentPath = null
 
+    // What the runtime may ARM, as two independent narrowings. Both are `null`
+    // when nothing narrows, which is the common case and the cheap one.
+    //
+    // ⛔ **Neither ever filters `track()`.** The registry is open by design, and
+    // a client-side allowlist over a foundation's own events would export one
+    // host's policy onto every host — including hosts that sent no list, whose
+    // sites would silently drop everything their foundation emits. These gate
+    // the runtime's OWN emissions and nothing else. See `arms()`.
+    this.hostEvents = options.hostEvents ? new Set(options.hostEvents) : null
+    this.siteEmit = options.siteEmit ? new Set(options.siteEmit) : null
+
     this.framed = detectFramed()
 
     // Called once when consent moves to granted, and never otherwise. The
@@ -235,6 +270,39 @@ export default class Tracker {
     return !!this.endpoint && this.isLiveDocument()
   }
 
+  /**
+   * Whether the runtime should ARM one of its own automatic emitters.
+   *
+   * ⭐ **Three questions, in the order that makes each one's absence safe:**
+   *
+   * 1. **Is there anywhere to send, in a live document?** — `isEnabled()`.
+   * 2. **Will the host consume this?** `hostEvents` is the host's cost switch:
+   *    no point arming an observer for a row nobody stores. ⛔ **Absent means NO
+   *    NARROWING, never an empty set** — a host that sends no list is an older
+   *    or simpler one, and reading absence as "consume nothing" would take
+   *    every site on that host dark with every gate reading yes.
+   * 3. **Did the site ask for it?** `siteEmit` is the operator's own selection.
+   *    Absent means everything.
+   *
+   * `override` is the per-page answer where one exists (`page.trackSections`).
+   * It replaces the SITE's answer and cannot escape the host's: a page may
+   * widen what its own site configured, and may not conjure a row the host
+   * declined to store.
+   *
+   * ⛔ **Not consulted by `track()`.** A foundation's events are never gated —
+   * see the constructor.
+   *
+   * @param {string} event
+   * @param {boolean} [override] - the per-page decision, when the caller has one
+   * @returns {boolean}
+   */
+  arms(event, override) {
+    if (!this.isEnabled()) return false
+    if (this.hostEvents && !this.hostEvents.has(event)) return false
+    if (override != null) return !!override
+    return !this.siteEmit || this.siteEmit.has(event)
+  }
+
   /** @returns {'granted'|'denied'|'pending'} */
   consentStatus() {
     return this.consent
@@ -309,7 +377,7 @@ export default class Tracker {
    * @param {string} path
    */
   trackPageView(path) {
-    if (!this.isEnabled() || !path) return
+    if (!this.arms('page_view') || !path) return
     if (path === this.currentPath) return
     this.currentPath = path
     // Promptly, rather than waiting out the batch window: a page view is the

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