@uniweb/runtime 1.1.11 → 1.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,15 +36,15 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@uniweb/core": "~1.3.1",
-    "@uniweb/theming": "~1.2.0"
+    "@uniweb/theming": "~1.2.0",
+    "@uniweb/core": "~1.4.0"
   },
   "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.5.2"
+    "@uniweb/build": "1.6.2"
   },
   "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)
 
-  return explicit ? { ...defaults, ...explicit } : defaults
+  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 layers
 }
 
 /**
@@ -132,19 +154,26 @@ 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
   }

package/src/components/BlockRenderer.jsx

@@ -10,6 +10,7 @@ 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 { sectionStickyStyle } from '../sticky.js'
 
 /**
  * Valid color contexts
@@ -78,8 +79,9 @@ 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 {boolean} [props.stickySelf] - whether a sticky section's own wrapper sticks (in the body)
  */
-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 +161,10 @@ export default function BlockRenderer({ block, as = 'section' }) {
   // Section mode — full treatment with wrapper, context classes, background.
   const { background, ...wrapperProps } = getWrapperProps(block)
 
+  // In the body, a sticky section's wrapper is the box that stays in view (`../sticky.js`).
+  const sticky = stickySelf ? sectionStickyStyle(block) : null
+  if (sticky) wrapperProps.style = { ...wrapperProps.style, ...sticky }
+
   // 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 {boolean} [props.stickySelf] - a sticky section's own wrapper is the box that sticks:
+ *   true 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,11 @@
  * - 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 { layoutStickiness, stickyStyle } from '../sticky.js'
+import { warnUnmovableSticky } from '../sticky-check.js'
 // The built-in layout — one copy, which the prerender renders too (`../default-layout.js`).
 import { DefaultLayout } from '../default-layout.js'
 
@@ -88,20 +91,32 @@ 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)
+    const style = areaWrapperStyle(region, transitions, layers, RemoteLayout ? sticky[region] : null)
     return style ? <div style={style}>{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 />) : null
 
   const areaElements = {}
   for (const [name, blocks] of Object.entries(areas)) {
     areaElements[name] = wrap(name, <Blocks blocks={blocks} />)
   }
 
+  // `uniweb dev` names a sticky element that cannot move — a component's own `sticky`, or an area
+  // a layout wraps in an element of its own. 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 +133,13 @@ export default function Layout({ page, website }) {
     )
   }
 
-  // Default layout
+  // Default layout — a sticky area's zone is the box that sticks.
+  const zone = (name) => (sticky[name] ? stickyStyle(sticky[name].top, layers?.[name]) : null)
   return (
     <DefaultLayout
       body={bodyElement}
       {...areaElements}
+      zones={{ header: zone('header'), footer: zone('footer') }}
     />
   )
 }

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 style (`zones`): 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,20 @@ 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 style, when it sticks
  * @returns {React.ReactElement}
  */
-export function DefaultLayout({ header, body, footer }) {
+export function DefaultLayout({ header, body, footer, zones }) {
+  const zone = (name) => (zones?.[name] ? { style: zones[name] } : null)
   return React.createElement(
     'div',
     { style: COLUMN },
-    header && React.createElement('header', null, header),
+    header && React.createElement('header', zone('header'), header),
     body && React.createElement('main', { style: GROW }, body),
-    footer && React.createElement('footer', null, footer),
+    footer && React.createElement('footer', zone('footer'), footer),
   )
 }

package/src/ssr-renderer.js

@@ -31,6 +31,7 @@ import {
   ensureThemeCss,
 } from './wire-foundation.js'
 import { resolveLayoutTransitions, resolveLayoutLayers, areaWrapperStyle } from './area-wrappers.js'
+import { layoutStickiness, sectionStickyStyle, stickyStyle } from './sticky.js'
 import { DefaultLayout } from './default-layout.js'
 import { renderAppearanceBootScript } from './appearance.js'
 import { documentTitle } from './document-title.js'
@@ -223,9 +224,10 @@ 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 {boolean} [options.stickySelf] - whether a sticky section's own wrapper sticks (in the body)
  * @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 +267,10 @@ export function renderBlock(block, { as = 'section' } = {}) {
   // Section mode: full treatment with wrapper, context classes, background.
   const { background, ...wrapperProps } = getWrapperProps(block)
 
+  // In the body, a sticky section's wrapper is the box that stays in view (`sticky.js`).
+  const sticky = stickySelf ? sectionStickyStyle(block) : null
+  if (sticky) wrapperProps.style = { ...wrapperProps.style, ...sticky }
+
   // Merge Component.className (static classes declared on the component function)
   const componentClassName = Component.className
   if (componentClassName) {
@@ -300,11 +306,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 +327,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 +340,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)
+    const style = areaWrapperStyle(name, transitions, layers, RemoteLayout ? sticky[name] : null)
     return style ? React.createElement('div', { style }, element) : element
   }
 
-  const bodyElement = bodyBlocks ? wrapArea('body', renderBlocks(bodyBlocks)) : null
+  const bodyElement = bodyBlocks ? wrapArea('body', renderBlocks(bodyBlocks, { stickySelf: true })) : null
   const areaElements = {}
   for (const [name, blocks] of Object.entries(areas)) {
     areaElements[name] = wrapArea(name, renderBlocks(blocks))
@@ -352,7 +369,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) => (sticky[name] ? stickyStyle(sticky[name].top, layers?.[name]) : null)
+  return React.createElement(DefaultLayout, {
+    body: bodyElement,
+    ...areaElements,
+    zones: { header: zone('header'), footer: zone('footer') },
+  })
 }
 
 // ============================================================================

package/src/sticky-check.js

@@ -0,0 +1,68 @@
+/**
+ * `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.
+ */
+
+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)
+}
+
+/**
+ * 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' || 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.js

@@ -0,0 +1,76 @@
+/**
+ * Where a section's `sticky` setting lands — pure, so the browser's renderer
+ * (`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`).
+ * 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:
+ *
+ *   - in the body, the section's own wrapper, whose parent, the body, spans every section;
+ *   - in any other area, the area's box when any of its sections is sticky: the zone, in the
+ *     built-in layout; the area wrapper, in a foundation's layout. That box takes the area's
+ *     layer, and a sticky area's layer is above every area that scrolls under it
+ *     (`resolveLayoutLayers`).
+ *
+ * ⛔ A layout that wraps an area in an element of its own confines the area wrapper, as the zone
+ * does in the built-in layout. That element is the layout's, so the layout makes it sticky, when
+ * `page.isSticky(area)`.
+ *
+ * ⛔ Until 2026-10-19 there was no setting, and a header's own `sticky top-0` — the starter
+ * templates' — scrolled away with the page.
+ */
+
+/** The very top of the viewport — a sticky box with no `top` of its own. */
+export const STICKY_TOP = '0px'
+
+/**
+ * The style that keeps a box in view.
+ *
+ * @param {string|null} [top] - how far below the viewport's top, a CSS length
+ * @param {number|null} [zIndex] - its layer, when it has one
+ * @returns {{ position: 'sticky', top: string, zIndex?: number }}
+ */
+export function stickyStyle(top, zIndex) {
+  const style = { position: 'sticky', top: top || STICKY_TOP }
+  if (zIndex != null) style.zIndex = zIndex
+  return style
+}
+
+/**
+ * Whether an area stays in view — when any of its sections is sticky — and how far below the
+ * top: the first sticky section's.
+ *
+ * @param {Array<Object>|null|undefined} blocks - the area's blocks, their components initialized
+ * @returns {{ top: string }|null}
+ */
+export function areaStickiness(blocks) {
+  const first = (blocks || []).find((block) => block?.sticky)
+  return first ? { top: first.stickyTop || STICKY_TOP } : null
+}
+
+/**
+ * Each layout area's stickiness, read from its sections — what both renderers compute before the
+ * areas' layers, since a sticky area is lifted above the rest (`resolveLayoutLayers`).
+ *
+ * @param {Object<string, Array<Object>>} areas - area name → its blocks, their components initialized
+ * @returns {Object<string, { top: string }|null>}
+ */
+export function layoutStickiness(areas) {
+  const sticky = {}
+  for (const [name, blocks] of Object.entries(areas || {})) sticky[name] = areaStickiness(blocks)
+  return sticky
+}
+
+/**
+ * The style a sticky section's own wrapper takes, in the body — or null. Layer 1, so it paints
+ * over the sections after it, which are positioned only when they have a background.
+ *
+ * @param {Object} block - its component initialized
+ * @returns {Object|null}
+ */
+export function sectionStickyStyle(block) {
+  return block?.sticky ? stickyStyle(block.stickyTop, 1) : null
+}