@symbo.ls/brender 3.14.661 → 3.14.663

package/render.js

@@ -8,7 +8,9 @@ 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 { createEarlySeedScript } from '@symbo.ls/fetch'
 
 // funcql plugin — enables evaluation of funcql schemas as property values
 // during SSR. Async-imported to avoid polluting non-funcql codepaths.
@@ -110,19 +112,6 @@ const structuredCloneDeep = (obj, seen = new WeakMap()) => {
   return clone
 }
 
-// JSON replacer that drops functions, circular refs, and non-serializable values
-const safeJsonReplacer = () => {
-  const seen = new WeakSet()
-  return (key, value) => {
-    if (typeof value === 'function') return undefined
-    if (typeof value === 'object' && value !== null) {
-      if (seen.has(value)) return undefined
-      seen.add(value)
-    }
-    return value
-  }
-}
-
 // ── Workspace detection ──────────────────────────────────────────────────────
 // Detect whether brender is running inside the monorepo or as an installed
 // npm package, and resolve paths accordingly.
@@ -257,26 +246,56 @@ const resolveDomqlPackage = (ws, pkg, ...subpath) => {
   return null
 }
 
-// ── Bundled import of createDomqlElement ──────────────────────────────────────
-// The smbls source tree uses extensionless/directory imports that Node.js ESM
-// cannot resolve natively. We bundle createDomql.js with esbuild (once, cached)
-// so all bare/directory specifiers are resolved at bundle time.
+// ── Loading createDomqlElement ────────────────────────────────────────────────
+// Three sources, in this order:
+//
+//   1. The smbls MONOREPO (brender running from plugins/brender next to
+//      packages/smbls/src): esbuild-bundle the live SOURCE createDomql.js, so
+//      framework development renders what is on disk.
+//   2. An INSTALLED smbls: its supported server-render entry, `smbls/ssr`
+//      (createDomqlElement + prepareContext, the same module instance as the
+//      `smbls` main entry). The published smbls ships bundles only — no src/,
+//      no dist/esm/src/ — so the old "bundle smbls's source" path failed every
+//      route of every npm install with "brender: cannot find createDomql.js"
+//      (xma.info report item 1). Rendering with the consumer's OWN smbls also
+//      keeps the server markup and the client that boots over it on one
+//      framework version; a createDomql prebuilt into brender's package would
+//      freeze whichever smbls brender was published against.
+//   3. Bundled runtimes (Cloudflare Workers — no import.meta.url, no
+//      filesystem): the same `smbls/ssr` specifier, a string literal the
+//      worker's bundler resolves and inlines. render.js used to import
+//      `./dist/createDomql.bundled.mjs` here, a file nothing ever built, so
+//      the mermaid worker fell back to client render on every request
+//      (FW-BRENDER-PREBUNDLED-CREATEDOMQL-NEVER-BUILT-WORKER-SSR-FALLS-BACK-1).
+//
+// An installed smbls OLDER than the ssr entry that still carries
+// src/createDomql.js (pre-54131b34d tarballs) keeps the source-bundle path.
 let _cachedCreateDomql = null
 
+// Exported for the packaging lock in __tests__/ssrEntryPackaging.test.js —
+// the specifier that test proves the packed smbls tarball serves.
+export const SMBLS_SSR_SPECIFIER = 'smbls/ssr'
+
+const importSmblsSsr = async () => {
+  // The literal (not the constant) is what a bundler can statically resolve.
+  const mod = await import('smbls/ssr')
+  if (typeof mod?.createDomqlElement !== 'function') {
+    throw new Error('smbls/ssr does not export createDomqlElement')
+  }
+  return mod
+}
+
 const bundleCreateDomql = async () => {
   if (_cachedCreateDomql) return _cachedCreateDomql
 
   const ws = detectWorkspace()
 
-  // In bundled environments (CF Workers), use the pre-bundled createDomql.
-  // Generated by: node scripts/prebundle-createDomql.js (or during npm prepublish)
   if (!_brenderRequire) {
     try {
-      const mod = await import('./dist/createDomql.bundled.mjs')
-      _cachedCreateDomql = mod
-      return mod
+      _cachedCreateDomql = await importSmblsSsr()
+      return _cachedCreateDomql
     } catch (err) {
-      throw new Error(`brender: pre-bundled createDomql not available in bundled runtime: ${err.message}`)
+      throw new Error(`brender: ${SMBLS_SSR_SPECIFIER} is not available in this bundled runtime (${err.message}). Bundle smbls ≥ the release that adds the smbls/ssr export alongside @symbo.ls/brender.`)
     }
   }
 
@@ -284,15 +303,25 @@ const bundleCreateDomql = async () => {
   let entry
   if (ws.isMonorepo) {
     entry = resolve(ws.monorepoRoot, 'packages', 'smbls', 'src', 'createDomql.js')
-  } else if (ws.smblsRoot) {
-    // Prefer src/ (shipped in smbls package), fall back to dist
-    const srcEntry = resolve(ws.smblsRoot, 'src', 'createDomql.js')
-    const distEntry = resolve(ws.smblsRoot, 'dist', 'esm', 'src', 'createDomql.js')
-    entry = existsSync(srcEntry) ? srcEntry : distEntry
-  }
-
-  if (!entry || !existsSync(entry)) {
-    throw new Error(`brender: cannot find createDomql.js (isMonorepo=${ws.isMonorepo}, entry=${entry})`)
+  } else {
+    let ssrError
+    try {
+      _cachedCreateDomql = await importSmblsSsr()
+      return _cachedCreateDomql
+    } catch (err) {
+      ssrError = err
+    }
+    // Legacy: an smbls that predates the ssr entry but still ships its source.
+    const srcEntry = ws.smblsRoot && resolve(ws.smblsRoot, 'src', 'createDomql.js')
+    if (srcEntry && existsSync(srcEntry)) {
+      entry = srcEntry
+    } else {
+      throw new Error(
+        `brender: cannot load ${SMBLS_SSR_SPECIFIER} (${ssrError.message}). ` +
+        'Server rendering needs smbls installed in this project, at a release that exports smbls/ssr' +
+        (ws.smblsRoot ? ` (found smbls at ${ws.smblsRoot}).` : ' (no smbls package found).')
+      )
+    }
   }
 
   const esbuild = await import('esbuild')
@@ -637,6 +666,116 @@ const buildPathRegistry = (element, path = '') => {
  * @param {object} [options.context] - Additional context overrides
  * @returns {Promise<{ html: string, metadata: object, registry: object, element: object }>}
  */
+// ── In-flight request tracking (the post-create flush) ──────────────────────
+// The render's flush waits for the requests a page starts while it renders
+// (fetch plugin, SDK, project code — all end in globalThis.fetch). One
+// counting wrapper is installed around whatever globalThis.fetch is at render
+// time and left in place: it returns the inner call's own promise untouched,
+// and re-installing per render would nest wrappers across concurrent renders
+// in one isolate. A host that swaps globalThis.fetch later gets wrapped again
+// on its next render. The count is process-wide — a concurrent render's
+// request can only make a flush wait longer, never cut one short, and the
+// flush is capped.
+let _inFlight = 0
+const FETCH_TRACKED = Symbol.for('brender.fetchTracked')
+const inFlightRequests = () => _inFlight
+// ── Recorded answers (the fetch seed, phase B) ──────────────────────────────
+// While exactly ONE render is running, the anonymous GETs it makes are
+// recorded — url, Accept-Language, status, content type, body — so the page
+// can carry them (@symbo.ls/fetch createEarlySeedScript) and the hydrating
+// client adopts them instead of asking again. A second render overlapping
+// in the same isolate taints the recording: another project's answers must
+// never land in this page, so an overlapped render carries none.
+// Only a GET whose headers are Accept-Language / Accept at most is recorded
+// (never a signed-in or keyed call), only an ok JSON or text answer, at most
+// SEED_ENTRY_MAX bytes each and SEED_TOTAL_MAX per page.
+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 requestShape = (args) => {
+  const [input, init] = args
+  const isRequest = input && typeof input === 'object' && typeof input.url === 'string'
+  const url = isRequest ? input.url : String(input)
+  const method = String((init && init.method) || (isRequest && input.method) || 'GET').toUpperCase()
+  const headers = {}
+  const add = (h) => {
+    if (!h) return
+    if (typeof h.forEach === 'function' && !Array.isArray(h)) h.forEach((v, k) => { headers[String(k).toLowerCase()] = String(v) })
+    else if (Array.isArray(h)) for (const [k, v] of h) headers[String(k).toLowerCase()] = String(v)
+    else for (const k in h) if (h[k] != null) headers[k.toLowerCase()] = String(h[k])
+  }
+  if (isRequest) add(input.headers)
+  if (init) add(init.headers)
+  return { url, method, headers }
+}
+
+const recordAnswer = (seed, shape, response, track) => {
+  if (!response || !response.ok || typeof response.clone !== 'function') return
+  const type = (response.headers && response.headers.get && response.headers.get('content-type')) || ''
+  if (!/json|^text\//i.test(type)) return
+  let copy
+  try { copy = response.clone() } catch { return }
+  track(copy.text().then((body) => {
+    if (seed.tainted || body.length > SEED_ENTRY_MAX || seed.bytes + body.length > SEED_TOTAL_MAX) return
+    seed.bytes += body.length
+    seed.entries.push({ url: shape.url, lang: shape.headers['accept-language'] || '', status: response.status, type, body })
+  }, () => {}))
+}
+
+const trackFetches = () => {
+  const inner = globalThis.fetch
+  if (typeof inner !== 'function' || inner[FETCH_TRACKED]) return
+  const tracked = function (...args) {
+    _inFlight++
+    let settled = false
+    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
+    let shape = null
+    if (seed) {
+      try {
+        shape = requestShape(args)
+        if (shape.method !== 'GET' || !/^https?:/i.test(shape.url) ||
+          Object.keys(shape.headers).some((h) => !SEED_HEADERS_OK.has(h))) shape = null
+      } catch { shape = null }
+    }
+    let result
+    try {
+      result = inner.apply(this, args)
+    } catch (err) {
+      done()
+      throw err
+    }
+    if (result && typeof result.then === 'function') {
+      result.then((response) => {
+        if (shape) recordAnswer(seed, shape, response, track)
+        done()
+      }, done)
+    } else done()
+    return result
+  }
+  tracked[FETCH_TRACKED] = true
+  globalThis.fetch = tracked
+}
+
+// ── Opt-in hydration boot scripts (phase B) ────────────────────────────────
+// What a page needs for the client to ADOPT the server DOM instead of
+// replacing it (smbls createDomql hydrateRender): the element-path registry,
+// the opt-in flag, and the recorded anonymous answers for the fetch plugin
+// (@symbo.ls/fetch createEarlySeedScript). Default off everywhere — a page
+// without these keeps the fresh client render.
+// FW-BRENDER-HYDRATION-AND-CF-DEPLOY-PROVIDER-1.
+export const adoptionScripts = ({ brRegistry, fetchSeed } = {}) => {
+  if (!brRegistry || !Object.keys(brRegistry).length) return ''
+  const registry = JSON.stringify(brRegistry).replace(/</g, '\\u003c')
+  return `<script>window.__BR_REGISTRY__=${registry};window.__BRENDER_HYDRATE__=true</script>` +
+    (fetchSeed && fetchSeed.length ? '\n' + createEarlySeedScript(fetchSeed) : '')
+}
+
 export const render = async (data, options = {}) => {
   const { route = '/', pathname, state: stateOverrides, context: contextOverrides, prefetch = false } = options
   // pathname is the actual URL path (e.g. /podcast/abc-123), route is the page pattern (e.g. /podcast/:id)
@@ -732,7 +871,7 @@ export const render = async (data, options = {}) => {
   if (data.polyglot && !config.polyglot) config.polyglot = data.polyglot
   if (data.fetch && !config.fetch) config.fetch = data.fetch
   if (data.router && !config.router) config.router = data.router
-  for (const k of ['useReset', 'useVariable', 'useFontImport', 'useIconSprite', 'useSvgSprite', 'useDefaultConfig', 'useDocumentTheme']) {
+  for (const k of SCRATCH_CONFIG_FLAGS) {
     if (data[k] != null && config[k] == null) config[k] = data[k]
   }
 
@@ -763,7 +902,25 @@ export const render = async (data, options = {}) => {
   // Reset the atomic CSS engine for this render pass
   resetCss()
 
+  // Every other top-level key of the payload, as the client gets it: the
+  // client boots with the WHOLE published payload as its context (mermaid
+  // bundle.js), so `globalScope` (frank's hoisted helpers behind `__scope.X`)
+  // and project-level context keys (`catalog`, `imageBase`, `siteUrl`, …)
+  // must be there on the server too — without them docs.symbols.app threw
+  // "__scope.isViewNavRoute is not a function" and shaker.ge read
+  // `this.context.catalog` as undefined (FW-BRENDER-HYDRATION-AND-CF-DEPLOY-
+  // PROVIDER-1). Cloned: a render must not write into a payload a multi-page
+  // build reuses. The explicit keys below still win.
+  const projectContext = {}
+  for (const key in data) {
+    if (key === 'app' || key === 'config' || key === 'pages' || key === 'components' ||
+      key === 'state' || key === 'snippets' || key === 'designSystem' || key === 'dependencies') continue
+    const value = data[key]
+    projectContext[key] = value && typeof value === 'object' ? structuredCloneDeep(value) : value
+  }
+
   const ctx = {
+    ...projectContext,
     state: baseState,
     ...(stateOverrides ? { state: { ...baseState, ...stateOverrides } } : {}),
     dependencies: structuredCloneDeep(data.dependencies || {}),
@@ -792,6 +949,15 @@ 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 },
+    // 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,
+    // so they are switched off here instead — after `...config`, because a
+    // project config that enables them for the browser must not attach
+    // SyncComponent / overlays to the pre-rendered DOM.
+    sync: false,
+    inspect: false,
+    notifications: false,
     // Caller overrides
     ...(contextOverrides || {})
   }
@@ -807,14 +973,42 @@ export const render = async (data, options = {}) => {
 
   resetKeys()
 
-  const 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.
-  const flushDelay = prefetch ? 2000 : 50
-  await new Promise(r => setTimeout(r, flushDelay))
+  trackFetches()
+  // 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
+  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.
+    //
+    // 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
+    // each platform pre-render. Now: a 50 ms quiet period, then — with
+    // prefetch — keep waiting while requests are in flight (the answers the
+    // flush exists for), each settled batch followed by another quiet period
+    // for the state updates and follow-up requests it triggers. The old
+    // 2000 ms stays the cap (FW-BRENDER-HYDRATION-AND-CF-DEPLOY-PROVIDER-1).
+    const flushStart = Date.now()
+    const flushCap = prefetch ? 2000 : 50
+    const sleep = (ms) => new Promise(r => setTimeout(r, ms))
+    await sleep(Math.min(50, flushCap))
+    while (prefetch && inFlightRequests() > 0 && Date.now() - flushStart < flushCap) {
+      while (inFlightRequests() > 0 && Date.now() - flushStart < flushCap) await sleep(10)
+      await sleep(Math.max(0, Math.min(50, flushCap - (Date.now() - flushStart))))
+    }
+  } finally {
+    _activeRenders--
+    if (_seed === seed) _seed = null
+  }
+  const fetchSeed = seed && !seed.tainted ? seed.entries.slice() : []
 
   // Assign data-br keys for hydration
   assignKeys(body)
@@ -832,20 +1026,30 @@ export const render = async (data, options = {}) => {
 
   // Extract CSS from style tags in virtual head (atomic CSS engine writes here)
   const emotionCSS = []
+  const capturedRules = []
   const head = document.head || document.querySelector('head')
   if (head) {
     for (const style of head.querySelectorAll('style')) {
       if (style.sheet && style.sheet.cssRules) {
         for (const rule of style.sheet.cssRules) {
-          if (rule.cssText) emotionCSS.push(rule.cssText)
+          if (rule.cssText) {
+            emotionCSS.push(rule.cssText)
+            capturedRules.push(rule)
+          }
         }
       }
       if (!emotionCSS.length) {
         const content = style.textContent || ''
-        if (content) emotionCSS.push(content)
+        if (content) {
+          emotionCSS.push(content)
+          capturedRules.push({ cssText: content })
+        }
       }
     }
   }
+  // globalCSS: the init-injected globals; classRules: everything else, in
+  // capture order (see splitCapturedCSS).
+  const { globalCSS, classRules } = splitCapturedCSS(capturedRules)
 
   let html = fixSvgContent(body.innerHTML)
 
@@ -866,7 +1070,7 @@ export const render = async (data, options = {}) => {
   if (_prevLoc !== undefined) globalThis.location = _prevLoc
   else delete globalThis.location
 
-  return { html, metadata, registry, brRegistry, element, emotionCSS, document, window, ssrTranslations, prefetchedPages }
+  return { html, metadata, registry, brRegistry, element, emotionCSS, globalCSS, classRules, fetchSeed, document, window, ssrTranslations, prefetchedPages }
 }
 
 /**
@@ -940,46 +1144,18 @@ const fixSvgContent = (html) => {
   )
 }
 
-// ── Global CSS generation ─────────────────────────────────────────────────────
-
-/**
- * Runs the scratch design-system pipeline (via esbuild bundling to work around
- * bare-import issues) to produce CSS variables and reset styles — the same
- * globals that the SPA runtime injects via emotion.injectGlobal.
- */
-let _cachedGlobalCSS = null
-
 // Frank serializes a project's `config.js` exports at the TOP LEVEL of the
 // data payload (not under `data.config`), so `globalTheme` / `themeStorageKey`
 // / `useReset` / etc. live alongside `components` / `pages` / `designSystem`.
-// Both renderRoute and renderPage used to call `generateGlobalCSS(ds,
-// data.config || data.settings)` which resolved to undefined for any project
-// pushed through frank — every config flag silently dropped, including
-// `globalTheme: 'light'`. The hardcoded `globalTheme: 'auto'` default in
-// generateGlobalCSS then won, prod always rendered in matchMedia-detected
-// theme regardless of what the project declared. Helper picks the config
-// flags from `data` whichever shape they arrive in.
+// render() lifts these into the render context, as the client's context
+// carries them — the global CSS is captured from that render, so a project's
+// `globalTheme: 'light'` decides which scheme lands in the :root fallback.
 const SCRATCH_CONFIG_FLAGS = [
   'globalTheme', 'themeStorageKey', 'themeRoot',
   'useReset', 'useVariable', 'useFontImport', 'useIconSprite', 'useSvgSprite',
   'useDocumentTheme', 'useDefaultConfig', 'useDefaultIcons',
   'useThemeSuffixedVars', 'verbose', 'semanticIcons',
 ]
-const pickProjectConfig = (data) => {
-  if (!data || typeof data !== 'object') return null
-  if (data.config && typeof data.config === 'object') return data.config
-  const out = {}
-  let any = false
-  for (const flag of SCRATCH_CONFIG_FLAGS) {
-    if (Object.prototype.hasOwnProperty.call(data, flag)) {
-      out[flag] = data[flag]
-      any = true
-    }
-  }
-  if (any) return out
-  return data.settings || null
-}
-
 // Serialise scratch `buildSkinVarStyles` output — `{ selector: { var: value },
 // '@media …': { selector: { var: value } } }` — as CSS text
 // (FW-SCRATCH-SKINS-DIMENSION-1).
@@ -1002,207 +1178,79 @@ export const skinRulesToCSS = (rules) => Object.entries(rules || {})
   .filter(Boolean)
   .join('\n\n')
 
-const generateGlobalCSS = async (ds, config) => {
-  if (_cachedGlobalCSS) return _cachedGlobalCSS
-
-  try {
-    const { existsSync, writeFileSync, unlinkSync } = await import('fs')
-    const { tmpdir } = await import('os')
-    const { randomBytes } = await import('crypto')
-
-    // Guard: skip if filesystem APIs aren't available (e.g. CF Workers)
-    try { tmpdir() } catch { return {} }
-
-    const esbuild = await import('esbuild')
-
-    // Write a temporary script that imports scratch, runs set(), and
-    // serialises the CSS_VARS + RESET objects as JSON.
-    const dsJson = JSON.stringify(ds || {}, safeJsonReplacer())
-    // Config may contain non-serializable values (e.g. a DB client with
-    // circular refs, functions). Strip those for the CSS generation script.
-    const cfgJson = JSON.stringify(config || {}, safeJsonReplacer())
-    const tmpEntry = join(tmpdir(), `br_global_${randomBytes(6).toString('hex')}.mjs`)
-    const tmpOut = join(tmpdir(), `br_global_${randomBytes(6).toString('hex')}_out.mjs`)
-
-    writeFileSync(tmpEntry, `
-      import { set, getActiveConfig, getFontFaceString } from '@symbo.ls/scratch'
-      // Namespace access for the skin builder: a scratch without it (version
-      // skew) gives an empty skin block instead of failing this whole bundle
-      // and, with it, every global rule.
-      import * as scratchNs from '@symbo.ls/scratch'
-      import { DEFAULT_CONFIG } from '@symbo.ls/default-config'
-
-      const ds = ${dsJson}
-      const cfg = ${cfgJson}
-
-      // Merge with defaults (same as initEmotion)
-      const merged = {}
-      for (const k in DEFAULT_CONFIG) merged[k] = DEFAULT_CONFIG[k]
-      for (const k in ds) {
-        if (typeof ds[k] === 'object' && !Array.isArray(ds[k]) && typeof merged[k] === 'object' && !Array.isArray(merged[k])) {
-          merged[k] = { ...merged[k], ...ds[k] }
-        } else {
-          merged[k] = ds[k]
-        }
-      }
-
-      const conf = set({
-        useReset: true,
-        useVariable: true,
-        useFontImport: true,
-        useDocumentTheme: true,
-        useDefaultConfig: true,
-        globalTheme: 'auto',
-        ...merged,
-        ...cfg
-      }, { newConfig: {} })
-
-      const result = {
-        CSS_VARS: conf.CSS_VARS || {},
-        CSS_MEDIA_VARS: conf.CSS_MEDIA_VARS || {},
-        // Skin rules — the same builder smbls init() injects on the client
-        // (FW-SCRATCH-SKINS-DIMENSION-1).
-        CSS_SKIN_RULES: typeof scratchNs.buildSkinVarStyles === 'function'
-          ? scratchNs.buildSkinVarStyles(conf.cssSkinVars, conf.cssSkinFallback, ':root')
-          : {},
-        reset: conf.reset || {},
-        animation: conf.animation || {}
-      }
-      // Export as globalThis so we can read it
-      globalThis.__BR_GLOBAL_CSS__ = result
-      export default result
-    `)
-
-    // Detect workspace layout (monorepo vs npm install)
-    const ws = detectWorkspace()
-
-    // Workspace resolve plugin: maps @symbo.ls/* and @symbo.ls/* to source paths
-    const workspacePlugin = {
-      name: 'workspace-resolve',
-      setup (build) {
-        build.onResolve({ filter: /^@symbo\.ls\// }, args => {
-          const pkg = args.path.replace('@symbo.ls/', '')
-          if (ws.isMonorepo) {
-            for (const dir of ['packages', 'plugins']) {
-              const src = resolve(ws.monorepoRoot, dir, pkg, 'src', 'index.js')
-              if (existsSync(src)) return { path: src }
-              const dist = resolve(ws.monorepoRoot, dir, pkg, 'index.js')
-              if (existsSync(dist)) return { path: dist }
-            }
-            const blank = resolve(ws.monorepoRoot, 'packages', 'default-config', 'blank', 'index.js')
-            if (pkg === 'default-config' && existsSync(blank)) return { path: blank }
-          } else {
-            const resolved = resolveSymbolsPackage(ws, pkg, 'src', 'index.js')
-            if (resolved && existsSync(resolved)) return { path: resolved }
-            const resolvedIdx = resolveSymbolsPackage(ws, pkg, 'index.js')
-            if (resolvedIdx && existsSync(resolvedIdx)) return { path: resolvedIdx }
-            if (pkg === 'default-config') {
-              const blank = resolveSymbolsPackage(ws, 'default-config', 'blank', 'index.js')
-              if (blank && existsSync(blank)) return { path: blank }
-            }
-          }
-        })
-        build.onResolve({ filter: /^@domql\// }, args => {
-          const pkg = args.path.replace('@symbo.ls/', '')
-          if (ws.isMonorepo) {
-            const src = resolve(ws.monorepoRoot, 'packages', 'domql', 'packages', pkg, 'src', 'index.js')
-            if (existsSync(src)) return { path: src }
-          } else {
-            const resolved = resolveDomqlPackage(ws, pkg, 'src', 'index.js')
-            if (resolved && existsSync(resolved)) return { path: resolved }
-            const resolvedIdx = resolveDomqlPackage(ws, pkg, 'index.js')
-            if (resolvedIdx && existsSync(resolvedIdx)) return { path: resolvedIdx }
-          }
-        })
-      }
-    }
-
-    await esbuild.build({
-      entryPoints: [tmpEntry],
-      bundle: true,
-      format: 'esm',
-      platform: 'node',
-      outfile: tmpOut,
-      write: true,
-      logLevel: 'silent',
-      plugins: [workspacePlugin],
-      nodePaths: ws.isMonorepo
-        ? [resolve(ws.monorepoRoot, 'node_modules')]
-        : [
-          ...(ws.smblsRoot ? [resolve(ws.smblsRoot, 'node_modules')] : []),
-          ...(ws.projectRoot ? [resolve(ws.projectRoot, 'node_modules')] : []),
-          ...(ws.smblsRoot ? [resolve(ws.smblsRoot, '..', '..', 'node_modules')] : [])
-        ].filter(p => existsSync(p)),
-      external: ['fs', 'path', 'os', 'crypto', 'url', 'http', 'https', 'stream', 'util', 'events', 'buffer', 'child_process', 'worker_threads', 'net', 'tls', 'dns', 'dgram', 'zlib', 'assert', 'querystring', 'string_decoder', 'readline', 'perf_hooks', 'async_hooks', 'v8', 'vm', 'cluster', 'inspector', 'module', 'process', 'tty', 'color-contrast-checker']
-    })
-
-    const mod = await import(`file://${tmpOut}`)
-    const data = mod.default || {}
-    try { unlinkSync(tmpEntry) } catch {} // cleanup: ignore if temp file already removed
-    try { unlinkSync(tmpOut) } catch {} // cleanup: ignore if temp file already removed
-
-    const cssVars = data.CSS_VARS || {}
-    const cssMediaVars = data.CSS_MEDIA_VARS || {}
-    const reset = data.RESET || {}
-    const animations = data.ANIMATION || {}
-
-    // ── :root CSS variables ──
-    const varDecls = Object.entries(cssVars)
-      .map(([k, v]) => `  ${k}: ${v}`)
-      .join(';\n')
-    let rootRule = varDecls ? `:root {\n${varDecls};\n}` : ''
-
-    // ── Theme-switching CSS vars (media queries + data-theme selectors) ──
-    const themeVarRules = Object.entries(cssMediaVars)
-      .map(([key, vars]) => {
-        const decls = Object.entries(vars)
-          .map(([k, v]) => `    ${k}: ${v}`)
-          .join(';\n')
-        if (!decls) return ''
-        if (key.startsWith('@media')) {
-          // Media query — only when no data-theme forces a theme
-          return `${key} {\n  :root:not([data-theme]) {\n${decls};\n  }\n}`
-        }
-        // Selector ([data-theme="..."]) — apply directly
-        return `${key} {\n${decls};\n}`
-      })
-      .filter(Boolean)
-      .join('\n\n')
-    if (themeVarRules) rootRule += '\n\n' + themeVarRules
-
-    // ── Skin rules ([data-skin] selectors + the reduced-transparency block) ──
-    // After the scheme blocks: on an equal specificity the skin wins, as it
-    // does in the hydrated page (smbls init injects them in the same order).
-    const skinRules = skinRulesToCSS(data.CSS_SKIN_RULES)
-    if (skinRules) rootRule += (rootRule ? '\n\n' : '') + skinRules
-
-    // ── Reset styles ──
-    const resetRules = generateResetCSS(reset)
-
-    // ── @keyframes animations ──
-    const keyframeRules = []
-    for (const name in animations) {
-      const frames = animations[name]
-      if (!frames || typeof frames !== 'object') continue
-      const frameRules = Object.entries(frames).map(([step, p]) => {
-        if (typeof p !== 'object') return ''
-        const decls = Object.entries(p).map(([k, v]) => `${camelToKebab(k)}: ${v}`).join('; ')
-        return `  ${step} { ${decls}; }`
-      }).join('\n')
-      keyframeRules.push(`@keyframes ${name} {\n${frameRules}\n}`)
-    }
+// ── Global CSS: the render's own capture, split ────────────────────────────
+// The rules smbls init injects into the virtual <head> during render() ARE
+// the page's global CSS — the :root variables, scheme and skin blocks, the
+// processed reset and every @keyframes — exactly what the client injects,
+// for THIS project and render. They are split off the captured sheet so a
+// page emits them once, ahead of the atomic classes, and so renderPage's
+// cross-page accumulation keeps only the classes.
+//
+// This replaced generateGlobalCSS, which re-derived the same CSS by bundling
+// a temp module with esbuild into tmpdir. It read data.RESET/data.ANIMATION
+// where the module exported reset/animation (resetRules and keyframeRules
+// were always '', and renderRoute fell back to the RAW design-system reset,
+// tokens unresolved); it threw on every cold Cloudflare isolate ("[unenv]
+// fs.writeFileSync is not implemented yet"); and its result was cached per
+// PROCESS, keyed on nothing, so a server rendering two projects gave the
+// second one the first one's :root (FW-BRENDER-HYDRATION-AND-CF-DEPLOY-PROVIDER-1).
+
+// A selector is global when no selector in its list targets a class — the
+// atomic engine's every rule does (`._p-a`, `.c1x:hover`, `[data-theme] .c2`).
+// Quoted strings and attribute brackets are masked first: a dot inside
+// `[href$=".pdf"]` is not a class.
+const CLASS_IN_SELECTOR = /\.[A-Za-z_\\-]/
+const isGlobalSelector = (selectorText) => {
+  if (typeof selectorText !== 'string' || !selectorText) return false
+  const masked = selectorText
+    .replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, '""')
+    .replace(/\[[^\]]*\]/g, '[]')
+  return !CLASS_IN_SELECTOR.test(masked)
+}
+const VARIABLE_SCOPE = /^\s*(:root|\[data-theme|\[data-skin)/
+
+// Classify one CSSOM rule: 'root' (variables, scheme and skin blocks),
+// 'keyframes', 'reset' (any other global rule), or null (stays with the
+// atomic classes).
+const classifyRule = (rule) => {
+  const text = rule && rule.cssText
+  if (typeof text !== 'string') return null
+  if (/^@(-webkit-)?keyframes\b/.test(text)) return 'keyframes'
+  // @font-face stays in the class stream (`css` / data-emotion), where every
+  // consumer — including a mermaid that predates this split and emits only
+  // rootRule/resetCss/keyframeRules + css — has always found it.
+  if (text.startsWith('@font-face')) return null
+  if (typeof rule.selectorText === 'string') {
+    if (!isGlobalSelector(rule.selectorText)) return null
+    return VARIABLE_SCOPE.test(rule.selectorText) ? 'root' : 'reset'
+  }
+  // A grouping rule (@media/@supports/@container) is global when all of its
+  // rules are; it joins the group its rules agree on.
+  const inner = rule.cssRules && Array.from(rule.cssRules)
+  if (inner && inner.length && /^@(media|supports|container)\b/.test(text)) {
+    const kinds = new Set(inner.map(classifyRule))
+    if (kinds.has(null) || kinds.size !== 1) return kinds.has(null) ? null : 'reset'
+    return [...kinds][0]
+  }
+  return null
+}
 
-    _cachedGlobalCSS = {
-      rootRule,
-      resetRules,
-      fontFaceCSS: '',
-      keyframeRules: keyframeRules.join('\n')
-    }
-    return _cachedGlobalCSS
-  } catch (err) {
-    console.warn('generateGlobalCSS failed:', err.message, err.stack)
-    _cachedGlobalCSS = { rootRule: '', resetRules: '', fontFaceCSS: '', keyframeRules: '' }
-    return _cachedGlobalCSS
+export const splitCapturedCSS = (rules) => {
+  const groups = { root: [], reset: [], keyframes: [] }
+  const rest = []
+  for (const rule of rules || []) {
+    const kind = classifyRule(rule)
+    if (kind) groups[kind].push(rule.cssText)
+    else if (rule && rule.cssText) rest.push(rule.cssText)
+  }
+  return {
+    globalCSS: {
+      rootRule: groups.root.join('\n'),
+      resetRules: groups.reset.join('\n'),
+      keyframeRules: groups.keyframes.join('\n'),
+      fontFaceCSS: ''
+    },
+    classRules: rest
   }
 }
 
@@ -1216,7 +1264,7 @@ let _accumulatedEmotionCSS = new Set()
 /**
  * Reset the cached global CSS and emotion CSS (useful when rendering multiple projects).
  */
-export const resetGlobalCSSCache = () => { _cachedGlobalCSS = null; _accumulatedEmotionCSS = new Set() }
+export const resetGlobalCSSCache = () => { _accumulatedEmotionCSS = new Set() }
 
 /**
  * Returns the complete accumulated emotion CSS from all renders so far.
@@ -1248,15 +1296,17 @@ 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 = {}) => {
-  const { route = '/', pathname } = options
+  // `prefetch: false` renders without the DB prefetch and translation fetch
+  // — 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.
   // Pass pathname so the virtual DOM location reflects the actual URL (for dynamic routes)
-  const result = await render(data, { route, pathname, prefetch: true })
+  const result = await render(data, { route, pathname, prefetch })
   if (!result) return null
 
   const ds = data.designSystem || {}
-  const globalCSS = await generateGlobalCSS(ds, pickProjectConfig(data))
+  const globalCSS = result.globalCSS
 
   // Extract prefetched state and language for metadata resolution
   let prefetchedState = null
@@ -1294,13 +1344,18 @@ export const renderRoute = async (data, options = {}) => {
 
   return {
     html: result.html,
-    css: result.emotionCSS ? result.emotionCSS.join('\n') : '',
+    css: result.classRules.join('\n'),
+    // the same rules as a list — a caller that unions several routes' CSS
+    // (the publish-time ssrCache) dedupes by rule
+    classRules: result.classRules.slice(),
     globalCSS,
-    resetCss: globalCSS.resetRules || generateResetCSS(ds.reset),
+    resetCss: globalCSS.resetRules,
     fontLinks: generateFontLinks(ds),
     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
+    fetchSeed: result.fetchSeed || [],
     ssrTranslations: result.ssrTranslations,
     prefetchedState,
     activeLang
@@ -1322,12 +1377,23 @@ export const renderRoute = async (data, options = {}) => {
  * @param {string} [options.lang='en'] - HTML lang attribute
  * @param {string} [options.themeColor] - theme-color meta
  * @param {object} [options.isr] - ISR options with clientScript path
- * @param {boolean} [options.hydrate=true] - Use true hydration (attach to existing DOM) instead of full SPA re-render
+ * @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
- * @returns {Promise<{ html: string, route: string, brKeyCount: number }>}
+ * @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`.
+ * @param {number} [options.depth] - Directory depth of the output file: rebases
+ *   the shell's relative asset URLs (with `shell`, default 0) and the ISR
+ *   client script path (default: derived from the route).
+ * @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 } = options
+  const { lang, themeColor, isr, hydrate = true, prefetch = true, shell, adoptDom = false } = options
 
   // Detect lang from project config, app metadata, or default
   const htmlLang = lang || data.state?.lang || data.app?.metadata?.lang || 'en'
@@ -1338,22 +1404,37 @@ export const renderPage = async (data, route = '/', options = {}) => {
 
   const metadata = { ...result.metadata }
   if (themeColor) metadata['theme-color'] = themeColor
+  // Rendering into a built shell: a title the project never declared is
+  // extractMetadata's fallback (`data.name || 'Symbols'`), and it must not
+  // replace the title the shell's author wrote — the client keeps that one
+  // too (helmet applies declared metadata only). Probed by handing
+  // extractMetadata a name nothing else can produce; the element and state
+  // go along so a function-valued title still counts as declared.
+  if (typeof shell === 'string' && !data.name) {
+    const probe = `\u0000brender-undeclared-title\u0000`
+    const probed = extractMetadata({ ...data, name: probe }, route, result.element, result.element?.state)
+    if (probed.title === probe) {
+      for (const key of ['title', 'og:title', 'twitter:title']) {
+        if (metadata[key] === result.metadata.title) delete metadata[key]
+      }
+    }
+  }
   const headTags = generateHeadHtml(metadata)
 
   // Accumulate emotion CSS from each page render.
   // Each page may introduce unique CSS classes not seen on previous pages.
   // Emotion's singleton cache only emits NEW classes per render, so we
   // collect all rules across renders to build the complete stylesheet.
-  if (result.emotionCSS && result.emotionCSS.length) {
-    for (const rule of result.emotionCSS) {
-      if (rule) _accumulatedEmotionCSS.add(rule)
-    }
+  // Only the classes accumulate: the globals are this page's own (one :root,
+  // one copy of each @keyframes — they used to pile up across pages).
+  for (const rule of result.classRules) {
+    if (rule) _accumulatedEmotionCSS.add(rule)
   }
   const emotionCSS = Array.from(_accumulatedEmotionCSS).join('\n')
 
-  // Generate global CSS (variables, reset, keyframes) via scratch pipeline
+  // Global CSS (variables, reset, keyframes): this render's own init output
   const ds = data.designSystem || {}
-  const globalCSS = await generateGlobalCSS(ds, pickProjectConfig(data))
+  const globalCSS = result.globalCSS
 
   // Generate font links from design system
   const fontLinks = generateFontLinks(ds)
@@ -1363,8 +1444,12 @@ export const renderPage = async (data, route = '/', options = {}) => {
   // ISR: include client SPA bundle for hydration + data fetching
   let isrBody = ''
   if (isr && isr.clientScript) {
-    // Calculate relative path from route directory to root
-    const depth = route === '/' ? 0 : route.replace(/^\/|\/$/g, '').split('/').length
+    // Calculate relative path from route directory to root — or take the
+    // caller's: the file a route is written to decides it ('/*' → 404.html
+    // sits at the root, not in a '*' directory).
+    const depth = Number.isInteger(options.depth)
+      ? options.depth
+      : route === '/' ? 0 : route.replace(/^\/|\/$/g, '').split('/').length
     const prefix = depth > 0 ? '../'.repeat(depth) : './'
 
     if (hydrate) {
@@ -1399,9 +1484,11 @@ export const renderPage = async (data, route = '/', options = {}) => {
       const brRegistryJson = result.brRegistry && Object.keys(result.brRegistry).length
         ? JSON.stringify(result.brRegistry)
         : null
-      const brRegistryScript = brRegistryJson
-        ? `<script>window.__BR_REGISTRY__=${brRegistryJson}</script>\n`
-        : ''
+      const brRegistryScript = adoptDom
+        ? (adoptionScripts(result) ? adoptionScripts(result) + '\n' : '')
+        : brRegistryJson
+          ? `<script>window.__BR_REGISTRY__=${brRegistryJson}</script>\n`
+          : ''
       isrBody = `${translationSeed}${brRegistryScript}<script>window.__BRENDER__=true</script>
 <script type="module" src="${prefix}${isr.clientScript}"></script>`
     } else {
@@ -1446,13 +1533,33 @@ export const renderPage = async (data, route = '/', options = {}) => {
     })
   }
 
+  // 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 styles = [
+      globalCSS.fontFaceCSS ? `<style data-brender>${globalCSS.fontFaceCSS}</style>` : '',
+      `<style data-brender>\n${globalCSS.rootRule || ''}\n${globalCSS.resetRules || ''}\n${globalCSS.keyframeRules || ''}\n</style>`,
+      emotionCSS ? `<style data-emotion="smbls">\n${emotionCSS}\n</style>` : ''
+    ]
+    const html = composeIntoShell(shell, {
+      headTags: resolvedHeadTags,
+      headEnd: [fontLinks, ...styles].filter(Boolean).join('\n'),
+      body: result.html,
+      depth: Number.isInteger(options.depth) ? options.depth : 0,
+      bootScripts: adoptDom ? adoptionScripts(result) : ''
+    })
+    return { html, route, brKeyCount, shell: true }
+  }
+
   const html = `<!DOCTYPE html>
 <html lang="${htmlLang}">
 <head>
 ${resolvedHeadTags}
 ${fontLinks}
-${globalCSS.fontFaceCSS ? `<style>${globalCSS.fontFaceCSS}</style>` : ''}
-<style>
+${globalCSS.fontFaceCSS ? `<style data-brender>${globalCSS.fontFaceCSS}</style>` : ''}
+<style data-brender>
 ${globalCSS.rootRule || ''}
 ${globalCSS.resetRules || ''}
 ${globalCSS.keyframeRules || ''}
@@ -1860,33 +1967,6 @@ const extractCSS = (element, ds) => {
   return [...keyframes, ...rules].join('\n')
 }
 
-const generateResetCSS = (reset) => {
-  if (!reset) return ''
-  const rules = []
-  for (const [selector, props] of Object.entries(reset)) {
-    if (!props || typeof props !== 'object') continue
-    const baseDecls = []
-    const mediaRules = []
-    for (const [k, v] of Object.entries(props)) {
-      if (typeof v === 'object' && v !== null) {
-        // Nested object: @media query or sub-selector
-        if (k.startsWith('@media') || k.startsWith('@')) {
-          const inner = Object.entries(v)
-            .filter(([, iv]) => typeof iv !== 'object')
-            .map(([ik, iv]) => `${camelToKebab(ik)}: ${iv}`)
-            .join('; ')
-          if (inner) mediaRules.push(`${k} { ${selector} { ${inner}; } }`)
-        }
-        continue
-      }
-      baseDecls.push(`${camelToKebab(k)}: ${v}`)
-    }
-    if (baseDecls.length) rules.push(`${selector} { ${baseDecls.join('; ')}; }`)
-    rules.push(...mediaRules)
-  }
-  return rules.join('\n')
-}
-
 const generateFontLinks = (ds) => {
   if (!ds) return ''
   const families = ds.font_family || ds.fontFamily || {}