@uniweb/runtime 1.1.20 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "1.1.20",
+  "version": "1.2.0",
   "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.5",
     "@uniweb/theming": "~1.2.1"
   },
   "devDependencies": {

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/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/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 } = {}) {

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/ssr-renderer.js

@@ -342,8 +342,8 @@ export function renderLayout(page, website) {
   }
 
   // Mirror Layout.jsx: wrap body + each area in a thin div carrying its
-  // view-transition-name, so the prerendered HTML matches what the SPA hydrates
-  // and the browser can animate regions independently on client navigation.
+  // view-transition-name, so the prerendered HTML matches the page the SPA renders
+  // in its place and the browser can animate regions independently on client navigation.
   const areaNames = Object.keys(areas)
   const transitions = website.viewTransitions
     ? resolveLayoutTransitions(areaNames, layoutMeta?.transitions)
@@ -674,7 +674,7 @@ export { escapeHtml }
  * Common operations shared by both build and cloud:
  * - Replace #root div with rendered HTML
  * - Update page title
- * - Add/update meta description
+ * - Write the page's head tags — description, canonical, hreflang, Open Graph (`writeHeadMeta`)
  * - Inject section override CSS
  * - Inject the pre-paint appearance script
  *
@@ -701,7 +701,7 @@ export function injectPageContent(html, renderedContent, page, options = {}) {
 
   // Pre-paint appearance script. Prerendered HTML carries real content styled
   // from :root (light) tokens, so a dark visitor would see a flash of light
-  // before the bundle hydrates and applies the class. Read off the page's
+  // before the bundle boots and applies the class. Read off the page's
   // website back-ref rather than a parameter: every lane builds the same graph,
   // so this needs no plumbing and no per-lane opt-in. Idempotent, because
   // @uniweb/build's injectBuildData may run over this HTML afterwards.
@@ -766,45 +766,66 @@ export function injectPageContent(html, renderedContent, page, options = {}) {
     )
   }
 
-  // Add/update meta description
-  if (page.description) {
-    const metaDesc = `<meta name="description" content="${escapeHtml(page.description)}">`
-    if (result.includes('<meta name="description"')) {
-      result = result.replace(/<meta name="description"[^>]*>/, metaDesc)
-    } else {
-      result = result.replace('</head>', `${metaDesc}\n</head>`)
-    }
-  }
-
-  // Social / SEO meta from the page's effective head metadata (page seo
-  // cascading over site-level seo — see Page.getHeadMeta). The SPA emits these
-  // client-side via useHeadMeta; this is the SSR twin, so crawlers and social
-  // unfurlers (which don't run JS) get them in the static HTML too.
-  const headMeta = page.getHeadMeta?.()
-  if (headMeta) {
-    const og = headMeta.og || {}
-    const keywords = Array.isArray(headMeta.keywords)
-      ? headMeta.keywords.join(', ')
-      : headMeta.keywords
-    const tags = []
-    if (keywords) tags.push(`<meta name="keywords" content="${escapeHtml(keywords)}">`)
-    if (headMeta.robots) tags.push(`<meta name="robots" content="${escapeHtml(headMeta.robots)}">`)
-    if (og.title) tags.push(`<meta property="og:title" content="${escapeHtml(og.title)}">`)
-    if (og.description) tags.push(`<meta property="og:description" content="${escapeHtml(og.description)}">`)
-    if (og.image) tags.push(`<meta property="og:image" content="${escapeHtml(og.image)}">`)
-    if (og.url) tags.push(`<meta property="og:url" content="${escapeHtml(og.url)}">`)
-    tags.push('<meta property="og:type" content="website">')
-    tags.push(`<meta name="twitter:card" content="${og.image ? 'summary_large_image' : 'summary'}">`)
-    if (og.title) tags.push(`<meta name="twitter:title" content="${escapeHtml(og.title)}">`)
-    if (og.description) tags.push(`<meta name="twitter:description" content="${escapeHtml(og.description)}">`)
-    if (og.image) tags.push(`<meta name="twitter:image" content="${escapeHtml(og.image)}">`)
-    if (headMeta.canonical) tags.push(`<link rel="canonical" href="${escapeHtml(headMeta.canonical)}">`)
-    if (tags.length) result = result.replace('</head>', `${tags.join('\n')}\n</head>`)
-  }
+  // ⭐ THE PAGE'S HEAD TAGS — description, canonical, hreflang, Open Graph, Twitter — from the
+  // page's own head metadata (`Page#getHeadMeta`, which the browser writes the same tags from in
+  // `useHeadMeta`), so crawlers and social unfurlers, which run no script, read the page's own.
+  // ⛔ Until 2026-10-25 these were APPENDED, after the static build had written the HOME page's
+  // into the one shell every page is rendered into: each page named the home page its canonical
+  // and carried two og:title and two og:url, the home page's first.
+  result = writeHeadMeta(result, page)
 
   return result
 }
 
+/**
+ * Write a page's head tags into `html`'s head. These tags are the framework's: each is set to the
+ * page's value, replacing any of its name the shell carries, and removed when the page has none —
+ * as the browser does on every navigation (`useHeadMeta`), so hydrating the page changes nothing a
+ * crawler read.
+ *
+ * @param {string} html
+ * @param {Object} page
+ * @returns {string}
+ */
+function writeHeadMeta(html, page) {
+  // A Page states its own (`getHeadMeta`); plain page data, which callers may hand in, its fields.
+  const meta = typeof page?.getHeadMeta === 'function' ? page.getHeadMeta() : { description: page?.description || null }
+  const end = html.indexOf('</head>')
+  if (!meta || end === -1) return html
+  const og = meta.og || {}
+  const keywords = Array.isArray(meta.keywords) ? meta.keywords.join(', ') : meta.keywords
+  const metaTags = [
+    ['name', 'description', meta.description],
+    ['name', 'keywords', keywords],
+    ['name', 'robots', meta.robots],
+    ['property', 'og:type', 'website'],
+    ['property', 'og:site_name', og.siteName],
+    ['property', 'og:title', og.title],
+    ['property', 'og:description', og.description],
+    ['property', 'og:image', og.image],
+    ['property', 'og:url', og.url],
+    ['name', 'twitter:card', og.image ? 'summary_large_image' : 'summary'],
+    ['name', 'twitter:site', meta.twitter?.site],
+    ['name', 'twitter:title', og.title],
+    ['name', 'twitter:description', og.description],
+    ['name', 'twitter:image', og.image],
+  ]
+  // The head alone: the page's content is in the body, and none of it is edited here.
+  let head = html.slice(0, end)
+  const written = []
+  for (const [attr, key, value] of metaTags) {
+    head = head.replace(new RegExp(`<meta\\b[^>]*\\b(?:name|property)=["']${key}["'][^>]*>\\s*`, 'gi'), '')
+    if (value) written.push(`<meta ${attr}="${key}" content="${escapeHtml(value)}">`)
+  }
+  head = head.replace(/<link\b[^>]*\brel=["']canonical["'][^>]*>\s*/gi, '')
+  if (meta.canonical) written.push(`<link rel="canonical" href="${escapeHtml(meta.canonical)}">`)
+  head = head.replace(/<link\b[^>]*\bhreflang=["'][^"']*["'][^>]*>\s*/gi, '')
+  for (const { hreflang, url } of meta.alternates || []) {
+    written.push(`<link rel="alternate" hreflang="${escapeHtml(hreflang)}" href="${escapeHtml(url)}">`)
+  }
+  return `${head}${written.join('\n')}\n${html.slice(end)}`
+}
+
 // ============================================================================
 // 404 fallback generation
 // ============================================================================