@bitstillery/mithril 3.4.2 → 3.7.0

package/api/router.ts

@@ -100,8 +100,13 @@ export default function router($window: any, mountRedraw: MountRedraw) {
             const vnode = Vnode(component, undefined, routeAttrs, null, null, null)
             if (currentResolver) {
                 const result = currentResolver.render!(vnode as any)
-                // Always wrap in a keyed fragment (stable shape). Key only changes when remountNonce bumps
-                // (route.set with remount: true), not on ordinary URL updates.
+                // SSR `renderToString(resolver.render(...))` has no outer fragment. Wrapping here breaks
+                // hydration: `createFragment` uses an empty DocumentFragment as parent, so descendant
+                // nodes never match `#app`'s existing SSR children (blank tree / mismatch recovery).
+                // After `remount: true`, bump `remountNonce` and use a keyed fragment to force remount.
+                if (remountNonce === 0) {
+                    return result
+                }
                 return hyperscript.fragment({key: 'm-route-' + remountNonce}, result)
             }
             // Wrap in a fragment to preserve existing key semantics
@@ -360,9 +365,9 @@ export default function router($window: any, mountRedraw: MountRedraw) {
     }
     route.get = function (): string {
         // If currentPath is not set (e.g., during SSR before route.resolve is called),
-        // fall back to extracting pathname from __SSR_URL__ using the isomorphic URI API
+        // fall back to extracting pathname + search from __SSR_URL__ using the isomorphic URI API
         if (currentPath === undefined) {
-            return getPathname()
+            return getPathname() + getSearch()
         }
         return currentPath ?? ''
     }
@@ -610,14 +615,6 @@ export default function router($window: any, mountRedraw: MountRedraw) {
                                     // resolver.render does: m(layout, null, componentVnode)
                                     const renderedVnode = resolver.render(componentVnode)
                                     const result = await renderToString(renderedVnode)
-                                    const html = typeof result === 'string' ? result : result.html
-                                    if (html) {
-                                        logger.info(`rendered route component`, {
-                                            pathname,
-                                            route: matchedRoute,
-                                            htmlSize: html.length,
-                                        })
-                                    }
                                     return result
                                 } catch (error) {
                                     logger.error('route render failed', error, {

package/index.ts

@@ -102,7 +102,7 @@ setSignalRedrawCallback((sig: Signal<any>) => {
 
 // Export signals API
 export {signal, computed, effect, Signal, ComputedSignal, state, watch, registerState, getRegisteredStates, clearStateRegistry}
-export type {State, StateOptions, StateSignals, Unwatch} from './state'
+export type {State, StateArray, StateOptions, StateSignals, Unwatch} from './state'
 
 // Export Store class
 export {Store} from './store'

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bitstillery/mithril",
-    "version": "3.4.2",
+    "version": "3.7.0",
     "description": "Mithril + Signals, Store and SSR",
     "license": "MIT",
     "author": "Bitstillery",

package/render/cachedAttrsIsStaticMap.ts

@@ -7,4 +7,8 @@ import emptyAttrs from './emptyAttrs'
 //
 // Since the attrs used as keys in this map are not released from the selectorCache object,
 // there is no risk of memory leaks. Therefore, Map is used here instead of WeakMap.
-export default new Map([[emptyAttrs, true]])
+
+const map = new Map<Record<string, any>, boolean>()
+// Each Mithril instance registers its own emptyAttrs as static.
+map.set(emptyAttrs, true)
+export default map

package/render/render.ts

@@ -1,5 +1,10 @@
 import {setCurrentComponent, clearCurrentComponent, clearComponentDependencies} from '../signal'
-import {logHydrationError, resetHydrationErrorCount} from '../util/ssr'
+import {
+    logHydrationError,
+    recordHydrationMismatchSummary,
+    resetHydrationErrorCount,
+    takeHydrationMismatchSummaries,
+} from '../util/ssr'
 import {logger} from '../server/logger'
 
 import Vnode from './vnode'
@@ -71,6 +76,156 @@ export default function renderFactory() {
             return null
         }
     }
+    // Positional hydration: walk existing DOM children in order, adopting each
+    // to the corresponding vnode. Handles text-node merging (SSR concatenates
+    // adjacent text runs into one node) and component/fragment recursion.
+    // Returns the next unprocessed DOM sibling (or null when exhausted).
+    function hydrateNode(
+        parent: Element,
+        vnode: any,
+        hooks: Array<() => void>,
+        ns: string | undefined,
+        cursor: Node | null,
+    ): Node | null {
+        if (vnode == null) return cursor
+        const tag = vnode.tag
+
+        if (typeof tag === 'string') {
+            switch (tag) {
+                case '#': {
+                    // Text vnode
+                    if (vnode.attrs != null) initLifecycle(vnode.attrs, vnode, hooks, true)
+                    const expected = String(vnode.children)
+                    if (cursor && cursor.nodeType === 3) {
+                        // Reuse existing text node; patch value if it differs
+                        vnode.dom = cursor as Text
+                        if ((cursor as Text).nodeValue !== expected) {
+                            ;(cursor as Text).nodeValue = expected
+                        }
+                        return cursor.nextSibling
+                    }
+                    // SSR may have merged multiple text vnodes into a single text node.
+                    // Check if the current text node *starts* with our expected text.
+                    if (cursor && cursor.nodeType === 3) {
+                        const full = (cursor as Text).nodeValue || ''
+                        if (full.startsWith(expected)) {
+                            // Split: take our portion, leave the rest for the next vnode
+                            ;(cursor as Text).splitText(expected.length)
+                            vnode.dom = cursor as Text
+                            return cursor.nextSibling
+                        }
+                    }
+                    // No matching text node — create one
+                    const textNode = getDocument(parent).createTextNode(expected)
+                    parent.insertBefore(textNode, cursor)
+                    vnode.dom = textNode
+                    return cursor
+                }
+                case '<': {
+                    // Trust HTML vnode — skip the corresponding DOM range.
+                    // Fall through to non-hydration creation (rare in hydration).
+                    vnode.state = {}
+                    if (vnode.attrs != null) initLifecycle(vnode.attrs, vnode, hooks, true)
+                    createHTML(parent, vnode, ns, cursor)
+                    return cursor
+                }
+                case '[': {
+                    // Fragment vnode
+                    vnode.state = {}
+                    if (vnode.attrs != null) initLifecycle(vnode.attrs, vnode, hooks, true)
+                    let c = cursor
+                    if (vnode.children != null) {
+                        for (let i = 0; i < vnode.children.length; i++) {
+                            c = hydrateNode(parent, vnode.children[i], hooks, ns, c)
+                        }
+                    }
+                    vnode.dom = vnode.children?.[0]?.dom ?? null
+                    let size = 0
+                    if (vnode.children) {
+                        for (let i = 0; i < vnode.children.length; i++) {
+                            const child = vnode.children[i]
+                            if (child != null) size += child.domSize ?? (child.dom ? 1 : 0)
+                        }
+                    }
+                    vnode.domSize = size
+                    return c
+                }
+                default: {
+                    // Element vnode
+                    vnode.state = {}
+                    if (vnode.attrs != null) initLifecycle(vnode.attrs, vnode, hooks, true)
+                    // Find matching element (skip whitespace text nodes)
+                    let el: Element | null = null
+                    let scan: Node | null = cursor
+                    while (scan) {
+                        if (scan.nodeType === 1) {
+                            const candidateTag = ((scan as Element).tagName || (scan as Element).nodeName || '').toLowerCase()
+                            if (candidateTag === tag.toLowerCase()) {
+                                el = scan as Element
+                                break
+                            }
+                            break // tag mismatch — don't skip ahead indefinitely
+                        }
+                        // Skip whitespace-only text nodes between elements
+                        if (scan.nodeType === 3 && scan.nodeValue && scan.nodeValue.trim() === '') {
+                            scan = scan.nextSibling
+                            continue
+                        }
+                        break
+                    }
+                    if (el) {
+                        vnode.dom = el
+                        ns = getNameSpace(vnode) || ns
+                        if (vnode.attrs != null) setAttrs(vnode, vnode.attrs, ns)
+                        if (!maybeSetContentEditable(vnode)) {
+                            if (vnode.children != null) {
+                                hydrateElementChildren(el, vnode.children, hooks, ns)
+                            }
+                        }
+                        vnode.domSize = 1
+                        return el.nextSibling
+                    }
+                    // No matching element — create from scratch
+                    createElement(parent, vnode, hooks, ns, cursor)
+                    return cursor
+                }
+            }
+        }
+
+        // Component vnode
+        initComponent(vnode, hooks, true)
+        if (vnode.instance != null) {
+            const nextCursor = hydrateNode(parent, vnode.instance, hooks, ns, cursor)
+            vnode.dom = vnode.instance.dom
+            vnode.domSize = vnode.instance.domSize
+            return nextCursor
+        }
+        vnode.domSize = 0
+        return cursor
+    }
+
+    function hydrateElementChildren(
+        element: Element,
+        children: (VnodeType | null)[],
+        hooks: Array<() => void>,
+        ns: string | undefined,
+    ) {
+        let cursor: Node | null = element.firstChild
+        for (let i = 0; i < children.length; i++) {
+            cursor = hydrateNode(element, children[i], hooks, ns, cursor)
+        }
+        // Remove leftover DOM nodes that weren't claimed by any vnode
+        while (cursor) {
+            const next: Node | null = cursor.nextSibling
+            try {
+                element.removeChild(cursor)
+            } catch (_e) {
+                // already removed
+            }
+            cursor = next
+        }
+    }
+
     // create
     function createNodes(
         parent: Element | DocumentFragment,
@@ -234,14 +389,35 @@ export default function renderFactory() {
         isHydrating: boolean = false,
         matchedNodes: Set<Node> | null = null,
     ) {
-        const fragment = getDocument(parent as Element).createDocumentFragment()
-        if (vnode.children != null) {
-            const children = vnode.children
-            createNodes(fragment, children, 0, children.length, hooks, null, ns, isHydrating, matchedNodes)
+        if (isHydrating && matchedNodes) {
+            // During hydration, render children directly into the real parent so they
+            // can match existing SSR DOM nodes. Using a DocumentFragment would isolate
+            // the children from the parent's childNodes, preventing any reuse.
+            const childCountBefore = parent.childNodes.length
+            if (vnode.children != null) {
+                const children = vnode.children
+                createNodes(parent, children, 0, children.length, hooks, nextSibling, ns, isHydrating, matchedNodes)
+            }
+            // Fragment's dom/domSize must reflect the children that were placed
+            vnode.dom = vnode.children?.[0]?.dom ?? null
+            let size = 0
+            if (vnode.children) {
+                for (let i = 0; i < vnode.children.length; i++) {
+                    const child = vnode.children[i]
+                    if (child != null) size += child.domSize ?? (child.dom ? 1 : 0)
+                }
+            }
+            vnode.domSize = size
+        } else {
+            const fragment = getDocument(parent as Element).createDocumentFragment()
+            if (vnode.children != null) {
+                const children = vnode.children
+                createNodes(fragment, children, 0, children.length, hooks, null, ns, isHydrating, matchedNodes)
+            }
+            vnode.dom = fragment.firstChild
+            vnode.domSize = fragment.childNodes.length
+            insertDOM(parent, fragment, nextSibling)
         }
-        vnode.dom = fragment.firstChild
-        vnode.domSize = fragment.childNodes.length
-        insertDOM(parent, fragment, nextSibling)
     }
     function createElement(
         parent: Element | DocumentFragment,
@@ -326,44 +502,13 @@ export default function renderFactory() {
         if (!maybeSetContentEditable(vnode)) {
             if (vnode.children != null) {
                 const children = vnode.children
-                // During hydration, if we reused an element, it already has children
-                // Create a new matchedNodes set for this element's children to avoid duplicates
-                const childMatchedNodes = isHydrating && element.firstChild ? new Set<Node>() : null
-                createNodes(element, children, 0, children.length, hooks, null, ns, isHydrating, childMatchedNodes)
-                // After creating/matching children, remove any unmatched nodes that remain
-                // Only remove unmatched nodes if we actually matched some nodes (to avoid clearing everything)
-                if (isHydrating && childMatchedNodes && element.firstChild && childMatchedNodes.size > 0) {
-                    let node: Node | null = element.firstChild
-                    while (node) {
-                        const next: Node | null = node.nextSibling
-                        if (!childMatchedNodes.has(node)) {
-                            // Verify node is still a child before attempting removal
-                            if (element.contains && element.contains(node)) {
-                                try {
-                                    element.removeChild(node)
-                                    hydrationMismatchCount++
-                                } catch (e) {
-                                    const error = e as Error
-                                    // Check if node was already removed (not a child anymore)
-                                    if (!element.contains || !element.contains(node)) {
-                                        // Node already removed, skip silently
-                                        node = next
-                                        continue
-                                    }
-                                    hydrationMismatchCount++
-                                    logHydrationError('removeChild (element children cleanup)', vnode, element, error, {
-                                        parent: element,
-                                        node,
-                                        matchedNodes: childMatchedNodes,
-                                    })
-                                    // Don't re-throw - we've already logged the error with all details
-                                    // Re-throwing causes the browser to log the DOMException stack trace
-                                }
-                            }
-                            // Node not in parent, already removed - skip silently
-                        }
-                        node = next
-                    }
+                if (isHydrating && element.firstChild) {
+                    // Positional adoption: walk existing DOM children in order, assigning
+                    // each to the corresponding vnode. This avoids the content-matching
+                    // approach which breaks when SSR merges adjacent text nodes.
+                    hydrateElementChildren(element, children, hooks, ns)
+                } else {
+                    createNodes(element, children, 0, children.length, hooks, null, ns)
                 }
                 if (vnode.tag === 'select' && attrs != null) setLateSelectAttrs(vnode, attrs)
             }
@@ -1194,13 +1339,13 @@ export default function renderFactory() {
                 isHydrating: isHydrating,
             }
             const result = callHook.call(source.oninit, vnode, context)
-            // Auto-redraw when async oninit completes (client-side only)
+            // Auto-redraw when async oninit completes (client-side only).
+            // Capture currentRedraw now — the closure variable is cleared in
+            // render()'s finally block before the microtask fires.
             if (result != null && typeof result.then === 'function' && currentRedraw != null) {
+                const capturedRedraw = currentRedraw
                 Promise.resolve(result).then(function () {
-                    if (currentRedraw != null) {
-                        // @ts-expect-error - Comma operator intentionally used to call without 'this' binding
-                        ;(0, currentRedraw)()
-                    }
+                    capturedRedraw()
                 })
             }
         }
@@ -1281,8 +1426,11 @@ export default function renderFactory() {
             // Check if we've exceeded mismatch threshold after processing nodes
             // If so, clear and re-render from scratch (client VDOM wins)
             if (isHydrating && hydrationMismatchCount > MAX_HYDRATION_MISMATCHES) {
+                const mismatchSummaries = takeHydrationMismatchSummaries()
                 logger.warn('hydration mismatch threshold exceeded. clearing parent and re-rendering from client vdom.', {
                     mismatchCount: hydrationMismatchCount,
+                    mismatches: mismatchSummaries,
+                    summariesTruncated: mismatchSummaries.length < hydrationMismatchCount,
                     threshold: MAX_HYDRATION_MISMATCHES,
                 })
                 dom.textContent = ''

package/render/ssrState.ts

@@ -239,7 +239,11 @@ export function deserializeStore(state: State<any>, serialized: any): void {
                 const signal = signalMap.get(key)
                 // Don't update ComputedSignal (they're read-only)
                 if (signal && !(signal instanceof ComputedSignal)) {
-                    signal.value = deserializedValue
+                    // Use the proxy setter, not `signal.value = …`. Direct assignment bypasses
+                    // initializeSignals() for nested objects, so nested state (e.g. identity.user)
+                    // stays plain JSON — readable as `user.first_name` but `$first_name` is missing
+                    // and components like FieldText that need model refs render nothing.
+                    ;(state as any)[key] = deserializedValue
                 }
             } else {
                 // Signal doesn't exist - use proxy setter to create it

package/server/logger.ts

@@ -55,13 +55,77 @@ function getTimestamp(): string {
 function formatLevel(level: 'info' | 'debug' | 'warn' | 'error'): string {
     const levelMap = {
         info: colorize('info', colors.bright + colors.cyan),
-        debug: colorize('debug', colors.bright + colors.blue),
+        debug: colorize('debug', colors.dim + colors.blue),
         warn: colorize('warn', colors.bright + colors.yellow),
         error: colorize('error', colors.bright + colors.red),
     }
     return levelMap[level]
 }
 
+function formatPrefixForServer(prefix: string): string {
+    return colorize(prefix, getColorByHash(prefix))
+}
+
+/** Simple hash function for string to generate a consistent number. */
+function hashString(str: string): number {
+    let hash = 0
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i)
+        hash = (hash << 5) - hash + char
+        hash = hash & hash // Convert to 32bit integer
+    }
+    return Math.abs(hash)
+}
+
+/** Get a color based on hash of the input string. */
+function getColorByHash(text: string): string {
+    const colorOptions = [
+        // Bright variants
+        colors.bright + colors.red,
+        colors.bright + colors.green,
+        colors.bright + colors.yellow,
+        colors.bright + colors.blue,
+        colors.bright + colors.magenta,
+        colors.bright + colors.cyan,
+        // Regular variants
+        colors.red,
+        colors.green,
+        colors.yellow,
+        colors.blue,
+        colors.magenta,
+        colors.cyan,
+    ]
+    const hash = hashString(text)
+    return colorOptions[hash % colorOptions.length]
+}
+
+const textEncoder = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null
+
+/** UTF-8 byte length of a string (for SSR response size). */
+export function utf8ByteLength(s: string): number {
+    return textEncoder ? textEncoder.encode(s).length : s.length
+}
+
+export interface SsrPageSummaryFields {
+    bytesHtml: number
+    bytesState: number
+    method: string
+    msTotal: number
+    pathname: string
+}
+
+/**
+ * One-line SSR summary for the terminal: dim labels, bright path, yellow numbers.
+ * Use with {@link Logger.infoRaw} so the body is not flattened into dim context.
+ */
+export function formatSsrPageSummaryLine(fields: SsrPageSummaryFields): string {
+    const d = (s: string) => colorize(s, colors.dim + colors.white)
+    const n = (v: number) => String(Math.round(v))
+    const path = colorize(fields.pathname, colors.green)
+    const method = colorize(fields.method, colors.cyan)
+    return `${d('page')} ${method} ${path} ${n(fields.msTotal)}ms ${d('body')} ${n(fields.bytesHtml / 1024)}KB ${d('state')} ${n(fields.bytesState / 1024)}KB`
+}
+
 export interface LogContext {
     pathname?: string
     method?: string
@@ -71,6 +135,22 @@ export interface LogContext {
     [key: string]: any
 }
 
+const RESERVED_CONTEXT_KEYS = new Set(['method', 'pathname', 'route', 'sessionId', 'module'])
+
+/** Serialize non-primitive context for terminal logs (avoids [object Object]). */
+function formatContextValueForServer(value: unknown): string {
+    if (value === undefined) return 'undefined'
+    if (value === null) return 'null'
+    const t = typeof value
+    if (t === 'string' || t === 'number' || t === 'boolean' || t === 'bigint') return String(value)
+    if (value instanceof Error) return value.stack ?? value.message
+    try {
+        return JSON.stringify(value)
+    } catch {
+        return String(value)
+    }
+}
+
 class Logger {
     // Default prefix: [ssr] for server infrastructure, [app] for application code
     private prefix: string = '[ssr]'
@@ -86,38 +166,42 @@ class Logger {
         const timestamp = colorize(getTimestamp(), colors.dim + colors.white)
         const levelStr = formatLevel(level)
 
-        // Always use the set prefix (e.g., [app] or [ssr])
-        const prefixStr = colorize(
-            this.prefix,
-            this.prefix === '[ssr]' ? colors.bright + colors.magenta : colors.bright + colors.cyan,
-        )
+        const prefixStr = formatPrefixForServer(this.prefix)
+        const isDebug = level === 'debug'
 
         // Include module in message if provided
         let displayMessage = message
         if (context?.module) {
             displayMessage = `[${context.module}] ${message}`
         }
+        if (isDebug) {
+            displayMessage = colorize(displayMessage, colors.dim + colors.white)
+        }
 
         let contextStr = ''
         if (context) {
             const contextParts: string[] = []
+            const methodColor = isDebug ? colors.dim + colors.cyan : colors.cyan
+            const pathColor = isDebug ? colors.dim + colors.green : colors.green
+            const routeColor = isDebug ? colors.dim + colors.blue : colors.blue
+            const extraColor = isDebug ? colors.dim + colors.blue : colors.dim + colors.white
             if (context.method) {
-                contextParts.push(colorize(context.method, colors.cyan))
+                contextParts.push(colorize(context.method, methodColor))
             }
             if (context.pathname) {
-                contextParts.push(colorize(context.pathname, colors.green))
+                contextParts.push(colorize(context.pathname, pathColor))
             }
             if (context.route) {
-                contextParts.push(colorize(`route:${context.route}`, colors.blue))
+                contextParts.push(colorize(`route:${context.route}`, routeColor))
             }
             if (context.sessionId) {
-                contextParts.push(colorize(`session:${context.sessionId.slice(0, 8)}...`, colors.dim + colors.white))
+                contextParts.push(colorize(`session:${context.sessionId.slice(0, 8)}...`, extraColor))
             }
 
             // Add any additional context fields (excluding module which is shown in message)
             for (const [key, value] of Object.entries(context)) {
-                if (!['method', 'pathname', 'route', 'sessionId', 'module'].includes(key)) {
-                    contextParts.push(colorize(`${key}:${value}`, colors.dim + colors.white))
+                if (!RESERVED_CONTEXT_KEYS.has(key)) {
+                    contextParts.push(colorize(`${key}:${formatContextValueForServer(value)}`, extraColor))
                 }
             }
 
@@ -129,19 +213,25 @@ class Logger {
         return `${timestamp} ${prefixStr} ${levelStr}${contextStr} ${displayMessage}`
     }
 
-    private formatContextForBrowser(context?: LogContext): string[] {
-        if (!context) return []
-        const parts: string[] = []
-        if (context.method) parts.push(`Method: ${context.method}`)
-        if (context.pathname) parts.push(`Path: ${context.pathname}`)
-        if (context.route) parts.push(`Route: ${context.route}`)
-        if (context.sessionId) parts.push(`Session: ${context.sessionId.slice(0, 8)}...`)
+    /**
+     * Emit context in DevTools-friendly form: objects/arrays are passed as separate arguments so
+     * they stay expandable instead of becoming "[object Object]" strings.
+     */
+    private logBrowserContext(logFn: typeof console.log, context: LogContext): void {
+        if (context.method != null) logFn('  method:', context.method)
+        if (context.pathname != null) logFn('  pathname:', context.pathname)
+        if (context.route != null) logFn('  route:', context.route)
+        if (context.sessionId != null) logFn('  sessionId:', `${context.sessionId.slice(0, 8)}...`)
+
         for (const [key, value] of Object.entries(context)) {
-            if (!['method', 'pathname', 'route', 'sessionId', 'module'].includes(key)) {
-                parts.push(`${key}: ${value}`)
+            if (RESERVED_CONTEXT_KEYS.has(key)) continue
+            const label = `  ${key}:`
+            if (value !== null && typeof value === 'object') {
+                logFn(label, value)
+            } else {
+                logFn(label, value as string | number | boolean | undefined)
             }
         }
-        return parts
     }
 
     private logBrowser(
@@ -151,24 +241,27 @@ class Logger {
         error?: Error | unknown,
     ): void {
         const displayMessage = context?.module ? `[${context.module}] ${message}` : message
-        const prefixStyle = this.prefix === '[ssr]' ? 'color: #d946ef; font-weight: bold' : 'color: #3b82f6; font-weight: bold'
+        const prefixStyle = this.prefix === '[ssr]' ? 'color: #d946ef; font-weight: bold' : 'color: #64748b; font-weight: normal'
         const levelStyles: Record<string, string> = {
             info: 'color: #22d3ee; font-weight: bold',
-            debug: 'color: #4ade80; font-weight: bold',
+            debug: 'color: #64748b; font-weight: normal',
             warn: 'color: #fbbf24; font-weight: bold',
             error: 'color: #ef4444; font-weight: bold',
         }
+        const bodyStyle = level === 'debug' ? 'color: #94a3b8; font-weight: normal' : 'color: inherit'
         const logFn = level === 'error' ? console.error : level === 'warn' ? console.warn : console.log
-        const contextParts = this.formatContextForBrowser(context)
-        if (contextParts.length > 0 || error) {
-            console.group(`%c${this.prefix}%c ${level}%c ${displayMessage}`, prefixStyle, levelStyles[level], 'color: inherit')
-            contextParts.forEach((part) => logFn(`  ${part}`))
+        const hasContext = context != null && Object.keys(context).length > 0
+        if (hasContext || error) {
+            console.group(`%c${this.prefix}%c ${level}%c ${displayMessage}`, prefixStyle, levelStyles[level], bodyStyle)
+            if (context && hasContext) {
+                this.logBrowserContext(logFn, context)
+            }
             if (error instanceof Error && error.stack) {
                 console.error('Stack trace:', error.stack)
             }
             console.groupEnd()
         } else {
-            logFn(`%c${this.prefix}%c ${level}%c ${displayMessage}`, prefixStyle, levelStyles[level], 'color: inherit')
+            logFn(`%c${this.prefix}%c ${level}%c ${displayMessage}`, prefixStyle, levelStyles[level], bodyStyle)
         }
     }
 
@@ -180,6 +273,20 @@ class Logger {
         }
     }
 
+    /**
+     * Server only: log one info line whose body may already contain ANSI (e.g. {@link formatSsrPageSummaryLine}).
+     */
+    infoRaw(messageBody: string): void {
+        if (isBrowser) {
+            console.log(`${this.prefix} info ${messageBody}`)
+            return
+        }
+        const timestamp = colorize(getTimestamp(), colors.dim + colors.white)
+        const levelStr = formatLevel('info')
+        const prefixStr = formatPrefixForServer(this.prefix)
+        console.log(`${timestamp} ${prefixStr} ${levelStr} ${messageBody}`)
+    }
+
     debug(message: string, context?: LogContext): void {
         const shouldLog =
             globalThis.__SSR_MODE__ || (isBrowser && typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production')

package/server/ssr.ts

@@ -3,6 +3,7 @@ import {readFile} from 'fs/promises'
 import m from '../server'
 import {runWithContextAsync} from '../ssrContext'
 
+import {formatSsrPageSummaryLine, utf8ByteLength} from './logger'
 import {extractSessionId} from './session'
 import {logger} from './ssrLogger'
 
@@ -10,14 +11,16 @@ import type {SessionStore} from './session'
 import type {SSRAccessContext} from '../ssrContext'
 
 declare global {
-    // eslint-disable-next-line @typescript-eslint/naming-convention
     var __SSR_MODE__: boolean | undefined
-    // eslint-disable-next-line @typescript-eslint/naming-convention
     var __SSR_URL__: string | undefined
 }
 
 globalThis.__SSR_MODE__ = true
 
+function ssrMetricsBreakdownEnabled(): boolean {
+    return process.env.MITHRIL_SSR_METRICS === '1'
+}
+
 export interface SSROptions {
     routes: Record<string, any>
     /** Create per-request context (store, stateRegistry, sessionId, sessionData). */
@@ -47,9 +50,9 @@ export async function getBunProcessedTemplate(
 ): Promise<string> {
     // Fetch from Bun's route handler to get processed template with HMR scripts
     // Use a special route that Bun processes but we don't use for SSR
-    const templateUrl = `http://localhost:${port}${templateRoute}`
+    const template_url = `http://localhost:${port}${templateRoute}`
     try {
-        const response = await fetch(templateUrl)
+        const response = await fetch(template_url)
         if (response.ok) {
             return await response.text()
         }
@@ -91,28 +94,28 @@ export async function createSSRResponse(pathname: string, req: Request, options:
 
     return runWithContextAsync(context, async () => {
         try {
-            await options.initRequestContext(context)
-
             globalThis.__SSR_URL__ = req.url
 
-            const routeCount = Object.keys(options.routes).length
-            logger.debug('resolving route', {pathname, routeCount, routeExists: !!options.routes[pathname]})
+            const t0 = performance.now()
+            await options.initRequestContext(context)
+            const t1 = performance.now()
 
             const result = await m.route.resolve(pathname, options.routes, m.renderToString)
+            const t2 = performance.now()
 
             const appHtml = typeof result === 'string' ? result : result.html
-            const serializedState = typeof result === 'string' ? {} : result.state
-            const htmlLength = appHtml?.length || 0
+            const baseSerializedState = typeof result === 'string' ? {} : result.state
+            const meta = context.ssrStateMeta
+            const serializedState =
+                meta && Object.keys(meta).length > 0 ? {...baseSerializedState, __meta: meta} : baseSerializedState
 
-            logger.debug('route resolved', {pathname, htmlLength, resultType: typeof result === 'string' ? 'string' : 'object'})
-
-            if (!appHtml || appHtml.trim() === '' || appHtml.trim() === '<div></div>') {
+            const emptyHtml = !appHtml || appHtml.trim() === '' || appHtml.trim() === '<div></div>'
+            if (emptyHtml) {
                 logger.warn('empty html rendered', {pathname})
-            } else {
-                logger.info(`get ${pathname} → ${htmlLength} chars`)
             }
 
             let html = await options.getHtmlTemplate()
+            const t3 = performance.now()
 
             const appSelector = options.appSelector || '#app'
 
@@ -135,16 +138,43 @@ export async function createSSRResponse(pathname: string, req: Request, options:
             })
 
             const stateScriptId = options.stateScriptId || '__SSR_STATE__'
-            const stateScript = `<script id="${stateScriptId}" type="application/json">${JSON.stringify(serializedState)}</script>`
+            const stateJson = JSON.stringify(serializedState)
+            const stateScript = `<script id="${stateScriptId}" type="application/json">${stateJson}</script>`
             html = html.replace('</head>', `${stateScript}</head>`)
 
+            const t4 = performance.now()
+
+            if (!emptyHtml) {
+                const msTotal = t4 - t0
+                const bytesHtml = utf8ByteLength(html)
+                const bytesState = utf8ByteLength(stateJson)
+                logger.infoRaw(
+                    formatSsrPageSummaryLine({
+                        bytesHtml,
+                        bytesState,
+                        method: req.method,
+                        msTotal,
+                        pathname,
+                    }),
+                )
+                if (ssrMetricsBreakdownEnabled()) {
+                    logger.debug('ssr phases', {
+                        ms_init_context: Math.round((t1 - t0) * 100) / 100,
+                        ms_route_render: Math.round((t2 - t1) * 100) / 100,
+                        ms_template_fetch: Math.round((t3 - t2) * 100) / 100,
+                        ms_template_merge: Math.round((t4 - t3) * 100) / 100,
+                        pathname,
+                    })
+                }
+            }
+
             const sessionId = context.sessionId ?? ''
 
             return new Response(html, {
                 headers: {
-                    // eslint-disable-next-line @typescript-eslint/naming-convention
+                    //
                     'Content-Type': 'text/html; charset=utf-8',
-                    // eslint-disable-next-line @typescript-eslint/naming-convention
+                    //
                     'Set-Cookie': `sessionId=${sessionId}; Path=/; HttpOnly; SameSite=Lax`,
                 },
             })
@@ -160,7 +190,7 @@ export async function createSSRResponse(pathname: string, req: Request, options:
 }
 
 /**
- * Create session update API handler factory
+ * Create se
  * Returns a handler function for POST /api/session requests
  */
 export function createSessionUpdateHandler(
@@ -191,7 +221,6 @@ export function createSessionUpdateHandler(
             })
 
             return new Response(JSON.stringify({success: true}), {
-                // eslint-disable-next-line @typescript-eslint/naming-convention
                 headers: {'Content-Type': 'application/json'},
             })
         } catch (error) {

package/ssrContext.ts

@@ -35,6 +35,11 @@ export interface SSRAccessContext {
     sessionData?: any
     /** Per-request EventEmitter; prevents event listeners from persisting between requests. */
     events?: any
+    /**
+     * Optional metadata merged into `#__SSR_STATE__` as top-level `__meta` when serializing.
+     * Consumers should strip `__meta` before `deserializeAllStates`. Set during SSR app init.
+     */
+    ssrStateMeta?: Record<string, unknown>
     /** Per-request watcher cleanup functions; prevents watchers from persisting between requests. */
     watchers?: Array<() => void>
 }

package/state.ts

@@ -756,6 +756,8 @@ export function state<T extends Record<string, any>>(initial: T, name?: string,
                 } else {
                     // Create new signal (new key added to object)
                     nestedSignalMap.set(key, createPropertySignal(value))
+                    // Mirror the key on the target so devtools show it when expanding <target>
+                    Reflect.set(target, prop, value)
                     // Notify parent so subscribers see the key addition
                     const parentSignal = arrayParentSignalMap.get(wrapped) || (wrapped as any)._parentSignal
                     if (parentSignal && typeof (parentSignal as any).trigger === 'function') {
@@ -799,6 +801,7 @@ export function state<T extends Record<string, any>>(initial: T, name?: string,
                     return {
                         enumerable: true,
                         configurable: true,
+                        writable: true,
                     }
                 }
                 return Reflect.getOwnPropertyDescriptor(target, prop)
@@ -865,19 +868,20 @@ export type StateSignals<T extends Record<string, any>> = {
           ? Signal<State<T[K]>>
           : Signal<T[K]>
 }
+type StateElem<E> = E extends Record<string, any> ? State<E> : E
 
-/**
- * State type - reactive object with signal-based properties
- *
- * Supports:
- * - Regular access: `state.prop` returns unwrapped value
- * - Signal access: `state.$prop` returns Signal instance ($ prefix convention)
- * - Functions become computed signals
- * - Nested objects become State instances (recursively)
- */
-export type State<T extends Record<string, any>> = {
-    [K in keyof T]: T[K] extends (...args: any[]) => infer R ? R : T[K] extends Record<string, any> ? State<T[K]> : T[K]
-} & StateSignals<T>
+export type StateArray<Elem> = Omit<Array<StateElem<Elem>>, 'fill' | 'push' | 'splice' | 'unshift'> & {
+    fill(value: Elem, start?: number, end?: number): StateArray<Elem>
+    push(...items: Elem[]): number
+    splice(start: number, deleteCount?: number, ...items: Elem[]): StateElem<Elem>[]
+    unshift(...items: Elem[]): number
+}
+
+export type State<T extends Record<string, any>> = T extends (infer Elem)[]
+    ? StateArray<Elem>
+    : {
+          [K in keyof T]: T[K] extends (...args: any[]) => infer R ? R : T[K] extends Record<string, any> ? State<T[K]> : T[K]
+      } & StateSignals<T>
 
 /** Function returned by watch() to remove the watcher */
 export type Unwatch = () => void

package/store.ts

@@ -118,6 +118,10 @@ function merge_deep(target: any, ...sources: any[]): any {
 
 const DEFAULT_LOOKUP_VERIFY_INTERVAL = 1000 * 10 // 10 seconds
 const DEFAULT_LOOKUP_TTL = 1000 * 60 * 60 * 24 // 1 day
+const DEFAULT_COOKIE_MAX_AGE = 60 * 60 * 24 * 365 // 1 year, in seconds
+// Browsers cap a single cookie at ~4KB; stay well under so we never silently drop a write
+// or bloat every request. The cookie tier is for small, render-affecting preferences only.
+const MAX_COOKIE_BYTES = 3500
 
 // Counter for generating unique store instance names
 let storeInstanceCounter = 0
@@ -131,6 +135,10 @@ let storeInstanceCounter = 0
  * - temporary: not persisted (resets on reload)
  * - tab: sessionStorage (survives page reloads, clears when tab closes)
  * - session: server-side session storage (optional, off by default; requires backend, hydrated via SSR)
+ * - cookie: a single JSON cookie (optional, off by default). Unlike localStorage, a cookie is sent
+ *   on the SSR document request, so the server can render with these values and avoid a hydration
+ *   flash. For small, render-affecting preferences only (≤MAX_COOKIE_BYTES) — never large or
+ *   growing data (it ships on every request).
  */
 export class Store<T extends Record<string, any> = Record<string, any>> {
     private stateInstance: State<T>
@@ -139,17 +147,30 @@ export class Store<T extends Record<string, any> = Record<string, any>> {
         temporary: {} as Partial<T>,
         tab: {} as Partial<T>,
         session: {} as Partial<T>,
+        cookie: {} as Partial<T>,
     }
     private lookup_verify_interval: number | null = null
     private lookup_ttl: number
     private computedPropertiesSetup?: () => void
     private storageKey: string
     private tabStorageKey: string
-
-    constructor(options: {lookup_ttl?: number; storageKey?: string; tabStorageKey?: string} = {lookup_ttl: DEFAULT_LOOKUP_TTL}) {
+    private cookieKey: string
+    private cookieMaxAge: number
+
+    constructor(
+        options: {
+            lookup_ttl?: number
+            storageKey?: string
+            tabStorageKey?: string
+            cookieKey?: string
+            cookieMaxAge?: number
+        } = {lookup_ttl: DEFAULT_LOOKUP_TTL},
+    ) {
         this.lookup_ttl = options.lookup_ttl || DEFAULT_LOOKUP_TTL
         this.storageKey = options.storageKey ?? 'store'
         this.tabStorageKey = options.tabStorageKey ?? this.storageKey
+        this.cookieKey = options.cookieKey ?? 'store_prefs'
+        this.cookieMaxAge = options.cookieMaxAge ?? DEFAULT_COOKIE_MAX_AGE
         // Initialize with empty state, will be loaded later (ADR-0013: defer computeds until ready() is called)
         const instanceName = `store.instance.${storeInstanceCounter++}`
         this.stateInstance = state({} as T, instanceName, {deferComputed: true})
@@ -184,23 +205,26 @@ export class Store<T extends Record<string, any> = Record<string, any>> {
         }
         const result: any = {}
         for (const key of Object.keys(blueprint)) {
-            if (Object.prototype.hasOwnProperty.call(state, key)) {
-                const blueprintValue = (blueprint as any)[key]
-                const stateValue = (state as any)[key]
-                if (!Array.isArray(blueprintValue) && blueprintValue !== null && is_object(blueprintValue)) {
-                    // (!) Convention: The contents of a state key with the name 'lookup' is
-                    // always one-one copied from the state, instead of being
-                    // blueprinted per-key. This is to accomodate key/value
-                    // lookups, without having to define each key in the
-                    // state's persistent section.
-                    if (key === 'lookup') {
-                        result[key] = copy_object(stateValue)
-                    } else {
-                        result[key] = this.blueprint(stateValue, blueprintValue)
-                    }
+            // Use `in` so Mithril state proxies (signal-backed roots) are not skipped; `hasOwnProperty`
+            // can be false for keys that only exist on the proxy’s `has` / signal map.
+            if (!(key in (state as object))) {
+                continue
+            }
+            const blueprintValue = (blueprint as any)[key]
+            const stateValue = (state as any)[key]
+            if (!Array.isArray(blueprintValue) && blueprintValue !== null && is_object(blueprintValue)) {
+                // (!) Convention: The contents of a state key with the name 'lookup' is
+                // always one-one copied from the state, instead of being
+                // blueprinted per-key. This is to accomodate key/value
+                // lookups, without having to define each key in the
+                // state's persistent section.
+                if (key === 'lookup') {
+                    result[key] = copy_object(stateValue)
                 } else {
-                    result[key] = stateValue
+                    result[key] = this.blueprint(stateValue, blueprintValue)
                 }
+            } else {
+                result[key] = stateValue
             }
         }
         return result as Partial<T>
@@ -272,7 +296,13 @@ export class Store<T extends Record<string, any> = Record<string, any>> {
         }
     }
 
-    load(saved: Partial<T>, temporary: Partial<T>, tab: Partial<T> = {} as Partial<T>, session: Partial<T> = {} as Partial<T>) {
+    load(
+        saved: Partial<T>,
+        temporary: Partial<T>,
+        tab: Partial<T> = {} as Partial<T>,
+        session: Partial<T> = {} as Partial<T>,
+        cookie: Partial<T> = {} as Partial<T>,
+    ) {
         const restored_state = {
             tab: this.get_tab_storage(this.tabStorageKey),
             store: this.get(this.storageKey),
@@ -283,6 +313,7 @@ export class Store<T extends Record<string, any> = Record<string, any>> {
             temporary,
             tab,
             session,
+            cookie,
         }
 
         try {
@@ -303,7 +334,6 @@ export class Store<T extends Record<string, any> = Record<string, any>> {
             console.log('[store] loading tab state from local store')
             tab_state = merge_deep(copy_object(this.templates.tab), store_state.tab)
         } else {
-            console.log('[store] restoring existing tab state')
             tab_state = merge_deep(copy_object(this.templates.tab), copy_object(restored_state.tab))
         }
 
@@ -319,6 +349,12 @@ export class Store<T extends Record<string, any> = Record<string, any>> {
         // Session state comes from server (SSR), not localStorage
         const final_state = merge_deep(temp_state, copy_object(session))
 
+        // Merge cookie state last so it wins for its keys. On the client we read the actual cookie
+        // from document.cookie; during SSR there is no document, so the caller passes the
+        // request-derived values as the `cookie` template (same pattern as session/sessionTemplate).
+        const cookie_state = merge_deep(copy_object(cookie), this.get_cookie(this.cookieKey))
+        merge_deep(final_state, cookie_state)
+
         // Merge templates (including computed properties) into "merged initial state"
         // This will be stored in registry so computed properties can be automatically restored
         // Use copy_object_preserve_functions to deep copy while preserving functions
@@ -329,7 +365,15 @@ export class Store<T extends Record<string, any> = Record<string, any>> {
         const mergedInitialTab = tab && Object.keys(tab).length > 0 ? {tab: copy_object_preserve_functions(tab)} : {}
         // Session template is merged directly (no nesting needed, structure matches final_state)
         const mergedInitialSession = copy_object_preserve_functions(session)
-        const mergedInitial = merge_deep(mergedInitialSaved, mergedInitialTemporary, mergedInitialTab, mergedInitialSession)
+        // Cookie template is merged directly too (structure matches final_state)
+        const mergedInitialCookie = copy_object_preserve_functions(cookie)
+        const mergedInitial = merge_deep(
+            mergedInitialSaved,
+            mergedInitialTemporary,
+            mergedInitialTab,
+            mergedInitialSession,
+            mergedInitialCookie,
+        )
 
         // Update registry entry to store merged templates as "initial" state
         // This allows deserializeAllStates() to automatically restore computed properties
@@ -363,19 +407,21 @@ export class Store<T extends Record<string, any> = Record<string, any>> {
     }
 
     /**
-     * Persist state to storage. When no options are passed, saves to localStorage (saved) and
-     * sessionStorage (tab). Session (server-side) is off by default; pass { session: true } to persist it.
+     * Persist state to storage. When no options are passed, saves to localStorage (saved),
+     * sessionStorage (tab), and the cookie tier (when a cookie template is registered). Session
+     * (server-side) is off by default; pass { session: true } to persist it.
      */
-    async save(options?: {saved?: boolean; tab?: boolean; session?: boolean}): Promise<void> {
+    async save(options?: {saved?: boolean; tab?: boolean; session?: boolean; cookie?: boolean}): Promise<void> {
         // Skip saving during SSR (server-side rendering in Bun)
         // On the server, there's no localStorage/sessionStorage and no need to persist state
         if (globalThis.__SSR_MODE__) {
             return
         }
 
-        // Default: write to localStorage and sessionStorage when no options; session is opt-in
+        // Default: write to localStorage, sessionStorage and cookie when no options; session is opt-in
         const writeLocalStorage = options?.saved ?? options === undefined
         const writeSessionStorage = options?.tab ?? options === undefined
+        const writeCookie = options?.cookie ?? options === undefined
         const writeSessionApi = options?.session === true
 
         const statePlain = serializeStore(this.stateInstance)
@@ -391,6 +437,12 @@ export class Store<T extends Record<string, any> = Record<string, any>> {
             this.persist_lookup_to_local_storage(statePlain)
         }
 
+        // Write cookie-backed preferences (small, SSR-visible). Only when a cookie template is
+        // registered, so consumers that don't opt in never get an empty cookie written.
+        if (writeCookie && this.templates.cookie && Object.keys(this.templates.cookie).length > 0) {
+            this.set_cookie(this.cookieKey, this.blueprint(statePlain, copy_object(this.templates.cookie)))
+        }
+
         // Write to sessionStorage (tab-scoped, cleared when tab closes)
         if (writeSessionStorage && this.templates.tab) {
             const tabState = (this.stateInstance as any).tab
@@ -474,6 +526,43 @@ export class Store<T extends Record<string, any> = Record<string, any>> {
         }
     }
 
+    /**
+     * Read and parse the JSON cookie tier. Returns {} when there is no document (SSR), the cookie
+     * is absent, or it cannot be parsed. During SSR the request cookie is injected via the `cookie`
+     * template in load() instead, so this only does real work in the browser.
+     */
+    get_cookie(key: string): Record<string, any> {
+        if (typeof document === 'undefined') return {}
+        try {
+            const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${key}=([^;]*)`))
+            if (!match) return {}
+            const parsed = JSON.parse(decodeURIComponent(match[1]))
+            return parsed && typeof parsed === 'object' ? parsed : {}
+        } catch {
+            return {}
+        }
+    }
+
+    /**
+     * Write the cookie tier as a single JSON cookie. Skips the write (with a warning) when the
+     * serialized value would exceed MAX_COOKIE_BYTES, so we never silently corrupt requests.
+     */
+    set_cookie(key: string, item: object): void {
+        if (typeof document === 'undefined') return
+        try {
+            const value = encodeURIComponent(JSON.stringify(item))
+            if (value.length > MAX_COOKIE_BYTES) {
+                console.warn(
+                    `[store] cookie '${key}' is ${value.length} bytes, over the ${MAX_COOKIE_BYTES} limit; skipping write. Keep the cookie tier small.`,
+                )
+                return
+            }
+            document.cookie = `${key}=${value}; Path=/; SameSite=Lax; Max-Age=${this.cookieMaxAge}`
+        } catch (err) {
+            console.error('Cannot write cookie; continue without.', err)
+        }
+    }
+
     set_tab(key: string, item: object): void {
         if (typeof window === 'undefined') return
         try {

package/util/ssr.ts

@@ -9,9 +9,20 @@ export const HYDRATION_DEBUG = typeof process !== 'undefined' && process.env?.NO
 let hydrationErrorCount = 0
 const MAX_HYDRATION_ERRORS = 10 // Limit number of errors logged per render cycle
 
+export interface HydrationMismatchSummary {
+    kind: 'unmatched_dom_child_removed' | 'remove_child_failed'
+    parentDom: string
+    parentVnode: string
+    removed: string
+}
+
+const hydrationMismatchSummaries: HydrationMismatchSummary[] = []
+const MAX_HYDRATION_MISMATCH_SUMMARIES = 32
+
 // Reset error count at the start of each render cycle
 export function resetHydrationErrorCount(): void {
     hydrationErrorCount = 0
+    hydrationMismatchSummaries.length = 0
 }
 
 export function getComponentName(vnode: any): string {
@@ -237,7 +248,68 @@ function buildComponentPath(vnode: any, context?: {oldVnode?: any; newVnode?: an
     return path
 }
 
-function formatComponentHierarchy(vnode: any, context?: {oldVnode?: any; newVnode?: any}): string {
+/** Short label for a DOM node during hydration debug (tag, text preview, or node type). */
+export function describeHydrationDomNode(node: Node, textPreviewMax = 80): string {
+    if (node.nodeType === 3) {
+        const raw = (node as Text).nodeValue ?? ''
+        const normalized = raw.replace(/\s+/g, ' ').trim()
+        const excerpt = normalized.length > textPreviewMax ? `${normalized.slice(0, textPreviewMax)}…` : normalized
+        return `text "${excerpt}"`
+    }
+    if (node.nodeType === 1) {
+        const el = node as Element
+        const tag = el.tagName.toLowerCase()
+        const id = el.id ? `#${el.id}` : ''
+        let cls = ''
+        if (el.className && typeof el.className === 'string') {
+            const parts = el.className.split(/\s+/).filter(Boolean).slice(0, 4)
+            if (parts.length) cls = `.${parts.join('.')}`
+        }
+        return `<${tag}${id}${cls}>`
+    }
+    if (node.nodeType === 8) {
+        const c = (node as Comment).data?.replace(/\s+/g, ' ').trim() ?? ''
+        const excerpt = c.length > textPreviewMax ? `${c.slice(0, textPreviewMax)}…` : c
+        return `comment "${excerpt}"`
+    }
+    return `${node.nodeName}[nodeType=${node.nodeType}]`
+}
+
+/** Opening-tag style summary for a parent element (hydration debug). */
+export function describeHydrationParentElement(el: Element): string {
+    const {openTag} = formatDOMElement(el)
+    return openTag
+}
+
+export function recordHydrationMismatchSummary(
+    kind: HydrationMismatchSummary['kind'],
+    parentVnode: any,
+    parentEl: Element,
+    removed: Node,
+    updateStats: boolean,
+): void {
+    if (updateStats) {
+        updateHydrationStats(parentVnode)
+    }
+    if (hydrationMismatchSummaries.length >= MAX_HYDRATION_MISMATCH_SUMMARIES) {
+        return
+    }
+    hydrationMismatchSummaries.push({
+        kind,
+        parentDom: describeHydrationParentElement(parentEl),
+        parentVnode: formatComponentHierarchy(parentVnode),
+        removed: describeHydrationDomNode(removed),
+    })
+}
+
+/** Returns buffered mismatch summaries from the current render and clears the buffer. */
+export function takeHydrationMismatchSummaries(): HydrationMismatchSummary[] {
+    const out = hydrationMismatchSummaries.slice()
+    hydrationMismatchSummaries.length = 0
+    return out
+}
+
+export function formatComponentHierarchy(vnode: any, context?: {oldVnode?: any; newVnode?: any}): string {
     if (!vnode) return 'Unknown'
 
     const path = buildComponentPath(vnode, context)