@uniweb/runtime 1.2.7 → 1.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {

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 } 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,44 @@ 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` has content not fetched yet: a site whose content is split. */
+function hasPagesToFetch(website) {
+  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 +187,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 +221,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,75 @@
+/**
+ * Prefetch on intent: a link's page is fetched while the reader is about to follow it.
+ *
+ * Only a site whose content is split loads this module (`useLinkInterceptor`). A site whose
+ * pages all arrived with it 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 the split
+ * content of the page the link goes to. A press fetches it at once, since a touch has no hover.
+ * The click that follows then usually finds the content 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 { prefetchContent } 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 the split content of the page a link goes to, 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
+  prefetchContent(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/navigation.js

@@ -0,0 +1,160 @@
+/**
+ * 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.** 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. So the content is fetched first, while
+ * the current page stays on screen and usable. The router is told once the content has arrived,
+ * or after `CONTENT_PREFETCH_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 is ready. 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.
+ */
+
+/** How long a navigation waits for the next page's content before it goes anyway. */
+const CONTENT_PREFETCH_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` can be shown now: `PageRenderer`'s own test. */
+function isReady(page) {
+  return !page || !page.hasContent() || page.isContentLoaded()
+}
+
+/** The wait for `page`'s split content, bounded by CONTENT_PREFETCH_TIMEOUT; undefined when there is none. */
+function contentOf(page) {
+  if (isReady(page)) return
+  return Promise.race([
+    page.loadContent(),
+    new Promise((resolve) => setTimeout(resolve, CONTENT_PREFETCH_TIMEOUT)),
+  ])
+}
+
+/**
+ * Fetch the split content of the page `route` names, giving up after CONTENT_PREFETCH_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) {
+  return contentOf(pageAt(route))
+}
+
+// The navigation the next swap belongs to. A later navigation supersedes one still waiting for
+// its content, 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 is 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 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 = contentOf(page)
+  // A fetch that fails still navigates: the page then shows what its content answered.
+  if (pending) 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/setup.js

@@ -31,6 +31,7 @@ import {
 import { ChildBlocks } from './components/PageRenderer.jsx'
 import Background from './components/Background.jsx'
 import { wireFoundationCapabilities, hydrateDataStore, ensureThemeCss } from './wire-foundation.js'
+import { navigateInApp } from './navigation.js'
 
 // Re-export so existing consumers importing hydrateDataStore from
 // setup.js keep working. The implementation moved to wire-foundation.js
@@ -38,56 +39,18 @@ import { wireFoundationCapabilities, hydrateDataStore, ensureThemeCss } from './
 // without dragging react-dom/server into the SPA bundle.
 export { hydrateDataStore }
 
-// ─── View Transition Wrappers ───────────────────────────────────────────────
-//
-// When the foundation enables viewTransitions, navigation is wrapped in
-// document.startViewTransition() to animate page changes. Split content
-// is prefetched inside the transition callback so the user never sees
-// a blank or loading state.
+// `@uniweb/runtime/setup` has exported these since view transitions landed. They live with the
+// navigation that uses them now.
+export { prefetchContent, prefersReducedMotion } from './navigation.js'
 
-/**
- * Prefetch split page content with a timeout.
- * Resolves when content is loaded or the timeout expires — whichever
- * comes first. This keeps the old-page screenshot from freezing too
- * long on slow connections. If the timeout wins, navigation proceeds
- * and the PageRenderer loading gate handles the rest.
- */
-const CONTENT_PREFETCH_TIMEOUT = 1000
-export const prefersReducedMotion =
-  typeof window !== 'undefined'
-  && window.matchMedia('(prefers-reduced-motion: reduce)').matches
-
-export function prefetchContent(route) {
-  const website = globalThis.uniweb?.activeWebsite
-  if (!route || !website) return
-
-  const targetPage = website.getPage(route)
-  if (!targetPage?.hasContent?.() || targetPage.isContentLoaded?.()) return
-
-  return Promise.race([
-    targetPage.loadContent(),
-    new Promise((resolve) => setTimeout(resolve, CONTENT_PREFETCH_TIMEOUT)),
-  ])
-}
-
-/**
- * Prefetch split content and navigate inside a view transition.
- * Falls back to plain navigation when transitions are not available.
- */
-function navigateWithTransition(navigate, to, options) {
-  const vt = globalThis.uniweb?.foundationConfig?.viewTransitions
-  if (vt && document.startViewTransition && !prefersReducedMotion) {
-    document.startViewTransition(async () => {
-      const route = typeof to === 'string' ? to : to?.pathname
-      await prefetchContent(route)
-      navigate(to, options)
-    })
-  } else {
-    navigate(to, options)
-  }
-}
+// ─── In-app navigation ──────────────────────────────────────────────────────
+//
+// Kit's <Link> and useRouting().useNavigate() reach the router through these, so every
+// navigation they make goes through `navigateInApp` (`navigation.js`): the current page is
+// held until the next one's content is here, and the swap is animated when view transitions
+// apply.
 
-const ViewTransitionLink = React.forwardRef(function ViewTransitionLink(
+const InAppLink = React.forwardRef(function InAppLink(
   { onClick, replace, state, preventScrollReset, ...props },
   ref,
 ) {
@@ -98,12 +61,13 @@ const ViewTransitionLink = React.forwardRef(function ViewTransitionLink(
     if (e.defaultPrevented) return
     if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return
     if (e.button !== 0) return
-
-    const vt = globalThis.uniweb?.foundationConfig?.viewTransitions
-    if (!vt || !document.startViewTransition || prefersReducedMotion) return
+    // Another tab or frame is the browser's to open. Kit passes a link's `target` on.
+    if (props.target && props.target !== '_self') return
 
     e.preventDefault()
-    navigateWithTransition(navigate, props.to, { replace, state, preventScrollReset })
+    // A link to the page already shown replaces its history entry, as React Router's own does.
+    const here = e.currentTarget.href === window.location.href
+    navigateInApp(navigate, props.to, { replace: replace ?? here, state, preventScrollReset })
   }
 
   return React.createElement(RouterLink, {
@@ -116,13 +80,10 @@ const ViewTransitionLink = React.forwardRef(function ViewTransitionLink(
   })
 })
 
-/**
- * View-transition-aware useNavigate hook.
- * The returned function wraps navigation in startViewTransition() when enabled.
- */
+/** React Router's `useNavigate`, its navigations made through `navigateInApp`. */
 function useNavigate() {
   const navigate = useRouterNavigate()
-  return (to, options) => navigateWithTransition(navigate, to, options)
+  return (to, options) => navigateInApp(navigate, to, options)
 }
 
 /**
@@ -130,7 +91,7 @@ function useNavigate() {
  * its own when it wraps DynamicApp in a MemoryRouter.
  */
 const DEFAULT_ROUTING_COMPONENTS = {
-  Link: ViewTransitionLink,
+  Link: InAppLink,
   useNavigate,
   useParams,
   useLocation,