@vmz/core 0.3.6 → 0.3.8

package/README.md

@@ -1,50 +1,50 @@
-# @vmz/core
-
-The browser should not have to rediscover an application's structure after every click. Yet that is the default cost of
-many UI systems: execute components again, compare a virtual tree, and infer which DOM work might be necessary.
-
-`@vmz/core` is the production runtime behind VMZ's alternative. It executes the creation, patch, SSR, resumption, HTTP,
-and lifetime schedules produced by the compiler. When VMZ can prove that a write affects one text binding, one control
-region, or one keyed item, the runtime can update that target directly rather than begin from a whole component tree.
-
-The same idea continues beyond a single browser update. SSR serializes planned regions; resumption attaches only
-reachable state and event entries instead of repeating completed server work; ownership regions give async tasks and
-resources a deterministic end; server and HTTP output stay tied to compiler-visible capabilities.
-
-| Instead of...                      | VMZ runtime work begins from...                       |
-|------------------------------------|-------------------------------------------------------|
-| Re-running a component tree        | A known affected binding or region                    |
-| Reconciling a generic virtual tree | Direct create, patch, switch, or keyed-list work      |
-| Hydrating every rendered component | The event and state entries that are actually reached |
-| Hoping cleanup follows callbacks   | A compiler-known ownership and disposal boundary      |
-
-For application authors, this mostly stays out of sight: write VMZ source and let the compiler generate the plan.
-`@vmz/core` matters when you care about the kind of runtime your product ships: small in responsibility, direct in
-execution, and able to account for why its work exists. 🌱
-
-## The hot path VMZ is aiming for
-
-```text
-state write
-  -> known dependency edge
-  -> affected computation or region
-  -> direct patch / switch / reconcile
-```
-
-There is no default detour through “execute every component that might matter, build virtual nodes, then compare them.”
-If analysis must widen, it widens to a safe region and should preserve the reason.
-
-## More than DOM updates
-
-- **Transactions:** related writes can settle before dependent work runs.
-- **Ownership:** branches, list items, resources, and tasks have a known lifetime.
-- **Cancellation:** an obsolete navigation or async generation cannot write into new state.
-- **Resumption:** the browser attaches to server-produced work at the smallest reachable boundary.
-- **Zero-JS delivery:** pages with no interactive requirement do not need an eager framework shell.
-
-The runtime should not grow a second compiler made of reflection, string dependencies, or generic proxies. Its quality
-comes from faithfully executing the generated plan while keeping the production surface focused.
-
-## License
-
-MIT
+# @vmz/core
+
+The browser should not have to rediscover an application's structure after every click. Yet that is the default cost of
+many UI systems: execute components again, compare a virtual tree, and infer which DOM work might be necessary.
+
+`@vmz/core` is the production runtime behind VMZ's alternative. It executes the creation, patch, SSR, resumption, HTTP,
+and lifetime schedules produced by the compiler. When VMZ can prove that a write affects one text binding, one control
+region, or one keyed item, the runtime can update that target directly rather than begin from a whole component tree.
+
+The same idea continues beyond a single browser update. SSR serializes planned regions; resumption attaches only
+reachable state and event entries instead of repeating completed server work; ownership regions give async tasks and
+resources a deterministic end; server and HTTP output stay tied to compiler-visible capabilities.
+
+| Instead of...                      | VMZ runtime work begins from...                       |
+|------------------------------------|-------------------------------------------------------|
+| Re-running a component tree        | A known affected binding or region                    |
+| Reconciling a generic virtual tree | Direct create, patch, switch, or keyed-list work      |
+| Hydrating every rendered component | The event and state entries that are actually reached |
+| Hoping cleanup follows callbacks   | A compiler-known ownership and disposal boundary      |
+
+For application authors, this mostly stays out of sight: write VMZ source and let the compiler generate the plan.
+`@vmz/core` matters when you care about the kind of runtime your product ships: small in responsibility, direct in
+execution, and able to account for why its work exists. 🌱
+
+## The hot path VMZ is aiming for
+
+```text
+state write
+  -> known dependency edge
+  -> affected computation or region
+  -> direct patch / switch / reconcile
+```
+
+There is no default detour through “execute every component that might matter, build virtual nodes, then compare them.”
+If analysis must widen, it widens to a safe region and should preserve the reason.
+
+## More than DOM updates
+
+- **Transactions:** related writes can settle before dependent work runs.
+- **Ownership:** branches, list items, resources, and tasks have a known lifetime.
+- **Cancellation:** an obsolete navigation or async generation cannot write into new state.
+- **Resumption:** the browser attaches to server-produced work at the smallest reachable boundary.
+- **Zero-JS delivery:** pages with no interactive requirement do not need an eager framework shell.
+
+The runtime should not grow a second compiler made of reflection, string dependencies, or generic proxies. Its quality
+comes from faithfully executing the generated plan while keeping the production surface focused.
+
+## License
+
+MIT

package/dist/browser/dom/component.d.ts

@@ -5,6 +5,24 @@ export declare function findOwnedDefaultSlot(root: any): any;
 export declare function findOwnedDefaultSlotTarget(root: any): any;
 export declare function createInstance(Component: any, props?: any): any;
 export declare function destroy(inst: any): void;
+/**
+ * DocumentFragment anchors are emptied by insertion (children move out, the
+ * fragment keeps no parentNode), so a projected fragment must anchor on its
+ * last child. Capture before inserting.
+ */
+export declare function slotAnchorFor(node: any): any;
+export declare function insertProjectedSlotNode(target: any, node: any): any;
+/**
+ * Hold projected children until the component's default slot exists.
+ *
+ * A slot inside an unmounted `v-if` branch (closed drawer/dialog, loading
+ * skeleton) is absent at projection time. Appending to the component root would
+ * paint the child into the live page, so keep it detached and splice it in when
+ * the slot is mounted.
+ */
+export declare function parkSlotNode(hostEl: any, node: any): void;
+/** Move parked children into the now-mounted default slot. Returns true when drained. */
+export declare function flushParkedSlotNodes(hostEl: any): boolean;
 export declare function disposeDomTree(root: any): void;
 export declare function snapshotInstanceState(inst: any): {};
 export declare function applyPreservedState(inst: any, state: any): void;

package/dist/browser/dom/component.js

@@ -183,6 +183,97 @@ export function destroy(inst) {
         }
     }
 }
+/**
+ * DocumentFragment anchors are emptied by insertion (children move out, the
+ * fragment keeps no parentNode), so a projected fragment must anchor on its
+ * last child. Capture before inserting.
+ */
+export function slotAnchorFor(node) {
+    return node && node.nodeType === 11 ? node.lastChild : node;
+}
+export function insertProjectedSlotNode(target, node) {
+    if (!target || !node)
+        return null;
+    const anchor = slotAnchorFor(node);
+    if (String(target.tagName || '').toLowerCase() === 'slot') {
+        target.replaceWith(node);
+        return anchor;
+    }
+    target.appendChild(node);
+    return anchor;
+}
+/**
+ * Hold projected children until the component's default slot exists.
+ *
+ * A slot inside an unmounted `v-if` branch (closed drawer/dialog, loading
+ * skeleton) is absent at projection time. Appending to the component root would
+ * paint the child into the live page, so keep it detached and splice it in when
+ * the slot is mounted.
+ */
+export function parkSlotNode(hostEl, node) {
+    if (!hostEl || !node)
+        return;
+    if (typeof MutationObserver === 'undefined') {
+        // Non-browser DOM (unit hosts): preserve the legacy root fallback.
+        const child = hostEl.__vmzInst;
+        const root = (child && child.__vmzDomRoot) || hostEl;
+        if (root && root.nodeType === 1 && typeof root.appendChild === 'function')
+            root.appendChild(node);
+        else if (typeof hostEl.appendChild === 'function')
+            hostEl.appendChild(node);
+        return;
+    }
+    const parked = hostEl.__vmzSlotParked || (hostEl.__vmzSlotParked = []);
+    parked.push(node);
+    if (hostEl.__vmzSlotObserver)
+        return;
+    hostEl.__vmzSlotObserver = new MutationObserver(() => {
+        flushParkedSlotNodes(hostEl);
+    });
+    const scope = (hostEl.__vmzInst && hostEl.__vmzInst.__vmzDomRoot) || hostEl;
+    if (scope && scope.nodeType === 1) {
+        hostEl.__vmzSlotObserver.observe(scope, { childList: true, subtree: true });
+    }
+}
+/** Move parked children into the now-mounted default slot. Returns true when drained. */
+export function flushParkedSlotNodes(hostEl) {
+    if (!hostEl)
+        return false;
+    const parked = hostEl.__vmzSlotParked;
+    if (!parked || !parked.length)
+        return false;
+    const child = hostEl.__vmzInst;
+    const root = (child && child.__vmzDomRoot) || hostEl;
+    if (!root || root.nodeType !== 1)
+        return false;
+    const target = findOwnedDefaultSlotTarget(root);
+    if (!target || !target.parentNode)
+        return false;
+    if (hostEl.__vmzSlotObserver) {
+        hostEl.__vmzSlotObserver.disconnect();
+        hostEl.__vmzSlotObserver = null;
+    }
+    hostEl.__vmzSlotParked = [];
+    const anchor = slotAnchorFor(parked[parked.length - 1]);
+    const tag = String(target.tagName || '').toLowerCase();
+    if (tag === 'slot') {
+        const frag = typeof document !== 'undefined' ? document.createDocumentFragment() : null;
+        if (!frag) {
+            target.replaceWith(parked[0]);
+            hostEl.__vmzSlotAnchor = anchor;
+            return true;
+        }
+        for (const node of parked)
+            frag.appendChild(node);
+        target.replaceWith(frag);
+        hostEl.__vmzSlotAnchor = anchor;
+        return true;
+    }
+    for (const node of parked)
+        target.appendChild(node);
+    hostEl.__vmzSlotAnchor = anchor;
+    return true;
+}
 export function disposeDomTree(root) {
     if (!root)
         return;
@@ -205,6 +296,14 @@ export function disposeDomTree(root) {
             node.__vmzInst = null;
             destroy(child);
         }
+        if (node.__vmzSlotObserver) {
+            node.__vmzSlotObserver.disconnect();
+            node.__vmzSlotObserver = null;
+        }
+        if (node.__vmzSlotParked)
+            node.__vmzSlotParked = [];
+        if (node.__vmzSlotAnchor)
+            node.__vmzSlotAnchor = null;
         let child = node.firstChild;
         while (child) {
             const next = child.nextSibling;

package/dist/browser/dom/direct-api.d.ts

@@ -13,6 +13,8 @@ export declare const directApi: {
     el(tag: any): any;
     elNS(ns: any, tag: any): Element;
     text(value: any): Text;
+    nsScopeDepth(): number;
+    rewindNsScope(depth: any): void;
     adoptEnter(node: any): boolean;
     adoptLeave(): void;
     frag(): DocumentFragment;

package/dist/browser/dom/direct-api.js

@@ -2,11 +2,34 @@ import { mergeClassParts, mergeStyleParts } from '../../shared/dom-attr-normaliz
 import { applyDirectHostBox } from '../direct-host-box.js';
 import { createUnknownComponentElement } from '../unknown-component.js';
 import { applyDomAttr, eventPropHandlerName } from './attributes.js';
-import { createInstance, disposeDomTree, findOwnedDefaultSlotTarget, runDirectCreate, stripFns } from './component.js';
+import { createInstance, disposeDomTree, findOwnedDefaultSlotTarget, insertProjectedSlotNode, parkSlotNode, runDirectCreate, slotAnchorFor, stripFns, } from './component.js';
 import { isEventEntryStrategy, noteDomCreate, noteDomRemove, scheduleClientOn } from './lifecycle.js';
 import { components, resolveComponent } from './registry.js';
 import { beginEventFlush, endEventFlush, inferHandlerMethod, methodAllowsSyncEventFlush, registerBind, runDomEventHandler, runPatch, scheduleRefresh, unregisterBind, } from '../reactivity/patch-scheduler.js';
 let directPropBindSeq = 0;
+const SVG_NS = 'http://www.w3.org/2000/svg';
+/**
+ * Nesting depth of inline `<svg>` subtrees during create/resume.
+ *
+ * Template emit creates every element through `api.el(tag)` and brackets each
+ * subtree with `adoptEnter`/`adoptLeave`. Elements inside `<svg>` must be built
+ * with `createElementNS`, otherwise the browser returns an HTMLUnknownElement:
+ * attribute names lose their case (`viewBox` → `viewbox`) and the node lays out
+ * at 0×0. Track the depth here so the generator stays namespace-agnostic.
+ */
+const nsStack = [];
+function inSvgScope() {
+    return nsStack.length > 0 && nsStack[nsStack.length - 1] === true;
+}
+function isSvgNode(node) {
+    if (!node || typeof node !== 'object')
+        return false;
+    const ns = node.namespaceURI;
+    if (ns === SVG_NS)
+        return true;
+    const tag = node.tagName;
+    return tag != null && String(tag).toLowerCase() === 'svg' && ns == null;
+}
 export const directApi = {
     _inst: null,
     _branchBinds: null,
@@ -14,17 +37,19 @@ export const directApi = {
     _eachCtx: null,
     _resumeAdopt: null,
     el(tag) {
+        const name = tag || 'div';
+        const svg = inSvgScope() || name === 'svg';
         if (directApi._resumeAdopt)
-            return directApi._resumeAdopt.el(tag);
+            return directApi._resumeAdopt.el(name, svg);
         noteDomCreate();
-        return document.createElement(tag || 'div');
+        return svg ? document.createElementNS(SVG_NS, name) : document.createElement(name);
     },
     elNS(ns, tag) {
         if (directApi._resumeAdopt && typeof directApi._resumeAdopt.elNS === 'function') {
             return directApi._resumeAdopt.elNS(ns, tag);
         }
         noteDomCreate();
-        return document.createElementNS(ns || 'http://www.w3.org/2000/svg', tag || 'g');
+        return document.createElementNS(ns || SVG_NS, tag || 'g');
     },
     text(value) {
         if (directApi._resumeAdopt)
@@ -32,7 +57,16 @@ export const directApi = {
         noteDomCreate();
         return document.createTextNode(value == null ? '' : String(value));
     },
+    nsScopeDepth() {
+        return nsStack.length;
+    },
+    rewindNsScope(depth) {
+        const target = Math.max(0, Number(depth) || 0);
+        while (nsStack.length > target)
+            nsStack.pop();
+    },
     adoptEnter(node) {
+        nsStack.push(isSvgNode(node));
         const adopt = directApi._resumeAdopt;
         if (adopt && typeof adopt.enter === 'function') {
             const ok = adopt.enter(node);
@@ -43,6 +77,7 @@ export const directApi = {
         return false;
     },
     adoptLeave() {
+        nsStack.pop();
         const adopt = directApi._resumeAdopt;
         // Emit always pairs leave after enter; if enter failed (fresh node, no
         // pool), do not pop ??unbalanced leave previously stole parent scopes
@@ -431,16 +466,21 @@ export const directApi = {
             root = hostEl;
         const target = root && root.nodeType === 1 ? findOwnedDefaultSlotTarget(root) : null;
         if (target && target.parentNode) {
-            if (String(target.tagName || '').toLowerCase() === 'slot') {
-                target.replaceWith(node);
-                return;
-            }
-            target.appendChild(node);
+            hostEl.__vmzSlotAnchor = insertProjectedSlotNode(target, node);
+            return;
+        }
+        // The `<slot>` was already replaced by an earlier projected child, so this
+        // call appends after the last one instead of re-searching for a slot.
+        const anchor = hostEl.__vmzSlotAnchor;
+        if (anchor && anchor.parentNode) {
+            const nextAnchor = slotAnchorFor(node);
+            anchor.parentNode.insertBefore(node, anchor.nextSibling);
+            hostEl.__vmzSlotAnchor = nextAnchor;
             return;
         }
-        if (root && root.nodeType === 1 && typeof root.appendChild === 'function')
-            root.appendChild(node);
-        else
-            hostEl.appendChild(node);
+        // Component slot may live inside an unmounted `v-if` branch (closed overlay,
+        // loading skeleton). Parking the child until the slot appears keeps it out of
+        // the component root, where it would otherwise leak into the rendered page.
+        parkSlotNode(hostEl, node);
     },
 };

package/dist/browser/dom-core.types.d.ts

@@ -69,7 +69,7 @@ export type TraceBuffer = {
     events: TraceEvent[];
 };
 export type ResumeAdoptCtx = {
-    el: (tag: string) => Element;
+    el: (tag: string, svg?: boolean) => Element;
     elNS?: (ns: string, tag: string) => Element;
     text: (value?: unknown) => Text;
     componentHost?: (name: string) => HTMLElement | null;

package/dist/browser/reactivity/patch-scheduler.js

@@ -53,6 +53,32 @@ export function scheduleRefresh(inst, notice) {
         }
     });
 }
+const ARROW_SIGNATURE = /^(?:async\s*)?(?:\(([^)]*)\)|([A-Za-z_$][\w$]*))\s*=>\s*([\s\S]*)$/;
+const EVENT_PASSTHROUGH_CALL = /^this\.([A-Za-z_$][\w$]*)\s*\(([^)]*)\)\s*;?$/;
+/**
+ * Direct-bind hint for `(ev) => this.method(ev)` handlers only. The closure is
+ * replaced by `method.call(inst, ev)`, so the shape must forward exactly the
+ * event: a handler that passes its own literal arguments (`() => this.pick("dark")`)
+ * must keep running as a closure, otherwise the event would overwrite the argument.
+ */
+function inferEventPassthroughMethod(src) {
+    const arrow = src.match(ARROW_SIGNATURE);
+    if (!arrow)
+        return null;
+    const params = (arrow[1] ?? arrow[2] ?? '')
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    if (params.length !== 1)
+        return null;
+    let body = arrow[3].trim();
+    if (body.startsWith('{') && body.endsWith('}'))
+        body = body.slice(1, -1).trim();
+    const call = body.match(EVENT_PASSTHROUGH_CALL);
+    if (!call || call[2].trim() !== params[0])
+        return null;
+    return call[1];
+}
 export function inferHandlerMethod(handler) {
     if (typeof handler !== 'function')
         return null;
@@ -62,8 +88,7 @@ export function inferHandlerMethod(handler) {
     let name = null;
     try {
         const src = Function.prototype.toString.call(handler);
-        const m = src.match(/this\.([A-Za-z_$][\w$]*)\s*\(/);
-        name = m ? m[1] : null;
+        name = inferEventPassthroughMethod(src);
     }
     catch {
         name = null;

package/dist/browser/resume/adopt.js

@@ -1,19 +1,8 @@
 import { directApi, noteDomCreate, runDirectCreate, } from '../dom-core.js';
+const SVG_NS = 'http://www.w3.org/2000/svg';
 function createResumeAdopt(pool, rootEl) {
     const used = new WeakSet();
     const scopeStack = [pool];
-    const walkTexts = (root, visit) => {
-        if (!root)
-            return;
-        if (root.nodeType === 3) {
-            visit(root);
-            return;
-        }
-        if (root.nodeType !== 1)
-            return;
-        for (let c = root.firstChild; c; c = c.nextSibling)
-            walkTexts(c, visit);
-    };
     const currentScope = () => scopeStack[scopeStack.length - 1] || pool;
     const markElement = (n) => {
         used.add(n);
@@ -42,27 +31,36 @@ function createResumeAdopt(pool, rootEl) {
             }
         }
     }
+    /**
+     * Text bindings always belong to the element whose scope is active, so only
+     * direct text children are candidates. Recursing into element children
+     * lets an earlier binding steal the text of a sibling that has not been
+     * adopted yet (soft navigation lost the landing CTA label this way).
+     */
     function* textCandidates() {
         const scope = currentScope();
-        const kids = [...scope.childNodes];
-        for (const n of kids) {
-            const found = [];
-            walkTexts(n, (t) => {
-                if (!used.has(t))
-                    found.push(t);
-            });
-            for (const t of found)
-                yield t;
+        for (const n of [...scope.childNodes]) {
+            if (n.nodeType === 3 && !used.has(n))
+                yield n;
         }
     }
-    const adoptElement = (tag) => {
+    const adoptElement = (tag, svg = false) => {
         const want = String(tag || 'div').toLowerCase();
         for (const el of elementCandidates()) {
             if (String(el.tagName).toLowerCase() === want)
                 return markElement(el);
         }
         noteDomCreate();
-        return document.createElement(tag || 'div');
+        return svg ? document.createElementNS(SVG_NS, tag || 'svg') : document.createElement(tag || 'div');
+    };
+    const adoptElementNS = (ns, tag) => {
+        const want = String(tag || 'g');
+        for (const el of elementCandidates()) {
+            if (el.namespaceURI === ns && String(el.localName) === want)
+                return markElement(el);
+        }
+        noteDomCreate();
+        return document.createElementNS(ns || SVG_NS, want);
     };
     const adoptText = (value) => {
         for (const n of textCandidates()) {
@@ -125,6 +123,7 @@ function createResumeAdopt(pool, rootEl) {
     };
     return {
         el: adoptElement,
+        elNS: adoptElementNS,
         text: adoptText,
         componentHost,
         enter,
@@ -148,6 +147,7 @@ export function runDirectResume(Component, inst, container) {
     const prevItems = directApi._itemPatches;
     const prevEach = directApi._eachCtx;
     const prevAdopt = directApi._resumeAdopt;
+    const prevNsDepth = directApi.nsScopeDepth();
     directApi._inst = inst;
     directApi._branchBinds = null;
     directApi._itemPatches = null;
@@ -157,6 +157,7 @@ export function runDirectResume(Component, inst, container) {
         return Component.__vmzCreate.call(inst, directApi);
     }
     finally {
+        directApi.rewindNsScope(prevNsDepth);
         directApi._resumeAdopt = prevAdopt;
         directApi._inst = prevInst;
         directApi._branchBinds = prevBranch;

package/dist/faces/server.js

@@ -605,32 +605,32 @@ function wantsBrowserHtml(req) {
 function browserErrorHtml(status, title, message, stack) {
     const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
     const stackBlock = stack ? `<pre class="stack">${esc(stack)}</pre>` : '';
-    return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>${esc(title)}</title>
-  <style>
-    body{margin:0;background:#0f1115;color:#f4f4f5;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
-    main{max-width:56rem;margin:0 auto;padding:2rem 1.25rem}
-    h1{margin:0 0 .75rem;color:#f87171;font-size:1.1rem}
-    .code{opacity:.65;font-size:12px;margin-bottom:.75rem}
-    pre{white-space:pre-wrap;margin:0 0 1rem}
-    .stack{opacity:.7;font-size:12px}
-    .hint{opacity:.65;font-size:12px}
-  </style>
-</head>
-<body data-vmz-error="${status}">
-  <main>
-    <p class="code">HTTP ${status}</p>
-    <h1>${esc(title)}</h1>
-    <pre>${esc(message)}</pre>
-    ${stackBlock}
-    <p class="hint">Document navigation returns HTML errors — not API JSON.</p>
-  </main>
-</body>
-</html>
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${esc(title)}</title>
+  <style>
+    body{margin:0;background:#0f1115;color:#f4f4f5;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+    main{max-width:56rem;margin:0 auto;padding:2rem 1.25rem}
+    h1{margin:0 0 .75rem;color:#f87171;font-size:1.1rem}
+    .code{opacity:.65;font-size:12px;margin-bottom:.75rem}
+    pre{white-space:pre-wrap;margin:0 0 1rem}
+    .stack{opacity:.7;font-size:12px}
+    .hint{opacity:.65;font-size:12px}
+  </style>
+</head>
+<body data-vmz-error="${status}">
+  <main>
+    <p class="code">HTTP ${status}</p>
+    <h1>${esc(title)}</h1>
+    <pre>${esc(message)}</pre>
+    ${stackBlock}
+    <p class="hint">Document navigation returns HTML errors — not API JSON.</p>
+  </main>
+</body>
+</html>
 `;
 }
 function sendJson(res, status, body) {

package/dist/host/serve/hmr-dev.js

@@ -87,29 +87,29 @@ export function normalizeDevError(err) {
 export async function* emitDevErrorHtml(err) {
     const msg = escapeHtml(err.message || 'Unknown error');
     const stack = err.stack ? escapeHtml(err.stack) : '';
-    const style = `<style>
-    body{margin:0;background:#0f1115;color:#f4f4f5;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
-    main{max-width:56rem;margin:0 auto;padding:2rem 1.25rem}
-    h1{margin:0 0 .75rem;color:#f87171;font-size:1.1rem}
-    pre{white-space:pre-wrap;margin:0 0 1rem}
-    .hint{opacity:.65;font-size:12px}
+    const style = `<style>
+    body{margin:0;background:#0f1115;color:#f4f4f5;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+    main{max-width:56rem;margin:0 auto;padding:2rem 1.25rem}
+    h1{margin:0 0 .75rem;color:#f87171;font-size:1.1rem}
+    pre{white-space:pre-wrap;margin:0 0 1rem}
+    .hint{opacity:.65;font-size:12px}
   </style>`;
-    const body = `${style}
-  <main data-vmz-error="500">
-    <h1>Dev Error</h1>
-    <pre>${msg}</pre>
-    ${stack ? `<pre style="opacity:.7;font-size:12px">${stack}</pre>` : ''}
-    <p class="hint">Dev host stayed up. Fix the source and save — soft reload will recover.</p>
-  </main>
-  <script>
-  (() => {
-    const es = new EventSource("/__vmz/events");
-    es.onmessage = (ev) => {
-      let msg = null;
-      try { msg = JSON.parse(ev.data); } catch {}
-      if (msg && msg.type === "hmr") location.reload();
-    };
-  })();
+    const body = `${style}
+  <main data-vmz-error="500">
+    <h1>Dev Error</h1>
+    <pre>${msg}</pre>
+    ${stack ? `<pre style="opacity:.7;font-size:12px">${stack}</pre>` : ''}
+    <p class="hint">Dev host stayed up. Fix the source and save — soft reload will recover.</p>
+  </main>
+  <script>
+  (() => {
+    const es = new EventSource("/__vmz/events");
+    es.onmessage = (ev) => {
+      let msg = null;
+      try { msg = JSON.parse(ev.data); } catch {}
+      if (msg && msg.type === "hmr") location.reload();
+    };
+  })();
   </script>`;
     try {
         const native = loadNativeAddon();

package/dist/host/serve/page-render.js

@@ -222,11 +222,11 @@ async function* emitAccessShell(marker) {
         bodyAttrs: [],
     });
 }
-function resolvePageDocumentMeta(Page) {
+function resolvePageDocumentMeta(Page, ctx = {}) {
     try {
         let raw = {};
         if (typeof Page?.meta === 'function')
-            raw = Page.meta() || {};
+            raw = Page.meta(ctx) || {};
         else if (Page?.meta && typeof Page.meta === 'object')
             raw = Page.meta;
         const title = String(raw.title || '').trim();
@@ -240,79 +240,79 @@ function resolvePageDocumentMeta(Page) {
 async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {}, layoutChain = [], localeCtx = {}) {
     const signal = opts.signal;
     const live = serveState.isDev
-        ? `\n  <script>
-  (() => {
-    const es = new EventSource("/__vmz/events");
-    let sawDisconnect = false;
-    es.onerror = () => { sawDisconnect = true; };
-    es.onopen = () => {
-      if (sawDisconnect) location.reload();
-    };
-    function showOverlay(err) {
-      let el = document.getElementById("vmz-dev-overlay");
-      if (!el) {
-        el = document.createElement("div");
-        el.id = "vmz-dev-overlay";
-        el.setAttribute("role", "alert");
-        Object.assign(el.style, {
-          position: "fixed", inset: "0", zIndex: "2147483646",
-          background: "rgba(15,17,21,0.92)", color: "#f4f4f5",
-          fontFamily: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
-          padding: "2rem", overflow: "auto",
-        });
-        document.documentElement.appendChild(el);
-      }
-      const msg = (err && err.message) || String(err || "Unknown error");
-      const stack = (err && err.stack) || "";
-      const esc = (s) => String(s).replace(/[&<>]/g, (c) => ({"&":"&amp;","<":"&lt;",">":"&gt;"}[c]));
-      el.innerHTML = "<div style=\\"max-width:56rem;margin:0 auto\\">"
-        + "<p style=\\"margin:0 0 .5rem;color:#f87171;font-weight:700\\">Dev Error</p>"
-        + "<pre style=\\"white-space:pre-wrap;margin:0 0 1rem;font-size:13px;line-height:1.45\\">" + esc(msg) + "</pre>"
-        + (stack ? "<pre style=\\"white-space:pre-wrap;opacity:.7;font-size:12px\\">" + esc(stack) + "</pre>" : "")
-        + "<p style=\\"opacity:.65;font-size:12px\\">Fix the file and save — soft reload will clear this overlay.</p>"
-        + "</div>";
-    }
-    function hideOverlay() {
-      const el = document.getElementById("vmz-dev-overlay");
-      if (el) el.remove();
-    }
-    es.onmessage = async (ev) => {
-      let msg = null;
-      try { msg = JSON.parse(ev.data); } catch { /* plain string */ }
-      if (msg && msg.type === "error") {
-        showOverlay(msg);
-        return;
-      }
-      if (!msg || msg.type !== "hmr") {
-        if (ev.data === "reload") location.reload();
-        return;
-      }
-      hideOverlay();
-      if (msg.mode === "island") {
-        try {
-          const { hydrate } = await import("/dom.browser.js?t=" + msg.token);
-          const root = document.getElementById("app");
-          const pageChunk = root && root.getAttribute("data-vmz-page");
-          if (root && pageChunk) {
-            const pageMod = await import("/" + pageChunk + ".client.js?t=" + msg.token);
-            let hmrProps = {};
-            try {
-              const raw = root.getAttribute("data-vmz-props");
-              if (raw) hmrProps = JSON.parse(raw);
-            } catch { /* ignore */ }
-            await hydrate(pageMod.default, root, hmrProps, { preserveState: true, skipOnMount: true });
-          } else {
-            location.reload();
-          }
-        } catch (err) {
-          console.error("vmz island HMR failed", err);
-          showOverlay({ message: String(err && err.message || err), stack: err && err.stack });
-        }
-        return;
-      }
-      location.reload();
-    };
-  })();
+        ? `\n  <script>
+  (() => {
+    const es = new EventSource("/__vmz/events");
+    let sawDisconnect = false;
+    es.onerror = () => { sawDisconnect = true; };
+    es.onopen = () => {
+      if (sawDisconnect) location.reload();
+    };
+    function showOverlay(err) {
+      let el = document.getElementById("vmz-dev-overlay");
+      if (!el) {
+        el = document.createElement("div");
+        el.id = "vmz-dev-overlay";
+        el.setAttribute("role", "alert");
+        Object.assign(el.style, {
+          position: "fixed", inset: "0", zIndex: "2147483646",
+          background: "rgba(15,17,21,0.92)", color: "#f4f4f5",
+          fontFamily: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
+          padding: "2rem", overflow: "auto",
+        });
+        document.documentElement.appendChild(el);
+      }
+      const msg = (err && err.message) || String(err || "Unknown error");
+      const stack = (err && err.stack) || "";
+      const esc = (s) => String(s).replace(/[&<>]/g, (c) => ({"&":"&amp;","<":"&lt;",">":"&gt;"}[c]));
+      el.innerHTML = "<div style=\\"max-width:56rem;margin:0 auto\\">"
+        + "<p style=\\"margin:0 0 .5rem;color:#f87171;font-weight:700\\">Dev Error</p>"
+        + "<pre style=\\"white-space:pre-wrap;margin:0 0 1rem;font-size:13px;line-height:1.45\\">" + esc(msg) + "</pre>"
+        + (stack ? "<pre style=\\"white-space:pre-wrap;opacity:.7;font-size:12px\\">" + esc(stack) + "</pre>" : "")
+        + "<p style=\\"opacity:.65;font-size:12px\\">Fix the file and save — soft reload will clear this overlay.</p>"
+        + "</div>";
+    }
+    function hideOverlay() {
+      const el = document.getElementById("vmz-dev-overlay");
+      if (el) el.remove();
+    }
+    es.onmessage = async (ev) => {
+      let msg = null;
+      try { msg = JSON.parse(ev.data); } catch { /* plain string */ }
+      if (msg && msg.type === "error") {
+        showOverlay(msg);
+        return;
+      }
+      if (!msg || msg.type !== "hmr") {
+        if (ev.data === "reload") location.reload();
+        return;
+      }
+      hideOverlay();
+      if (msg.mode === "island") {
+        try {
+          const { hydrate } = await import("/dom.browser.js?t=" + msg.token);
+          const root = document.getElementById("app");
+          const pageChunk = root && root.getAttribute("data-vmz-page");
+          if (root && pageChunk) {
+            const pageMod = await import("/" + pageChunk + ".client.js?t=" + msg.token);
+            let hmrProps = {};
+            try {
+              const raw = root.getAttribute("data-vmz-props");
+              if (raw) hmrProps = JSON.parse(raw);
+            } catch { /* ignore */ }
+            await hydrate(pageMod.default, root, hmrProps, { preserveState: true, skipOnMount: true });
+          } else {
+            location.reload();
+          }
+        } catch (err) {
+          console.error("vmz island HMR failed", err);
+          showOverlay({ message: String(err && err.message || err), stack: err && err.stack });
+        }
+        return;
+      }
+      location.reload();
+    };
+  })();
   </script>`
         : '';
     const bootOverlay = serveState.isDev && serveState.lastDevError
@@ -349,7 +349,7 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
             htmlExtraAttrs.push('data-vmz-locale-hrefs', JSON.stringify(hrefTable));
         }
     }
-    const pageDocMeta = resolvePageDocumentMeta(Page);
+    const pageDocMeta = resolvePageDocumentMeta(Page, { localeId });
     const prevLocaleHint = globalThis.__vmzLocaleIdHint;
     globalThis.__vmzLocaleIdHint = localeId;
     if (!serveState.ssrRenderHost) {

package/dist/ssr/document.js

@@ -58,8 +58,12 @@ export function ensureSsrDocument() {
             const detail = errors.length ? `\n${errors.join('\n')}` : '';
             throw new Error(`linkedom unresolved for SSR document${detail}`);
         }
-        const { window, document } = parseHTML('<!DOCTYPE html><html><body></body></html>');
-        globalThis.window = window;
+        // SSR host contract: expose `document` only. Installing the linkedom
+        // `window` would make `typeof window !== "undefined"` true on the server
+        // while still having no browser `location`, so client code would take
+        // browser branches and diverge from the browser lifecycle. The window is
+        // still reachable as `document.defaultView` when DOM APIs need it.
+        const { document } = parseHTML('<!DOCTYPE html><html><body></body></html>');
         globalThis.document = document;
         _ssrDocumentLastError = null;
         return typeof document.createElement === 'function';

package/dist/ssr/serialize.js

@@ -548,8 +548,9 @@ const serializeApi = {
             target.children.push(node);
             return;
         }
-        if (root)
-            root.appendChild(node);
+        // No default slot in this render: children belong to a branch that is not
+        // mounted (closed overlay, loading skeleton). Mirror the browser runtime and
+        // drop them instead of painting them into the component root.
     },
     setHtml(el, value) {
         if (!el || el.__kind !== 'el')

package/package.json

@@ -68,12 +68,12 @@
   "main": "./dist/faces/server.js",
   "name": "@vmz/core",
   "optionalDependencies": {
-    "@vmz/vmz-darwin-arm64": "0.3.6",
-    "@vmz/vmz-darwin-x64": "0.3.6",
-    "@vmz/vmz-linux-arm64": "0.3.6",
-    "@vmz/vmz-linux-x64": "0.3.6",
-    "@vmz/vmz-win32-arm64": "0.3.6",
-    "@vmz/vmz-win32-x64": "0.3.6"
+    "@vmz/vmz-darwin-arm64": "0.3.8",
+    "@vmz/vmz-darwin-x64": "0.3.8",
+    "@vmz/vmz-linux-arm64": "0.3.8",
+    "@vmz/vmz-linux-x64": "0.3.8",
+    "@vmz/vmz-win32-arm64": "0.3.8",
+    "@vmz/vmz-win32-x64": "0.3.8"
   },
   "publishConfig": {
     "access": "public"
@@ -88,5 +88,5 @@
   },
   "type": "module",
   "types": "./dist/faces/index.d.ts",
-  "version": "0.3.6"
+  "version": "0.3.8"
 }