@uniweb/runtime 1.3.2 → 1.3.4

package/package.json

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

package/src/carry-animations.js

@@ -0,0 +1,50 @@
+/**
+ * A page's CSS animations carry on across the browser's first render.
+ *
+ * ⭐ The browser renders over a prerendered page rather than hydrating it (`createRoot`, `index.jsx`),
+ * and a CSS animation's clock belongs to its element. So the commit that replaces the page restarts
+ * every animation in it, and a page's first commit usually lands while its entrance is still running:
+ * a hero already on screen would drop back to invisible and play again. `uniweb dev` never prerenders,
+ * so a foundation's author never sees it.
+ *
+ * Each animation of the new page takes as its start the moment the old page was first painted, which
+ * is when its twin started, so it goes on from where its twin was. The observer fires after the commit
+ * and before the browser paints, so no frame shows a restart. It disconnects at that first commit, so
+ * a later navigation is left as it was.
+ *
+ * ⭐ The time of first paint rather than the old animations' own start times, read before the commit:
+ * an animation that has ended with no fill is gone from `getAnimations()`, and its twin would play
+ * again.
+ *
+ * ⛔ Only a running animation on the document's timeline:
+ * - a paused one is waiting for something, like a reveal that starts when its section scrolls into
+ *   view, and setting a start time would start it;
+ * - a scroll-driven one has a timeline of its own, whose time is no moment on this clock.
+ *
+ * It reaches CSS animations alone. One a component starts from JavaScript when it mounts never ran on
+ * the prerendered page: it starts at boot, over whatever that page has shown by then.
+ *
+ * Nothing to carry: an empty root (`uniweb dev`, a page served without a prerender), and a page not
+ * painted yet, whose first render is the first thing a visitor sees. That can include a page painted
+ * a frame ago, which the browser has not reported yet: its animations have hardly begun.
+ *
+ * @param {Element} root - The element React is about to render into.
+ */
+export function carryAnimations(root) {
+  if (!root.firstChild || !document.getAnimations) return
+  new MutationObserver((_, watch) => {
+    watch.disconnect()
+    const painted = performance.getEntriesByName('first-contentful-paint')[0]?.startTime
+    if (painted == null) return
+    for (const animation of document.getAnimations()) {
+      if (
+        animation.animationName &&
+        animation.playState === 'running' &&
+        animation.timeline === document.timeline &&
+        root.contains(animation.effect?.target)
+      ) {
+        animation.startTime = painted
+      }
+    }
+  }).observe(root, { childList: true })
+}

package/src/index.jsx

@@ -12,6 +12,7 @@ import { initUniweb, decodeData } from './setup.js'
 import { wireTracker } from './wire-foundation.js'
 import { loadFoundation, loadExtensions } from './foundation-loader.js'
 import { initAppearance } from './appearance.js'
+import { carryAnimations } from './carry-animations.js'
 import RuntimeProvider from './RuntimeProvider.jsx'
 
 /**
@@ -146,6 +147,8 @@ async function initRuntime(foundationSource, options = {}) {
 
     const app = <RuntimeProvider basename={routerBasename} development={development} />
 
+    // Armed before the render it watches for: the one that replaces a prerendered page.
+    carryAnimations(container)
     createRoot(container).render(app)
 
     // Log success

package/src/load-page-data.js

@@ -28,6 +28,7 @@ import { getComponentMeta } from './prepare-props.js'
 import { createDefaultFetcher } from './default-fetcher.js'
 import { requireTransport } from './require-transport.js'
 import { blocksOf } from './page-blocks.js'
+import { loadPageIcons } from './page-icons.js'
 
 /**
  * Fetch what one route's render will read.
@@ -53,10 +54,15 @@ import { blocksOf } from './page-blocks.js'
  *   fresh, and the default (a cache per call) is what does that. A shared cache changes nothing
  *   about what is ASKED or returned — every request is still recorded, hit or miss, and whether a
  *   record is held whole already is answered from this call's own requests, never the cache's.
+ * @param {boolean} [options.icons] - also ask for the icons the page's content names, and keep them on
+ *   the graph for the render (`page-icons.js`). They are not entries of the list this returns. A
+ *   caller that has its own answer for icons, as a static build does, says `false`.
  * @returns {Promise<Array<{ config: Object, outcome: 'fetched'|'failed'|'skipped', data: *, meta?: Object, error?: string }>>}
- *   one entry per request the render will make, keyed downstream by `deriveCacheKey(config)`
+ *   one entry per request the render will make, keyed downstream by `deriveCacheKey(config)`.
+ *   ⛔ The page's data and nothing else: a host counts this list to decide how long to keep the
+ *   page, so one more entry shortens its life, and one that fails can end it.
  */
-export async function loadPageData({ website, route, fetch, dev = false, locale = null, prerender = 'always', cache = null }) {
+export async function loadPageData({ website, route, fetch, dev = false, locale = null, prerender = 'always', cache = null, icons = true }) {
   if (prerender !== 'author' && prerender !== 'always') {
     throw new Error(`loadPageData: prerender must be 'author' or 'always', got ${JSON.stringify(prerender)}`)
   }
@@ -76,6 +82,7 @@ export async function loadPageData({ website, route, fetch, dev = false, locale
   // through the global, and a host holding several graphs in one isolate has it naming the newest
   // (`Website#makeCurrent`).
   website.makeCurrent()
+  const iconCache = globalThis.uniweb?.iconCache
   const named = typeof route === 'string' ? resolveRequestedPage(website, route) : route
   // ⭐ A route that names no page, or a page served from elsewhere (`resolveRequestedPage`), renders
   // the site's not-found page (`createPageRenderer`), so it is that page's data the render reads.
@@ -142,6 +149,7 @@ export async function loadPageData({ website, route, fetch, dev = false, locale
   }
 
   const store = website.entityStore
+  const blocks = blocksOf(page)
   // ⭐ Every block's first request goes out in the same tick, which is what lets a question door
   // answer a page in one POST. A step that depends on an answer takes a later one, and only its
   // own key waits.
@@ -149,7 +157,8 @@ export async function loadPageData({ website, route, fetch, dev = false, locale
     // The page's own record: asked whether or not a section declares the route key, because the
     // page names itself from it and a URL naming no record is a 404.
     store.fetchPageRecord(page, { dispatcher: recording }),
-    ...blocksOf(page).map((block) => store.fetch(block, getComponentMeta(block.type), { dispatcher: recording })),
+    ...blocks.map((block) => store.fetch(block, getComponentMeta(block.type), { dispatcher: recording })),
+    icons && iconCache && loadPageIcons({ blocks, website, fetch, cache: iconCache }),
   ])
 
   return [...entries.values()]

package/src/page-icons.js

@@ -0,0 +1,136 @@
+/**
+ * A PAGE'S ICONS, IN ITS PRERENDER.
+ *
+ * An icon is a file. On a page a host renders, nothing had fetched it by the time the page was
+ * written, so the page held a blank box in its place until the browser had booted and fetched it:
+ * about a second, on a fast connection (measured 2026-10-30). The render is synchronous and reads an
+ * icon from `uniweb.iconCache` (`getIconSync`, kit's `<Icon>`), so what a page shows has to be there
+ * before it starts, as with its data. Two halves:
+ *
+ * - The data step asks the host's transport for the icons the page's content names, and keeps them
+ *   on the graph (`loadPageIcons`).
+ * - The render door notes which icons it drew (`whileReadingIcons`), and the page carries exactly
+ *   those in `__ICON_CACHE__`, which `setup.js` reads before the browser's first render. The browser
+ *   renders over the prerendered page, so it has to draw what the page drew, or it would blank them.
+ *
+ * ⛔ NOT AN ENTRY OF THE DATA STEP'S LIST. A host counts that list to decide how long to keep the
+ * page: an icon in it would shorten the life of every page holding one, and a failed one could end
+ * it. So nothing here is reported. A host carries nothing new and changes nothing.
+ *
+ * ⚖️ What the walk cannot find: an icon a foundation's own code names, or one in a fetched record.
+ * Those stay as they were, the placeholder and then the browser's fetch. So does any icon that fails
+ * or arrives late, because a page without an icon is a page that still works.
+ *
+ * Renderer-free, as the data step's graph is (`tests/data-step-graph.test.js`), and not in the
+ * browser's bundle: nothing `setup.js` or `index.jsx` imports reaches it.
+ */
+import { DEFAULT_ICON_BASE, ICON_FAMILY_MAP, iconUrl } from '@uniweb/core/icon-corpus'
+
+/** How long a page waits for its icons. Past this it renders without the ones still on their way. */
+export const ICON_WAIT_MS = 1000
+
+/** The most a page asks for in one step, so an icon gallery cannot spend a host's budget of requests. */
+export const MAX_ICON_REQUESTS = 40
+
+/** A reference a link carries as its `icon`: `lu-play` or `lu:play`, as kit's `<Icon>` reads one. */
+function parseIconReference(ref) {
+  if (typeof ref !== 'string') return null
+  const colon = ref.indexOf(':')
+  if (colon > 0) return { library: ref.slice(0, colon), name: ref.slice(colon + 1) }
+  const dash = ref.indexOf('-')
+  if (dash < 2 || dash > 3) return null
+  const library = ref.slice(0, dash)
+  return ICON_FAMILY_MAP[library] ? { library, name: ref.slice(dash + 1) } : null
+}
+
+function visit(node, found) {
+  if (!node || typeof node !== 'object') return
+  if (node.type === 'image' && node.attrs?.role === 'icon') found.push(node.attrs)
+  for (const mark of node.marks || []) {
+    const ref = parseIconReference(mark?.attrs?.icon)
+    if (ref) found.push(ref)
+  }
+  if (Array.isArray(node.content)) for (const child of node.content) visit(child, found)
+}
+
+/**
+ * The icons the content of these blocks names, each once.
+ *
+ * Keyed as `<Icon>` asks for one, by the library and name as written, since that is what
+ * `getIconSync` looks up. The address uses the family's code and the corpus's spelling of the name.
+ *
+ * @param {Object[]} blocks
+ * @returns {Map<string, { family: string, name: string }>}
+ */
+export function pageIcons(blocks) {
+  const named = []
+  for (const block of blocks) visit(block.rawContent?.doc ?? block.rawContent, named)
+  const icons = new Map()
+  for (const { library, name } of named) {
+    const family = ICON_FAMILY_MAP[String(library).toLowerCase()]
+    if (family && name) icons.set(`${library}:${name}`, { family, name })
+  }
+  return icons
+}
+
+/**
+ * Fetch the icons these blocks name through the host's transport, into the graph's icon cache. One a
+ * warm graph holds is not asked for again. Resolves when they are all in, or at `ICON_WAIT_MS`.
+ *
+ * @param {Object} options
+ * @param {Object[]} options.blocks - the page's blocks (`blocksOf`)
+ * @param {Object} options.website - the Website, whose `config.icons` says where the icons are
+ * @param {Function} options.fetch - the transport
+ * @param {Map<string, string>} options.cache - the graph's `iconCache`
+ * @returns {Promise<void>}
+ */
+export async function loadPageIcons({ blocks, website, fetch, cache }) {
+  const config = website.config?.icons
+  if (config?.cdn === false) return
+  const base = config?.base || DEFAULT_ICON_BASE
+  const wanted = [...pageIcons(blocks)].filter(([key]) => !cache.has(key)).slice(0, MAX_ICON_REQUESTS)
+  if (wanted.length === 0) return
+
+  const all = Promise.all(wanted.map(async ([key, { family, name }]) => {
+    try {
+      const response = await fetch(iconUrl(family, name, base), { method: 'GET' })
+      if (!response.ok) return
+      const svg = await response.text()
+      if (/<svg[\s>]/i.test(svg)) cache.set(key, svg)
+    } catch {
+      // The transport may refuse an address. The icon stays on the browser's path.
+    }
+  }))
+  let timer
+  const waited = new Promise((resolve) => { timer = setTimeout(resolve, ICON_WAIT_MS) })
+  await Promise.race([all, waited])
+  clearTimeout(timer)
+}
+
+/**
+ * Run a render and collect the icons it drew, so the page can carry exactly those. On a graph reused
+ * across pages that can include one this page's walk did not find, which is why this reads the
+ * render rather than the walk: whatever the HTML shows, the browser's first render can show too.
+ *
+ * The render is synchronous, so no other request can read through this while it runs.
+ *
+ * @param {Object|undefined} uniweb - what `globalThis.uniweb` names for this render
+ * @param {Map<string, string>} read - filled with each icon drawn
+ * @param {Function} draw - the render
+ * @returns {*} what `draw` returned
+ */
+export function whileReadingIcons(uniweb, read, draw) {
+  const cache = uniweb?.iconCache
+  if (!cache) return draw()
+  const { get } = cache
+  cache.get = (key) => {
+    const svg = get.call(cache, key)
+    if (svg) read.set(key, svg)
+    return svg
+  }
+  try {
+    return draw()
+  } finally {
+    delete cache.get
+  }
+}

package/src/page-renderer.js

@@ -39,6 +39,7 @@ import { hydrateDataStore } from './wire-foundation.js'
 import { loadPageData } from './load-page-data.js'
 import { requireTransport } from './require-transport.js'
 import { restoreStartPage } from './start-page.js'
+import { whileReadingIcons } from './page-icons.js'
 
 /**
  * A renderer bound to one initialized Website and one shell.
@@ -158,9 +159,11 @@ export function createPageRenderer({ website, shell }) {
     // request's page.
     restoreStartPage(website)
     if (typeof target === 'string') website.setActivePage(target)
+    // ⭐ The page carries the icons it drew, so the browser's first render draws them too.
+    const icons = new Map()
     let result
     try {
-      result = renderPage(page, website)
+      result = whileReadingIcons(globalThis.uniweb, icons, () => renderPage(page, website))
     } catch (err) {
       // `renderPage` handles its own errors, but a foundation can throw from
       // module scope in ways it does not catch. Classify rather than propagate,
@@ -179,6 +182,7 @@ export function createPageRenderer({ website, shell }) {
     const html = injectPageContent(shell, result.renderedContent, page, {
       ...inject,
       sectionOverrideCSS: result.sectionOverrideCSS,
+      icons,
     })
     return { outcome: missing ? 'notFound' : 'rendered', html, page, error: null }
   }

package/src/setup.js

@@ -19,7 +19,7 @@
 
 import React from 'react'
 import { createUniweb } from '@uniweb/core'
-import { DEFAULT_ICON_BASE, iconUrl } from '@uniweb/core/icon-corpus'
+import { DEFAULT_ICON_BASE, ICON_FAMILY_MAP, iconUrl } from '@uniweb/core/icon-corpus'
 import { createDefaultFetcher } from './default-fetcher.js'
 import {
   Link as RouterLink,
@@ -100,43 +100,6 @@ const DEFAULT_ROUTING_COMPONENTS = {
 
 // ─── Icon resolution ────────────────────────────────────────────────────────
 
-const ICON_FAMILY_MAP = {
-  lucide: 'lu',
-  heroicons: 'hi',
-  heroicons2: 'hi2',
-  phosphor: 'pi',
-  tabler: 'tb',
-  feather: 'fi',
-  fa: 'fa',
-  fa6: 'fa6',
-  bootstrap: 'bs',
-  'material-design': 'md',
-  'ant-design': 'ai',
-  remix: 'ri',
-  'simple-icons': 'si',
-  ionicons: 'io5',
-  boxicons: 'bi',
-  vscode: 'vsc',
-  weather: 'wi',
-  game: 'gi',
-  lu: 'lu',
-  hi: 'hi',
-  hi2: 'hi2',
-  pi: 'pi',
-  tb: 'tb',
-  fi: 'fi',
-  bs: 'bs',
-  md: 'md',
-  ai: 'ai',
-  ri: 'ri',
-  io5: 'io5',
-  bi: 'bi',
-  si: 'si',
-  vsc: 'vsc',
-  wi: 'wi',
-  gi: 'gi',
-}
-
 /**
  * Create CDN-based icon resolver.
  *

package/src/ssr-renderer.js

@@ -39,6 +39,7 @@ import { renderAppearanceBootScript } from './appearance.js'
 import { documentTitle } from './document-title.js'
 import { recordStartPage } from './start-page.js'
 import { escapeHtml } from '@uniweb/core/page-shell'
+import { jsonForScript } from '@uniweb/core/data-script'
 
 // Re-export L2 helpers so the public `@uniweb/runtime/ssr` surface
 // carries everything an SSR consumer needs from one entry point.
@@ -669,6 +670,13 @@ export function injectPageContent(html, renderedContent, page, options = {}) {
     result = result.replace('</head>', `${overrideStyle}\n</head>`)
   }
 
+  // The icons this page drew, which the browser reads before its first render (`setup.js`), so it
+  // draws them too. A replacer function, since `$` in a replacement string is not literal.
+  if (options.icons?.size && !result.includes('id="__ICON_CACHE__"')) {
+    const iconScript = `<script id="__ICON_CACHE__" type="application/json">${jsonForScript(Object.fromEntries(options.icons))}</script>`
+    result = result.replace('</head>', () => `  ${iconScript}\n</head>`)
+  }
+
   // Replace the empty root div with pre-rendered content
   result = result.replace(
     /<div id="root">[\s\S]*?<\/div>/,