@uniweb/runtime 1.4.5 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "1.4.5",
+  "version": "1.5.0",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,15 +36,15 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@uniweb/core": "~1.6.4",
-    "@uniweb/theming": "~1.2.1"
+    "@uniweb/core": "~1.6.6",
+    "@uniweb/theming": "~1.3.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.15.3"
+    "@uniweb/build": "1.17.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/components/BlockRenderer.jsx

@@ -13,6 +13,7 @@ import Background from './Background.jsx'
 import { sectionStickyProps, sectionScrollMargin } from '../sticky.js'
 import { noteBodySection } from '../sticky-top.js'
 import { noteSectionWrapper } from '../sticky-check.js'
+import { openingUnderHeader, underHeaderProps } from '../under-header.js'
 
 /**
  * Valid color contexts
@@ -173,6 +174,14 @@ export default function BlockRenderer({ block, as = 'section', stickySelf = fals
   // On a page whose layout has a sticky area, a link to this section lands below it.
   const margin = sectionScrollMargin(block, stickySelf)
   if (margin) wrapperProps.style = { ...wrapperProps.style, ...margin }
+  // The page's opening section, when the header lies over it: the header's height to clear, the
+  // declared one until the browser measures it (`../under-header.js`). Mirrored in `ssr-renderer.js`.
+  const overlay = stickySelf === 'section' || stickySelf === true ? openingUnderHeader(block) : null
+  if (overlay) {
+    const under = underHeaderProps(overlay)
+    wrapperProps.style = { ...wrapperProps.style, ...under.style }
+    wrapperProps['data-uw-under-header'] = under['data-uw-under-header']
+  }
   // A body section's element, for the measurement of what is stuck over the body (`../sticky-top.js`);
   // in dev, every section's, so `uniweb dev`'s sticky check knows a component's outermost element.
   const bodySection = stickySelf === 'section' || stickySelf === true
@@ -202,6 +211,11 @@ export default function BlockRenderer({ block, as = 'section', stickySelf = fals
   // and let the engine background show through.
   block.hasBackground = hasBackground
 
+  // `background: 'self'` is everything behind the content: the theme leaves this wrapper
+  // unpainted too, and the component paints its context's surface where it wants it
+  // (`@uniweb/theming`'s section rule). Mirrored in `ssr-renderer.js`.
+  if (meta?.background === 'self') wrapperProps['data-uw-background'] = 'self'
+
   // Determine wrapper element:
   // - Explicit as prop (not 'section') → use as prop directly
   // - Component.as → use component's declared tag (e.g., Header.as = 'header')

package/src/components/Layout.jsx

@@ -35,6 +35,7 @@ import { useEffect } from 'react'
 import Blocks from './Blocks.jsx'
 import { resolveLayoutTransitions, resolveLayoutLayers, areaWrapperProps } from '../area-wrappers.js'
 import { layoutStickiness, zoneProps } from '../sticky.js'
+import { headerOverlay, overlayBoxProps } from '../under-header.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`).
@@ -95,9 +96,14 @@ export default function Layout({ page, website }) {
   // it is lifted above the areas that scroll under it.
   const sticky = layoutStickiness(areas)
   const layers = resolveLayoutLayers(areaNames, layoutMeta?.layers, sticky)
+  // A page that opens with a section under the header has the header lie over it: the header's box
+  // takes no room in the flow (`../under-header.js`). In a foundation's layout that box is the area
+  // wrapper; in the built-in one, the zone around it.
+  const overlay = headerOverlay(page)
 
   const wrap = (region, children) => {
-    const props = areaWrapperProps(region, transitions, layers, RemoteLayout ? sticky[region] : null)
+    let props = areaWrapperProps(region, transitions, layers, RemoteLayout ? sticky[region] : null)
+    if (overlay && RemoteLayout && region === 'header') props = overlayBoxProps(props)
     return props ? <div {...props}>{children}</div> : children
   }
 
@@ -143,7 +149,7 @@ export default function Layout({ page, website }) {
     <DefaultLayout
       body={bodyElement}
       {...areaElements}
-      zones={{ header: zone('header'), footer: zone('footer') }}
+      zones={{ header: overlay ? overlayBoxProps(zone('header')) : zone('header'), footer: zone('footer') }}
     />
   )
 }

package/src/ssr-renderer.js

@@ -34,6 +34,7 @@ import {
 } from './wire-foundation.js'
 import { resolveLayoutTransitions, resolveLayoutLayers, areaWrapperProps } from './area-wrappers.js'
 import { layoutStickiness, sectionStickyProps, sectionScrollMargin, zoneProps } from './sticky.js'
+import { headerOverlay, overlayBoxProps, openingUnderHeader, underHeaderProps } from './under-header.js'
 import { DefaultLayout } from './default-layout.js'
 import { renderAppearanceBootScript } from './appearance.js'
 import { documentTitle } from './document-title.js'
@@ -185,6 +186,14 @@ export function renderBlock(block, { as = 'section', stickySelf = false } = {})
   // On a page whose layout has a sticky area, a link to this section lands below it.
   const margin = sectionScrollMargin(block, stickySelf)
   if (margin) wrapperProps.style = { ...wrapperProps.style, ...margin }
+  // The page's opening section, when the header lies over it: the header's height to clear
+  // (`under-header.js`). Mirrors `BlockRenderer.jsx`.
+  const overlay = stickySelf === 'section' || stickySelf === true ? openingUnderHeader(block) : null
+  if (overlay) {
+    const under = underHeaderProps(overlay)
+    wrapperProps.style = { ...wrapperProps.style, ...under.style }
+    wrapperProps['data-uw-under-header'] = under['data-uw-under-header']
+  }
 
   // Merge Component.className (static classes declared on the component function)
   const componentClassName = Component.className
@@ -197,6 +206,8 @@ export function renderBlock(block, { as = 'section', stickySelf = false } = {})
   // Check if component handles its own background
   const hasBackground = background?.mode && meta?.background !== 'self'
   block.hasBackground = hasBackground
+  // `background: 'self'` leaves the wrapper unpainted by the theme too (`BlockRenderer.jsx`).
+  if (meta?.background === 'self') wrapperProps['data-uw-background'] = 'self'
 
   // Determine wrapper element:
   // - Explicit as (not 'section') → use as prop directly
@@ -261,8 +272,11 @@ export function renderLayout(page, website) {
   // above the areas that scroll under it.
   const sticky = layoutStickiness(areas)
   const layers = resolveLayoutLayers(areaNames, layoutMeta?.layers, sticky)
+  // Mirror Layout.jsx: the header lies over a page's opening section under it (`under-header.js`).
+  const overlay = headerOverlay(page)
   const wrapArea = (name, element) => {
-    const props = areaWrapperProps(name, transitions, layers, RemoteLayout ? sticky[name] : null)
+    let props = areaWrapperProps(name, transitions, layers, RemoteLayout ? sticky[name] : null)
+    if (overlay && RemoteLayout && name === 'header') props = overlayBoxProps(props)
     return props ? React.createElement('div', props, element) : element
   }
 
@@ -288,7 +302,7 @@ export function renderLayout(page, website) {
   return React.createElement(DefaultLayout, {
     body: bodyElement,
     ...areaElements,
-    zones: { header: zone('header'), footer: zone('footer') },
+    zones: { header: overlay ? overlayBoxProps(zone('header')) : zone('header'), footer: zone('footer') },
   })
 }
 

package/src/sticky-top.js

@@ -16,8 +16,15 @@
  * 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).
+ *
+ * ⭐ A HEADER OVER THE OPENING SECTION (`under-header.js`) takes no room in the flow, so its box is
+ * as tall as nothing: what it reaches is what it holds, the runtime's own wrappers inside it. Its
+ * height is published too, as `--uw-header-measured`, which the opening section's
+ * `--uw-header-height` reads in place of the height the header type declared for the first paint.
  */
 
+import { MEASURED_HEADER_HEIGHT } from './under-header.js'
+
 const VARIABLE = '--uw-sticky-top'
 const FOLLOWING = 4 // Node.DOCUMENT_POSITION_FOLLOWING
 
@@ -40,6 +47,34 @@ export function bodySectionOf(block) {
   return (block && bodySections.get(block)) || null
 }
 
+/**
+ * How tall a box is drawn: its own height — or, for the header's box over the page's opening
+ * section (`data-uw-header="over"`, `under-header.js`), which takes no room in the flow, how far what
+ * it holds reaches below its top. What it holds is the runtime's own elements (the area's wrapper,
+ * the sections' wrappers), never a guess at a foundation's markup.
+ *
+ * @param {Element} box
+ * @returns {number}
+ */
+function drawnHeight(box) {
+  const own = box.getBoundingClientRect()
+  if (box.getAttribute('data-uw-header') !== 'over') return own.height
+  let bottom = own.top
+  for (const child of box.children) bottom = Math.max(bottom, child.getBoundingClientRect().bottom)
+  return bottom - own.top
+}
+
+/**
+ * How tall the header lying over the page's opening section is, in px — null on a page with none.
+ *
+ * @param {Document} doc
+ * @returns {number|null}
+ */
+export function measureHeaderOverlay(doc) {
+  const box = doc.querySelector('[data-uw-header="over"]')
+  return box ? Math.round(drawnHeight(box) * 100) / 100 : null
+}
+
 /**
  * How far down the viewport the stuck chrome over the body reaches, in px — 0 when none does.
  *
@@ -57,7 +92,7 @@ export function measureStickyTop(doc, body) {
     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)
+    reach = Math.max(reach, top + drawnHeight(box))
   }
   return Math.round(reach * 100) / 100
 }
@@ -78,13 +113,19 @@ export function watchStickyTop(doc, body) {
     const reach = measureStickyTop(doc, body)
     if (reach > 0) root.style.setProperty(VARIABLE, `${reach}px`)
     else root.style.removeProperty(VARIABLE)
+    // The header over the opening section: what the section's `--uw-header-height` reads once known.
+    const header = measureHeaderOverlay(doc)
+    if (header != null) root.style.setProperty(MEASURED_HEADER_HEIGHT, `${header}px`)
+    else root.style.removeProperty(MEASURED_HEADER_HEIGHT)
+  }
+  const forget = () => {
+    root.style.removeProperty(VARIABLE)
+    root.style.removeProperty(MEASURED_HEADER_HEIGHT)
   }
   apply()
 
   const View = doc.defaultView
-  if (!body || typeof View?.ResizeObserver !== 'function') {
-    return () => root.style.removeProperty(VARIABLE)
-  }
+  if (!body || typeof View?.ResizeObserver !== 'function') return forget
   let frame = 0
   const observer = new View.ResizeObserver(() => {
     View.cancelAnimationFrame(frame)
@@ -92,9 +133,11 @@ export function watchStickyTop(doc, body) {
   })
   observer.observe(body)
   for (const box of doc.querySelectorAll('[data-uw-sticky="area"]')) observer.observe(box)
+  // A box over the opening section keeps no height of its own to change: what it holds does.
+  for (const box of doc.querySelectorAll('[data-uw-header="over"]')) for (const child of box.children) observer.observe(child)
   return () => {
     View.cancelAnimationFrame(frame)
     observer.disconnect()
-    root.style.removeProperty(VARIABLE)
+    forget()
   }
 }

package/src/under-header.js

@@ -0,0 +1,83 @@
+/**
+ * The header laid over a page's opening section — `underHeader`, a setting of the section.
+ *
+ * A page that opens with a section that can sit under the header (`underHeader: true`: its type's
+ * default in `meta.js`, or its author's) has the header lie over it. The header's box takes no room
+ * in the flow, so the section starts at the top of the window and its picture reaches up behind a
+ * see-through header; the header keeps its own height inside that box, and stays in view if it
+ * sticks. Pure, so both renderers (`components/Layout.jsx`, `ssr-renderer.js`) build the same page,
+ * and the browser's measurement (`sticky-top.js`) reads the same boxes.
+ *
+ * ⭐ THE RUNTIME DOES IT, AS IT DOES `sticky`, because a component cannot move the box the runtime
+ * puts it in. Foundations that floated a header from inside its own section took the bar out of
+ * the flow (`absolute`, `fixed`), which left the box the runtime measures with no height: no
+ * `--uw-sticky-top`, and a link to a section landing under the bar (measured 2026-11-06 on a site's
+ * store page, in Chromium and WebKit). Five sites solved it five ways.
+ *
+ * The opening section keeps its content clear of the header by `--uw-header-height`, which the
+ * runtime gives its wrapper: the header type's `height` on the first paint, which no prerender can
+ * measure, then what the browser measures. The header reads `getNextBlockInfo().underHeader` to
+ * paint itself see-through, and its box says `data-uw-header="over"` for a stylesheet.
+ */
+
+/** The header's height, on the opening section's wrapper: what its content is padded by. */
+export const HEADER_HEIGHT = '--uw-header-height'
+
+/** What the browser measured, on the root, which the opening section's value defers to. */
+export const MEASURED_HEADER_HEIGHT = '--uw-header-measured'
+
+/**
+ * Whether the page's header lies over its opening section, and how tall the header is before the
+ * browser measures it: the `height` its sections' types declare, else `0px` until measured.
+ *
+ * @param {Object} page - its blocks' components initialized, as both renderers do before rendering
+ * @returns {{ height: string }|null}
+ */
+export function headerOverlay(page) {
+  const first = page?.getBodyBlocks?.()?.[0]
+  if (!first?.underHeader) return null
+  const header = page.getLayoutAreas?.()?.header
+  if (!Array.isArray(header) || header.length === 0) return null
+  const heights = header.map((block) => block?.height).filter(Boolean)
+  const height = heights.length === 0 ? '0px' : heights.length === 1 ? heights[0] : `calc(${heights.join(' + ')})`
+  return { height }
+}
+
+/**
+ * The props of the header's box — the built-in layout's zone, or a foundation layout's area
+ * wrapper — when it lies over the opening section: it takes no room in the flow, and what it holds
+ * keeps its height. Whatever else the box has (its layer, its stickiness) stays.
+ *
+ * @param {Object|null} props - the box's props without the overlay
+ * @returns {Object}
+ */
+export function overlayBoxProps(props) {
+  return { ...(props || {}), style: { ...(props?.style || {}), height: 0, minHeight: 0 }, 'data-uw-header': 'over' }
+}
+
+/**
+ * What the opening section's wrapper adds when the header lies over it: the header's height, the
+ * declared one until the browser has measured it.
+ *
+ * @param {{ height: string }} overlay - `headerOverlay(page)`
+ * @returns {{ style: Object, 'data-uw-under-header': string }}
+ */
+export function underHeaderProps(overlay) {
+  return {
+    style: { [HEADER_HEIGHT]: `var(${MEASURED_HEADER_HEIGHT}, ${overlay.height})` },
+    'data-uw-under-header': '',
+  }
+}
+
+/**
+ * Whether `block` is its page's opening section under the header — what its wrapper asks before it
+ * adds `underHeaderProps`.
+ *
+ * @param {Object} block - a body section's block, its component initialized
+ * @returns {{ height: string }|null} the page's overlay, when it opens with this section
+ */
+export function openingUnderHeader(block) {
+  const page = block?.page
+  if (!page || page.getBodyBlocks?.()?.[0] !== block) return null
+  return headerOverlay(page)
+}