@uniweb/runtime 1.1.20 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "1.1.20",
+  "version": "1.2.1",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@uniweb/core": "~1.4.4",
+    "@uniweb/core": "~1.4.6",
     "@uniweb/theming": "~1.2.1"
   },
   "devDependencies": {
@@ -44,7 +44,7 @@
     "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.8.5"
+    "@uniweb/build": "1.9.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/background-shared.js

@@ -4,13 +4,13 @@
  *
  * ## Why this module exists
  *
- * Backgrounds are an L3 pair by design: `components/Background.jsx` renders
- * with hooks and DOM, `ssr-renderer.js` renders with `React.createElement`
- * only, and the runtime-layer rule says that
- * pair is twinned on purpose. ⛔ **What it also says is that only the RENDERING
- * is twinned — "pure data → L1, one home" — and two pure helpers had been
- * dragged across the seam with it**: a base-path joiner and a colour-opacity
- * converter, byte-identical in both files.
+ * Backgrounds were an L3 pair until 2026-10-25: `components/Background.jsx`
+ * rendered for the browser and `ssr-renderer.js` with `React.createElement`
+ * only. ⛔ **Only the RENDERING was ever meant to be twinned — "pure data →
+ * L1, one home" — and two pure helpers had been dragged across the seam with
+ * it**: a base-path joiner and a colour-opacity converter, byte-identical in
+ * both files. The rendering is one copy now too (`background.js`: it needs no
+ * hooks or DOM); these stay apart from it because they are not rendering.
  *
  * ⚠️ **And the copies had already drifted from the rule they were copying.**
  * The base-path joiner is `@uniweb/core`'s `applyBasePath`, whose own docblock
@@ -59,9 +59,15 @@ export function siteUrl(url) {
 export function withOpacity(color, opacity) {
   if (typeof color !== 'string' || !color) return color
   if (color.startsWith('#')) {
-    const r = parseInt(color.slice(1, 3), 16)
-    const g = parseInt(color.slice(3, 5), 16)
-    const b = parseInt(color.slice(5, 7), 16)
+    // `#rgb` and `#rgba` are written out first; an alpha pair is replaced by `opacity`.
+    // ⛔ Until 2026-10-25 every hex was read as six digits, so `#000` gave `rgba(0, 0, NaN, …)`,
+    // and a gradient using it was invalid CSS that drew nothing.
+    let hex = color.slice(1)
+    if (hex.length === 3 || hex.length === 4) hex = [...hex].map((c) => c + c).join('')
+    if (!/^[0-9a-f]{6}([0-9a-f]{2})?$/i.test(hex)) return color
+    const r = parseInt(hex.slice(0, 2), 16)
+    const g = parseInt(hex.slice(2, 4), 16)
+    const b = parseInt(hex.slice(4, 6), 16)
     return `rgba(${r}, ${g}, ${b}, ${opacity})`
   }
   if (color.startsWith('rgb')) {

package/src/background.js

@@ -0,0 +1,182 @@
+/**
+ * A section's background — the layer the runtime draws behind a section's content: a color, a
+ * gradient, an image or a video, under an optional overlay. It reads `block.background`, which core
+ * normalizes once (`Block.normalizeBackground`).
+ *
+ * ⭐ ONE COPY, FOR BOTH RENDERERS: the browser's (`components/Background.jsx`) and the prerender's
+ * (`ssr-renderer.js`, behind `uniweb build` and a host's prerender alike). It needs no hooks, no
+ * Router and no DOM, so it is written with `createElement` and both draw it — the L3 twins exist for
+ * code that needs those (`default-layout.js` is the same rule).
+ * ⛔ Until 2026-10-25 each renderer wrote its own, and they had drifted: the prerender read an
+ * overlay's `angle: 0` and `endPosition: 0` as unset (`||`), drew no video background at all, and
+ * dropped the `className` kit's `SectionBackground` passes. Each showed as the page changing when
+ * the browser rendered it in place of the prerendered one. Pinned by `tests/page-parity.test.js`.
+ *
+ * ⭐ A VIDEO IS ITS POSTER UNTIL THE BROWSER HAS MOUNTED IT. Both renderers draw the poster
+ * (`VideoPoster`); the browser then swaps in the playing `<video>` (`components/Background.jsx`),
+ * unless the visitor prefers reduced motion and there is a poster to keep (`videoMoves`). That
+ * preference is the one thing here that needs the DOM, so it is read in an effect, never in the first
+ * render: read there, it made the browser's first render differ from the prerendered page for exactly
+ * those visitors.
+ *
+ * ⭐ An unset value is `undefined` or `null`, never a falsy one: `0` is an angle, a position and an
+ * opacity like any other (`??`, not `||`).
+ */
+
+import React from 'react'
+import { siteUrl, withOpacity } from './background-shared.js'
+
+const h = React.createElement
+
+/** The box every layer fills: the section's, behind its content (`BlockRenderer.jsx`). */
+const FILL = { position: 'absolute', inset: 0 }
+
+function ColorLayer({ color }) {
+  if (!color) return null
+  return h('div', { className: 'background-color', style: { ...FILL, backgroundColor: color }, 'aria-hidden': 'true' })
+}
+
+function GradientLayer({ gradient }) {
+  if (!gradient) return null
+
+  // A CSS gradient as written ("linear-gradient(to bottom, #000, #333)")
+  if (typeof gradient === 'string') {
+    return h('div', { className: 'background-gradient', style: { ...FILL, background: gradient }, 'aria-hidden': 'true' })
+  }
+
+  const start = gradient.start ?? 'transparent'
+  const end = gradient.end ?? 'transparent'
+  const startOpacity = gradient.startOpacity ?? 1
+  const endOpacity = gradient.endOpacity ?? 1
+  const startColor = startOpacity < 1 ? withOpacity(start, startOpacity) : start
+  const endColor = endOpacity < 1 ? withOpacity(end, endOpacity) : end
+  const background =
+    `linear-gradient(${gradient.angle ?? 0}deg, ` +
+    `${startColor} ${gradient.startPosition ?? 0}%, ${endColor} ${gradient.endPosition ?? 100}%)`
+
+  return h('div', { className: 'background-gradient', style: { ...FILL, background }, 'aria-hidden': 'true' })
+}
+
+function ImageLayer({ image }) {
+  if (!image?.src) return null
+  const style = {
+    ...FILL,
+    backgroundImage: `url(${siteUrl(image.src)})`,
+    backgroundPosition: image.position ?? 'center',
+    backgroundSize: image.size ?? 'cover',
+    backgroundRepeat: 'no-repeat',
+  }
+  return h('div', { className: 'background-image', style, 'aria-hidden': 'true' })
+}
+
+/**
+ * A video background as both renderers first draw it: its poster, as an image layer — or nothing,
+ * when it has none. The browser replaces it with `VideoElement` once mounted.
+ */
+export function VideoPoster({ video }) {
+  if (!video?.src || !video.poster) return null
+  return h(ImageLayer, { image: { src: video.poster, size: 'cover', position: 'center' } })
+}
+
+/**
+ * Whether a mounted video background plays: always, unless the visitor prefers reduced motion and
+ * there is a poster to show instead.
+ *
+ * @param {Object} video - `background.video`
+ * @param {boolean} reducedMotion - the visitor's `prefers-reduced-motion`
+ * @returns {boolean}
+ */
+export function videoMoves(video, reducedMotion) {
+  if (!video?.src) return false
+  return !(reducedMotion && video.poster)
+}
+
+/** The playing video, which only the browser draws, once mounted (`components/Background.jsx`). */
+export function VideoElement({ video }) {
+  if (!video?.src) return null
+  const sources = (video.sources || inferSources(video.src)).map((s) => ({ ...s, src: siteUrl(s.src) }))
+  return h(
+    'video',
+    {
+      className: 'background-video',
+      style: { ...FILL, width: '100%', height: '100%', objectFit: 'cover' },
+      autoPlay: true,
+      loop: video.loop ?? true,
+      muted: video.muted ?? true,
+      playsInline: true,
+      poster: siteUrl(video.poster),
+      'aria-hidden': 'true',
+    },
+    sources.map(({ src, type }, index) => h('source', { key: index, src, type })),
+  )
+}
+
+/**
+ * The formats to offer for a single `src`: an `.mp4` is offered as `.webm` first (better
+ * compression), and the reverse; the browser plays the first it supports.
+ */
+function inferSources(src) {
+  const ext = src.split('.').pop()?.toLowerCase()
+  const base = src.slice(0, src.lastIndexOf('.'))
+  if (ext === 'mp4') return [{ src: `${base}.webm`, type: 'video/webm' }, { src, type: 'video/mp4' }]
+  if (ext === 'webm') return [{ src, type: 'video/webm' }, { src: `${base}.mp4`, type: 'video/mp4' }]
+  const type = src.endsWith('.ogg') || src.endsWith('.ogv') ? 'video/ogg' : 'video/mp4'
+  return [{ src, type }]
+}
+
+function Overlay({ overlay }) {
+  if (!overlay?.enabled) return null
+  const opacity = overlay.opacity ?? 0.5
+
+  if (overlay.gradient) {
+    const g = overlay.gradient
+    const 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}%)`
+    return h('div', {
+      className: 'background-overlay background-overlay--gradient',
+      style: { ...FILL, background, opacity, pointerEvents: 'none' },
+      'aria-hidden': 'true',
+    })
+  }
+
+  const base = overlay.type === 'light' ? '255, 255, 255' : '0, 0, 0'
+  return h('div', {
+    className: 'background-overlay background-overlay--solid',
+    style: { ...FILL, backgroundColor: `rgba(${base}, ${opacity})`, pointerEvents: 'none' },
+    'aria-hidden': 'true',
+  })
+}
+
+/**
+ * The background layer: `block.background`'s fields, and a `className` for the layer (kit's
+ * `SectionBackground` passes one).
+ *
+ * @param {Object} props
+ * @param {string} props.mode - 'color' | 'gradient' | 'image' | 'video'; nothing is drawn without one
+ * @param {string} [props.color]
+ * @param {string|Object} [props.gradient]
+ * @param {Object} [props.image]
+ * @param {Object} [props.video]
+ * @param {Object} [props.overlay]
+ * @param {string} [props.className]
+ * @param {Function} [props.Video] - how a video background is drawn: its poster (the default, and the
+ *   prerender's), or the browser's, which plays it once mounted
+ * @returns {React.ReactElement|null}
+ */
+export function Background({ mode, color, gradient, image, video, overlay, className = '', Video = VideoPoster }) {
+  if (!mode) return null
+  return h(
+    'div',
+    {
+      className: `background background--${mode} ${className}`.trim(),
+      style: { ...FILL, overflow: 'hidden', zIndex: 0 },
+      'aria-hidden': 'true',
+    },
+    mode === 'color' ? h(ColorLayer, { color }) : null,
+    mode === 'gradient' ? h(GradientLayer, { gradient }) : null,
+    mode === 'image' ? h(ImageLayer, { image }) : null,
+    mode === 'video' ? h(Video, { video }) : null,
+    h(Overlay, { overlay }),
+  )
+}

package/src/collect-records.js

@@ -48,6 +48,7 @@
 import { resolveFetchConfigs } from '@uniweb/core/fetch-config'
 import { resolveRecordsService } from '@uniweb/core/records-service'
 import { createDefaultFetcher } from './default-fetcher.js'
+import { requireTransport } from './require-transport.js'
 
 /**
  * Ask a site's records service for every record its declared queries return.
@@ -56,7 +57,8 @@ import { createDefaultFetcher } from './default-fetcher.js'
  * @param {Object} options
  * @param {string} options.locale - the locale to ask in; it is a route segment
  *   of the service's address, so there is no asking without one
- * @param {Function} options.fetch - the transport, `(url, init) => Response`
+ * @param {Function} options.fetch - the transport, `(url, init) => Response`. Required: a missing
+ *   one is refused, never replaced by the ambient `fetch` (`require-transport.js`)
  * @param {AbortSignal} [options.signal]
  * @param {string[]} [options.only] - restrict to these query names
  * @param {boolean} [options.whole=false] - what to ask for. `false` is the brief a
@@ -84,6 +86,10 @@ export async function collectSiteRecords(
   content,
   { locale, fetch, signal, only = null, whole = false, maxPages } = {},
 ) {
+  // ⛔ Before the empties below: those are states of a site, while a lost transport is the caller's
+  // wiring, and a site with no live records must not hide it.
+  requireTransport(fetch, 'collectSiteRecords')
+
   const config = content?.config
   const services = config?.services ?? null
   const queries = config?.queries ?? null

package/src/components/Background.jsx

@@ -1,311 +1,36 @@
 /**
  * Background
  *
- * Renders section backgrounds (color, gradient, image, video) with optional overlay.
- * Positioned absolutely behind content with proper z-index stacking.
- *
- * @module @uniweb/runtime/components/Background
- */
-
-import React from 'react'
-import { siteUrl, withOpacity } from '../background-shared.js'
-
-/**
- * Background modes
- */
-const MODES = {
-  COLOR: 'color',
-  GRADIENT: 'gradient',
-  IMAGE: 'image',
-  VIDEO: 'video',
-}
-
-/**
- * Default overlay colors
- */
-const OVERLAY_COLORS = {
-  light: 'rgba(255, 255, 255, 0.5)',
-  dark: 'rgba(0, 0, 0, 0.5)',
-}
-
-/**
- * Render gradient overlay
- */
-function GradientOverlay({ gradient, opacity = 0.5 }) {
-  const {
-    start = 'rgba(0,0,0,0.7)',
-    end = 'rgba(0,0,0,0)',
-    angle = 180,
-    startPosition = 0,
-    endPosition = 100,
-  } = gradient
-
-  const style = {
-    position: 'absolute',
-    inset: 0,
-    background: `linear-gradient(${angle}deg, ${start} ${startPosition}%, ${end} ${endPosition}%)`,
-    opacity,
-    pointerEvents: 'none',
-  }
-
-  return <div className="background-overlay background-overlay--gradient" style={style} aria-hidden="true" />
-}
-
-/**
- * Render solid overlay
- */
-function SolidOverlay({ type = 'dark', opacity = 0.5 }) {
-  const baseColor = type === 'light' ? '255, 255, 255' : '0, 0, 0'
-
-  const style = {
-    position: 'absolute',
-    inset: 0,
-    backgroundColor: `rgba(${baseColor}, ${opacity})`,
-    pointerEvents: 'none',
-  }
-
-  return <div className="background-overlay background-overlay--solid" style={style} aria-hidden="true" />
-}
-
-/**
- * Render overlay (gradient or solid)
- */
-function Overlay({ overlay }) {
-  if (!overlay?.enabled) return null
-
-  if (overlay.gradient) {
-    return <GradientOverlay gradient={overlay.gradient} opacity={overlay.opacity} />
-  }
-
-  return <SolidOverlay type={overlay.type} opacity={overlay.opacity} />
-}
-
-/**
- * Color background
- */
-function ColorBackground({ color }) {
-  if (!color) return null
-
-  const style = {
-    position: 'absolute',
-    inset: 0,
-    backgroundColor: color,
-  }
-
-  return <div className="background-color" style={style} aria-hidden="true" />
-}
-
-/**
- * Gradient background
- */
-function GradientBackground({ gradient }) {
-  if (!gradient) return null
-
-  // Raw CSS gradient string (e.g., "linear-gradient(to bottom, #000, #333)")
-  if (typeof gradient === 'string') {
-    const style = { position: 'absolute', inset: 0, background: gradient }
-    return <div className="background-gradient" style={style} aria-hidden="true" />
-  }
-
-  const {
-    start = 'transparent',
-    end = 'transparent',
-    angle = 0,
-    startPosition = 0,
-    endPosition = 100,
-    startOpacity = 1,
-    endOpacity = 1,
-  } = gradient
-
-  // Convert colors to rgba if opacity is specified
-  const startColor = startOpacity < 1 ? withOpacity(start, startOpacity) : start
-  const endColor = endOpacity < 1 ? withOpacity(end, endOpacity) : end
-
-  const style = {
-    position: 'absolute',
-    inset: 0,
-    background: `linear-gradient(${angle}deg, ${startColor} ${startPosition}%, ${endColor} ${endPosition}%)`,
-  }
-
-  return <div className="background-gradient" style={style} aria-hidden="true" />
-}
-
-/**
- * Image background
+ * A section's background in the browser: the one the prerender draws (`../background.js`, one copy
+ * for both renderers), plus the one thing only a browser does — playing a video background once it
+ * has mounted.
  */
-function ImageBackground({ image }) {
-  if (!image?.src) return null
-
-  const {
-    src,
-    position = 'center',
-    size = 'cover',
-    lazy = true,
-  } = image
-
-  const style = {
-    position: 'absolute',
-    inset: 0,
-    backgroundImage: `url(${siteUrl(src)})`,
-    backgroundPosition: position,
-    backgroundSize: size,
-    backgroundRepeat: 'no-repeat',
-  }
 
-  // For lazy loading, we could use an img tag with loading="lazy"
-  // But for backgrounds, CSS is more appropriate
-  // The lazy prop could be used for future intersection observer optimization
+import React, { useEffect, useState } from 'react'
+import { Background as Layer, VideoPoster, VideoElement, videoMoves } from '../background.js'
 
-  return <div className="background-image" style={style} aria-hidden="true" />
-}
-
-/**
- * Check if user prefers reduced motion
- */
+/** The visitor's `prefers-reduced-motion`; false where it cannot be read (old webviews, no DOM). */
 function prefersReducedMotion() {
-  if (typeof window === 'undefined') return false
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false
   return window.matchMedia('(prefers-reduced-motion: reduce)').matches
 }
 
 /**
- * Video background
- *
- * Supports multiple source formats with automatic fallback.
- * Respects prefers-reduced-motion by showing poster image instead.
- */
-function VideoBackground({ video }) {
-  if (!video?.src) return null
-
-  const {
-    src,
-    sources,      // Array of { src, type } for multiple formats
-    poster,
-    loop = true,
-    muted = true,
-  } = video
-
-  // Respect reduced motion preference - show poster image instead
-  if (prefersReducedMotion() && poster) {
-    return <ImageBackground image={{ src: poster, size: 'cover', position: 'center' }} />
-  }
-
-  const style = {
-    position: 'absolute',
-    inset: 0,
-    width: '100%',
-    height: '100%',
-    objectFit: 'cover',
-  }
-
-  // Build source list: explicit sources array, or infer from src
-  const sourceList = (sources || inferSources(src)).map(s => ({
-    ...s,
-    src: siteUrl(s.src)
-  }))
-
-  return (
-    <video
-      className="background-video"
-      style={style}
-      autoPlay
-      loop={loop}
-      muted={muted}
-      playsInline
-      poster={siteUrl(poster)}
-      aria-hidden="true"
-    >
-      {sourceList.map(({ src: sourceSrc, type }, index) => (
-        <source key={index} src={sourceSrc} type={type} />
-      ))}
-    </video>
-  )
-}
-
-/**
- * Infer multiple source formats from a single src
- *
- * If given "video.mp4", also tries "video.webm" (better compression)
- * Browser will use first supported format
+ * A video background: its poster first — the prerendered page's, so the render that replaces that
+ * page draws the same — and the playing video once mounted (`videoMoves`).
  */
-function inferSources(src) {
-  const sources = []
-  const ext = src.split('.').pop()?.toLowerCase()
-  const basePath = src.slice(0, src.lastIndexOf('.'))
-
-  // Prefer webm (better compression), fall back to original
-  if (ext === 'mp4') {
-    sources.push({ src: `${basePath}.webm`, type: 'video/webm' })
-    sources.push({ src, type: 'video/mp4' })
-  } else if (ext === 'webm') {
-    sources.push({ src, type: 'video/webm' })
-    sources.push({ src: `${basePath}.mp4`, type: 'video/mp4' })
-  } else {
-    // Single source for other formats
-    sources.push({ src, type: getVideoMimeType(src) })
-  }
-
-  return sources
+function MovingVideo({ video }) {
+  const [moving, setMoving] = useState(false)
+  useEffect(() => {
+    setMoving(videoMoves(video, prefersReducedMotion()))
+  }, [video])
+  return moving ? <VideoElement video={video} /> : <VideoPoster video={video} />
 }
 
 /**
- * Get video MIME type from URL
+ * @param {Object} props - `block.background`'s fields (`mode`, `color`, `gradient`, `image`, `video`,
+ *   `overlay`), and a `className` for the layer
  */
-function getVideoMimeType(src) {
-  if (src.endsWith('.webm')) return 'video/webm'
-  if (src.endsWith('.ogg') || src.endsWith('.ogv')) return 'video/ogg'
-  return 'video/mp4'
+export default function Background(props) {
+  return <Layer {...props} Video={MovingVideo} />
 }
-
-/**
- * Background component
- *
- * @param {Object} props
- * @param {string} props.mode - Background mode: 'color', 'gradient', 'image', 'video'
- * @param {string} props.color - Color value (for color mode)
- * @param {Object} props.gradient - Gradient configuration
- * @param {Object} props.image - Image configuration
- * @param {Object} props.video - Video configuration
- * @param {Object} props.overlay - Overlay configuration
- * @param {string} props.className - Additional CSS class
- */
-export default function Background({
-  mode,
-  color,
-  gradient,
-  image,
-  video,
-  overlay,
-  className = '',
-}) {
-  // No background to render
-  if (!mode) return null
-
-  const containerStyle = {
-    position: 'absolute',
-    inset: 0,
-    overflow: 'hidden',
-    zIndex: 0,
-  }
-
-  return (
-    <div
-      className={`background background--${mode} ${className}`.trim()}
-      style={containerStyle}
-      aria-hidden="true"
-    >
-      {/* Render background based on mode */}
-      {mode === MODES.COLOR && <ColorBackground color={color} />}
-      {mode === MODES.GRADIENT && <GradientBackground gradient={gradient} />}
-      {mode === MODES.IMAGE && <ImageBackground image={image} />}
-      {mode === MODES.VIDEO && <VideoBackground video={video} />}
-
-      {/* Overlay on top of background */}
-      <Overlay overlay={overlay} />
-    </div>
-  )
-}
-
-/**
- * Export background modes for external use
- */
-export { MODES as BackgroundModes }

package/src/components/BlockRenderer.jsx

@@ -12,6 +12,7 @@ import { prepareProps, getComponentMeta } from '../prepare-props.js'
 import Background from './Background.jsx'
 import { sectionStickyProps, sectionScrollMargin } from '../sticky.js'
 import { noteBodySection } from '../sticky-top.js'
+import { noteSectionWrapper } from '../sticky-check.js'
 
 /**
  * Valid color contexts
@@ -172,8 +173,15 @@ 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 }
-  // 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)
+  // 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
+  if (bodySection || import.meta.env?.DEV) {
+    wrapperProps.ref = (element) => {
+      if (bodySection) noteBodySection(block, element)
+      if (import.meta.env?.DEV) noteSectionWrapper(element)
+    }
+  }
 
   // Merge Component.className (static classes declared on the component function)
   // Order: context-{theme} + block.state.className + Component.className

package/src/components/Layout.jsx

@@ -117,9 +117,10 @@ export default function Layout({ page, website }) {
   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.
+  // layout wraps in an element of its own, a box that clips — measured once the page's data is in.
+  // Dropped from a published page's runtime.
   useEffect(() => {
-    if (import.meta.env?.DEV) return warnUnmovableSticky()
+    if (import.meta.env?.DEV) return warnUnmovableSticky(document, { settled: () => website.dataStore.whenIdle() })
   }, [page])
 
   // Use foundation's custom Layout if provided

package/src/components/PageRenderer.jsx

@@ -246,8 +246,10 @@ export default function PageRenderer() {
     )
   }
 
-  // Wait for content before rendering blocks (split page content).
-  // The prerendered HTML is already visible while we load.
+  // Wait for content before rendering blocks (split page content): reached after an in-app
+  // navigation to a page not loaded yet, and it renders nothing until the sections arrive. Not at
+  // boot — the page a visit starts on carries its own sections (`splitPageSections`) — and never
+  // over the prerendered HTML: the browser's first commit replaces it (`createRoot`, index.jsx).
   if (!contentReady) return null
 
   const appearance = website?.themeData?.appearance

package/src/default-fetcher.js

@@ -70,7 +70,10 @@ import {
  *   fetches outside a browser (an SSR isolate) decides how a site-relative
  *   address is dispatched — through its own origin or a service binding — and
  *   hands that in. Defaults to the global `fetch`, resolved at call time so a
- *   test stub installed later is honoured.
+ *   test stub installed later is honoured. ⛔ The entries a host calls
+ *   (`loadPageData`, `prefetchAndHydrate`, `collectSiteRecords`) never reach this
+ *   default: they refuse a missing transport (`require-transport.js`). It serves
+ *   the browser and a harness that builds its own fetcher.
  * @returns {{ cacheKey: (req: Object) => string, resolve: (req: Object, ctx: Object) => Promise<{ data, error?, meta? }> }}
  */
 export function createDefaultFetcher({ basePath = '', dev = false, fetch: fetchImpl = null } = {}) {