@uniweb/runtime 1.1.19 → 1.2.0

package/src/ssr-renderer.js

@@ -342,8 +342,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)
@@ -674,7 +674,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 +701,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 +766,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:
  *