@symbo.ls/brender 3.8.1 → 3.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbo.ls/brender",
-  "version": "3.8.1",
+  "version": "3.8.2",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "module": "./dist/esm/index.js",

package/render.js

@@ -543,6 +543,40 @@ const UIKIT_STUBS = {
   Text: { tag: 'span' }
 }
 
+// ── BR path registry ─────────────────────────────────────────────────────────
+
+/**
+ * Walks a DOMQL element tree (after mapKeysToElements has set __brKey on each
+ * element) and returns a plain object mapping "element path" → "data-br key".
+ *
+ * The path is a dot-separated chain of element keys from root to leaf:
+ *   '' (root element itself) → '__root'
+ *   'Header'                 → 'Header'
+ *   'Header.Nav'             → 'Header.Nav'
+ *
+ * The registry is serialized into the pre-rendered HTML so the browser can
+ * assign the correct brKey to each skeleton element during true hydration.
+ */
+const buildPathRegistry = (element, path = '') => {
+  if (!element || !element.__ref) return {}
+  const registry = {}
+
+  const brKey = element.__ref.__brKey
+  if (brKey) registry[path === '' ? '__root' : path] = brKey
+
+  if (element.__ref.__children) {
+    for (const childKey of element.__ref.__children) {
+      const child = element[childKey]
+      if (child && child.__ref) {
+        const childPath = path === '' ? childKey : `${path}.${childKey}`
+        Object.assign(registry, buildPathRegistry(child, childPath))
+      }
+    }
+  }
+
+  return registry
+}
+
 /**
  * Renders a Symbols/DOMQL project to HTML on the server.
  *
@@ -740,6 +774,10 @@ export const render = async (data, options = {}) => {
 
   const registry = mapKeysToElements(element)
 
+  // Build element path → brKey registry for client-side true hydration.
+  // Walks the element tree after mapKeysToElements has set __brKey on each element.
+  const brRegistry = buildPathRegistry(element)
+
   // Extract metadata for the rendered route
   // Pass the rendered element and its state so function-valued metadata
   // (e.g. detail page titles from fetched data) can be resolved
@@ -809,7 +847,7 @@ export const render = async (data, options = {}) => {
   if (_prevLoc !== undefined) globalThis.location = _prevLoc
   else delete globalThis.location
 
-  return { html, metadata, registry, element, emotionCSS, document, window, ssrTranslations, prefetchedPages }
+  return { html, metadata, registry, brRegistry, element, emotionCSS, document, window, ssrTranslations, prefetchedPages }
 }
 
 /**
@@ -1171,6 +1209,7 @@ export const renderRoute = async (data, options = {}) => {
     fontLinks: generateFontLinks(ds),
     metadata: result.metadata || extractMetadata(data, route),
     brKeyCount: result.registry ? Object.keys(result.registry).length : 0,
+    brRegistry: result.brRegistry || {},
     ssrTranslations: result.ssrTranslations,
     prefetchedState,
     activeLang
@@ -1265,7 +1304,14 @@ export const renderPage = async (data, route = '/', options = {}) => {
           translationSeed = `<script>try{${seedEntries.join(';')}}catch(e){}</script>\n`
         }
       }
-      isrBody = `${translationSeed}<script>window.__BRENDER__ = true</script>
+      // Embed BR registry for true DOM-adoption hydration
+      const brRegistryJson = result.brRegistry && Object.keys(result.brRegistry).length
+        ? JSON.stringify(result.brRegistry)
+        : null
+      const brRegistryScript = 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 {
       // Legacy swap mode: SPA creates new DOM, MutationObserver removes brender nodes