@uniweb/runtime 1.2.7 → 1.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@uniweb/core": "~1.4.10",
+    "@uniweb/core": "~1.4.11",
     "@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.10.8"
+    "@uniweb/build": "1.10.10"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/components/PageRenderer.jsx

@@ -6,12 +6,13 @@
  * Manages head meta tags for SEO and social sharing.
  */
 
-import React, { useMemo, useEffect, useReducer, useRef } from 'react'
+import React, { useMemo, useEffect, useLayoutEffect, useReducer, useRef } from 'react'
 import { useLocation, useNavigate } from 'react-router-dom'
 import BlockRenderer from './BlockRenderer.jsx'
 import Layout from './Layout.jsx'
 import { useHeadMeta } from '../hooks/useHeadMeta.js'
 import { useSectionViews } from '../hooks/useSectionViews.js'
+import { pageCommitted } from '../navigation.js'
 import { buildSectionOverrides } from '@uniweb/theming'
 import { carryQuery } from '@uniweb/core/resolve-route'
 import { Default404 } from '../default-404.js'
@@ -206,6 +207,10 @@ export default function PageRenderer() {
 
   useHeadMeta(headMeta, { siteName })
 
+  // ⭐ The DOM holds the page the router committed, and the browser has not painted it yet. A view
+  // transition waiting on the navigation may capture it now (`navigation.js`).
+  useLayoutEffect(() => { pageCommitted() }, [location])
+
   // For dynamic pages created before collection data was available (hard reload),
   // the page title starts as the template name (e.g. '[id]'). Subscribe to
   // DataStore updates so we re-render once the collection loads — _createDynamicPage
@@ -246,10 +251,12 @@ export default function PageRenderer() {
     )
   }
 
-  // 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).
+  // Wait for content before rendering blocks (split page content); nothing renders until the
+  // sections arrive. An in-app navigation waits for them before it reaches here
+  // (`navigation.js`), so this is the fallback: content slower than that wait, or a navigation made
+  // around the runtime's. 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/hooks/useLinkInterceptor.js

@@ -15,7 +15,7 @@
 import { useEffect, useCallback } from 'react'
 import { useNavigate, useLocation } from 'react-router-dom'
 import { localeOfPath } from '@uniweb/core/resolve-route'
-import { prefetchContent, prefersReducedMotion } from '../setup.js'
+import { navigateInApp, readsData } from '../navigation.js'
 
 /**
  * Check if a URL is internal (same origin, no external protocol)
@@ -64,7 +64,7 @@ function shouldNavigate(event) {
  * @param {EventTarget} target - The event target
  * @returns {HTMLAnchorElement|null}
  */
-function findAnchorElement(target) {
+export function findAnchorElement(target) {
   let element = target
   while (element && element !== document.body) {
     if (element.tagName === 'A') {
@@ -75,6 +75,48 @@ function findAnchorElement(target) {
   return null
 }
 
+/**
+ * A link the runtime may route, or null: an anchor whose href stays on this site, downloads
+ * nothing and opens in this tab.
+ *
+ * `routeHref` is where the browser would go, as a path: the href resolved against this page's
+ * URL, so a query (`?tab=2`) or a relative href (`about`) is judged like any other path. The base
+ * path comes off, because React Router and locale detection work with router-relative paths (a
+ * <Link reload> carries the base).
+ *
+ * ⛔ Until 2026-10-24 an href that was not a path counted as the default locale's, so on any
+ * other locale's page it was a page load: a query or a relative link reloaded the page, and left
+ * an editor's preview frame.
+ *
+ * @param {HTMLAnchorElement|null} anchor
+ * @returns {{ anchor: HTMLAnchorElement, href: string, routeHref: string, website: Object }|null}
+ */
+export function inAppLink(anchor) {
+  const href = anchor?.getAttribute('href')
+  if (!href || !isInternalLink(href)) return null
+  if (anchor.hasAttribute('download')) return null
+  const target = anchor.getAttribute('target')
+  if (target && target !== '_self') return null
+
+  const website = globalThis.uniweb?.activeWebsite
+  const basePath = website?.basePath || ''
+  const resolved = new URL(href, window.location.href)
+  let routeHref = resolved.pathname + resolved.search + resolved.hash
+  if (basePath && routeHref.startsWith(basePath)) {
+    routeHref = routeHref.slice(basePath.length) || '/'
+  }
+  return { anchor, href, routeHref, website }
+}
+
+/**
+ * Whether a page of `website` can have something to fetch before it is shown: content not here
+ * yet, on a site whose content is split, or data, which a site declaring queries reads.
+ */
+function hasPagesToFetch(website) {
+  if (readsData(website)) return true
+  return !!website?.pages?.some((page) => page.hasContent() && !page.isContentLoaded())
+}
+
 /**
  * The locale and page a link goes to when it leaves the active locale, or null.
  *
@@ -149,40 +191,9 @@ export function useLinkInterceptor(options = {}) {
       // Check if we should handle this click
       if (!shouldNavigate(event)) return
 
-      // Find the anchor element
-      const anchor = findAnchorElement(event.target)
-      if (!anchor) return
-
-      // Get the href
-      const href = anchor.getAttribute('href')
-      if (!href) return
-
-      // Check if it's an internal link
-      if (!isInternalLink(href)) return
-
-      // Check for download attribute
-      if (anchor.hasAttribute('download')) return
-
-      // Check for target="_blank" or other non-self targets
-      const target = anchor.getAttribute('target')
-      if (target && target !== '_self') return
-
-      const website = globalThis.uniweb?.activeWebsite
-      const basePath = website?.basePath || ''
-
-      // Where the browser would go, as a path: the href resolved against this page's URL, so
-      // a query (`?tab=2`) or a relative href (`about`) is judged like any other path. The
-      // base path comes off, because React Router and locale detection work with
-      // router-relative paths (a <Link reload> carries the base).
-      //
-      // ⛔ Until 2026-10-24 an href that was not a path counted as the default locale's, so
-      // on any other locale's page it was a page load: a query or a relative link reloaded
-      // the page, and left an editor's preview frame.
-      const resolved = new URL(href, window.location.href)
-      let routeHref = resolved.pathname + resolved.search + resolved.hash
-      if (basePath && routeHref.startsWith(basePath)) {
-        routeHref = routeHref.slice(basePath.length) || '/'
-      }
+      const link = inAppLink(findAnchorElement(event.target))
+      if (!link) return
+      const { anchor, href, routeHref, website } = link
 
       // A link to another locale's page is a page load, since that locale is its own document,
       // and the browser makes it. A host that switches locale its own way (`uniweb.localeSwitch`:
@@ -214,27 +225,33 @@ export function useLinkInterceptor(options = {}) {
         return
       }
 
-      // Use React Router navigation (with router-relative path)
-      // React Router will handle the path, and our useEffect above
-      // will handle scrolling to hash after navigation completes
-      const useTransition = website?.viewTransitions && document.startViewTransition
-        && !prefersReducedMotion
-
-      if (useTransition) {
-        document.startViewTransition(async () => {
-          await prefetchContent(routeHref)
-          navigate(routeHref)
-        })
-      } else {
-        navigate(routeHref)
-      }
+      // React Router takes the router-relative path, and the effect above scrolls to a fragment
+      // once the page is there. Like a <Link>, the click holds this page until the next one's
+      // content has arrived, and the swap is animated when view transitions apply (`navigation.js`).
+      navigateInApp(navigate, routeHref)
     }
 
-    // Add click listener to document
     document.addEventListener('click', handleClick)
 
+    // ⭐ A page is fetched while the reader is about to follow a link to it (`link-intent.js`),
+    // on a site with pages still to fetch. A site whose pages all came with it never downloads
+    // that module. `cancelled` covers an effect torn down before the module arrives.
+    let cancelled = false
+    let stopIntent = null
+    if (hasPagesToFetch(globalThis.uniweb?.activeWebsite)) {
+      import('../link-intent.js')
+        .then((m) => {
+          if (!cancelled) stopIntent = m.watchLinkIntent()
+        })
+        .catch(() => {
+          // Without it, a click still holds the page until its content arrives.
+        })
+    }
+
     return () => {
       document.removeEventListener('click', handleClick)
+      cancelled = true
+      if (stopIntent) stopIntent()
     }
   }, [enabled, navigate])
 }

package/src/link-intent.js

@@ -0,0 +1,77 @@
+/**
+ * Prefetch on intent: a link's page is fetched while the reader is about to follow it.
+ *
+ * Only a site with something to fetch before a page is shown loads this module
+ * (`useLinkInterceptor`): split content not here yet, or data, which a site declaring queries
+ * reads. A site with neither never downloads it, so the runtime every site carries pays only for
+ * the decision.
+ *
+ * A pointer resting on a link, or focus staying on one, for INTENT_DELAY fetches what the page
+ * the link goes to will read: its split content, then its sections' data, whatever is not held
+ * already. A press fetches it at once, since a touch has no hover. The click that follows then
+ * usually finds it all here, and the page changes without waiting (`navigation.js`). A pointer
+ * sweeping across a rail of links fetches nothing, and nothing is fetched for a connection that
+ * asks to save data.
+ */
+
+import { prefetchPage } from './navigation.js'
+import { findAnchorElement, inAppLink, localeSwitchOf } from './hooks/useLinkInterceptor.js'
+
+/** How long a pointer rests on a link, or focus stays on it, before its page is fetched. */
+const INTENT_DELAY = 65
+
+/**
+ * Fetch what the page a link goes to will read, when a click on it would navigate in the app: not
+ * a fragment on this page, a `<Link reload>`, or a page in another locale.
+ *
+ * @param {HTMLAnchorElement} anchor
+ */
+function prefetchFor(anchor) {
+  const link = inAppLink(anchor)
+  if (!link || link.href.startsWith('#') || anchor.hasAttribute('data-reload')) return
+  if (localeSwitchOf(link.routeHref, link.website)) return
+  prefetchPage(link.routeHref)
+}
+
+/**
+ * Fetch a link's page whenever a reader is about to follow it.
+ *
+ * @returns {() => void} stops watching
+ */
+export function watchLinkIntent() {
+  if (globalThis.navigator?.connection?.saveData) return () => {}
+
+  let intent = null
+
+  const rest = (event) => {
+    const anchor = findAnchorElement(event.target)
+    if (!anchor || anchor === intent?.anchor) return
+    clearTimeout(intent?.timer)
+    intent = { anchor, timer: setTimeout(() => prefetchFor(anchor), INTENT_DELAY) }
+  }
+
+  const leave = (event) => {
+    if (!intent || intent.anchor.contains(event.relatedTarget)) return
+    clearTimeout(intent.timer)
+    intent = null
+  }
+
+  const press = (event) => {
+    const anchor = findAnchorElement(event.target)
+    if (anchor) prefetchFor(anchor)
+  }
+
+  const listeners = [
+    ['pointerover', rest],
+    ['focusin', rest],
+    ['pointerout', leave],
+    ['focusout', leave],
+    ['pointerdown', press],
+  ]
+  for (const [type, listener] of listeners) document.addEventListener(type, listener)
+
+  return () => {
+    for (const [type, listener] of listeners) document.removeEventListener(type, listener)
+    clearTimeout(intent?.timer)
+  }
+}

package/src/load-page-data.js

@@ -27,26 +27,7 @@ import { resolveRequestedPage } from './resolve-page.js'
 import { getComponentMeta } from './prepare-props.js'
 import { createDefaultFetcher } from './default-fetcher.js'
 import { requireTransport } from './require-transport.js'
-
-/**
- * Every block the page's render can reach: its body and the layout areas it uses (the runtime's own
- * layout choice — the page's `layout:`, else the foundation's default, else the site's default set,
- * minus any area the page hides), plus what those blocks hold.
- */
-function blocksOf(page) {
-  const out = []
-  const walk = (list) => {
-    for (const block of list || []) {
-      if (!block) continue
-      out.push(block)
-      walk(block.childBlocks)
-      walk(block.insets)
-    }
-  }
-  walk(page.getBodyBlocks?.() ?? page.bodyBlocks)
-  for (const area of Object.values(page.getLayoutAreas?.() ?? {})) walk(area)
-  return out
-}
+import { blocksOf } from './page-blocks.js'
 
 /**
  * Fetch what one route's render will read.
@@ -136,7 +117,11 @@ export async function loadPageData({ website, route, fetch, dev = false, locale
   const answered = new DataStore()
 
   const recording = {
-    peek: (request, ctx) => dispatcher.peek(request, ctx),
+    // ⭐ What the plan uses without asking (`keyProgram`'s held steps) is what THIS call's own
+    // requests answered, as `peekRecord` is: the page carries every answer its render reads, so
+    // it may use nothing it did not ask for itself — not another page's answer in a cache the
+    // static build shares.
+    peek: (request) => answered.get(deriveCacheKey(request)),
     peekRecord: (id) => answered.getRecord(id),
     dispatch: async (request, ctx) => {
       if (prerender === 'author' && request?.prerender === false) {

package/src/navigation.js

@@ -0,0 +1,229 @@
+/**
+ * In-app navigation: what the runtime does between a click and the next page.
+ *
+ * Every navigation the runtime makes goes through `navigateInApp`. That covers kit's `<Link>` and
+ * `useNavigate()` (the routing components `setup.js` registers) and a link in prose
+ * (`useLinkInterceptor`). It is one function so the two paths cannot decide differently again.
+ *
+ * ⭐ **The current page is held until the next one can be shown, content and data.** On a site
+ * whose content is split, a page not visited yet has no sections until its content file arrives,
+ * and `PageRenderer` renders nothing for its body until then. A section that reads data asks for it
+ * only once it has rendered (`BlockRenderer`), and shows its loading state until the answer arrives.
+ * So both are asked first, while the current page stays on screen and usable:
+ * - the content;
+ * - then, its sections known, what they will read, by the plan their render runs (`EntityStore`).
+ *
+ * Only what is not held is asked. A block the cache answers already is passed over, and within a
+ * block the dispatcher answers what it holds and joins what is in flight. The router is told once
+ * the content and data are here, or after `HOLD_TIMEOUT`. That holds for every visitor: it depends
+ * on neither the View Transitions API nor a motion preference.
+ *
+ * ⭐ **The animation is a layer on the swap.** The swap runs inside
+ * `document.startViewTransition` when four things hold: view transitions are on
+ * (`website.viewTransitions`, on unless the foundation says `false`), the browser has the API,
+ * the visitor has no reduced-motion preference, and the next page's content is here. The update
+ * callback resolves once the router has committed the new page (`nextPageCommit`). React Router
+ * commits a navigation inside `React.startTransition`, after `navigate()` has returned. A callback
+ * that resolved when `navigate()` did had the browser capture the old page as the new one.
+ *
+ * ⛔ **Until 2026-10-27 the two paths decided differently**, and neither held the page right:
+ * - `setup.js` read `foundationConfig.viewTransitions` as an opt-in, which
+ *   `Website#viewTransitions` stopped being on 2026-04-11. So a `<Link>` neither animated nor
+ *   waited for the content, and on a split site its body went blank until the content arrived
+ *   (measured on two docs sites: 160–330 ms).
+ * - A prose link waited inside the transition, with the page frozen, and its callback resolved
+ *   before the commit, so the crossfade went from the old page to itself.
+ * - A route carrying a query or a fragment found no page to wait for (`Website#getPage` takes a
+ *   path).
+ * - A reduced-motion preference skipped the wait along with the animation.
+ *
+ * Later that day the hold took in the page's data. Until then the page was held for its content
+ * alone, and a section reading data showed its loading state after the swap. Measured on a site's
+ * blog: its content was in at 331 ms, its data was asked only after the render, and the list
+ * showed at 582 ms.
+ */
+
+import { getComponentMeta } from './prepare-props.js'
+import { blocksOf } from './page-blocks.js'
+
+/** How long a navigation holds the current page for the next one's content and data. */
+const HOLD_TIMEOUT = 1000
+
+/**
+ * How long a view transition waits for the router to commit. A navigation that commits nothing
+ * then cannot hold the frozen page until the browser gives up on it.
+ */
+const COMMIT_TIMEOUT = 1000
+
+/** Read once, when the runtime loads. */
+export const prefersReducedMotion =
+  typeof window !== 'undefined'
+  && window.matchMedia('(prefers-reduced-motion: reduce)').matches
+
+/**
+ * The page a navigation target names, found by its path: `Website#getPage` takes no query or
+ * fragment, and a docs link names a fragment as often as not.
+ *
+ * @param {string|Object} to - a router path, or `navigate`'s `{ pathname }`
+ * @returns {import('@uniweb/core').Page|null}
+ */
+function pageAt(to) {
+  const website = globalThis.uniweb?.activeWebsite
+  const route = typeof to === 'string' ? to : to?.pathname
+  if (!route || !website) return null
+  return website.getPage(route.split(/[?#]/)[0]) || null
+}
+
+/** Whether `page`'s content can be shown now: `PageRenderer`'s own test. */
+function isReady(page) {
+  return !page || !page.hasContent() || page.isContentLoaded()
+}
+
+/**
+ * Whether the site declares a query. Data comes from a named query (`config.queries`), so a site
+ * that declares none reads none, and its pages are not walked for it.
+ *
+ * @param {Object|null|undefined} website
+ * @returns {boolean}
+ */
+export function readsData(website) {
+  const queries = website?.config?.queries
+  return !!queries && typeof queries === 'object' && Object.keys(queries).length > 0
+}
+
+/**
+ * Ask what `page`'s render will read and the cache does not hold: off a parametric page, the
+ * page's own record, which names it; and each block's data, by the same call the renderer makes
+ * after mount (`EntityStore.fetch`).
+ *
+ * @param {Object} page - its content here
+ * @returns {Promise|undefined} undefined when nothing was asked
+ */
+function dataOf(page) {
+  const website = page.website
+  const store = website?.entityStore
+  if (!store || !readsData(website)) return
+  const asks = []
+  if (page.dynamicContext) asks.push(store.fetchPageRecord(page))
+  for (const block of blocksOf(page)) {
+    const meta = getComponentMeta(block.type)
+    if (store.resolve(block, meta).status === 'pending') asks.push(store.fetch(block, meta))
+  }
+  return asks.length ? Promise.all(asks) : undefined
+}
+
+/**
+ * The wait for what `page`'s render reads and is not here yet: its split content, then, its
+ * sections known, their data.
+ *
+ * @param {Object|null} page
+ * @returns {Promise|undefined} undefined when it is all here
+ */
+function loadPage(page) {
+  if (!page) return
+  if (!isReady(page)) return page.loadContent().then(() => dataOf(page))
+  return dataOf(page)
+}
+
+/** `wait`, or the end of HOLD_TIMEOUT, whichever comes first. */
+function bounded(wait) {
+  return Promise.race([wait, new Promise((resolve) => setTimeout(resolve, HOLD_TIMEOUT))])
+}
+
+/**
+ * Fetch the split content of the page `route` names, giving up after HOLD_TIMEOUT. Undefined when
+ * there is nothing to fetch: no such page, a page with no content, or one already loaded.
+ *
+ * @param {string} route - a router path; a query or fragment is ignored
+ * @returns {Promise|undefined}
+ */
+export function prefetchContent(route) {
+  const page = pageAt(route)
+  if (isReady(page)) return
+  return bounded(page.loadContent())
+}
+
+/**
+ * Fetch what the page `route` names will read when it is shown, its split content and then its
+ * data, ahead of a navigation to it (`link-intent.js`). Nothing waits on it: what arrives is held
+ * for the render, and a request that fails is the navigation's to make again.
+ *
+ * @param {string} route - a router path; a query or fragment is ignored
+ * @returns {Promise|undefined} undefined when it is all here
+ */
+export function prefetchPage(route) {
+  return loadPage(pageAt(route))?.catch(() => {})
+}
+
+// The navigation the next swap belongs to. A later navigation supersedes one still waiting for
+// its page, so a slow page reached by an earlier click cannot replace the page clicked last.
+let latest = 0
+
+/**
+ * Navigate in the app. The current page is held until the next one's content and data are here,
+ * then the pages are swapped, animated when view transitions apply.
+ *
+ * @param {Function} navigate - React Router's `navigate`
+ * @param {string|Object|number} to - where to, as `navigate` takes it
+ * @param {Object} [options] - `navigate`'s options
+ */
+export function navigateInApp(navigate, to, options) {
+  const ticket = ++latest
+  const page = pageAt(to)
+
+  const swap = () => {
+    if (ticket !== latest) return
+    const website = globalThis.uniweb?.activeWebsite
+    // A page whose content is still not here after the wait goes without the animation: a
+    // crossfade to an empty body would only draw out the wait.
+    const animate = isReady(page) && website?.viewTransitions
+      && typeof document !== 'undefined' && document.startViewTransition && !prefersReducedMotion
+    if (!animate) {
+      navigate(to, options)
+      return
+    }
+    const transition = document.startViewTransition(() => {
+      // Asked before navigating: a router that commits synchronously settles it from inside `navigate`.
+      const committed = nextPageCommit()
+      navigate(to, options)
+      return committed
+    })
+    // A transition the browser skips, for a duplicate `view-transition-name` or a newer
+    // transition, still runs its callback, so the page is swapped all the same. The browser
+    // reports the reason itself.
+    transition.ready.catch(() => {})
+  }
+
+  const pending = loadPage(page)
+  // A request that fails still navigates: the page then shows what it has, as it renders it.
+  if (pending) bounded(pending).then(swap, swap)
+  else swap()
+}
+
+const commitWaiters = new Set()
+
+/**
+ * A promise settled when `PageRenderer` next commits a page, or after COMMIT_TIMEOUT.
+ *
+ * @returns {Promise<void>}
+ */
+function nextPageCommit() {
+  return new Promise((resolve) => {
+    const settle = () => {
+      clearTimeout(timer)
+      commitWaiters.delete(settle)
+      resolve()
+    }
+    const timer = setTimeout(settle, COMMIT_TIMEOUT)
+    commitWaiters.add(settle)
+  })
+}
+
+/**
+ * Called by `PageRenderer` from a layout effect, once the DOM holds the page the router
+ * committed and before the browser paints it. That is the moment a view transition may capture
+ * it. It has no SSR twin, since the prerender makes no navigation.
+ */
+export function pageCommitted() {
+  for (const settle of [...commitWaiters]) settle()
+}

package/src/page-blocks.js

@@ -0,0 +1,26 @@
+/**
+ * Every block a page's render can reach: its body and the layout areas it uses (the runtime's own
+ * layout choice — the page's `layout:`, else the foundation's default, else the site's default set,
+ * minus any area the page hides), plus what those blocks hold.
+ *
+ * ⭐ One walk for the two that ask for a page's data before its render: a host's data step
+ * (`load-page-data.js`) and the browser before it shows a page it navigates to (`navigation.js`).
+ * So the two cannot disagree about which blocks a page reaches.
+ *
+ * @param {Object} page - a Page
+ * @returns {Object[]} its blocks, each one once
+ */
+export function blocksOf(page) {
+  const out = []
+  const walk = (list) => {
+    for (const block of list || []) {
+      if (!block) continue
+      out.push(block)
+      walk(block.childBlocks)
+      walk(block.insets)
+    }
+  }
+  walk(page.getBodyBlocks?.() ?? page.bodyBlocks)
+  for (const area of Object.values(page.getLayoutAreas?.() ?? {})) walk(area)
+  return out
+}