@symbo.ls/brender 3.14.664 → 3.14.666

package/render.js

@@ -4,15 +4,16 @@ import { resolvePackageEntry } from './packageEntry.js'
 import { tmpdir } from 'os'
 import { randomBytes } from 'crypto'
 import { createRequire } from 'module'
+import { pathToFileURL } from 'url'
 import { createEnv } from './env.js'
 import { resetKeys, assignKeys, mapKeysToElements } from './keys.js'
 import { extractMetadata, generateHeadHtml } from './metadata.js'
 import { hydrate } from './hydrate.js'
 import { composeIntoShell } from './shell.js'
-import { prefetchPageData, injectPrefetchedState, fetchSSRTranslations } from './prefetch.js'
+import { fetchSSRTranslations } from './prefetch.js'
 import { createEarlySeedScript } from '@symbo.ls/fetch'
 import { headerEntries } from '@symbo.ls/fetch/rest'
-import { jsonForScript } from '@symbo.ls/utils'
+import { brenderRegistryBlock, escapeRegExp, jsonForScript, polyglotFallbackLang } from '@symbo.ls/utils'
 
 // funcql plugin — enables evaluation of funcql schemas as property values
 // during SSR. Async-imported to avoid polluting non-funcql codepaths.
@@ -28,6 +29,7 @@ const getFuncqlPlugin = async () => {
   }
 }
 import { parseHTML } from 'linkedom'
+import { createEarlySeedBlock } from '@symbo.ls/fetch'
 import { css, injectGlobal, reset as resetCss } from '@symbo.ls/css'
 
 // Lightweight SSR polyglot functions — resolve translations from context
@@ -45,17 +47,17 @@ const ssrResolve = (map, key) => {
   return v
 }
 
-const ssrTranslate = function (key, lang) {
-  if (!key) return ''
-  const ctx = this?.context
-  const poly = ctx?.polyglot
-  // Default lang fallback must match the polyglot plugin's contract
-  // (`'en'`) — when a project doesn't set polyglot.defaultLang, SSR was
-  // resolving against KA translations while client hydrate resolved
-  // against EN, producing different text in the SSR shell vs the
-  // hydrated DOM. See plugins/polyglot/index.js:41.
-  const activeLang = lang || poly?.defaultLang || 'en'
-
+// The language a server render shows: the root state's — a page under a
+// language prefix sets it (a router guard reading `/en/…`) — else the
+// project's default, else 'en' (@symbo.ls/utils polyglotFallbackLang, the
+// order plugins/polyglot getActiveLang resolves it in). Diverging produces
+// SSR/hydrate text mismatches.
+const activeLangOf = (root, poly) => polyglotFallbackLang(root?.lang, poly)
+
+// One label lookup, the order the client's translate() reads: static
+// translations, then the labels loaded into the root state, then the
+// default language's static ones. `undefined` when no table has the key.
+const findLabel = (key, activeLang, poly, root) => {
   // Static translations from context.polyglot.translations
   if (poly?.translations) {
     const langMap = poly.translations[activeLang]
@@ -66,7 +68,6 @@ const ssrTranslate = function (key, lang) {
   }
 
   // Server-loaded translations in root state
-  const root = this?.state?.root || ctx?.state?.root
   if (root?.translations) {
     const langMap = root.translations[activeLang]
     if (langMap) {
@@ -76,7 +77,7 @@ const ssrTranslate = function (key, lang) {
   }
 
   // Fallback to default lang
-  const defaultLang = poly?.defaultLang || 'en'
+  const defaultLang = polyglotFallbackLang(undefined, poly)
   if (defaultLang !== activeLang && poly?.translations) {
     const fallback = poly.translations[defaultLang]
     if (fallback) {
@@ -84,15 +85,30 @@ const ssrTranslate = function (key, lang) {
       if (val !== undefined) return val
     }
   }
+  return undefined
+}
 
+const ssrTranslate = function (key, lang) {
+  if (!key) return ''
+  const ctx = this?.context
+  const poly = ctx?.polyglot
+  const root = this?.state?.root || ctx?.state?.root
+  // The ROOT's language, as the client's translate() asks getActiveLang.
+  // This used to read `poly.defaultLang` straight, so a page rendered for
+  // /en/about had `en` in its state and Georgian text in its markup
+  // (xma.info report, brender build item 8).
+  const val = findLabel(key, lang || activeLangOf(root, poly), poly, root)
+  if (val !== undefined) return val
+  // A key with no label yet. The labels may still be on their way (a
+  // project's own polyglot.fetch loads them during the render), so this only
+  // notes the key; the end of the render checks it again (see rawLabelKeys).
+  const diag = liveRecord(DIAG)
+  if (poly && diag) diag.labelKeys.add(key)
   return key
 }
 
 const ssrGetActiveLang = function () {
-  const ctx = this?.context
-  // 'en' matches plugins/polyglot/index.js#getActiveLang — diverging here
-  // produces SSR/hydrate text mismatches.
-  return this?.state?.root?.lang || ctx?.polyglot?.defaultLang || 'en'
+  return activeLangOf(this?.state?.root, this?.context?.polyglot)
 }
 
 // Deep clone that preserves functions and avoids circular refs
@@ -272,6 +288,13 @@ const resolveDomqlPackage = (ws, pkg, ...subpath) => {
 //
 // An installed smbls OLDER than the ssr entry that still carries
 // src/createDomql.js (pre-54131b34d tarballs) keeps the source-bundle path.
+//
+// Loaded once per process, and the load in progress is shared: it kept the
+// loaded module, set when the load finished, so renders that started together
+// before then loaded one each — two esbuild runs, and two framework instances
+// in one process (two signal and CSS engines, two @symbo.ls/fetch copies with
+// their own query caches); the renders after them got whichever finished
+// last. A failed load is not kept: the next render tries again.
 let _cachedCreateDomql = null
 
 // Exported for the packaging lock in __tests__/ssrEntryPackaging.test.js —
@@ -287,9 +310,17 @@ const importSmblsSsr = async () => {
   return mod
 }
 
-const bundleCreateDomql = async () => {
-  if (_cachedCreateDomql) return _cachedCreateDomql
+const bundleCreateDomql = () => {
+  if (!_cachedCreateDomql) {
+    _cachedCreateDomql = loadCreateDomql().catch((err) => {
+      _cachedCreateDomql = null
+      throw err
+    })
+  }
+  return _cachedCreateDomql
+}
 
+const loadCreateDomql = async () => {
   const ws = detectWorkspace()
 
   // Resolve entry point: the monorepo's source, else `smbls/ssr` (one import
@@ -300,8 +331,7 @@ const bundleCreateDomql = async () => {
   } else {
     let ssrError
     try {
-      _cachedCreateDomql = await importSmblsSsr()
-      return _cachedCreateDomql
+      return await importSmblsSsr()
     } catch (err) {
       ssrError = err
     }
@@ -326,9 +356,44 @@ const bundleCreateDomql = async () => {
 
   const tryResolve = resolvePackageEntry
 
+  // In the monorepo, every workspace specifier the handlers below do not own
+  // — a SUBPATH of a sibling (`@symbo.ls/dropdown/components`,
+  // `@symbo.ls/sync/applier`, `@symbo.ls/utils/function.js`) and an unscoped
+  // sibling (`attrs-in-props`) — resolves to its source through the map the
+  // test runner and smbls's own build resolve with
+  // (scripts/vite-workspace-source.mjs). They fell through to esbuild, which
+  // followed each package's `exports` into its dist/: a render ran whatever
+  // build was left on disk (the legacy Dropdown kit of an earlier build, a
+  // sync applier without the exports createDomql imports now), and a
+  // checkout without dist/ could not render at all. A dist input now fails
+  // the bundle.
+  const workspaceSource = ws.isMonorepo
+    ? await import(pathToFileURL(resolve(ws.monorepoRoot, 'scripts', 'vite-workspace-source.mjs')).href)
+    : null
+  const workspaceNames = workspaceSource
+    ? new Set(workspaceSource.workspacePackageRoots().map((dir) => workspaceSource.workspacePackageAt(dir).name))
+    : null
+  // Bare specifiers the handlers below resolve themselves (the sync stub
+  // among them).
+  const OWN_HANDLERS = /^(?:smbls(?:\/.*)?|domql|css-in-props(?:\/.*)?|@symbo\.ls\/[^/]+)$/
+
   const workspacePlugin = {
     name: 'workspace-resolve',
     setup (build) {
+      if (workspaceSource) {
+        build.onResolve({ filter: /^[^./]/ }, (args) => {
+          if (OWN_HANDLERS.test(args.path)) return
+          const parts = args.path.split('/')
+          const name = args.path.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0]
+          if (!workspaceNames.has(name)) return
+          const source = workspaceSource.resolveWorkspaceSource(args.path, args.importer || entry)
+          if (source) return { path: source }
+          return { errors: [{ text: `"${args.path}" names no source file in the workspace` }] }
+        })
+        build.onLoad({ filter: /[\\/]dist[\\/]/ }, (args) => workspaceSource.isWorkspaceDist(args.path)
+          ? { errors: [{ text: `${args.path} is a BUILD of a workspace package — the render bundles source` }] }
+          : undefined)
+      }
       // Resolve smbls bare import
       build.onResolve({ filter: /^smbls/ }, (args) => {
         const subpath = args.path.replace(/^smbls\/?/, '')
@@ -543,7 +608,6 @@ const bundleCreateDomql = async () => {
     console.log('[brender] Bundle saved:', outFile)
   }
 
-  _cachedCreateDomql = mod
   return mod
 }
 
@@ -634,17 +698,24 @@ const UIKIT_STUBS = {
  */
 const buildPathRegistry = (element, elementPath) => {
   const registry = {}
+  walkElements(element, (el, ref) => {
+    if (!ref.__brKey) return
+    const path = elementPath(el)
+    registry[path === '' ? '__root' : path] = ref.__brKey
+  })
+  return registry
+}
+
+// Every element of a rendered tree, each before its children, in the order of
+// `__ref.__children`.
+const walkElements = (root, visit) => {
   const walk = (el) => {
     const ref = el && el.__ref
     if (!ref) return
-    if (ref.__brKey) {
-      const path = elementPath(el)
-      registry[path === '' ? '__root' : path] = ref.__brKey
-    }
+    visit(el, ref)
     if (ref.__children) for (const childKey of ref.__children) walk(el[childKey])
   }
-  walk(element)
-  return registry
+  walk(root)
 }
 
 /**
@@ -697,13 +768,64 @@ const inFlightRequests = () => _inFlight
 const SEED_ENTRY_MAX = 256 * 1024
 const SEED_TOTAL_MAX = 1024 * 1024
 const SEED_HEADERS_OK = new Set(['accept-language', 'accept'])
-let _activeRenders = 0
-let _seed = null
+const SEED = { renders: 0, record: null }
+// ── What went wrong in a render (its diagnostics) ───────────────────────────
+// Kept like the seed — one record while exactly ONE render runs, tainted by
+// an overlapping one — so a build can tell a page made from data from a page
+// made from nothing: the requests that failed (a non-ok status or a network
+// error) and the label keys that missed (ssrTranslate notes them; the end of
+// the render checks them again, see rawLabelKeys). A build with its database
+// unreachable printed "✓ 22 of 22 routes" and exited 0 while every page
+// carried raw keys (xma.info report, brender build item 9).
+const DIAG_FAILURES_MAX = 50
+const DIAG = { renders: 0, record: null }
+
+// One record per window of overlapping renders (the seed's and the
+// diagnostics' windows open at different points of a render, so each has its
+// own slot): the first render of a window opens it, a render that overlaps it
+// taints it — another project's answers or failures must never land in this
+// page — and it goes as soon as one of the renders holding it ends. A render
+// that starts inside a window whose record is gone gets none.
+const openRenderRecord = (slot, make) => {
+  slot.renders++
+  if (slot.renders === 1) slot.record = make()
+  else if (slot.record) slot.record.tainted = true
+  const record = slot.record
+  const close = () => {
+    slot.renders--
+    if (slot.record === record) slot.record = null
+  }
+  return { record, close }
+}
+
+// The slot's record while it is the only render's, else null.
+const liveRecord = (slot) => slot.record && !slot.record.tainted ? slot.record : null
+
+// A request as a diagnostic names it: origin and path. The query is left out
+// — a public read can carry its key there (`?apikey=…`), and a log line is no
+// place for one.
+const requestLabel = (url) => {
+  try {
+    const u = new URL(url)
+    return u.origin + u.pathname
+  } catch {
+    return String(url).split('?')[0]
+  }
+}
+
+const recordFailure = (diag, url, reason) => {
+  if (!diag || diag.tainted || diag.failures.length >= DIAG_FAILURES_MAX) return
+  diag.failures.push({ url: requestLabel(url), reason })
+}
+
+// The URL a fetch() call asks for: a Request's own, else its input as text.
+const requestUrl = (input) =>
+  input && typeof input === 'object' && typeof input.url === 'string' ? input.url : String(input)
 
 const requestShape = (args) => {
   const [input, init] = args
   const isRequest = input && typeof input === 'object' && typeof input.url === 'string'
-  const url = isRequest ? input.url : String(input)
+  const url = requestUrl(input)
   const method = String((init && init.method) || (isRequest && input.method) || 'GET').toUpperCase()
   const headers = {}
   // Any fetch HeadersInit, read like the REST adapter reads one (headerEntries).
@@ -743,7 +865,8 @@ const trackFetches = () => {
     const done = () => { if (!settled) { settled = true; _inFlight-- } }
     // a pending body read counts as in flight: the flush waits for it too
     const track = (promise) => { _inFlight++; promise.then(() => { _inFlight-- }, () => { _inFlight-- }) }
-    const seed = _seed && !_seed.tainted ? _seed : null
+    const seed = liveRecord(SEED)
+    const diag = liveRecord(DIAG)
     let shape = null
     if (seed) {
       try {
@@ -752,18 +875,24 @@ const trackFetches = () => {
           Object.keys(shape.headers).some((h) => !SEED_HEADERS_OK.has(h))) shape = null
       } catch { shape = null }
     }
+    const urlOf = () => requestUrl(args[0])
     let result
     try {
       result = inner.apply(this, args)
     } catch (err) {
+      recordFailure(diag, urlOf(), (err && err.message) || 'failed')
       done()
       throw err
     }
     if (result && typeof result.then === 'function') {
       result.then((response) => {
         if (shape) recordAnswer(seed, shape, response, track)
+        if (diag && response && response.ok === false) recordFailure(diag, urlOf(), 'HTTP ' + response.status)
+        done()
+      }, (err) => {
+        recordFailure(diag, urlOf(), (err && err.message) || 'network error')
         done()
-      }, done)
+      })
     } else done()
     return result
   }
@@ -795,55 +924,35 @@ export const render = async (data, options = {}) => {
   // pathname is the actual URL path (e.g. /podcast/abc-123), route is the page pattern (e.g. /podcast/:id)
   const locationPath = pathname || route
 
-  // ── SSR data prefetching ──
-  // When prefetch is enabled, walk the page definition to find fetch
-  // declarations, execute them against the DB adapter, and inject
-  // the results into element state before rendering.
-  // Set up globalThis.location early so fetch params that reference
-  // window.location.pathname (e.g. to extract :id from URL) work during prefetch.
-  const _prevLocPrefetch = globalThis.location
-  const _prevWinPrefetch = globalThis.window
-  if (!globalThis.location || globalThis.location.pathname !== locationPath) {
-    globalThis.location = { pathname: locationPath, href: locationPath, search: '', hash: '', origin: '' }
-  }
-  if (!globalThis.window) {
-    globalThis.window = { location: globalThis.location }
-  }
-  let prefetchedPages
-  if (prefetch) {
-    try {
-      const pages = data.pages || {}
-      prefetchedPages = { ...pages }
-      const stateUpdates = await prefetchPageData(data, route)
-      if (stateUpdates.size) {
-        // Deep clone the page def to avoid mutating the original
-        const pageDef = JSON.parse(JSON.stringify(pages[route], (key, value) => {
-          if (typeof value === 'function') return undefined
-          return value
-        }))
-        // Re-attach functions from original
-        const copyFunctions = (src, dst) => {
-          if (!src || !dst) return
-          for (const k in src) {
-            if (typeof src[k] === 'function') {
-              dst[k] = src[k]
-            } else if (typeof src[k] === 'object' && src[k] !== null && !Array.isArray(src[k]) && typeof dst[k] === 'object' && dst[k] !== null) {
-              copyFunctions(src[k], dst[k])
-            }
-          }
-        }
-        copyFunctions(pages[route], pageDef)
-        injectPrefetchedState(pageDef, stateUpdates)
-        prefetchedPages[route] = pageDef
-      }
-    } catch (prefetchErr) {
-      console.error('[brender] Prefetch error:', prefetchErr)
-      prefetchedPages = data.pages
-    }
+  // This render's diagnostics (see `DIAG`), open before its first request.
+  trackFetches()
+  const diag = openRenderRecord(DIAG, () => ({ failures: [], labelKeys: new Set(), tainted: false }))
+  try {
+    return await renderWithDiagnostics(data, { route, locationPath, stateOverrides, contextOverrides, prefetch }, diag.record)
+  } finally {
+    diag.close()
   }
+}
+
+const renderWithDiagnostics = async (data, { route, locationPath, stateOverrides, contextOverrides, prefetch }, diag) => {
+  // The page's data is NOT fetched here. The fetch plugin runs during the
+  // render below with the real element — its `transform(data, el, state)`,
+  // its `children` re-run on the answer — and the post-create flush waits
+  // for its requests. A pre-fetch used to run every page `fetch` through a
+  // second code path: `transform(data)` without the element (a transform
+  // reading `el.call(...)` threw, so the RAW rows landed in state) and
+  // `children` functions evaluated once with a stand-in element whose
+  // call() hard-coded 'ka' and read the wrong argument, then frozen into
+  // static arrays the real answer could no longer replace — cards without
+  // titles, a calendar of NaN (xma.info report, brender build items 5, 13).
 
   // ── SSR polyglot translations ──
-  // Fetch translations from the DB so polyglot resolves during render
+  // Labels a project serves through a table/RPC (`polyglot.fetch: { rpc }`)
+  // are fetched before the render, for every language. A FUNCTION
+  // `polyglot.fetch` is the project's own loader: it runs inside the render,
+  // called by the polyglot plugin with the real root element (see
+  // fetchSSRTranslations), and its labels are read back from the root state
+  // afterwards (renderedLabels).
   let ssrTranslations
   if (prefetch) {
     try {
@@ -853,24 +962,27 @@ export const render = async (data, options = {}) => {
     }
   }
 
-  // Restore location/window before createEnv sets them properly
-  if (_prevLocPrefetch !== undefined) globalThis.location = _prevLocPrefetch
-  else delete globalThis.location
-  if (_prevWinPrefetch !== undefined) globalThis.window = _prevWinPrefetch
-  else delete globalThis.window
-
   const { window, document } = createEnv()
   const body = document.body
 
   // Set route on location so the router picks it up
   window.location.pathname = locationPath
 
-  // Set globalThis.document/location so the bundled smbls code
-  // (which uses `window = globalThis`) can access them during SSR.
-  const _prevDoc = globalThis.document
-  const _prevLoc = globalThis.location
-  globalThis.document = document
-  globalThis.location = window.location
+  // globalThis.document/location for the bundled smbls code (which uses
+  // `window = globalThis`) during SSR, and the render's own storage behind
+  // the bare `localStorage` the framework reads (smbls prepareState):
+  // polyglot persists the language a page switched to and the labels it
+  // loaded there, and one shared store handed them to the next page of the
+  // build (createEnv). Swapped by descriptor and put back however the render
+  // ends, a throw included — a host's own Web Storage global (Node's is a
+  // lazy accessor) is never read or lost.
+  const restoreGlobals = [
+    swapGlobal('document', document),
+    swapGlobal('location', window.location),
+    swapGlobal('localStorage', window.localStorage),
+    swapGlobal('sessionStorage', window.sessionStorage)
+  ]
+  try {
 
   // Import createDomqlElement via bundled smbls source.
   // The smbls monorepo uses extensionless/directory imports that Node.js ESM
@@ -903,7 +1015,7 @@ export const render = async (data, options = {}) => {
   if (ssrTranslations || polyglotConfig) {
     if (!baseState.root) baseState.root = {}
     if (polyglotConfig) {
-      baseState.root.lang = baseState.root.lang || polyglotConfig.defaultLang || 'en'
+      baseState.root.lang = polyglotFallbackLang(baseState.root.lang, polyglotConfig)
     }
     if (ssrTranslations) {
       baseState.root.translations = {
@@ -939,7 +1051,7 @@ export const render = async (data, options = {}) => {
     dependencies: structuredCloneDeep(data.dependencies || {}),
     components: structuredCloneDeep(data.components || {}),
     snippets: structuredCloneDeep(data.snippets || {}),
-    pages: structuredCloneDeep(prefetchedPages || data.pages || {}),
+    pages: structuredCloneDeep(data.pages || {}),
     functions: {
       ...(data.functions || {}),
       // SSR polyglot functions — enable {{ key | polyglot }} resolution during render
@@ -962,6 +1074,11 @@ export const render = async (data, options = {}) => {
     // Disable sourcemap tracking in SSR — it causes stack overflows
     // when state contains large data arrays (articles, events, etc.)
     domqlOptions: { sourcemap: false },
+    // The server builds the page in one go: the browser boot's short tasks
+    // (smbls firstRender.js) serve input and paint, and a server has neither.
+    // smbls skips them by itself in a realm without requestAnimationFrame;
+    // this document shims it (env.js), so it says so here.
+    firstRender: false,
     // Editor/live-sync, inspector and toast plugins have no place in server
     // markup. The source-bundle path used to stub @symbo.ls/sync to no-ops at
     // bundle time; the installed `smbls/ssr` entry carries the real plugins,
@@ -971,6 +1088,19 @@ export const render = async (data, options = {}) => {
     sync: false,
     inspect: false,
     notifications: false,
+    // Every server render processes the design system the way the page's
+    // own single boot does, on a config of its own — the first render of a
+    // process used to share the global config and every later one took the
+    // iframe path, so their theme variables differed (smbls
+    // prepareDesignSystem; xma.info report, brender build item 7).
+    isolateDesignSystem: true,
+    // Every server render starts from an empty query cache (@symbo.ls/fetch
+    // enterContext). The fetch plugin's cache outlives a render, so a page
+    // rendered after another one that read the same key showed those rows
+    // without a request, and its fetch seed — recorded from requests — did
+    // not carry them: the browser asked for them again after boot (xma.info,
+    // 2026-10-16: index.html 10 seed entries, about.html 3).
+    isolateFetchCache: true,
     // Caller overrides
     ...(contextOverrides || {})
   }
@@ -986,21 +1116,19 @@ export const render = async (data, options = {}) => {
 
   resetKeys()
 
-  trackFetches()
-  // the recording of this render's answers (see `_seed`): tainted the moment
+  // the recording of this render's answers (see `SEED`): tainted the moment
   // another render overlaps it
-  _activeRenders++
-  if (_activeRenders === 1) _seed = { entries: [], bytes: 0, tainted: false }
-  else if (_seed) _seed.tainted = true
-  const seed = _seed
+  const recording = openRenderRecord(SEED, () => ({ entries: [], bytes: 0, tainted: false }))
+  const seed = recording.record
   let element
   try {
     element = await createDomqlElement(app, ctx)
 
     // Allow async operations (fetch callbacks, state updates, re-renders) to flush.
-    // DOMQL's fetch plugin fires on element creation and updates state asynchronously.
-    // With prefetch enabled, data is pre-injected but DOMQL's fetch may also fire
-    // and trigger state updates. Give enough time for these to complete.
+    // DOMQL's fetch plugin fires on element creation and updates state
+    // asynchronously — it is what loads the page's data (nothing is
+    // pre-injected) — and a function polyglot.fetch loads the labels the
+    // same way. Give enough time for these to complete.
     //
     // It used to sleep a flat 2000 ms with prefetch — measured in workerd on
     // six published projects, `flush` was 2000 ms on every route, 40–90 % of
@@ -1019,8 +1147,7 @@ export const render = async (data, options = {}) => {
       if (inFlightRequests() === 0) await sleep(Math.max(0, Math.min(50, flushCap - (Date.now() - flushStart))))
     }
   } finally {
-    _activeRenders--
-    if (_seed === seed) _seed = null
+    recording.close()
   }
   const fetchSeed = seed && !seed.tainted ? seed.entries.slice() : []
 
@@ -1062,24 +1189,106 @@ export const render = async (data, options = {}) => {
 
   let html = fixSvgContent(body.innerHTML)
 
+  // The language this page was rendered in and the labels it ended with:
+  // the ones fetched before the render plus whatever the project's own
+  // polyglot.fetch loaded into the root state during it.
+  const root = element?.state?.root
+  const activeLang = activeLangOf(root, polyglotConfig)
+  const labels = renderedLabels(ssrTranslations, root)
+
   // Post-process: resolve any remaining {{ key | polyglot }} templates
-  // that weren't resolved during DOMQL rendering (e.g. due to timing)
-  if (ssrTranslations) {
-    const defaultLang = polyglotConfig?.defaultLang || 'en'
-    const langMap = ssrTranslations[defaultLang] || Object.values(ssrTranslations)[0] || {}
-    html = html.replace(/\{\{\s*([^|{}]+?)\s*\|\s*polyglot\s*\}\}/g, (match, key) => {
-      const trimmed = key.trim()
-      return langMap[trimmed] ?? match
-    })
+  // that weren't resolved during DOMQL rendering (e.g. due to timing) — in
+  // the page's language. It used the default language, so a page rendered
+  // for /en/… got its leftover templates in the default language's words
+  // (xma.info report, brender build item 8).
+  if (labels) html = resolveLabelTemplates(html, labelMapFor(labels, activeLang, polyglotConfig))
+
+  const diagnostics = diag && !diag.tainted
+    ? {
+        failedRequests: diag.failures.slice(),
+        rawLabelKeys: rawLabelKeys(diag.labelKeys, html, activeLang, polyglotConfig, root)
+      }
+    : null
+
+  return { html, metadata, registry, brRegistry, element, emotionCSS, globalCSS, classRules, fetchSeed, document, window, ssrTranslations: labels || undefined, activeLang, diagnostics }
+  } finally {
+    for (const restore of restoreGlobals) restore()
   }
+}
 
-  // Restore globalThis after render
-  if (_prevDoc !== undefined) globalThis.document = _prevDoc
-  else delete globalThis.document
-  if (_prevLoc !== undefined) globalThis.location = _prevLoc
-  else delete globalThis.location
+// Put `value` on globalThis[name] for a render and hand back what puts the
+// old property back, descriptor and all. Never reads the old value — a host
+// global can be a lazy accessor that warns or throws when read.
+const swapGlobal = (name, value) => {
+  const previous = Object.getOwnPropertyDescriptor(globalThis, name)
+  if (previous && !previous.configurable) {
+    if (!previous.writable && !previous.set) return () => {}
+    globalThis[name] = value
+    return () => {}
+  }
+  Object.defineProperty(globalThis, name, { value, writable: true, configurable: true, enumerable: true })
+  return () => {
+    if (previous) Object.defineProperty(globalThis, name, previous)
+    else delete globalThis[name]
+  }
+}
+
+// ── Labels after a render ───────────────────────────────────────────────────
+
+const LABEL_TEMPLATE = /\{\{\s*([^|{}]+?)\s*\|\s*polyglot\s*\}\}/g
+
+const plainOf = (value) => value && typeof value.parse === 'function' ? value.parse() : value
+
+// The labels a render ended with, by language: the ones fetched before it
+// (`ssrTranslations`), with the root state's own — loaded during the render
+// by the project's polyglot.fetch — over them. Null when there are none.
+const renderedLabels = (ssrTranslations, root) => {
+  const loaded = plainOf(root?.translations)
+  const out = {}
+  for (const source of [ssrTranslations, loaded]) {
+    if (!source || typeof source !== 'object') continue
+    for (const lang in source) {
+      const map = plainOf(source[lang])
+      if (map && typeof map === 'object') out[lang] = { ...(out[lang] || {}), ...map }
+    }
+  }
+  return Object.keys(out).length ? out : null
+}
+
+// One language's labels: the page's, else the default language's, else the
+// first there is — the order the post-render pass always fell back in.
+const labelMapFor = (labels, activeLang, poly) =>
+  labels[activeLang] || labels[polyglotFallbackLang(undefined, poly)] || Object.values(labels)[0] || {}
 
-  return { html, metadata, registry, brRegistry, element, emotionCSS, globalCSS, classRules, fetchSeed, document, window, ssrTranslations, prefetchedPages }
+const resolveLabelTemplates = (html, langMap) =>
+  html.replace(LABEL_TEMPLATE, (match, key) => {
+    const val = ssrResolve(langMap, key.trim())
+    return val ?? match
+  })
+
+// JSON data blocks (registry, fetch seed) are data, not what a visitor reads.
+const DATA_BLOCK = /<script\b[^>]*\btype\s*=\s*["']?application\/json["']?[^>]*>[\s\S]*?<\/script\s*>/gi
+// The key as a whole token: not part of a longer key or word.
+const keyInMarkup = (markup, key) =>
+  new RegExp(`(?:^|[^\\w.-])${escapeRegExp(key)}(?![\\w-]|\\.\\w)`).test(markup)
+
+// The label keys a page shows raw: every key ssrTranslate missed that the
+// labels the render ended with still do not have AND that reached the
+// markup, plus every `{{ key | polyglot }}` template left in it. A lookup
+// whose result never rendered (a discarded value, a branch not taken) is no
+// raw key on screen — XMA /vlog failed `--strict` on `ui.vlog.desc`, which
+// appeared 0 times in the page. A miss with whitespace in it is text handed
+// to `polyglot`, not a key.
+const rawLabelKeys = (missed, html, activeLang, poly, root) => {
+  const raw = new Set()
+  const markup = html.replace(DATA_BLOCK, '')
+  for (const key of missed) {
+    if (/\s/.test(key)) continue
+    if (findLabel(key, activeLang, poly, root) !== undefined) continue
+    if (keyInMarkup(markup, key)) raw.add(key)
+  }
+  for (const m of markup.matchAll(LABEL_TEMPLATE)) raw.add(m[1].trim())
+  return [...raw]
 }
 
 /**
@@ -1284,8 +1493,9 @@ export const replaceEmotionCSS = (html, newCSS) => {
  * @returns {Promise<{ html: string, css: string, resetCss: string, fontLinks: string, metadata: object, brKeyCount: number }>}
  */
 export const renderRoute = async (data, options = {}) => {
-  // `prefetch: false` renders without the DB prefetch and translation fetch
-  // — the publish-time pre-render (smbls publish → ssrCache) renders data-free.
+  // `prefetch: false` fetches no table/RPC labels first and does not wait for
+  // the page's requests — the publish-time pre-render (smbls publish →
+  // ssrCache) renders data-free.
   const { route = '/', pathname, prefetch = true } = options
 
   // Use the full render pipeline which handles polyglot, prefetch, emotion, etc.
@@ -1296,39 +1506,16 @@ export const renderRoute = async (data, options = {}) => {
   const ds = data.designSystem || {}
   const globalCSS = result.globalCSS
 
-  // Extract prefetched state and language for metadata resolution
+  // The page data the render ended with and its language, for a caller's
+  // metadata (mermaid's fallback reads them). The data is what the fetch
+  // plugin put into state during the render (collectFetchedState) — it used
+  // to be the RAW rows a pre-fetch had injected into the page definition.
   let prefetchedState = null
-  let activeLang = null
   try {
-    const el = result.element
-    const polyglot = el?.context?.polyglot || data.polyglot || data.config?.polyglot
-    activeLang = el?.state?.root?.lang || polyglot?.defaultLang || 'en'
-
-    // Get prefetched data from the injected page definitions (pre-DOMQL proxy)
-    if (result.prefetchedPages && result.prefetchedPages[route]) {
-      const pageDef = result.prefetchedPages[route]
-      // Collect all state entries from the page definition tree
-      const collectStates = (def, result = {}) => {
-        if (!def || typeof def !== 'object') return result
-        if (def.state && typeof def.state === 'object') {
-          for (const [k, v] of Object.entries(def.state)) {
-            if (v !== undefined && v !== null && typeof v !== 'function') {
-              result[k] = v
-            }
-          }
-        }
-        // Recurse into all child definitions (not just those with state)
-        for (const [key, child] of Object.entries(def)) {
-          if (key === 'state' || key === 'props' || key === 'attr' || key === 'on' || key === 'define' || key === '__ref' || key.startsWith('__')) continue
-          if (child && typeof child === 'object' && !Array.isArray(child)) {
-            collectStates(child, result)
-          }
-        }
-        return result
-      }
-      prefetchedState = collectStates(pageDef)
-    }
+    const fetched = collectFetchedState(result.element)
+    if (Object.keys(fetched).length) prefetchedState = fetched
   } catch (e) { /* ignore */ }
+  const activeLang = result.activeLang
 
   return {
     html: result.html,
@@ -1342,14 +1529,39 @@ export const renderRoute = async (data, options = {}) => {
     metadata: result.metadata || extractMetadata(data, route),
     brKeyCount: result.registry ? Object.keys(result.registry).length : 0,
     brRegistry: result.brRegistry || {},
-    // anonymous GET answers this render got (see `_seed`) — for adoptionScripts
+    // anonymous GET answers this render got (see `SEED`) — for adoptionScripts
     fetchSeed: result.fetchSeed || [],
     ssrTranslations: result.ssrTranslations,
     prefetchedState,
-    activeLang
+    activeLang,
+    // failed requests and raw label keys (see `DIAG`); null when an
+    // overlapping render made them unknowable
+    diagnostics: result.diagnostics
   }
 }
 
+// What the fetch plugin put into state during a render, by the `as` key each
+// `fetch` config names — a `~/key` one read off the root state. Configs
+// without `as` (a transform spreading into the element's state) and function
+// configs are not read: a function would have to run again.
+const collectFetchedState = (element) => {
+  const out = {}
+  walkElements(element, (el) => {
+    const decl = el.fetch
+    if (!decl || typeof decl !== 'object' || !el.state) return
+    for (const cfg of Array.isArray(decl) ? decl : [decl]) {
+      const as = cfg && typeof cfg === 'object' && typeof cfg.as === 'string' ? cfg.as : null
+      if (!as) continue
+      const fromRoot = as.startsWith('~/')
+      const name = fromRoot ? as.slice(2) : as
+      const source = fromRoot ? el.state.root : el.state
+      const value = plainOf(source && source[name])
+      if (name && value != null && typeof value !== 'function') out[name] = value
+    }
+  })
+  return out
+}
+
 // ── Full page SSR ─────────────────────────────────────────────────────────────
 
 /**
@@ -1366,12 +1578,20 @@ export const renderRoute = async (data, options = {}) => {
  * @param {string} [options.themeColor] - theme-color meta
  * @param {object} [options.isr] - ISR options with clientScript path
  * @param {boolean} [options.hydrate=true] - With `isr`: boot the client over the
- *   pre-rendered markup (`__BRENDER__`; the client replaces it with a fresh
- *   render) instead of the legacy swap script
- * @param {boolean} [options.adoptDom=false] - Opt-in hydration: also ship the
- *   element-path registry, `__BRENDER_HYDRATE__` and the recorded anonymous
- *   fetch answers, so the client ADOPTS the server DOM (smbls hydrateRender)
- * @param {boolean} [options.prefetch=true] - Whether to prefetch data via DB adapter
+ *   pre-rendered markup (the page's `<meta name="brender">`) instead of the
+ *   legacy swap script
+ * @param {boolean} [options.adoptDom=false] - Hydration: also ship the
+ *   element-path registry (a JSON data block), so the client ADOPTS the
+ *   server DOM (smbls prerender.js) instead of replacing it. `smbls build`
+ *   passes symbols.json `brender.hydrate` (cli helpers/runBrender.js).
+ * @param {string} [options.nonce] - The Content-Security-Policy nonce for the
+ *   inline scripts the page needs (the ISR paths only: a page rendered into a
+ *   shell carries none — its flag is a <meta>, its registry and fetch seed are
+ *   data blocks, which no policy blocks)
+ * @param {boolean} [options.prefetch=true] - Fetch table/RPC labels before the
+ *   render and wait (up to 2 s) for the requests the page starts; false waits
+ *   only a 50 ms quiet period. The page's data always comes from the fetch
+ *   plugin during the render.
  * @param {string} [options.shell] - A built app document (e.g. dist/index.html)
  *   to render INTO instead of emitting a standalone document (see shell.js).
  *   The result then carries `shell: true`.
@@ -1381,13 +1601,18 @@ export const renderRoute = async (data, options = {}) => {
  * @returns {Promise<{ html: string, route: string, brKeyCount: number, shell?: true }>}
  */
 export const renderPage = async (data, route = '/', options = {}) => {
-  const { lang, themeColor, isr, hydrate = true, prefetch = true, shell, adoptDom = false } = options
+  const { lang, themeColor, isr, hydrate = true, prefetch = true, shell, adoptDom = false, pathname, eagerImages = EAGER_IMAGES_DEFAULT, preloadScripts = true, nonce } = options
+  const nonceAttr = nonceAttribute(nonce)
 
   // Detect lang from project config, app metadata, or default
   const htmlLang = lang || data.state?.lang || data.app?.metadata?.lang || 'en'
 
-  // Use the full smbls pipeline for rendering
-  const result = await render(data, { route, prefetch })
+  // Use the full smbls pipeline for rendering. `pathname` is the address the
+  // page is rendered at — the router matches it, location and every
+  // canonical/og:url built from it read it. Without it a route was rendered
+  // at its own pattern: the `/*` page wrote a `/*` canonical into 404.html
+  // (xma.info report, brender build item 7).
+  const result = await render(data, { route, pathname, prefetch })
   if (!result) return null
 
   const metadata = { ...result.metadata }
@@ -1431,9 +1656,11 @@ export const renderPage = async (data, route = '/', options = {}) => {
 
   const brKeyCount = Object.keys(result.registry).length
 
-  // The element-path registry — with the opt-in hydration flag and the
-  // recorded fetch answers under `adoptDom` (adoptionScripts).
-  const bootScripts = adoptionScripts({ brRegistry: result.brRegistry, fetchSeed: result.fetchSeed, hydrateFlag: adoptDom })
+  // What the client boots with (prerenderParts): the page's mark for <head>,
+  // and the data blocks after the markup — the registry under `adoptDom`,
+  // and the recorded anonymous answers, so the client renders from the data
+  // the server used instead of asking for all of it again.
+  const prerender = prerenderParts({ brRegistry: result.brRegistry, fetchSeed: result.fetchSeed, adoptDom })
 
   // ISR: include client SPA bundle for hydration + data fetching
   let isrBody = ''
@@ -1447,9 +1674,9 @@ export const renderPage = async (data, route = '/', options = {}) => {
     const prefix = depth > 0 ? '../'.repeat(depth) : './'
 
     if (hydrate) {
-      // True hydration: signal the SPA to adopt existing DOM nodes
-      // instead of creating new ones. The SPA detects __BRENDER__ flag
-      // and uses onlyResolveExtends + node adoption.
+      // The client boots over the markup: it knows the page by its
+      // `<meta name="brender">` and adopts the markup when the page carries
+      // the registry (`adoptDom`), else replaces it (smbls prerender.js).
       //
       // Seed client-side polyglot with SSR translations so that
       // el.call('polyglot', key) resolves immediately during hydration
@@ -1467,20 +1694,20 @@ export const renderPage = async (data, route = '/', options = {}) => {
           }
         }
         if (storageLangKey) {
-          const defaultLang = polyglotCfg?.defaultLang || 'en'
+          const defaultLang = polyglotFallbackLang(undefined, polyglotCfg)
           seedEntries.push(`if(!localStorage.getItem(${JSON.stringify(storageLangKey)}))localStorage.setItem(${JSON.stringify(storageLangKey)},${JSON.stringify(defaultLang)})`)
         }
         if (seedEntries.length) {
-          translationSeed = `<script>try{${seedEntries.join(';')}}catch(e){}</script>\n`
+          translationSeed = `<script${nonceAttr}>try{${seedEntries.join(';')}}catch(e){}</script>\n`
         }
       }
-      // Embed BR registry for true DOM-adoption hydration
-      const brRegistryScript = bootScripts ? bootScripts + '\n' : ''
-      isrBody = `${translationSeed}${brRegistryScript}<script>window.__BRENDER__=true</script>
-<script type="module" src="${prefix}${isr.clientScript}"></script>`
+      // The registry and the fetch seed as data blocks; the page's mark is
+      // its <meta name="brender"> (no inline flag a policy could block).
+      const blocks = prerender.blocks ? prerender.blocks + '\n' : ''
+      isrBody = `${translationSeed}${blocks}<script type="module" src="${prefix}${isr.clientScript}"${nonceAttr}></script>`
     } else {
       // Legacy swap mode: SPA creates new DOM, MutationObserver removes brender nodes
-      isrBody = `<script type="module">
+      isrBody = `<script type="module"${nonceAttr}>
 {
   const brEls = document.querySelectorAll('body > :not(script):not(style)')
   const observer = new MutationObserver((mutations) => {
@@ -1497,42 +1724,56 @@ export const renderPage = async (data, route = '/', options = {}) => {
   observer.observe(document.body, { childList: true })
 }
 </script>
-<script type="module" src="${prefix}${isr.clientScript}"></script>`
+<script type="module" src="${prefix}${isr.clientScript}"${nonceAttr}></script>`
     }
   }
 
   // Resolve any {{ key | polyglot }} templates in head tags (title, meta, etc.)
+  // — in the page's language, with the labels the render ended with.
   const headConfig = { ...(data.config || {}) }
   if (data.polyglot && !headConfig.polyglot) headConfig.polyglot = data.polyglot
   const polyglotCfg = headConfig.polyglot
   let resolvedHeadTags = headTags
   if (polyglotCfg) {
-    const defaultLang = polyglotCfg.defaultLang || 'en'
     // Use SSR-fetched translations (from render result) merged with static translations
-    const translations = {
-      ...(polyglotCfg.translations || {}),
-      ...(result.ssrTranslations || {})
+    const translations = { ...(polyglotCfg.translations || {}) }
+    for (const lang in result.ssrTranslations || {}) {
+      translations[lang] = { ...(translations[lang] || {}), ...result.ssrTranslations[lang] }
     }
-    const langMap = translations[defaultLang] || {}
-    resolvedHeadTags = headTags.replace(/\{\{\s*([^|{}]+?)\s*\|\s*polyglot\s*\}\}/g, (match, key) => {
-      const trimmed = key.trim()
-      return langMap[trimmed] ?? match
-    })
+    resolvedHeadTags = resolveLabelTemplates(headTags, labelMapFor(translations, result.activeLang, polyglotCfg))
   }
 
+  // A template the head still carries is a raw key too.
+  const diagnostics = result.diagnostics
+  if (diagnostics) {
+    for (const m of resolvedHeadTags.matchAll(LABEL_TEMPLATE)) {
+      const key = m[1].trim()
+      if (!diagnostics.rawLabelKeys.includes(key)) diagnostics.rawLabelKeys.push(key)
+    }
+  }
+
+  // Images past the first `eagerImages` load lazily unless they say how to
+  // load (see markLazyImages).
+  const bodyHtml = markLazyImages(result.html, eagerImages)
+
   // Build path: render INTO the app's own built document (shell.js) — the
   // standalone document below carries no app code unless `isr` adds a
   // client bundle, so writing it over a bundler's dist/index.html shipped
   // pages that never booted.
   if (typeof shell === 'string') {
     const html = composeIntoShell(shell, {
-      headTags: resolvedHeadTags,
+      headTags: `${resolvedHeadTags}\n${prerender.meta}`,
       headEnd: [fontLinks, brenderStyle, emotionStyle].filter(Boolean).join('\n'),
-      body: result.html,
+      body: bodyHtml,
       depth: Number.isInteger(options.depth) ? options.depth : 0,
-      bootScripts: adoptDom ? bootScripts : ''
+      bootScripts: prerender.blocks,
+      // The page's language on <html>, as the client's polyglot sets it at
+      // boot — a page rendered for /en/… kept the shell's `lang="ka"`.
+      // Only when the project has languages (or the caller names one).
+      lang: lang || (polyglotCfg ? result.activeLang : undefined),
+      preloadScripts
     })
-    return { html, route, brKeyCount, shell: true }
+    return { html, route, brKeyCount, shell: true, diagnostics }
   }
 
   // (The empty line after the font links held a @font-face <style> that
@@ -1540,19 +1781,43 @@ export const renderPage = async (data, route = '/', options = {}) => {
   const html = `<!DOCTYPE html>
 <html lang="${htmlLang}">
 <head>
-${resolvedHeadTags}
+${resolvedHeadTags}${isr && isr.clientScript && hydrate ? `\n${prerender.meta}` : ''}
 ${fontLinks}
 
 ${brenderStyle}
 ${emotionStyle}
 </head>
 <body>
-${result.html}
+${bodyHtml}
 ${isrBody}
 </body>
 </html>`
 
-  return { html, route, brKeyCount }
+  return { html, route, brKeyCount, diagnostics }
+}
+
+// ── Images below the fold ───────────────────────────────────────────────────
+// A pre-rendered page's images are in the markup before the app's script,
+// and on a slow connection they took its bandwidth: measured on a throttled
+// phone, the app's 214 KB script finished at 2.65 s instead of 1.75 s while
+// 165–191 KB of images loaded (xma.info report, brender build item 14). The
+// server cannot see the fold, so the first `eager` images in document order
+// load as written and every later one that does not say how to load gets
+// `loading="lazy"` — a lazy image inside the viewport still loads right after
+// layout. An image that names its own `loading` is left alone. `eager:
+// false` turns this off.
+export const EAGER_IMAGES_DEFAULT = 2
+const IMG_TAG = /<img\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi
+const HAS_LOADING = /\sloading\s*=/i
+
+export const markLazyImages = (html, eager = EAGER_IMAGES_DEFAULT) => {
+  if (eager === false || eager == null || typeof html !== 'string') return html
+  const keep = Math.max(0, Number(eager) || 0)
+  let seen = 0
+  return html.replace(IMG_TAG, (tag) => {
+    if (seen++ < keep || HAS_LOADING.test(tag)) return tag
+    return tag.replace(/^<img\b/i, '<img loading="lazy"')
+  })
 }
 
 const generateFontLinks = (ds) => {
@@ -1581,3 +1846,38 @@ const generateFontLinks = (ds) => {
     `<link href="https://fonts.googleapis.com/css2?${params}&display=swap" rel="stylesheet">`
   ].join('\n')
 }
+
+// ── The page's boot data (CSP-safe) ─────────────────────────────────────────
+// A pre-rendered page tells the client what it is without one inline script:
+// XMA serves `script-src 'self'` (no 'unsafe-inline'), which blocked the
+// `<script>window.__BRENDER__=true</script>` flag — the client then created
+// the app from scratch and appended it after the server markup, two app
+// roots (XMA report, brender item 1). A policy blocks inline scripts, never
+// <meta> tags or data blocks. The format smbls reads (smbls prerender.js):
+//   meta    `<meta name="brender" content="hydrate|replace">` for <head>
+//   blocks  after the markup — the element-path registry under `adoptDom`
+//           (`<script type="application/json" data-brender="registry">`),
+//           and the recorded anonymous answers (@symbo.ls/fetch
+//           createEarlySeedBlock), which the client adopts instead of asking
+//           again. Placed after the markup, so they never delay its paint;
+//           the app's scripts run after them either way.
+// `adoptionScripts` above stays for older callers (the platform's renderer).
+export const prerenderParts = ({ brRegistry, fetchSeed, adoptDom = false } = {}) => {
+  const registry = adoptDom && brRegistry && Object.keys(brRegistry).length
+    ? brenderRegistryBlock(brRegistry)
+    : ''
+  const seed = createEarlySeedBlock(fetchSeed)
+  return {
+    meta: `<meta name="brender" content="${registry ? 'hydrate' : 'replace'}">`,
+    blocks: [registry, seed].filter(Boolean).join('\n')
+  }
+}
+
+// ` nonce="…"` for an inline script, or '' — a value that could break out of
+// the attribute is refused.
+const nonceAttribute = (nonce) => {
+  if (nonce == null || nonce === '') return ''
+  const value = String(nonce)
+  if (!/^[A-Za-z0-9+/=_-]+$/.test(value)) throw new Error('brender: a nonce is base64 or base64url text')
+  return ` nonce="${value}"`
+}