@uniweb/runtime 1.1.20 → 1.2.1

package/src/ssr-renderer.js

@@ -2,11 +2,13 @@
  * SSR Renderer
  *
  * Hook-free rendering pipeline for SSG (build) and server-side SSR.
- * Mirrors BlockRenderer.jsx + Background.jsx using React.createElement
- * directly — no hooks, no JSX, no browser APIs.
+ * Mirrors BlockRenderer.jsx using React.createElement directly — no hooks,
+ * no JSX, no browser APIs. A section's background and the built-in layout are
+ * not mirrored: both renderers draw the one copy (`background.js`,
+ * `default-layout.js`).
  *
  * This is the single source of truth for how blocks render during prerender.
- * When modifying BlockRenderer.jsx or Background.jsx, update this file to match.
+ * When modifying BlockRenderer.jsx, update `renderBlock` here to match.
  *
  * Exports three layers:
  *   1. Rendering functions (renderBlock, renderBlocks, renderLayout, renderBackground)
@@ -18,7 +20,7 @@ import React from 'react'
 import { renderToString } from 'react-dom/server'
 import { createUniweb, resolveDefaultLocale } from '@uniweb/core'
 import { sectionDomId } from '@uniweb/core/section-id'
-import { siteUrl, withOpacity } from './background-shared.js'
+import { Background } from './background.js'
 import { routePatternToRegex, isDynamicRoute } from '@uniweb/core/route-match'
 import { DEFAULT_ICON_BASE, iconUrl } from '@uniweb/core/icon-corpus'
 import { buildSectionOverrides, FONT_LINKS_MARKER } from '@uniweb/theming'
@@ -95,123 +97,17 @@ export function getWrapperProps(block) {
 
 
 /**
- * Render a background element for SSR.
- * Mirrors Background.jsx (color, gradient, image — not video).
- * Video backgrounds require JS for autoplay and are skipped during SSR.
+ * Render a section's background for SSR: the one implementation both renderers draw
+ * (`background.js`). A video background is drawn as its poster — what the browser draws too,
+ * until it has mounted and starts the video.
+ * ⛔ Until 2026-10-25 this was a copy of `Background.jsx`, and drew no video at all.
+ *
+ * @param {Object} background - `block.background`, normalized by core
+ * @returns {React.ReactElement|null}
  */
 export function renderBackground(background) {
   if (!background?.mode) return null
-
-  const containerStyle = {
-    position: 'absolute',
-    inset: '0',
-    overflow: 'hidden',
-    zIndex: 0,
-  }
-
-  const children = []
-
-  // Color background
-  if (background.mode === 'color' && background.color) {
-    children.push(
-      React.createElement('div', {
-        key: 'bg-color',
-        className: 'background-color',
-        style: { position: 'absolute', inset: '0', backgroundColor: background.color },
-        'aria-hidden': 'true',
-      })
-    )
-  }
-
-  // Gradient background (supports string or object with opacity)
-  if (background.mode === 'gradient' && background.gradient) {
-    const g = background.gradient
-
-    let bgValue
-    if (typeof g === 'string') {
-      bgValue = g
-    } else {
-      const {
-        start = 'transparent',
-        end = 'transparent',
-        angle = 0,
-        startPosition = 0,
-        endPosition = 100,
-        startOpacity = 1,
-        endOpacity = 1,
-      } = g
-      const startColor = startOpacity < 1 ? withOpacity(start, startOpacity) : start
-      const endColor = endOpacity < 1 ? withOpacity(end, endOpacity) : end
-      bgValue = `linear-gradient(${angle}deg, ${startColor} ${startPosition}%, ${endColor} ${endPosition}%)`
-    }
-
-    children.push(
-      React.createElement('div', {
-        key: 'bg-gradient',
-        className: 'background-gradient',
-        style: { position: 'absolute', inset: '0', background: bgValue },
-        'aria-hidden': 'true',
-      })
-    )
-  }
-
-  // Image background
-  if (background.mode === 'image' && background.image?.src) {
-    const img = background.image
-    children.push(
-      React.createElement('div', {
-        key: 'bg-image',
-        className: 'background-image',
-        style: {
-          position: 'absolute',
-          inset: '0',
-          backgroundImage: `url(${siteUrl(img.src)})`,
-          backgroundPosition: img.position || 'center',
-          backgroundSize: img.size || 'cover',
-          backgroundRepeat: 'no-repeat',
-        },
-        'aria-hidden': 'true',
-      })
-    )
-  }
-
-  // Overlay (gradient or solid)
-  if (background.overlay?.enabled) {
-    const ov = background.overlay
-    let overlayStyle
-
-    if (ov.gradient) {
-      const g = ov.gradient
-      overlayStyle = {
-        position: 'absolute', inset: '0', pointerEvents: 'none',
-        background: `linear-gradient(${g.angle || 180}deg, ${g.start || 'rgba(0,0,0,0.7)'} ${g.startPosition || 0}%, ${g.end || 'rgba(0,0,0,0)'} ${g.endPosition || 100}%)`,
-        opacity: ov.opacity ?? 0.5,
-      }
-    } else {
-      const baseColor = ov.type === 'light' ? '255, 255, 255' : '0, 0, 0'
-      overlayStyle = {
-        position: 'absolute', inset: '0', pointerEvents: 'none',
-        backgroundColor: `rgba(${baseColor}, ${ov.opacity ?? 0.5})`,
-      }
-    }
-
-    children.push(
-      React.createElement('div', {
-        key: 'bg-overlay',
-        className: ov.gradient ? 'background-overlay background-overlay--gradient' : 'background-overlay background-overlay--solid',
-        style: overlayStyle,
-        'aria-hidden': 'true',
-      })
-    )
-  }
-
-  if (children.length === 0) return null
-
-  return React.createElement('div', {
-    className: `background background--${background.mode}`,
-    style: containerStyle,
-    'aria-hidden': 'true',
-  }, ...children)
+  return React.createElement(Background, background)
 }
 
 /**
@@ -244,11 +140,20 @@ export function renderBlock(block, { as = 'section', stickySelf = false } = {})
   const meta = getComponentMeta(block.type)
   const entityStore = block.website?.entityStore
   let entityData = null
+  let pending = false
   if (entityStore) {
     const resolved = entityStore.resolve(block, meta)
     if (resolved.status === 'ready') entityData = resolved.data
+    pending = resolved.status === 'pending'
   }
 
+  // ⭐ A block whose data is still out is LOADING here, as in the browser, which sets the same flag
+  // before `prepareProps` (`BlockRenderer.jsx`) and fetches the data once it boots. So the page
+  // paints the component's loading state, the one the browser renders in its place.
+  // ⛔ Until 2026-10-25 this was never set, and such a section prerendered its EMPTY state —
+  // "nothing found", or an error — then switched to loading when the browser took over.
+  block.dataLoading = pending
+
   // Build content and params with runtime guarantees.
   // prepareProps handles the full pipeline: entity data merge,
   // foundation content handler invocation, guaranteed content
@@ -342,8 +247,8 @@ export function renderLayout(page, website) {
   }
 
   // Mirror Layout.jsx: wrap body + each area in a thin div carrying its
-  // view-transition-name, so the prerendered HTML matches what the SPA hydrates
-  // and the browser can animate regions independently on client navigation.
+  // view-transition-name, so the prerendered HTML matches the page the SPA renders
+  // in its place and the browser can animate regions independently on client navigation.
   const areaNames = Object.keys(areas)
   const transitions = website.viewTransitions
     ? resolveLayoutTransitions(areaNames, layoutMeta?.transitions)
@@ -475,10 +380,9 @@ export function initPrerender(content, foundation, extensionsOrOptions, maybeOpt
   }
 
   // The same background a section gets, for kit's `SectionBackground` — a component that
-  // paints its own (`background: 'self'`). Mirrors the SPA's `Background` (setup.js).
-  uniweb.backgroundRenderer = function InlineBackground(background) {
-    return renderBackground(background)
-  }
+  // paints its own (`background: 'self'`). The one implementation, which the browser draws
+  // too (setup.js); its `className` is the layer's. ⛔ Until 2026-10-25 this dropped it.
+  uniweb.backgroundRenderer = Background
 
   // L2 (singleton wiring): defaultInsets, xref.build(), and any future
   // framework-level capability bridge — shared with setup.js so both
@@ -674,7 +578,7 @@ export { escapeHtml }
  * Common operations shared by both build and cloud:
  * - Replace #root div with rendered HTML
  * - Update page title
- * - Add/update meta description
+ * - Write the page's head tags — description, canonical, hreflang, Open Graph (`writeHeadMeta`)
  * - Inject section override CSS
  * - Inject the pre-paint appearance script
  *
@@ -701,7 +605,7 @@ export function injectPageContent(html, renderedContent, page, options = {}) {
 
   // Pre-paint appearance script. Prerendered HTML carries real content styled
   // from :root (light) tokens, so a dark visitor would see a flash of light
-  // before the bundle hydrates and applies the class. Read off the page's
+  // before the bundle boots and applies the class. Read off the page's
   // website back-ref rather than a parameter: every lane builds the same graph,
   // so this needs no plumbing and no per-lane opt-in. Idempotent, because
   // @uniweb/build's injectBuildData may run over this HTML afterwards.
@@ -766,45 +670,66 @@ export function injectPageContent(html, renderedContent, page, options = {}) {
     )
   }
 
-  // Add/update meta description
-  if (page.description) {
-    const metaDesc = `<meta name="description" content="${escapeHtml(page.description)}">`
-    if (result.includes('<meta name="description"')) {
-      result = result.replace(/<meta name="description"[^>]*>/, metaDesc)
-    } else {
-      result = result.replace('</head>', `${metaDesc}\n</head>`)
-    }
-  }
-
-  // Social / SEO meta from the page's effective head metadata (page seo
-  // cascading over site-level seo — see Page.getHeadMeta). The SPA emits these
-  // client-side via useHeadMeta; this is the SSR twin, so crawlers and social
-  // unfurlers (which don't run JS) get them in the static HTML too.
-  const headMeta = page.getHeadMeta?.()
-  if (headMeta) {
-    const og = headMeta.og || {}
-    const keywords = Array.isArray(headMeta.keywords)
-      ? headMeta.keywords.join(', ')
-      : headMeta.keywords
-    const tags = []
-    if (keywords) tags.push(`<meta name="keywords" content="${escapeHtml(keywords)}">`)
-    if (headMeta.robots) tags.push(`<meta name="robots" content="${escapeHtml(headMeta.robots)}">`)
-    if (og.title) tags.push(`<meta property="og:title" content="${escapeHtml(og.title)}">`)
-    if (og.description) tags.push(`<meta property="og:description" content="${escapeHtml(og.description)}">`)
-    if (og.image) tags.push(`<meta property="og:image" content="${escapeHtml(og.image)}">`)
-    if (og.url) tags.push(`<meta property="og:url" content="${escapeHtml(og.url)}">`)
-    tags.push('<meta property="og:type" content="website">')
-    tags.push(`<meta name="twitter:card" content="${og.image ? 'summary_large_image' : 'summary'}">`)
-    if (og.title) tags.push(`<meta name="twitter:title" content="${escapeHtml(og.title)}">`)
-    if (og.description) tags.push(`<meta name="twitter:description" content="${escapeHtml(og.description)}">`)
-    if (og.image) tags.push(`<meta name="twitter:image" content="${escapeHtml(og.image)}">`)
-    if (headMeta.canonical) tags.push(`<link rel="canonical" href="${escapeHtml(headMeta.canonical)}">`)
-    if (tags.length) result = result.replace('</head>', `${tags.join('\n')}\n</head>`)
-  }
+  // ⭐ THE PAGE'S HEAD TAGS — description, canonical, hreflang, Open Graph, Twitter — from the
+  // page's own head metadata (`Page#getHeadMeta`, which the browser writes the same tags from in
+  // `useHeadMeta`), so crawlers and social unfurlers, which run no script, read the page's own.
+  // ⛔ Until 2026-10-25 these were APPENDED, after the static build had written the HOME page's
+  // into the one shell every page is rendered into: each page named the home page its canonical
+  // and carried two og:title and two og:url, the home page's first.
+  result = writeHeadMeta(result, page)
 
   return result
 }
 
+/**
+ * Write a page's head tags into `html`'s head. These tags are the framework's: each is set to the
+ * page's value, replacing any of its name the shell carries, and removed when the page has none —
+ * as the browser does on every navigation (`useHeadMeta`), so hydrating the page changes nothing a
+ * crawler read.
+ *
+ * @param {string} html
+ * @param {Object} page
+ * @returns {string}
+ */
+function writeHeadMeta(html, page) {
+  // A Page states its own (`getHeadMeta`); plain page data, which callers may hand in, its fields.
+  const meta = typeof page?.getHeadMeta === 'function' ? page.getHeadMeta() : { description: page?.description || null }
+  const end = html.indexOf('</head>')
+  if (!meta || end === -1) return html
+  const og = meta.og || {}
+  const keywords = Array.isArray(meta.keywords) ? meta.keywords.join(', ') : meta.keywords
+  const metaTags = [
+    ['name', 'description', meta.description],
+    ['name', 'keywords', keywords],
+    ['name', 'robots', meta.robots],
+    ['property', 'og:type', 'website'],
+    ['property', 'og:site_name', og.siteName],
+    ['property', 'og:title', og.title],
+    ['property', 'og:description', og.description],
+    ['property', 'og:image', og.image],
+    ['property', 'og:url', og.url],
+    ['name', 'twitter:card', og.image ? 'summary_large_image' : 'summary'],
+    ['name', 'twitter:site', meta.twitter?.site],
+    ['name', 'twitter:title', og.title],
+    ['name', 'twitter:description', og.description],
+    ['name', 'twitter:image', og.image],
+  ]
+  // The head alone: the page's content is in the body, and none of it is edited here.
+  let head = html.slice(0, end)
+  const written = []
+  for (const [attr, key, value] of metaTags) {
+    head = head.replace(new RegExp(`<meta\\b[^>]*\\b(?:name|property)=["']${key}["'][^>]*>\\s*`, 'gi'), '')
+    if (value) written.push(`<meta ${attr}="${key}" content="${escapeHtml(value)}">`)
+  }
+  head = head.replace(/<link\b[^>]*\brel=["']canonical["'][^>]*>\s*/gi, '')
+  if (meta.canonical) written.push(`<link rel="canonical" href="${escapeHtml(meta.canonical)}">`)
+  head = head.replace(/<link\b[^>]*\bhreflang=["'][^"']*["'][^>]*>\s*/gi, '')
+  for (const { hreflang, url } of meta.alternates || []) {
+    written.push(`<link rel="alternate" hreflang="${escapeHtml(hreflang)}" href="${escapeHtml(url)}">`)
+  }
+  return `${head}${written.join('\n')}\n${html.slice(end)}`
+}
+
 // ============================================================================
 // 404 fallback generation
 // ============================================================================

package/src/sticky-check.js

@@ -4,13 +4,23 @@
  *
  * `position: sticky` keeps an element inside its parent's box. When the parent is no taller than
  * the element (no wider, for one that sticks sideways), the element has no room and scrolls away
- * with the page, and nothing says so. The two ways it happens:
+ * with the page, and nothing says so. Whose box the parent is says what to do (`unmovableAdvice`):
  *
- *   - a component's own `sticky top-0`: a section's markup sits in boxes as tall as itself, so it
- *     never moves. The section's `sticky: true` asks the runtime to make sticky the box that can
- *     (`sticky.js`).
- *   - a layout that wraps a sticky area in an element of its own, which confines the area's box.
- *     The layout makes its element sticky when `page.isSticky(area)`.
+ *   - a component's outermost element — a header's own `sticky top-0` — sits in the section's
+ *     wrapper, as tall as itself, so it never moves. The section's `sticky: true` asks the runtime
+ *     to make sticky the box that can (`sticky.js`).
+ *   - a box the runtime made sticky (`data-uw-sticky`) in an element a layout wraps it in, which
+ *     confines it. The layout makes its element sticky when `page.isSticky(area)`.
+ *   - an element inside a component sits in a box the component draws. A side panel beside a list
+ *     sticks within the row the two share, and cannot when its box is only as tall as the panel:
+ *     the fix is the component's, to give that box room or make it the sticky one.
+ *
+ * ⭐ MEASURED ON THE SETTLED PAGE. A box's height can wait on the page's data — a list fills its
+ * column once its records arrive — so the check runs once nothing is in flight (the layout passes
+ * `website.dataStore.whenIdle` as `settled`), after the page's fonts, in the frames after that:
+ * React has committed what arrived, and the browser has laid it out. ⛔ Until 2026-10-25 it
+ * measured in the first frame after the page mounted, while the page's fetches were still out,
+ * and named a side panel whose column was waiting for its records as one that could never move.
  *
  * Table parts are left out: a sticky table header cell sticks within its table, though its row is
  * no taller than it is. So is a child section the runtime made sticky (`data-uw-sticky="child"`):
@@ -25,6 +35,22 @@
 
 const warned = new WeakSet()
 
+/** Every section wrapper the browser's renderer drew, noted in dev (`BlockRenderer.jsx`). */
+const sectionWrappers = new WeakSet()
+
+/** How long the check waits on the page's fetches before it measures anyway. */
+const SETTLE_CAP_MS = 10_000
+
+/**
+ * Note a section's wrapper, so the check can tell a component's outermost element — the one in
+ * it — from an element inside a component. A ref callback's argument: null on unmount.
+ *
+ * @param {Element|null} element
+ */
+export function noteSectionWrapper(element) {
+  if (element) sectionWrappers.add(element)
+}
+
 /** The nearest ancestor that draws a box — `display: contents` draws none. */
 function boxParent(el) {
   let parent = el.parentElement
@@ -73,38 +99,85 @@ export function clippingAncestor(el) {
 }
 
 /**
- * Warn, once per element, about each sticky element on the page that cannot move.
+ * What to do about a sticky element that cannot move, by whose box holds it (see above).
  *
- * @param {Document} [doc]
- * @returns {() => void} cancels a check not yet run
+ * @param {Element} el
+ * @returns {string}
  */
-export function warnUnmovableSticky(doc = globalThis.document) {
-  if (!doc?.body || typeof requestAnimationFrame !== 'function') return () => {}
-  const frame = requestAnimationFrame(() => {
-    for (const el of doc.body.querySelectorAll('*')) {
-      if (warned.has(el) || getComputedStyle(el).position !== 'sticky') continue
-      const clip = clippingAncestor(el)
-      if (clip) {
-        warned.add(el)
-        console.warn(
-          '[uniweb] This element is sticky but sits in a box that clips its overflow (`overflow: hidden`, ' +
-            'or `overflow-x: hidden`), so it sticks to that box, which does not scroll, and never moves. ' +
-            'Clip with `overflow: clip` instead: it clips the same and keeps the element sticking.',
-          el,
-          clip,
-        )
-        continue
-      }
-      if (el.getAttribute('data-uw-sticky') === 'child' || canStick(el)) continue
+export function unmovableAdvice(el) {
+  if (el.getAttribute('data-uw-sticky')) {
+    return (
+      'It is the box the runtime makes sticky for a section, and an element of the layout around it ' +
+      'confines it: a layout that wraps an area in an element of its own makes that element sticky ' +
+      'when `page.isSticky(area)`.'
+    )
+  }
+  if (sectionWrappers.has(boxParent(el))) {
+    return (
+      "It is a section's outermost element, and the section's wrapper is as tall as it is. To keep the " +
+      'section in view, give it `sticky: true` (its type may default it in meta.js), and the runtime ' +
+      'makes sticky the box that can.'
+    )
+  }
+  return (
+    'It sits in a box the component draws. Give that box room — let it stretch with its row rather ' +
+    'than fit its content (`items-start` or `self-start` shrinks it) — or make that box the sticky one.'
+  )
+}
+
+/** Warn, once per element, about each sticky element on the page that cannot move. */
+function checkPage(doc) {
+  for (const el of doc.body.querySelectorAll('*')) {
+    if (warned.has(el) || getComputedStyle(el).position !== 'sticky') continue
+    const clip = clippingAncestor(el)
+    if (clip) {
       warned.add(el)
       console.warn(
-        '[uniweb] This element is sticky but cannot move: its parent is no taller than it is, so it ' +
-          'scrolls away with the page. To keep a section in view, give the section `sticky: true` ' +
-          '(its type may default it in meta.js) — no box a component draws can stick. A layout that ' +
-          'wraps an area in an element of its own makes that element sticky when `page.isSticky(area)`.',
+        '[uniweb] This element is sticky but sits in a box that clips its overflow (`overflow: hidden`, ' +
+          'or `overflow-x: hidden`), so it sticks to that box, which does not scroll, and never moves. ' +
+          'Clip with `overflow: clip` instead: it clips the same and keeps the element sticking.',
         el,
+        clip,
       )
+      continue
     }
-  })
-  return () => cancelAnimationFrame(frame)
+    if (el.getAttribute('data-uw-sticky') === 'child' || canStick(el)) continue
+    warned.add(el)
+    console.warn(
+      '[uniweb] This element is sticky but cannot move: its parent is no taller than it is, so it ' +
+        `scrolls away with the page. ${unmovableAdvice(el)}`,
+      el,
+    )
+  }
+}
+
+/**
+ * Check the page once it has settled: when `settled()` resolves (or after `SETTLE_CAP_MS`, so a
+ * fetch that never answers does not silence the check), its fonts have loaded, and two frames have
+ * passed — the first for React to commit what arrived, the second to lay it out.
+ *
+ * @param {Document} [doc]
+ * @param {{ settled?: () => Promise<unknown> }} [options] - what the page waits on: its data
+ * @returns {() => void} cancels a check not yet run
+ */
+export function warnUnmovableSticky(doc = globalThis.document, { settled } = {}) {
+  if (!doc?.body || typeof requestAnimationFrame !== 'function') return () => {}
+  let cancelled = false
+  let frame = 0
+  let cap = 0
+  const nextFrame = () => new Promise((resolve) => { frame = requestAnimationFrame(resolve) })
+  const capped = new Promise((resolve) => { cap = setTimeout(resolve, SETTLE_CAP_MS) })
+  ;(async () => {
+    await Promise.race([Promise.resolve(settled?.()).catch(() => {}), capped])
+    clearTimeout(cap)
+    await doc.fonts?.ready
+    if (!cancelled) await nextFrame()
+    if (!cancelled) await nextFrame()
+    if (!cancelled) checkPage(doc)
+  })()
+  return () => {
+    cancelled = true
+    clearTimeout(cap)
+    cancelAnimationFrame(frame)
+  }
 }

package/src/sticky.js

@@ -3,9 +3,11 @@
  * (`components/Layout.jsx`, `BlockRenderer.jsx`) and the prerender's (`ssr-renderer.js`) make the
  * same boxes sticky, and a prerendered page does not change when the browser renders over it.
  *
- * ⭐ NO BOX A COMPONENT DRAWS CAN STICK. `position: sticky` moves an element only within its
- * parent's box, and a component's markup sits in boxes as tall as itself: the section's wrapper,
- * the layout area's wrapper (`area-wrappers.js`), the built-in layout's zone (`default-layout.js`).
+ * ⭐ A COMPONENT'S OUTERMOST ELEMENT CANNOT STICK. `position: sticky` moves an element only within
+ * its parent's box, and a component sits in boxes as tall as itself: the section's wrapper, the
+ * layout area's wrapper (`area-wrappers.js`), the built-in layout's zone (`default-layout.js`). (An
+ * element inside a component can stick within a taller box the component draws — a side panel in
+ * the row beside a list — which is the component's own layout and asks nothing of this module.)
  * So a section asks — `sticky:`, one of a section's own settings (`@uniweb/schemas/section`),
  * defaulted by its type's `meta.js` — and the runtime makes sticky the box that can:
  *