@uniweb/runtime 1.1.20 → 1.2.1

package/src/hooks/useHeadMeta.js

@@ -3,6 +3,13 @@
  *
  * Manages document head meta tags for SEO and social sharing.
  * Updates meta tags when page changes in SPA navigation.
+ *
+ * ⭐ The browser twin of `injectPageContent`'s head tags, from the same source
+ * (`Page#getHeadMeta`), so a crawler that runs the page's script reads what one that
+ * does not read. These tags are the framework's: each is set when the page has a value
+ * and removed when it has none — as it must be, or a tag of the page before survives a
+ * navigation. ⛔ Until 2026-10-25 this removed the canonical of every page that did not
+ * author one, after the prerendered HTML had stated it.
  */
 
 import { useEffect, useRef } from 'react'
@@ -20,7 +27,9 @@ const META_TAGS = {
   'og:image': { property: 'og:image' },
   'og:url': { property: 'og:url' },
   'og:type': { property: 'og:type' },
+  'og:site_name': { property: 'og:site_name' },
   'twitter:card': { name: 'twitter:card' },
+  'twitter:site': { name: 'twitter:site' },
   'twitter:title': { name: 'twitter:title' },
   'twitter:description': { name: 'twitter:description' },
   'twitter:image': { name: 'twitter:image' }
@@ -72,13 +81,17 @@ function getOrCreateLinkTag(rel) {
 }
 
 /**
- * Set or remove a meta tag's content
+ * Set or remove a meta tag's content — one tag of each name, whoever wrote the others
  * @param {string} key - Meta tag key
  * @param {string|null} content - Content value (null to remove)
  */
 function setMetaContent(key, content) {
   const element = getOrCreateMetaTag(key)
   if (!element) return
+  const config = META_TAGS[key]
+  for (const extra of document.querySelectorAll(`meta[${config.property ? 'property' : 'name'}="${config.property || config.name}"]`)) {
+    if (extra !== element) extra.remove()
+  }
 
   if (content) {
     element.setAttribute('content', content)
@@ -88,6 +101,21 @@ function setMetaContent(key, content) {
   }
 }
 
+/**
+ * The page's URL in each locale (`hreflang`), replacing whatever the document carried
+ * @param {Array<{hreflang: string, url: string}>} alternates
+ */
+function setAlternates(alternates) {
+  for (const link of document.querySelectorAll('link[rel="alternate"][hreflang]')) link.remove()
+  for (const { hreflang, url } of alternates || []) {
+    const link = document.createElement('link')
+    link.setAttribute('rel', 'alternate')
+    link.setAttribute('hreflang', hreflang)
+    link.setAttribute('href', url)
+    document.head.appendChild(link)
+  }
+}
+
 /**
  * useHeadMeta hook
  *
@@ -138,26 +166,30 @@ export function useHeadMeta(meta, options = {}) {
       setMetaContent('og:image', meta.og.image || null)
       setMetaContent('og:url', meta.og.url || null)
       setMetaContent('og:type', 'website')
+      setMetaContent('og:site_name', meta.og.siteName || null)
 
       // Twitter cards (fallback to OG values)
       setMetaContent('twitter:card', meta.og.image ? 'summary_large_image' : 'summary')
+      setMetaContent('twitter:site', meta.twitter?.site || null)
       setMetaContent('twitter:title', meta.og.title || meta.title || null)
       setMetaContent('twitter:description', meta.og.description || meta.description || null)
       setMetaContent('twitter:image', meta.og.image || null)
     }
 
-    // Update canonical link
+    // Update canonical link — the page's own URL unless it authors one, and none when the site's
+    // address is unknown (`Page#getHeadMeta`)
     if (meta.canonical) {
       const canonicalLink = getOrCreateLinkTag('canonical')
       canonicalLink.setAttribute('href', meta.canonical)
-    } else {
-      // Remove canonical if not set
-      const existingCanonical = document.querySelector('link[rel="canonical"]')
-      if (existingCanonical) {
-        existingCanonical.remove()
+      for (const extra of document.querySelectorAll('link[rel="canonical"]')) {
+        if (extra !== canonicalLink) extra.remove()
       }
+    } else {
+      for (const existing of document.querySelectorAll('link[rel="canonical"]')) existing.remove()
     }
 
+    setAlternates(meta.alternates)
+
     // Cleanup function - reset to defaults on unmount
     return () => {
       // We don't remove tags on cleanup because another page will set them
@@ -174,6 +206,9 @@ export function useHeadMeta(meta, options = {}) {
     meta?.og?.description,
     meta?.og?.image,
     meta?.og?.url,
+    meta?.og?.siteName,
+    meta?.twitter?.site,
+    JSON.stringify(meta?.alternates || []),
     siteName
   ])
 }

package/src/load-page-data.js

@@ -26,6 +26,7 @@ import DataStore, { deriveCacheKey } from '@uniweb/core/datastore'
 import { resolvePage } 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
@@ -53,7 +54,8 @@ function blocksOf(page) {
  * @param {Object} options
  * @param {Object} options.website - the initialized Website the render will use (`initPrerender`)
  * @param {string|Object} options.route - the route, or an already-resolved Page
- * @param {Function} options.fetch - the transport, per request
+ * @param {Function} options.fetch - the transport, per request. Required: a missing one is refused,
+ *   never replaced by the ambient `fetch` (`require-transport.js`)
  * @param {boolean} [options.dev]
  * @param {string|null} [options.locale] - ⛔ NOT a locale to fetch in: the Website is already
  *   locale-sliced (`initPrerenderForLocale`) and every address is resolved in ITS locale. Passing
@@ -74,6 +76,9 @@ export async function loadPageData({ website, route, fetch, dev = false, locale
   if (prerender !== 'author' && prerender !== 'always') {
     throw new Error(`loadPageData: prerender must be 'author' or 'always', got ${JSON.stringify(prerender)}`)
   }
+  // Before the route is resolved: a lost transport is the caller's wiring, and an unknown route
+  // must not hide it.
+  requireTransport(fetch, 'loadPageData')
   const active = website?.getActiveLocale?.() ?? null
   if (locale && active && locale !== active) {
     throw new Error(

package/src/page-renderer.js

@@ -22,17 +22,19 @@
  *     modelling a deployment it cannot see (the host drew this line itself,
  *     2026-09-03: a serve location is read from the payload, never constructed here).
  *   - **Init and hydration.** The two lanes differ REALLY here, not incidentally: a
- *     build initializes once and hydrates every collection up front, an isolate
- *     initializes per locale and prefetches per route. Folding either in would fit
- *     one caller and lie to the other. `initPrerender` / `initPrerenderForLocale` /
- *     `prefetchPageData` / `hydrateDataStore` stay separate exports, and
- *     `prefetchAndHydrate` below is the isolate's two-step, not a general one.
+ *     build initializes once per locale, hydrates its executor's answers up front and
+ *     then runs the data step for each page over one cache for the whole run; an
+ *     isolate initializes per locale and runs the step fresh for each request. Folding
+ *     either in would fit one caller and lie to the other. `initPrerender` /
+ *     `initPrerenderForLocale` / `loadPageData` / `hydrateDataStore` stay separate
+ *     exports, and `prefetchAndHydrate` below is the isolate's two-step, not a general one.
  *   - **Anything build-only.** `injectBuildData` stays in the build lane; it is the
  *     other half of the head seam and has its own parity guard.
  */
 import { resolvePage, renderPage, classifyRenderError, injectPageContent } from './ssr-renderer.js'
 import { hydrateDataStore } from './wire-foundation.js'
 import { loadPageData } from './load-page-data.js'
+import { requireTransport } from './require-transport.js'
 
 /**
  * A renderer bound to one initialized Website and one shell.
@@ -55,8 +57,8 @@ export function createPageRenderer({ website, shell }) {
    * ⭐ Returns an OUTCOME rather than throwing or returning a bare string, because
    * the two callers branch differently on the same three cases and neither wants an
    * exception: a build logs and keeps going so one broken section cannot fail a whole
-   * site, an isolate decides a status code and a cache policy. Same reasoning as
-   * `prefetchPageData`'s per-entry outcome.
+   * site, an isolate decides a status code and a cache policy. Same reasoning as the
+   * per-entry outcome `loadPageData` returns.
    *
    * @param {string|Object} target - a route (`/blog/1`, resolved through the same
    *   matcher the browser uses, so a dynamic route works) or an already-resolved
@@ -143,13 +145,14 @@ export function createPageRenderer({ website, shell }) {
  * on the Website it is handed: the keys each component declares, the layout the page actually
  * draws, and the transport the site chose for a key. `content` is no longer read — the graph
  * carries everything — and stays in the signature for callers that pass it.
- * ⛔ `prefetchPageData` works from the payload alone and cannot know any of those; it asks for
- * every fetch on every level instead, and still gets four cases wrong. Prefer this entry.
+ * ⛔ `prefetchPageData`, which it replaced, worked from the payload alone and could know none of
+ * those: it asked for every fetch on every level and still got four cases wrong. It was removed
+ * on 2026-09-20.
  *
- * ⛔ The build lane does NOT call this: it hydrates every collection once, before
- * its page loop, from its own executor that honours the author's `prerender:` flag.
- * That difference is why this is a named isolate helper and not a step inside
- * `render`.
+ * ⛔ The build lane does NOT call this: it runs `loadPageData` itself for each page, with one
+ * cache for the whole run (which this entry does not take) and `prerender: 'author'`, and keeps
+ * the entries to embed in that page's HTML. That difference is why this is a named isolate
+ * helper and not a step inside `render`.
  *
  * @returns {Promise<Array<{config: Object, outcome: string, data: any, error?: string}>>}
  */
@@ -162,33 +165,11 @@ export async function prefetchAndHydrate({ website, content, route, locale = nul
     throw new Error('prefetchAndHydrate: `website` must be an initialized Website with a dataStore')
   }
 
-  // ⛔ THE TRANSPORT IS REQUIRED HERE, unlike on `prefetchPageData`, and this is the
-  // one place the difference matters.
-  //
-  // A function does NOT survive every isolate boundary. Measured by a host against
-  // a real isolate loader, 2026-09-03: passed through an
-  // entrypoint's `fetch(Request)` with a JSON body the transport arrives
-  // **`undefined`**; passed as an argument to an RPC method it arrives as a callable
-  // function and the isolate invokes it. Only the RPC shape carries it.
-  //
-  // ⚠️ And `undefined` is not where it stops, which is the part their measurement
-  // could not see from outside our code. `createDefaultFetcher` resolves the
-  // transport as `fetchImpl || globalThis.fetch`, so a transport that failed to cross
-  // silently becomes THE ISOLATE'S OWN NETWORK — outside the host's timeout, byte
-  // budget and site-relative address resolution. With an absolute address it does not
-  // even fail: the request goes out from the wrong place and comes back
-  // `outcome: 'fetched'`. A wiring mistake wearing a success.
-  //
-  // ⇒ So the entry whose only caller crosses that boundary demands a real function
-  // rather than defaulting. A Node or browser caller that genuinely wants the global
-  // passes `fetch: globalThis.fetch` — one word, and it says so.
-  if (typeof fetch !== 'function') {
-    throw new Error(
-      'prefetchAndHydrate: `fetch` must be a function. A transport does not survive a ' +
-      'JSON-serialized isolate boundary — pass it as an RPC method argument. ' +
-      'To use the ambient fetch deliberately, pass `fetch: globalThis.fetch`.'
-    )
-  }
+  // ⛔ THE TRANSPORT IS REQUIRED, as on every entry a host calls to have the runtime fetch for
+  // it: one that did not cross the isolate boundary is refused here, never replaced by the
+  // isolate's own network (`require-transport.js`, which records the measurement). Checked here
+  // as well as in `loadPageData` so the message names the entry the caller called.
+  requireTransport(fetch, 'prefetchAndHydrate')
   // ⛔ `locale` is forwarded to be CHECKED, not applied: the Website is locale-sliced already, so a
   // caller whose two disagree gets an error rather than a page prerendered in one language with the
   // data of another.

package/src/prepare-props.js

@@ -133,9 +133,10 @@ export function applyDefaults(params, defaults) {
  *
  * A key declared `single: true` then holds one record, or `null` (`holdOneRecord`).
  *
- * A tagged data block under a key the component does not declare is left out, and said so
- * in dev (`warnUndeclaredBlocks`); it stays in `content.sequence`. The data object is
- * rebuilt on each render from those sources, never from the last render's.
+ * A tagged block the section holds under a key the component does not declare is left out, and
+ * said so in dev (`warnUndeclaredBlocks`); it stays in `content.sequence`. A block inside an item
+ * is that item's (`content.items[n].data`), never held here. The data object is rebuilt on each
+ * render from those sources, never from the last render's.
  *
  * ⛔ Until 2026-09-14 this merged every delivered key into what the section held, so a
  * section received every fetch that reached it and every tagged block it had.
@@ -149,7 +150,8 @@ function assembleData(block, meta, entityData) {
     else if (entityData && entityData[key] !== undefined) data[key] = entityData[key]
     else data[key] = null
   }
-  warnUndeclaredBlocks(block, declared)
+  // What the section holds and this leaves out — the keys the dev warning reports.
+  warnUndeclaredBlocks(block, Object.keys(held).filter((key) => !Object.hasOwn(data, key)))
   block.parsedContent.data = data
   return declared
 }
@@ -177,26 +179,36 @@ function holdOneRecord(block, declared) {
 }
 
 /**
- * Say once, in dev, that a tagged block — a data block or a concept block — did not reach its
- * section's component: its key is not declared. The block is still in `content.sequence`, where a component that
- * renders the sequence finds it.
+ * Say once, in dev, that a tagged block the section holds — a data block or a concept block — did
+ * not reach its component: its key is not declared. `assembleData` passes the keys it left out, so
+ * this names exactly what the component did not receive. The block is still in `content.sequence`,
+ * where a component that renders the sequence finds it.
+ *
+ * ⭐ AN ITEM'S BLOCK IS NEVER ONE OF THEM. The parser keeps a block inside an item with that item
+ * (`content.items[n].data`), which asks no declaration, and only the section's own blocks reach
+ * `block.heldData`. ⛔ Until 2026-10-25 this walked `content.sequence`, which lists every element of
+ * the section, its items' included, and so reported each card's `meta` block in a card grid as left
+ * out of `content.data`, where it never belonged.
  */
 const warnedBlocks = new Set()
-function warnUndeclaredBlocks(block, declared) {
-  if (!block.website?.entityStore?.dev) return
-  const keys = new Set(declared.map(([key]) => key))
-  for (const item of block.parsedContent?.sequence || []) {
-    // A data block (```yaml:tag) and a concept block (```md:tag) both land under their tag, so
-    // both need the key declared. ⛔ Until 2026-09-29 only a data block was reported, and an
-    // undeclared concept block left content.data without a word.
-    const kind = item?.type === 'dataBlock' ? 'data block' : item?.type === 'concept_block' ? 'concept block' : null
-    if (!kind || typeof item.tag !== 'string' || keys.has(item.tag)) continue
-    const memo = `${block.type}::${item.tag}`
+function warnUndeclaredBlocks(block, leftOut) {
+  if (!leftOut.length || !block.website?.entityStore?.dev) return
+  const sequence = block.parsedContent?.sequence || []
+  for (const tag of leftOut) {
+    const memo = `${block.type}::${tag}`
     if (warnedBlocks.has(memo)) continue
+    // The section's own block under the tag is the first in the sequence: the parser cuts the
+    // sequence into slices, and the section's own content is the first (`groups.js`). None means
+    // the key holds a fetch's prerendered answer, which is not a block.
+    // A data block (```yaml:tag) and a concept block (```md:tag) both land under their tag, so
+    // both need the key declared. ⛔ Until 2026-09-29 only a data block was reported.
+    const element = sequence.find((e) => (e?.type === 'dataBlock' || e?.type === 'concept_block') && e.tag === tag)
+    if (!element) continue
     warnedBlocks.add(memo)
+    const kind = element.type === 'dataBlock' ? 'data block' : 'concept block'
     console.warn(
-      `[uniweb] ${block.type}: the \`${item.tag}\` ${kind} is not in content.data — ${block.type} does not ` +
-        `declare \`${item.tag}\` in its meta.js \`data:\`. It stays in content.sequence.`
+      `[uniweb] ${block.type}: the \`${tag}\` ${kind} is not in content.data — ${block.type} does not ` +
+        `declare \`${tag}\` in its meta.js \`data:\`. It stays in content.sequence.`
     )
   }
 }

package/src/require-transport.js

@@ -0,0 +1,35 @@
+/**
+ * THE HOST'S TRANSPORT, REQUIRED — on every entry a host calls to have the runtime fetch on its
+ * behalf: `loadPageData`, `prefetchAndHydrate` and `collectSiteRecords`.
+ *
+ * ⛔ The failure this prevents is not "no transport". `createDefaultFetcher` resolves its transport
+ * as `fetchImpl || globalThis.fetch`, so a missing one becomes the ambient network — in an isolate,
+ * the isolate's own, outside the host's timeout and byte budget and outside its resolution of
+ * site-relative addresses. With an absolute address the request does not even fail: it leaves from
+ * the wrong place and comes back `fetched`. A wiring mistake wearing a success.
+ *
+ * Reachable, not hypothetical: a host measured against a real isolate loader (2026-09-03) that a
+ * function passed through an entrypoint's `fetch(Request)` with a JSON body arrives `undefined`,
+ * and survives only as an RPC method argument.
+ *
+ * ⛔ Until 2026-10-25 only `prefetchAndHydrate` refused one, while the entries a host's isolate
+ * calls — the data step and the corpus entry — fell back to the ambient network silently.
+ *
+ * The default stays where it is right: in the browser, which has one network, and in a harness
+ * that builds a default fetcher itself. A caller of these entries that wants the ambient fetch
+ * passes `fetch: globalThis.fetch`, which is one word and says so.
+ *
+ * Zero-dependency leaf, so the data step's graph stays renderer-free (`tests/data-step-graph.test.js`).
+ *
+ * @param {*} fetch - what the caller passed as `fetch`
+ * @param {string} entry - the entry's name, for the message
+ * @returns {Function} the transport
+ */
+export function requireTransport(fetch, entry) {
+  if (typeof fetch === 'function') return fetch
+  throw new Error(
+    `${entry}: \`fetch\` must be a function. A transport does not survive a ` +
+    'JSON-serialized isolate boundary — pass it as an RPC method argument. ' +
+    'To use the ambient fetch deliberately, pass `fetch: globalThis.fetch`.'
+  )
+}

package/src/setup.js

@@ -291,7 +291,8 @@ export function initUniweb({ content, foundation, extensions = [], routingCompon
 
   uniweb.childBlockRenderer = ChildBlocks
   // The same background a section gets, for kit's `SectionBackground` — a component that
-  // paints its own (`background: 'self'`). The SSR twin sets its own (`ssr-renderer.js`).
+  // paints its own (`background: 'self'`). The prerender sets the same one (`ssr-renderer.js`):
+  // one implementation (`background.js`), of which this is the browser's, which plays a video.
   uniweb.backgroundRenderer = Background
 
   // L2 (singleton wiring): defaultInsets, xref.build(), and any future