@vmz/core 0.3.13 → 0.3.15

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

@@ -7,7 +7,15 @@ export type ComponentCtor = ComponentCtorLike & {
     [key: string]: unknown;
 };
 export type VmzDomElement = Element & {
+    /** `v-pre` subtree: attributes are written exactly as authored. */
+    __vmzVerbatim?: boolean;
     __vmzEvt?: Record<string, EventListener>;
+    __vmzObjEvt?: Record<string, {
+        types: Record<string, {
+            handlers: Function[];
+            wrapper: EventListener;
+        }>;
+    }>;
     __vmzInst?: DirectInstance;
     __vmzPropBindSeq?: number;
     __vmzDispose?: (() => void) | null;
@@ -69,15 +77,24 @@ export type TraceBuffer = {
     events: TraceEvent[];
 };
 export type ResumeAdoptCtx = {
-    el: (tag: string, svg?: boolean) => Element;
+    el: (tag: string, svg?: boolean, key?: unknown) => Element;
     elNS?: (ns: string, tag: string) => Element;
     text: (value?: unknown) => Text;
-    componentHost?: (name: string) => HTMLElement | null;
+    componentHost?: (name: string, key?: unknown) => HTMLElement | null;
     enter?: (node: Element) => boolean;
+    /** Open a named `<slot name="…">` projection scope inside a component host. */
+    enterSlot?: (hostEl: Element, name: string) => boolean;
     leave?: () => void;
     scopeDepth?: () => number;
     rewindScope?: (depth: number) => void;
     beginBranchScope?: () => () => void;
+    /** Open a multi-root `<template v-for>` row scope (claim the SSR marker pair). */
+    rowStart?: (key: unknown) => boolean;
+    rowEnd?: () => void;
+    /** Keep the parked SSR subtree when its SSR payload digest equals `digest`. */
+    reclaimHtml?: (el: Element, digest: string) => boolean;
+    /** Keep the parked SSR subtree when this create has no payload yet. */
+    keepHtml?: (el: Element) => boolean;
     _enterBalance?: number;
     inst?: DirectInstance;
 };

package/dist/browser/navigation/client-navigation.js

@@ -39,9 +39,6 @@ export function installClientNavigation(opts = {}) {
         else if (win?.vmzDestroy)
             win.vmzDestroy(inst);
     }
-    async function loadDomFallback() {
-        return import(/* @vite-ignore */ '/dom.browser.js');
-    }
     async function transitionTo(url, { replace = false, fromPop = false, softFail = false } = {}) {
         const target = new URL(url, loc.href);
         if (target.origin !== loc.origin) {
@@ -98,7 +95,12 @@ export function installClientNavigation(opts = {}) {
                 else
                     hist.pushState({ vmzClientNav: true }, '', target.href);
             }
-            const importChunk = opts.importPage || (async (id) => (await import(/* @vite-ignore */ `/${id}.client.js`)).default);
+            const importChunk = (id) => {
+                if (typeof opts.importPage !== 'function') {
+                    throw new Error('vmz:client-nav missing importPage — the generated entry must pass the pack manifest table');
+                }
+                return opts.importPage(id);
+            };
             let liveRoot = root;
             let retainedLayout = false;
             applyLocaleRealization(doc, nextApp);
@@ -106,28 +108,21 @@ export function installClientNavigation(opts = {}) {
                 applyAppAttrs(root, nextApp);
                 if (chunkId) {
                     const Page = await importChunk(chunkId);
-                    let hydrateRoutePage = opts.hydrateRoutePage;
-                    if (typeof hydrateRoutePage !== 'function') {
-                        const dom = await loadDomFallback();
-                        hydrateRoutePage = dom.hydrateRoutePage;
-                    }
-                    if (typeof hydrateRoutePage === 'function') {
-                        await hydrateRoutePage(Page, root, props);
+                    if (typeof opts.hydrateRoutePage === 'function') {
+                        await opts.hydrateRoutePage(Page, root, props);
                     }
-                    else {
-                        let hydrate = opts.hydrate;
-                        if (typeof hydrate !== 'function') {
-                            const dom = await loadDomFallback();
-                            hydrate = dom.hydrate;
-                        }
+                    else if (typeof opts.hydrate === 'function') {
                         const pageHost = root.__vmzPageHost || root;
                         if (pageHost.__vmzInst)
                             destroyInst(pageHost.__vmzInst);
-                        await hydrate(Page, pageHost, props);
+                        await opts.hydrate(Page, pageHost, props);
                         root.__vmzPageHost = pageHost;
                         if (!root.__vmzLayoutInsts?.length)
                             root.__vmzInst = pageHost.__vmzInst;
                     }
+                    else {
+                        throw new Error('vmz:client-nav missing hydrateRoutePage and hydrate — the generated entry must pass the packed face');
+                    }
                 }
                 retainedLayout = true;
             }
@@ -148,21 +143,14 @@ export function installClientNavigation(opts = {}) {
                     for (const id of nextLayout) {
                         layoutCtors.push(await importChunk(id));
                     }
-                    let hydrateRoute = opts.hydrateRoute;
-                    if (typeof hydrateRoute !== 'function') {
-                        const dom = await loadDomFallback();
-                        hydrateRoute = dom.hydrateRoute;
+                    if (typeof opts.hydrateRoute === 'function') {
+                        await opts.hydrateRoute(Page, fresh, props, layoutCtors);
                     }
-                    if (typeof hydrateRoute === 'function') {
-                        await hydrateRoute(Page, fresh, props, layoutCtors);
+                    else if (typeof opts.hydrate === 'function') {
+                        await opts.hydrate(Page, fresh, props);
                     }
                     else {
-                        let hydrate = opts.hydrate;
-                        if (typeof hydrate !== 'function') {
-                            const dom = await loadDomFallback();
-                            hydrate = dom.hydrate;
-                        }
-                        await hydrate(Page, fresh, props);
+                        throw new Error('vmz:client-nav missing hydrateRoute and hydrate — the generated entry must pass the packed face');
                     }
                 }
             }

package/dist/browser/reactivity/write-barrier.js

@@ -187,7 +187,11 @@ export function __vmzWritePath(inst, root, segs, value) {
     const rootObj = inst[root];
     const rootArr = rootObj;
     const isRootIndex = normSegs.length === 1 && Array.isArray(rootArr) && leaf !== 'length' && String(Number(leaf)) === leaf;
-    if (isRootIndex) {
+    // Root `rows.length = n` truncates or grows the list itself: the bare `rows`
+    // structure depot only matches a replace notice, so a path notice on
+    // `rows.length` leaves the rendered rows stale.
+    const isRootLength = normSegs.length === 1 && Array.isArray(rootArr) && leaf === 'length';
+    if (isRootIndex || isRootLength) {
         if (!notifyWbShared(rootObj, null)) {
             scheduleRefresh(inst, { type: 'replace', root });
         }

package/dist/browser/resume/adopt.js

@@ -1,9 +1,13 @@
-import { directApi, noteDomCreate, runDirectCreate, } from '../dom-core.js';
+import { directApi, findOwnedDefaultSlot, findOwnedNamedSlot, noteDomCreate, runDirectCreate, } from '../dom-core.js';
+import { HTML_HASH_ATTR } from '../../shared/html-digest.js';
+import { ROW_END_MARKER_PREFIX, ROW_MARKER_PREFIX, rowEndMarker, rowMarker } from '../../shared/row-key.js';
 const SVG_NS = 'http://www.w3.org/2000/svg';
 function createResumeAdopt(pool, rootEl) {
     const used = new WeakSet();
     const scopeStack = [pool];
     const currentScope = () => scopeStack[scopeStack.length - 1] || pool;
+    /** `rootEl`'s children were parked into `pool` before create — see bottom. */
+    let rootElTookPool = false;
     const markElement = (n) => {
         used.add(n);
         if (typeof n.getAttribute === 'function') {
@@ -11,14 +15,32 @@ function createResumeAdopt(pool, rootEl) {
             if (k != null && n.__vmzKey == null)
                 n.__vmzKey = k;
         }
-        // Private child pool ??never dump into the parent/global pool (that let
-        // if branches reclaim Drawer/sibling hosts parked as uncles).
-        const childPool = document.createDocumentFragment();
-        while (n.firstChild)
-            childPool.appendChild(n.firstChild);
+        // `runDirectResume` parks `rootEl`'s children into the top-level pool
+        // before create. Adopting `rootEl` must hand that same pool to it as the
+        // child scope: making a fresh (empty) child pool here would leave every
+        // SSR descendant unreachable and silently recreate the whole subtree.
+        let childPool;
+        if (n === rootEl && !rootElTookPool) {
+            rootElTookPool = true;
+            childPool = pool;
+        }
+        else {
+            // Private child pool ??never dump into the parent/global pool (that let
+            // if branches reclaim Drawer/sibling hosts parked as uncles).
+            childPool = document.createDocumentFragment();
+            while (n.firstChild)
+                childPool.appendChild(n.firstChild);
+        }
         n.__vmzResumePool = childPool;
         return n;
     };
+    /**
+     * Component hosts are claimed only by `componentHost`, never by plain element
+     * adoption. Hosts may be `<span>` (phrasing inline chips) or `<div>` (block
+     * surfaces), so tag matching alone would let a page `<span>` steal a chip host
+     * and force a rebuild.
+     */
+    const isComponentHost = (el) => typeof el.getAttribute === 'function' && el.getAttribute('data-vmz') != null;
     function* elementCandidates() {
         const scope = currentScope();
         if (scope === pool && rootEl && !used.has(rootEl))
@@ -44,14 +66,40 @@ function createResumeAdopt(pool, rootEl) {
                 yield n;
         }
     }
-    const adoptElement = (tag, svg = false) => {
+    const adoptElement = (tag, svg = false, key = null) => {
         const want = String(tag || 'div').toLowerCase();
+        // Keyed non-kernel rows (`component`, `v-once`, `v-memo`) carry their key on
+        // the root, so reclaim by identity. Falling back to tag order reuses a node
+        // that belongs to another key as soon as list order diverges from SSR.
+        if (key != null) {
+            const wanted = String(key);
+            for (const el of elementCandidates()) {
+                if (String(el.tagName).toLowerCase() !== want)
+                    continue;
+                if (typeof el.getAttribute !== 'function')
+                    continue;
+                if (el.getAttribute('data-vmz-key') !== wanted)
+                    continue;
+                return markElement(el);
+            }
+            noteDomCreate();
+            const fresh = svg ? document.createElementNS(SVG_NS, tag || 'svg') : document.createElement(tag || 'div');
+            fresh.__vmzKey = wanted;
+            return fresh;
+        }
         for (const el of elementCandidates()) {
-            if (String(el.tagName).toLowerCase() === want)
+            if (String(el.tagName).toLowerCase() === want && !isComponentHost(el))
                 return markElement(el);
         }
         noteDomCreate();
-        return svg ? document.createElementNS(SVG_NS, tag || 'svg') : document.createElement(tag || 'div');
+        const fresh = svg ? document.createElementNS(SVG_NS, tag || 'svg') : document.createElement(tag || 'div');
+        // Direct SSR flattens `<slot/>` away and writes the projected children in
+        // place, so a rebuilt outlet has no SSR counterpart: its projection stays
+        // in the enclosing scope. Share that scope as the outlet pool so a later
+        // `adoptEnter(host)` can still reclaim the projected subtree.
+        if (want === 'slot')
+            fresh.__vmzResumePool = currentScope();
+        return fresh;
     };
     const adoptElementNS = (ns, tag) => {
         const want = String(tag || 'g');
@@ -62,6 +110,43 @@ function createResumeAdopt(pool, rootEl) {
         noteDomCreate();
         return document.createElementNS(ns || SVG_NS, want);
     };
+    /**
+     * Reclaim the SSR row root for one keyed-each key.
+     *
+     * Tag-order adoption cannot distinguish rows when the client list is already
+     * ahead of the SSR order (persisted state, re-filtered store): the first
+     * `<li>` would be reused for whichever key the client renders first, so the
+     * retained DOM node (focus, caret, typed value) belongs to another key.
+     * Keyed rows carry `data-vmz-key` on the server, so match it exactly and leave
+     * unmatched SSR rows for the pool teardown. `null` means "not present in SSR"
+     * and the caller creates a fresh row.
+     */
+    const claimKeyed = (tag, key) => {
+        if (key == null)
+            return null;
+        const want = String(tag || '').toLowerCase();
+        const wanted = String(key);
+        if (!want)
+            return null;
+        for (const el of elementCandidates()) {
+            if (String(el.tagName).toLowerCase() !== want)
+                continue;
+            if (typeof el.getAttribute !== 'function')
+                continue;
+            if (el.getAttribute('data-vmz-key') !== wanted)
+                continue;
+            // Row kernels own the whole row subtree (no nested each/component), and
+            // `hydrate` reads `root.firstChild` for its text slots. Do not stash the
+            // row's children into a resume pool here: the row must keep its SSR
+            // structure as-is.
+            used.add(el);
+            const k = el.getAttribute('data-vmz-key');
+            if (k != null && el.__vmzKey == null)
+                el.__vmzKey = k;
+            return el;
+        }
+        return null;
+    };
     const adoptText = (value) => {
         for (const n of textCandidates()) {
             used.add(n);
@@ -72,21 +157,78 @@ function createResumeAdopt(pool, rootEl) {
         noteDomCreate();
         return document.createTextNode(value == null ? '' : String(value));
     };
-    const componentHost = (name) => {
+    const componentHost = (name, key = null) => {
         const want = String(name || '');
+        const wanted = key == null ? null : String(key);
         for (const el of elementCandidates()) {
-            if (String(el.tagName).toLowerCase() !== 'div')
-                continue;
             if (el.getAttribute('data-vmz') !== want)
                 continue;
+            if (wanted != null && el.getAttribute('data-vmz-key') !== wanted)
+                continue;
             return markElement(el);
         }
         return null;
     };
+    /** Any parked SSR node in `frag` that no earlier create has claimed. */
+    const hasUnusedNode = (frag) => {
+        for (const n of frag.childNodes) {
+            if (!used.has(n))
+                return true;
+        }
+        return false;
+    };
     const enter = (node) => {
-        if (!node || !node.__vmzResumePool)
+        if (!node)
             return false;
-        scopeStack.push(node.__vmzResumePool);
+        // `adoptEnter(host)` in the parent template wraps the *projection*, not the
+        // component's own internals (its host pool was consumed by the component
+        // create). The parked projection lives under the default `<slot/>` outlet,
+        // so entering the host must push that outlet's pool.
+        const owner = node.__vmzInst;
+        if (owner) {
+            const slot = findOwnedDefaultSlot(owner.__vmzDomRoot);
+            const slotPool = slot && slot.__vmzResumePool;
+            if (slotPool && hasUnusedNode(slotPool)) {
+                scopeStack.push(slotPool);
+                return true;
+            }
+        }
+        // Emitted `adoptEnter` is always paired with `adoptLeave`, but a node that
+        // has no SSR counterpart (fresh element or fresh component host) has no
+        // parked pool. Returning without pushing made that paired leave pop the
+        // caller's scope instead, so each rebuilt node drifted the stack one level
+        // up and later projection siblings (slot roots 2..n) lost their pool.
+        // Push an isolated empty scope: the rebuilt subtree has no SSR counterpart
+        // to reclaim, and its children must not steal the enclosing siblings.
+        scopeStack.push(node.__vmzResumePool || document.createDocumentFragment());
+        return true;
+    };
+    /**
+     * Push the parked pool of an owned named `<slot name="…">` outlet.
+     *
+     * SSR inlines named projections exactly like the default outlet, so the nodes
+     * a page projects into `#header` sit under the named outlet and stay
+     * unreachable from the default pool that `enter(host)` pushes. Without this
+     * scope the named projection is rebuilt on every load while the default
+     * projection is reclaimed. A host without that outlet (fresh component or a
+     * name the component never declares) gets an isolated empty scope so the
+     * emitted enter/leave pair always stays balanced.
+     */
+    const enterSlot = (hostEl, name) => {
+        if (!hostEl)
+            return false;
+        const wanted = name == null ? '' : String(name);
+        if (!wanted || wanted === 'default')
+            return enter(hostEl);
+        const owner = hostEl.__vmzInst;
+        const root = (owner && owner.__vmzDomRoot) || hostEl;
+        const slot = root && root.nodeType === 1 ? findOwnedNamedSlot(root, wanted) : null;
+        const slotPool = slot && slot.__vmzResumePool;
+        if (slotPool && hasUnusedNode(slotPool)) {
+            scopeStack.push(slotPool);
+            return true;
+        }
+        scopeStack.push(document.createDocumentFragment());
         return true;
     };
     const leave = () => {
@@ -121,16 +263,144 @@ function createResumeAdopt(pool, rootEl) {
             rewindScope(depth - 1);
         };
     };
+    /**
+     * `v-html` on a reclaimed element. `markElement` parked its SSR children, so
+     * the live element reads empty. SSR stamped the digest of the exact payload
+     * string it wrote on the host (`HTML_HASH_ATTR`), so compare that marker with
+     * the digest of the string this create would write: equal means the parked
+     * subtree already *is* that payload, and moving it back keeps every SSR node.
+     * A different digest drops the parked payload so the normal write replaces it.
+     */
+    const reclaimHtml = (el, digest) => {
+        if (!used.has(el))
+            return false;
+        const childPool = el.__vmzResumePool;
+        const stamp = String(el.getAttribute(HTML_HASH_ATTR) || '');
+        if (stamp !== digest) {
+            // A different payload replaces this host, so parked SSR children can
+            // never be adopted afterwards. Drop them now instead of leaving a
+            // stale pool for a later identical patch to resurrect.
+            if (childPool)
+                while (childPool.firstChild)
+                    childPool.removeChild(childPool.firstChild);
+            return false;
+        }
+        if (childPool)
+            while (childPool.firstChild)
+                el.appendChild(childPool.firstChild);
+        return true;
+    };
+    /**
+     * `v-html` create with no payload yet (e.g. an async highlighter that has
+     * not produced one). The host may still own the SSR payload: hand the parked
+     * subtree back and leave the SSR stamp untouched so a later authoritative
+     * patch can still match it. The host keeps that payload until a real payload
+     * lands; once one does, a null patch clears it like `v-html` always has.
+     */
+    const keepHtml = (el) => {
+        if (!used.has(el))
+            return false;
+        // The emitted `v-html` create and its tracked patch both run with a null
+        // payload (the patch applies once right after create), so the hold must
+        // outlive the resume pass: one restore is enough until a payload lands.
+        if (el.__vmzHtmlKeep)
+            return true;
+        const childPool = el.__vmzResumePool;
+        if (!childPool || !childPool.firstChild)
+            return false;
+        while (childPool.firstChild)
+            el.appendChild(childPool.firstChild);
+        el.__vmzResumePool = null;
+        el.__vmzHtmlKeep = true;
+        return true;
+    };
+    /**
+     * Scope adoption to one multi-root `<template v-for>` row.
+     *
+     * The row has no element root to carry `data-vmz-key`, so SSR wrote a
+     * `<!--vmz-row:KEY-->…<!--vmz-row-end:KEY-->` pair around its nodes. Claim
+     * exactly that pair, move its inner nodes into a private scope, and drop the
+     * markers so the resumed DOM matches a client-created row. A missing or
+     * unbalanced pair means "this row is not in SSR": push an empty scope so the
+     * row is built fresh instead of stealing a sibling row's nodes.
+     */
+    const rowStart = (key) => {
+        const scope = currentScope();
+        const rowPool = document.createDocumentFragment();
+        let claimed = false;
+        if (key != null) {
+            const wanted = rowMarker(key);
+            const wantedEnd = rowEndMarker(key);
+            const nodes = [...scope.childNodes];
+            let start = -1;
+            for (let i = 0; i < nodes.length; i++) {
+                const n = nodes[i];
+                if (n.nodeType !== 8)
+                    continue;
+                if (String(n.nodeValue || '') === wanted) {
+                    start = i;
+                    break;
+                }
+            }
+            let end = -1;
+            if (start >= 0) {
+                // Nested rows directly inside this row contribute their own pair at
+                // the same sibling level, so pairing is depth-counted.
+                let depth = 0;
+                for (let i = start + 1; i < nodes.length; i++) {
+                    const n = nodes[i];
+                    if (n.nodeType !== 8)
+                        continue;
+                    const data = String(n.nodeValue || '');
+                    if (data.startsWith(ROW_MARKER_PREFIX)) {
+                        depth += 1;
+                    }
+                    else if (data.startsWith(ROW_END_MARKER_PREFIX)) {
+                        if (depth === 0) {
+                            if (data === wantedEnd)
+                                end = i;
+                            break;
+                        }
+                        depth -= 1;
+                    }
+                }
+            }
+            if (end > start) {
+                const startMarker = nodes[start];
+                const endMarker = nodes[end];
+                for (let i = start + 1; i < end; i++)
+                    rowPool.appendChild(nodes[i]);
+                if (startMarker.parentNode === scope)
+                    scope.removeChild(startMarker);
+                if (endMarker.parentNode === scope)
+                    scope.removeChild(endMarker);
+                claimed = true;
+            }
+        }
+        scopeStack.push(rowPool);
+        return claimed;
+    };
+    const rowEnd = () => {
+        if (scopeStack.length <= 1)
+            return;
+        scopeStack.pop();
+    };
     return {
         el: adoptElement,
         elNS: adoptElementNS,
+        claimKeyed,
+        rowStart,
+        rowEnd,
         text: adoptText,
         componentHost,
         enter,
+        enterSlot,
         leave,
         scopeDepth,
         rewindScope,
         beginBranchScope,
+        reclaimHtml,
+        keepHtml,
     };
 }
 export function runDirectResume(Component, inst, container) {

package/dist/browser/resume/hydrate.js

@@ -1,6 +1,31 @@
 import { adoptTopLevelDomRoot, applyPreservedState, createInstance, destroy, findOwnedDefaultSlot, hasMeaningfulChild, mount, runDirectCreate, settlePendingChildMounts, snapshotInstanceState, } from '../dom-core.js';
 import { runDirectResume } from './adopt.js';
 import { resumeIslands } from './resume.js';
+/**
+ * A layout whose whole template is a default `<slot/>` contributes no DOM of its
+ * own: SSR renders the page straight into the route container. Mounting such a
+ * layout would `replaceChildren()` the SSR tree, so the page hydrate that follows
+ * always sees an empty host and recreates every node (verified on the homepage and
+ * charts route: 0 of 336 / 0 of 18743 SSR nodes were reused).
+ *
+ * Only trusted for layouts with no state, props, or lifecycle, so dropping the
+ * instance cannot change behavior — a pass-through layout has nothing to run.
+ */
+function isTransparentSlotLayout(Layout) {
+    const plan = Layout && Layout.__vmzPlan;
+    if (!plan || !Array.isArray(plan.root_ids) || !Array.isArray(plan.nodes) || plan.root_ids.length !== 1) {
+        return false;
+    }
+    const root = plan.nodes.find((n) => n && n.id === plan.root_ids[0]);
+    if (!root || root.kind !== 'slot')
+        return false;
+    if (Array.isArray(Layout.__vmzState) && Layout.__vmzState.length)
+        return false;
+    if (Array.isArray(Layout.__vmzProps) && Layout.__vmzProps.length)
+        return false;
+    const proto = Layout.prototype;
+    return !(proto && (typeof proto.onMount === 'function' || typeof proto.onDestroy === 'function'));
+}
 export async function hydrateRoute(Page, container, props = {}, layoutCtors = [], opts = {}) {
     if (typeof document === 'undefined') {
         throw new Error('vmz:dom hydrateRoute() requires a document (browser)');
@@ -14,6 +39,15 @@ export async function hydrateRoute(Page, container, props = {}, layoutCtors = []
     const layoutInsts = [];
     let host = container;
     const ctors = Array.isArray(layoutCtors) ? layoutCtors.filter(Boolean) : [];
+    // Pass-through layout chain: hydrate the page into the SSR container directly so
+    // the rendered subtree becomes the adopt pool instead of being wiped by mount().
+    if (ctors.length && ctors.every(isTransparentSlotLayout) && hasMeaningfulChild(container)) {
+        const pageInst = await hydrate(Page, container, props, opts);
+        container.__vmzPageHost = container;
+        container.__vmzLayoutInsts = [];
+        container.__vmzInst = pageInst;
+        return pageInst;
+    }
     for (const Layout of ctors) {
         const inst = await mount(Layout, host, {});
         layoutInsts.push(inst);

package/dist/host/deployment/deployment-registry.js

@@ -97,14 +97,17 @@ export async function loadComponentEntries(distDir, opts = {}) {
 export async function importAndRegisterComponentEntries(distDir, entries, registerComponents, opts = {}) {
     const map = {};
     const loaded = opts.loaded ?? null;
-    const packNode = readPackNodeManifest(distDir);
+    const packNode = opts.unpacked ? null : readPackNodeManifest(distDir);
     for (const entry of entries) {
         if (loaded && loaded.has(entry.chunkId))
             continue;
         // Node/SSR consumes the packed unit bytes (`_vmz/pack-node/`) whenever the
         // build packed the node graph — bare package imports in dependency
         // components only exist in vendored form there. Dev sessions do not pack:
-        // the unpacked `${chunkId}.client.js` remains the module identity.
+        // the unpacked `${chunkId}.client.js` remains the module identity. Client
+        // hosts pass `unpacked` and stay on that tree: units they mount come from
+        // the unpacked client graph, including client-only fixtures that no page
+        // reaches and the node graph therefore excludes.
         const abs = packNode ? packNodeEntryAbs(distDir, entry, packNode) : path.join(distDir, entry.entry);
         let href = pathToFileURL(abs).href;
         if (opts.cacheBust != null && opts.cacheBust !== '') {

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

@@ -18,6 +18,7 @@ export async function createRenderHost(distDir, opts = {}) {
         loaded: loadedChunkIds,
         preload: opts.preload ?? 'none',
         closureRoots: opts.closureRoots,
+        unpacked: opts.unpackedEntries === true,
     };
     if (bootstrapOpts.preload !== 'none') {
         await bootstrapComponentRegistry(distDir, dom.registerComponents, bootstrapOpts);
@@ -36,6 +37,7 @@ export async function createRenderHost(distDir, opts = {}) {
         return importAndRegisterComponentEntries(distDir, entries, dom.registerComponents, {
             cacheBust: opts.cacheBust,
             loaded: loadedChunkIds,
+            unpacked: opts.unpackedEntries === true,
         });
     }
     /**

package/dist/host/serve/bootstrap.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { setServerModuleResolver } from '../../faces/vmz-runtime.js';
-import { installDevImportTokenHooks, normalizeDevError, softReload } from './hmr-dev.js';
+import { commitReload, installDevImportTokenHooks, normalizeDevError, prepareReload } from './hmr-dev.js';
 import { bustUrl } from './page-catalog.js';
 import { installAppModuleResolveHooks } from './paths.js';
 import { serveState } from './state.js';
@@ -13,13 +13,17 @@ export async function bootstrapServeHost() {
         const rel = moduleId.replace(/^#server\//, '') + '.js';
         return bustUrl(pathToFileURL(path.join(serveState.distDir, '#server', rel)).href);
     });
+    // dev：入口模块写好后必须由 CLI 侧 pack 再 commit，host 自己不能置 ready。
+    // 生产 serve：pack 已在构建期完成，直接 prepare + commit。
+    if (serveState.isDev)
+        return;
     try {
-        await softReload({ quiet: true });
-        serveState.ready = true;
+        await prepareReload({ quiet: true });
+        commitReload();
     }
     catch (err) {
         serveState.lastDevError = normalizeDevError(err);
         serveState.ready = true;
-        console.error('vmz serve: initial load failed (dev host stays up)', serveState.lastDevError.message);
+        console.error('vmz serve: initial load failed (host stays up)', serveState.lastDevError.message);
     }
 }

package/dist/host/serve/hmr-dev.d.ts

@@ -13,22 +13,21 @@ export declare function emitDevErrorHtml(err: {
     message?: string;
     stack?: string;
 }): AsyncGenerator<any, void, unknown>;
-export declare function softReload(opts?: {
+/**
+ * 第一阶段：加载构建产物、写客户端入口模块，但**不**发布 SSE、不置 ready。
+ *
+ * dev 的浏览器交付必须经 `vmz-pack`，而 pack 由 CLI 侧执行（runtime 不反向
+ * 依赖 `@vmz/vmz`）。因此先把入口写到 outDir，让调用方 pack，再 `commitReload`。
+ */
+export declare function prepareReload(opts?: {
     quiet?: boolean;
     payload?: Record<string, unknown>;
-}): Promise<{
-    affectedChunks: string[];
-    seedChunks: string[];
-    full: boolean;
-    islandHmr: boolean;
-    mode: string;
-    eventOnlyShell: boolean;
-    pageCount: number;
-    reloadedPages: number;
-    reloadAllPages: boolean;
-    buildId: string;
-    sourceRevision: string;
-    bundleRevision: string;
-    serveRevision: string;
-    token: number;
-}>;
+}): Promise<Record<string, unknown>>;
+/**
+ * 第二阶段：发布 SSE 并置 ready。island 热更新的地址表从 pack manifest 精确
+ * 查得（逻辑 `chunkId` → chunk 文件、含 `dom.browser` 的共享 chunk），不做后缀
+ * 猜测；查不到即整页 reload。
+ */
+export declare function commitReload(): Record<string, unknown>;
+/** pack 失败：回滚到上一轮已发布状态，并以 SSE error 显式告知浏览器。 */
+export declare function abortReload(err: unknown): void;