@uniweb/runtime 1.1.12 → 1.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "1.1.12",
+  "version": "1.1.14",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,15 +36,15 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@uniweb/core": "~1.3.2",
-    "@uniweb/theming": "~1.2.0"
+    "@uniweb/core": "~1.4.0",
+    "@uniweb/theming": "~1.2.1"
   },
   "devDependencies": {
     "@vitejs/plugin-react": "^4.5.2",
     "esbuild": "^0.21.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.27.0 || ^0.28.0",
     "vite": "^7.3.1",
     "vitest": "^4.1.7",
-    "@uniweb/build": "1.6.1"
+    "@uniweb/build": "1.7.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/area-wrappers.js

@@ -29,6 +29,8 @@
  * the hydrated SPA aligned.
  */
 
+import { stickyStyle } from './sticky.js'
+
 // Namespace so generated names can't collide with `view-transition-name`s a
 // foundation sets inside its own component CSS. The prefix also guarantees a
 // valid CSS <custom-ident> (starts with a letter).
@@ -66,7 +68,8 @@ export function resolveLayoutTransitions(areaNames, explicit) {
  * The stacking layer of each area's wrapper.
  *
  * Default: every area except the body gets `1`, and the body gets nothing —
- * content is the backdrop, chrome is above it. That is the whole of what the
+ * content is the backdrop, chrome is above it — and a sticky area gets one more
+ * than every area that does not stick (below). That is the whole of what the
  * framework claims to know, and it is deliberately not more.
  *
  * The body is left unstacked rather than pinned to `0` on purpose. A layer
@@ -103,17 +106,36 @@ export function resolveLayoutTransitions(areaNames, explicit) {
  * whole — a foundation could set `layers: { header: 0 }` on the default layout
  * and measurably nothing happened.
  *
+ * ⭐ The one ordering the framework does know is a sticky area's (`sticky.js` — any of its sections
+ * is). It stays in view while the rest of the page scrolls under it, so it is lifted above every
+ * area that does not stick: the runtime made it stick, so it owes it the layer. Left equal to them,
+ * a footer taller than the space below a stuck header paints over the header at the bottom of the
+ * page, since it comes later in the DOM (measured 2026-10-19: a 521px footer on a 480px-tall
+ * phone). That is a fact about the box, not a reading of the area's name, and the layout's
+ * `layers` still rank a sticky area it names.
+ *
  * @param {string[]} areaNames - Names of the areas rendered for this page (excludes `body`).
  * @param {Object|false|null|undefined} explicit - `layoutMeta.layers`.
+ * @param {Object} [sticky] - region → its stickiness, or null (`layoutStickiness`).
  * @returns {Object} region → z-index. Empty when the layout opts out.
  */
-export function resolveLayoutLayers(areaNames, explicit) {
+export function resolveLayoutLayers(areaNames, explicit, sticky = null) {
   if (explicit === false) return {}
 
-  const defaults = {}
-  for (const name of areaNames) defaults[name] = 1
+  const layers = {}
+  for (const name of areaNames) layers[name] = 1
+  if (explicit) Object.assign(layers, explicit)
+
+  const lifted = areaNames.filter((name) => sticky?.[name] && !(explicit && name in explicit))
+  if (lifted.length > 0) {
+    const under = Object.entries(layers)
+      .filter(([name, layer]) => !sticky?.[name] && Number.isFinite(layer))
+      .map(([, layer]) => layer)
+    const above = Math.max(0, ...under) + 1
+    for (const name of lifted) layers[name] = above
+  }
 
-  return explicit ? { ...defaults, ...explicit } : defaults
+  return layers
 }
 
 /**
@@ -132,22 +154,46 @@ export function resolveLayoutLayers(areaNames, explicit) {
  * absolutely-positioned descendant on the page, and the ordering does not need
  * it.
  *
+ * A sticky area (`sticky.js` — any of its sections is) is `position: sticky` in place of
+ * `relative`, keeping its layer and its transition name. Only a foundation's layout passes one: the
+ * built-in layout's area wrapper sits in its zone, as tall as itself, so the zone sticks instead.
+ *
  * @param {string} region - Area name, or `body`.
  * @param {Object|null} transitions - region → view-transition-name.
  * @param {Object} layers - region → z-index.
+ * @param {{ top: string }|null} [sticky] - the area's stickiness, when its box is the one that sticks
  * @returns {Object|null} Inline style object, or null for no wrapper.
  */
-export function areaWrapperStyle(region, transitions, layers) {
+export function areaWrapperStyle(region, transitions, layers, sticky = null) {
   const style = {}
 
   const name = transitions?.[region]
   if (name) style.viewTransitionName = name
 
   const layer = layers?.[region]
-  if (layer != null) {
+  if (sticky) {
+    Object.assign(style, stickyStyle(sticky.top, layer))
+  } else if (layer != null) {
     style.position = 'relative'
     style.zIndex = layer
   }
 
   return Object.keys(style).length > 0 ? style : null
 }
+
+/**
+ * The props for one area's wrapper element — its style, and `data-uw-sticky="area"` when it is
+ * the box that sticks (`sticky.js`) — or `null` when the region needs no wrapper. Both renderers
+ * build the wrapper from this, so the prerendered page and the browser's agree.
+ *
+ * @param {string} region - Area name, or `body`.
+ * @param {Object|null} transitions - region → view-transition-name.
+ * @param {Object} layers - region → z-index.
+ * @param {{ top: string }|null} [sticky] - the area's stickiness, when its box is the one that sticks
+ * @returns {{ style: Object, 'data-uw-sticky'?: 'area' }|null}
+ */
+export function areaWrapperProps(region, transitions, layers, sticky = null) {
+  const style = areaWrapperStyle(region, transitions, layers, sticky)
+  if (!style) return null
+  return sticky ? { style, 'data-uw-sticky': 'area' } : { style }
+}

package/src/components/BlockRenderer.jsx

@@ -10,6 +10,8 @@ import React, { useState, useEffect } from 'react'
 import { sectionDomId } from '@uniweb/core/section-id'
 import { prepareProps, getComponentMeta } from '../prepare-props.js'
 import Background from './Background.jsx'
+import { sectionStickyProps } from '../sticky.js'
+import { noteBodySection } from '../sticky-top.js'
 
 /**
  * Valid color contexts
@@ -78,8 +80,10 @@ const getWrapperProps = (block) => {
  * @param {Object} props
  * @param {Block} props.block - Block instance to render
  * @param {string|null} props.as - Wrapper element tag for section mode, or null/false for bare mode
+ * @param {'section'|'child'|boolean} [props.stickySelf] - whether a sticky section's own wrapper is
+ *   the box that sticks: a body section's (`'section'`), or a child section's (`'child'`)
  */
-export default function BlockRenderer({ block, as = 'section' }) {
+export default function BlockRenderer({ block, as = 'section', stickySelf = false }) {
   const Component = block.initComponent()
 
   // Entity-aware data resolution via EntityStore
@@ -159,6 +163,15 @@ export default function BlockRenderer({ block, as = 'section' }) {
   // Section mode — full treatment with wrapper, context classes, background.
   const { background, ...wrapperProps } = getWrapperProps(block)
 
+  // A body section's wrapper, or a child section's, is the box that stays in view (`../sticky.js`).
+  const sticky = sectionStickyProps(block, stickySelf)
+  if (sticky) {
+    wrapperProps.style = { ...wrapperProps.style, ...sticky.style }
+    wrapperProps['data-uw-sticky'] = sticky['data-uw-sticky']
+  }
+  // A body section's element, for the measurement of what is stuck over the body (`../sticky-top.js`).
+  if (stickySelf === 'section' || stickySelf === true) wrapperProps.ref = (element) => noteBodySection(block, element)
+
   // Merge Component.className (static classes declared on the component function)
   // Order: context-{theme} + block.state.className + Component.className
   const componentClassName = Component.className

package/src/components/Blocks.jsx

@@ -16,12 +16,18 @@ import BlockRenderer from './BlockRenderer.jsx'
  * @param {Object} props
  * @param {Block[]} props.blocks - Array of Block instances to render
  */
-export default function Blocks({ blocks }) {
+/**
+ * @param {Object} props
+ * @param {Block[]} props.blocks
+ * @param {'section'|false} [props.stickySelf] - a sticky section's own wrapper is the box that
+ *   sticks: `'section'` in the body; an area's sections leave it to the area's box (`../sticky.js`)
+ */
+export default function Blocks({ blocks, stickySelf = false }) {
   if (!blocks || blocks.length === 0) return null
 
   return blocks.map((block, index) => (
     <React.Fragment key={block.id || index}>
-      <BlockRenderer block={block} />
+      <BlockRenderer block={block} stickySelf={stickySelf} />
     </React.Fragment>
   ))
 }

package/src/components/Layout.jsx

@@ -31,8 +31,12 @@
  * - header, footer, left, right, ...: Pre-rendered area React elements
  */
 
+import { useEffect } from 'react'
 import Blocks from './Blocks.jsx'
-import { resolveLayoutTransitions, resolveLayoutLayers, areaWrapperStyle } from '../area-wrappers.js'
+import { resolveLayoutTransitions, resolveLayoutLayers, areaWrapperProps } from '../area-wrappers.js'
+import { layoutStickiness, zoneProps } from '../sticky.js'
+import { warnUnmovableSticky } from '../sticky-check.js'
+import { watchStickyTop, bodySectionOf } from '../sticky-top.js'
 // The built-in layout — one copy, which the prerender renders too (`../default-layout.js`).
 import { DefaultLayout } from '../default-layout.js'
 
@@ -88,20 +92,36 @@ export default function Layout({ page, website }) {
   const transitions = website.viewTransitions
     ? resolveLayoutTransitions(areaNames, layoutMeta?.transitions)
     : null
-  const layers = resolveLayoutLayers(areaNames, layoutMeta?.layers)
+  // An area stays in view when any of its sections is sticky (`../sticky.js`): in a foundation's
+  // layout its wrapper sticks; in the built-in one, the zone around the wrapper does. Either way
+  // it is lifted above the areas that scroll under it.
+  const sticky = layoutStickiness(areas)
+  const layers = resolveLayoutLayers(areaNames, layoutMeta?.layers, sticky)
 
   const wrap = (region, children) => {
-    const style = areaWrapperStyle(region, transitions, layers)
-    return style ? <div style={style}>{children}</div> : children
+    const props = areaWrapperProps(region, transitions, layers, RemoteLayout ? sticky[region] : null)
+    return props ? <div {...props}>{children}</div> : children
   }
 
-  const bodyElement = bodyBlocks ? wrap('body', <Blocks blocks={bodyBlocks} />) : null
+  // A body section's own wrapper is the box that sticks for it; an area's sections leave that to
+  // the area's box.
+  const bodyElement = bodyBlocks ? wrap('body', <Blocks blocks={bodyBlocks} stickySelf="section" />) : null
 
   const areaElements = {}
   for (const [name, blocks] of Object.entries(areas)) {
     areaElements[name] = wrap(name, <Blocks blocks={blocks} />)
   }
 
+  // How far down the stuck chrome reaches — `--uw-sticky-top`, where a sticky section with no
+  // `top` of its own stays, and where kit's anchors land (`../sticky-top.js`).
+  useEffect(() => watchStickyTop(document, bodySectionOf(bodyBlocks?.[0])), [page])
+
+  // `uniweb dev` names a sticky element that cannot move — a component's own `sticky`, an area a
+  // layout wraps in an element of its own, a box that clips. Dropped from a published page's runtime.
+  useEffect(() => {
+    if (import.meta.env?.DEV) return warnUnmovableSticky()
+  }, [page])
+
   // Use foundation's custom Layout if provided
   if (RemoteLayout) {
     const params = mergeParams(page.getLayoutParams(), layoutMeta?.defaults)
@@ -118,11 +138,13 @@ export default function Layout({ page, website }) {
     )
   }
 
-  // Default layout
+  // Default layout — a sticky area's zone is the box that sticks.
+  const zone = (name) => zoneProps(sticky[name], layers?.[name])
   return (
     <DefaultLayout
       body={bodyElement}
       {...areaElements}
+      zones={{ header: zone('header'), footer: zone('footer') }}
     />
   )
 }

package/src/components/PageRenderer.jsx

@@ -45,7 +45,7 @@ export function ChildBlocks({ blocks, from, wrapAs }) {
 
   return blockList.map((childBlock, index) => (
     <React.Fragment key={childBlock.id || index}>
-      <BlockRenderer block={childBlock} as={wrapAs || null} />
+      <BlockRenderer block={childBlock} as={wrapAs || null} stickySelf={wrapAs ? 'child' : false} />
     </React.Fragment>
   ))
 }

package/src/default-layout.js

@@ -19,6 +19,11 @@
  * the ordering, those numbers were a second mechanism for it, and the older one won — a positioned
  * element here becomes a stacking context that seals the area's own layer inside it. Measured
  * 2026-07-31: `layers: { header: 0 }` on the default layout changed nothing.
+ *
+ * ⭐ A ZONE IS THE BOX THAT STICKS. When a section of the header (or footer) area is sticky, the
+ * runtime hands this layout the zone's props (`zones`, from `zoneProps`): its parent is the page
+ * column, so it can stay in view, where the area wrapper inside it, as tall as itself, cannot
+ * (`sticky.js`). The style carries the area's layer, which the sticky zone then holds.
  */
 
 import React from 'react'
@@ -27,15 +32,19 @@ const COLUMN = { display: 'flex', flexDirection: 'column', minHeight: '100vh' }
 const GROW = { flex: 1 }
 
 /**
- * @param {{ header?: React.ReactNode, body?: React.ReactNode, footer?: React.ReactNode }} props
+ * @param {Object} props
+ * @param {React.ReactNode} [props.header]
+ * @param {React.ReactNode} [props.body]
+ * @param {React.ReactNode} [props.footer]
+ * @param {{ header?: Object, footer?: Object }} [props.zones] - a zone's props, when it sticks
  * @returns {React.ReactElement}
  */
-export function DefaultLayout({ header, body, footer }) {
+export function DefaultLayout({ header, body, footer, zones }) {
   return React.createElement(
     'div',
     { style: COLUMN },
-    header && React.createElement('header', null, header),
+    header && React.createElement('header', zones?.header || null, header),
     body && React.createElement('main', { style: GROW }, body),
-    footer && React.createElement('footer', null, footer),
+    footer && React.createElement('footer', zones?.footer || null, footer),
   )
 }

package/src/ssr-renderer.js

@@ -30,7 +30,8 @@ import {
   hydrateDataStore,
   ensureThemeCss,
 } from './wire-foundation.js'
-import { resolveLayoutTransitions, resolveLayoutLayers, areaWrapperStyle } from './area-wrappers.js'
+import { resolveLayoutTransitions, resolveLayoutLayers, areaWrapperProps } from './area-wrappers.js'
+import { layoutStickiness, sectionStickyProps, zoneProps } from './sticky.js'
 import { DefaultLayout } from './default-layout.js'
 import { renderAppearanceBootScript } from './appearance.js'
 import { documentTitle } from './document-title.js'
@@ -223,9 +224,11 @@ export function renderBackground(background) {
  * @param {Block} block - Block instance to render
  * @param {Object} [options]
  * @param {string|null} [options.as='section'] - Wrapper element tag, or null/false for bare mode
+ * @param {'section'|'child'|boolean} [options.stickySelf] - whether a sticky section's own wrapper
+ *   is the box that sticks: a body section's (`'section'`), or a child section's (`'child'`)
  * @returns {React.ReactElement}
  */
-export function renderBlock(block, { as = 'section' } = {}) {
+export function renderBlock(block, { as = 'section', stickySelf = false } = {}) {
   const Component = block.initComponent()
 
   if (!Component) {
@@ -265,6 +268,13 @@ export function renderBlock(block, { as = 'section' } = {}) {
   // Section mode: full treatment with wrapper, context classes, background.
   const { background, ...wrapperProps } = getWrapperProps(block)
 
+  // A body section's wrapper, or a child section's, is the box that stays in view (`sticky.js`).
+  const sticky = sectionStickyProps(block, stickySelf)
+  if (sticky) {
+    wrapperProps.style = { ...wrapperProps.style, ...sticky.style }
+    wrapperProps['data-uw-sticky'] = sticky['data-uw-sticky']
+  }
+
   // Merge Component.className (static classes declared on the component function)
   const componentClassName = Component.className
   if (componentClassName) {
@@ -300,11 +310,11 @@ export function renderBlock(block, { as = 'section' } = {}) {
 /**
  * Render an array of blocks for SSR.
  */
-export function renderBlocks(blocks) {
+export function renderBlocks(blocks, { stickySelf = false } = {}) {
   if (!blocks || blocks.length === 0) return null
   return blocks.map((block, index) =>
     React.createElement(React.Fragment, { key: block.id || index },
-      renderBlock(block)
+      renderBlock(block, { stickySelf })
     )
   )
 }
@@ -321,6 +331,12 @@ export function renderLayout(page, website) {
   const bodyBlocks = page.getBodyBlocks()
   const areas = page.getLayoutAreas()
 
+  // Mirror Layout.jsx: every block's component initialized before anything renders, so each
+  // section's `sticky` — its type's default included — is known before the areas' layers are.
+  for (const blocks of [bodyBlocks, ...Object.values(areas)]) {
+    for (const block of blocks || []) block.initComponent()
+  }
+
   // 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.
@@ -328,13 +344,18 @@ export function renderLayout(page, website) {
   const transitions = website.viewTransitions
     ? resolveLayoutTransitions(areaNames, layoutMeta?.transitions)
     : null
-  const layers = resolveLayoutLayers(areaNames, layoutMeta?.layers)
+
+  // Mirror Layout.jsx: an area stays in view when any of its sections is sticky — in a
+  // foundation's layout its wrapper sticks, in the built-in one the zone around it — and is lifted
+  // above the areas that scroll under it.
+  const sticky = layoutStickiness(areas)
+  const layers = resolveLayoutLayers(areaNames, layoutMeta?.layers, sticky)
   const wrapArea = (name, element) => {
-    const style = areaWrapperStyle(name, transitions, layers)
-    return style ? React.createElement('div', { style }, element) : element
+    const props = areaWrapperProps(name, transitions, layers, RemoteLayout ? sticky[name] : null)
+    return props ? React.createElement('div', props, element) : element
   }
 
-  const bodyElement = bodyBlocks ? wrapArea('body', renderBlocks(bodyBlocks)) : null
+  const bodyElement = bodyBlocks ? wrapArea('body', renderBlocks(bodyBlocks, { stickySelf: 'section' })) : null
   const areaElements = {}
   for (const [name, blocks] of Object.entries(areas)) {
     areaElements[name] = wrapArea(name, renderBlocks(blocks))
@@ -352,7 +373,12 @@ export function renderLayout(page, website) {
   // The built-in layout — the browser's own copy, not a mirror of it (`default-layout.js`).
   // ⛔ Until 2026-10-07 this wrote its own, with no full-height column, so the prerendered
   // page differed from the one the browser renders over it.
-  return React.createElement(DefaultLayout, { body: bodyElement, ...areaElements })
+  const zone = (name) => zoneProps(sticky[name], layers?.[name])
+  return React.createElement(DefaultLayout, {
+    body: bodyElement,
+    ...areaElements,
+    zones: { header: zone('header'), footer: zone('footer') },
+  })
 }
 
 // ============================================================================
@@ -439,7 +465,7 @@ export function initPrerender(content, foundation, extensionsOrOptions, maybeOpt
     const blockList = blocks || from?.childBlocks || []
     return blockList.map((childBlock, index) =>
       React.createElement(React.Fragment, { key: childBlock.id || index },
-        renderBlock(childBlock, { as: wrapAs || null })
+        renderBlock(childBlock, { as: wrapAs || null, stickySelf: wrapAs ? 'child' : false })
       )
     )
   }

package/src/sticky-check.js

@@ -0,0 +1,110 @@
+/**
+ * `uniweb dev`'s warning about a sticky element that cannot move — browser-only, run by
+ * `components/Layout.jsx` behind `import.meta.env.DEV`, so a published page's runtime drops it.
+ *
+ * `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:
+ *
+ *   - 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)`.
+ *
+ * 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"`):
+ * with no room — stacked at one column, or the tallest in its row — it does not stick, by design.
+ *
+ * And an element that sits in a box that CLIPS — `overflow: hidden`, or `overflow-x: hidden`
+ * alone, which makes the box scroll vertically too — sticks to that box in place of the page,
+ * and the box does not scroll, so it never moves. Components clip for rounded corners; the
+ * warning names `overflow: clip`, which clips and keeps it sticking. A box that really scrolls
+ * (a layout's own scrolling `<main>`) is the element's scroller, and is left alone.
+ */
+
+const warned = new WeakSet()
+
+/** The nearest ancestor that draws a box — `display: contents` draws none. */
+function boxParent(el) {
+  let parent = el.parentElement
+  while (parent && getComputedStyle(parent).display === 'contents') parent = parent.parentElement
+  return parent
+}
+
+/**
+ * Whether a sticky element has room to move in the direction it sticks.
+ *
+ * @param {Element} el
+ * @returns {boolean}
+ */
+export function canStick(el) {
+  const style = getComputedStyle(el)
+  if (style.display.startsWith('table')) return true
+  const parent = boxParent(el)
+  if (!parent) return true
+  const own = el.getBoundingClientRect()
+  const room = parent.getBoundingClientRect()
+  const vertical = style.top !== 'auto' || style.bottom !== 'auto'
+  const horizontal = style.left !== 'auto' || style.right !== 'auto'
+  return (vertical && room.height > own.height + 0.5) || (horizontal && room.width > own.width + 0.5)
+}
+
+/**
+ * The box a sticky element would stick to in place of the page, because it clips its overflow
+ * without scrolling — or null. Looks no further than the nearest box with an overflow of its own:
+ * one that scrolls is the element's scroller, which is fine. Stops below `<body>`, whose overflow
+ * is the viewport's.
+ *
+ * @param {Element} el
+ * @returns {Element|null}
+ */
+export function clippingAncestor(el) {
+  const doc = el.ownerDocument
+  for (let node = el.parentElement; node && node !== doc?.body && node !== doc?.documentElement; node = node.parentElement) {
+    const { overflowX, overflowY } = getComputedStyle(node)
+    if (overflowY === 'visible' || overflowY === 'clip') continue
+    if (overflowY === 'hidden') return node
+    // `auto` / `scroll`: a scroller — unless it is only `overflow-x: hidden`'s side effect.
+    const scrolls = node.scrollHeight > node.clientHeight + 1
+    return overflowX === 'hidden' && !scrolls ? node : null
+  }
+  return null
+}
+
+/**
+ * Warn, once per element, about each sticky element on the page that cannot move.
+ *
+ * @param {Document} [doc]
+ * @returns {() => void} cancels a check not yet run
+ */
+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
+      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)`.',
+        el,
+      )
+    }
+  })
+  return () => cancelAnimationFrame(frame)
+}

package/src/sticky-top.js

@@ -0,0 +1,100 @@
+/**
+ * `--uw-sticky-top` — how far down the viewport the page's stuck chrome reaches.
+ *
+ * A sticky section with no `top` of its own stays in view below it (`sticky.js`), and kit's
+ * anchors land below it — a heading a contents rail scrolls to, a figure a cross-reference links
+ * to. Browser-only, run by `components/Layout.jsx`: only a browser knows a box's height, and the
+ * height is all that varies — a header that wraps on a phone, an announcement bar above it.
+ *
+ * ⭐ A MEASUREMENT THE PRERENDER DOES NOT NEED. The offset matters only once something is stuck,
+ * which takes scrolling; by then the browser has rendered and measured. A prerendered page, and
+ * one read without scripts, keep the variable's fallback.
+ *
+ * WHAT COUNTS: each box the runtime made sticky for an area (`data-uw-sticky="area"`) that comes
+ * before the body and spans over it — a header — but not one that follows it (a footer that
+ * sticks never reaches the top) or sits beside it (a rail stuck at the top covers no content). It
+ * reaches its `top` plus its height; the variable is the furthest any of them reaches. A rule of
+ * position, so it reads no meaning into an area's name (`area-wrappers.js` refuses to for the
+ * same reason).
+ */
+
+const VARIABLE = '--uw-sticky-top'
+const FOLLOWING = 4 // Node.DOCUMENT_POSITION_FOLLOWING
+
+/**
+ * The body's sections, by their Block — noted by `components/BlockRenderer.jsx` — so the
+ * measurement finds the body by the block it rendered, never by an id: a header's section and a
+ * body's can carry the same one.
+ */
+const bodySections = new WeakMap()
+
+/** Note (or forget, with `null`) the element a body section rendered into. */
+export function noteBodySection(block, element) {
+  if (!block) return
+  if (element) bodySections.set(block, element)
+  else bodySections.delete(block)
+}
+
+/** The element a body section rendered into, or null. */
+export function bodySectionOf(block) {
+  return (block && bodySections.get(block)) || null
+}
+
+/**
+ * How far down the viewport the stuck chrome over the body reaches, in px — 0 when none does.
+ *
+ * @param {Document} doc
+ * @param {Element|null} body - the body's first section
+ * @returns {number}
+ */
+export function measureStickyTop(doc, body) {
+  if (!body) return 0
+  const over = body.getBoundingClientRect()
+  let reach = 0
+  for (const box of doc.querySelectorAll('[data-uw-sticky="area"]')) {
+    if (box.contains(body)) continue
+    if (!(box.compareDocumentPosition(body) & FOLLOWING)) continue // the body comes first: a footer
+    const own = box.getBoundingClientRect()
+    if (own.right <= over.left || own.left >= over.right) continue // beside the body: a rail
+    const top = parseFloat(doc.defaultView.getComputedStyle(box).top) || 0
+    reach = Math.max(reach, top + own.height)
+  }
+  return Math.round(reach * 100) / 100
+}
+
+/**
+ * Keep `--uw-sticky-top` on the root element as the page's stuck chrome changes size, and remove
+ * it when nothing over the body sticks.
+ *
+ * @param {Document} doc
+ * @param {Element|null} body - the body's first section
+ * @returns {() => void} stops watching, and removes the variable
+ */
+export function watchStickyTop(doc, body) {
+  const root = doc?.documentElement
+  if (!root) return () => {}
+
+  const apply = () => {
+    const reach = measureStickyTop(doc, body)
+    if (reach > 0) root.style.setProperty(VARIABLE, `${reach}px`)
+    else root.style.removeProperty(VARIABLE)
+  }
+  apply()
+
+  const View = doc.defaultView
+  if (!body || typeof View?.ResizeObserver !== 'function') {
+    return () => root.style.removeProperty(VARIABLE)
+  }
+  let frame = 0
+  const observer = new View.ResizeObserver(() => {
+    View.cancelAnimationFrame(frame)
+    frame = View.requestAnimationFrame(apply)
+  })
+  observer.observe(body)
+  for (const box of doc.querySelectorAll('[data-uw-sticky="area"]')) observer.observe(box)
+  return () => {
+    View.cancelAnimationFrame(frame)
+    observer.disconnect()
+    root.style.removeProperty(VARIABLE)
+  }
+}