@vmz/core 0.3.12 → 0.3.14

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

@@ -71,6 +71,7 @@ export function __vmzReadPath(inst, root, segs) {
     return obj;
 }
 export function __vmzWritePathLogical(inst, root, segs, kind, rhs) {
+    assertWritePathSegs('__vmzWritePathLogical', root, segs);
     const cur = __vmzReadPath(inst, root, segs);
     if (kind === '||') {
         if (cur)
@@ -139,16 +140,26 @@ function notifyArrayItemLeaf(inst, root, idx, leaf) {
     }
     scheduleRefresh(inst, { type: 'path', root, segs: [String(idx), leaf] });
 }
+function assertWritePathSegs(fn, root, segs) {
+    if (!root)
+        return;
+    if (!Array.isArray(segs) || segs.length === 0) {
+        throw new Error(`vmz:dom ${fn} requires a non-empty path under root ${JSON.stringify(root)}; root field writes must stay plain assignments so the field setter reports them`);
+    }
+}
 export function __vmzWritePath(inst, root, segs, value) {
     if (!inst || inst.__vmzDestroyed)
         return value;
-    if (!root || !Array.isArray(segs) || segs.length === 0)
+    assertWritePathSegs('__vmzWritePath', root, segs);
+    if (!root)
         return value;
+    const normSegs = segs.map((s) => String(s));
     // Hot path: array item field write (`rows[i].label`) ??no map/slice, no shared-owner walk.
-    if (segs.length === 2) {
-        return __vmzWritePathItem(inst, root, segs[0], segs[1], value);
+    // Only a real array root takes the item fast path; a two-segment object path
+    // (`user.address.city`) must stay on the generic walk or the write is dropped.
+    if (normSegs.length === 2 && Array.isArray(inst[root])) {
+        return __vmzWritePathItem(inst, root, normSegs[0], normSegs[1], value);
     }
-    const normSegs = segs.map((s) => String(s));
     let obj = inst[root];
     if (obj == null || typeof obj !== 'object')
         return value;
@@ -176,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 });
         }
@@ -192,8 +207,12 @@ export function __vmzWritePathItem(inst, root, idx, leaf, value) {
     if (!root || leaf == null)
         return value;
     const arr = inst[root];
-    if (!Array.isArray(arr))
-        return value;
+    if (!Array.isArray(arr)) {
+        // Computed member on a plain object root: same write, generic path.
+        if (arr == null || typeof arr !== 'object')
+            return value;
+        return __vmzWritePath(inst, root, [idx, leaf], value);
+    }
     const item = arr[idx];
     if (item == null || typeof item !== 'object')
         return value;
@@ -226,9 +245,10 @@ export function __vmzListTranspose(inst, root, ia, ib) {
 export function __vmzWritePathCompound(inst, root, segs, op, rhs) {
     if (!inst || inst.__vmzDestroyed)
         return undefined;
-    if (!root || !Array.isArray(segs) || segs.length === 0)
+    assertWritePathSegs('__vmzWritePathCompound', root, segs);
+    if (!root)
         return undefined;
-    if (segs.length === 2) {
+    if (segs.length === 2 && Array.isArray(inst[root])) {
         return __vmzWritePathCompoundItem(inst, root, segs[0], segs[1], op, rhs);
     }
     const cur = __vmzReadPath(inst, root, segs);
@@ -241,8 +261,12 @@ export function __vmzWritePathCompoundItem(inst, root, idx, leaf, op, rhs) {
     if (!root || leaf == null)
         return undefined;
     const arr = inst[root];
-    if (!Array.isArray(arr))
-        return undefined;
+    if (!Array.isArray(arr)) {
+        // Computed member on a plain object root: same write, generic path.
+        if (arr == null || typeof arr !== 'object')
+            return undefined;
+        return __vmzWritePathCompound(inst, root, [idx, leaf], op, rhs);
+    }
     const item = arr[idx];
     if (item == null || typeof item !== 'object')
         return undefined;
@@ -333,6 +357,9 @@ export function __vmzArrayMutate(inst, root, baseSegs, method, args) {
     }
     if (!Array.isArray(arr) || typeof arr[method] !== 'function')
         return undefined;
+    if (args !== undefined && !Array.isArray(args)) {
+        throw new Error(`vmz:dom __vmzArrayMutate expects the argument list as one array (root ${JSON.stringify(root)}, method ${JSON.stringify(method)}); stale artifacts must be rebuilt`);
+    }
     const list = Array.isArray(args) ? args : [];
     const ret = arr[method](...list);
     const rootObj = inst[root];

package/dist/browser/resume/adopt.js

@@ -1,9 +1,12 @@
-import { directApi, noteDomCreate, runDirectCreate, } from '../dom-core.js';
+import { directApi, findOwnedDefaultSlot, noteDomCreate, runDirectCreate, } from '../dom-core.js';
+import { HTML_HASH_ATTR } from '../../shared/html-digest.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,11 +14,22 @@ 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;
     };
@@ -44,14 +58,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)
                 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 +102,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,19 +149,45 @@ 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;
+        // `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;
+            }
+        }
+        if (!node.__vmzResumePool)
             return false;
         scopeStack.push(node.__vmzResumePool);
         return true;
@@ -121,9 +224,37 @@ 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;
+    };
     return {
         el: adoptElement,
         elNS: adoptElementNS,
+        claimKeyed,
         text: adoptText,
         componentHost,
         enter,
@@ -131,6 +262,7 @@ function createResumeAdopt(pool, rootEl) {
         scopeDepth,
         rewindScope,
         beginBranchScope,
+        reclaimHtml,
     };
 }
 export function runDirectResume(Component, inst, container) {

package/dist/browser/resume/hydrate.js

@@ -1,6 +1,31 @@
-import { applyPreservedState, createInstance, destroy, findOwnedDefaultSlot, hasMeaningfulChild, mount, runDirectCreate, settlePendingChildMounts, snapshotInstanceState, } from '../dom-core.js';
+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);
@@ -82,10 +116,7 @@ export async function hydrate(Component, container, props = {}, opts = {}) {
     // onMount may still patch state / redirect afterwards (same end state as SSR order).
     if (!hasMeaningfulChild(container)) {
         const node = runDirectCreate(Component, inst);
-        if (node) {
-            inst.__vmzDomRoot = node;
-            container.appendChild(node);
-        }
+        adoptTopLevelDomRoot(inst, node, container);
     }
     else {
         // Deep adopt: park SSR children, rebuild schedule, reclaim nodes (no orphan siblings).

package/dist/browser/resume/resume.js

@@ -1,5 +1,5 @@
 import { applyDirectHostBox } from '../direct-host-box.js';
-import { applyPreservedState, createInstance, destroy, hasMeaningfulChild, isEventEntryStrategy, resolveComponent, runDirectCreate, scheduleClientOn, } from '../dom-core.js';
+import { adoptTopLevelDomRoot, applyPreservedState, createInstance, destroy, hasMeaningfulChild, isEventEntryStrategy, resolveComponent, runDirectCreate, scheduleClientOn, } from '../dom-core.js';
 import { markUnknownComponentHost } from '../unknown-component.js';
 import { runDirectResume } from './adopt.js';
 export async function resume(Component, container, slice = null) {
@@ -42,10 +42,7 @@ export async function resume(Component, container, slice = null) {
     if (Component.__vmzDirect && typeof Component.__vmzCreate === 'function') {
         if (!hasMeaningfulChild(container)) {
             const node = runDirectCreate(Component, inst);
-            if (node) {
-                inst.__vmzDomRoot = node;
-                container.appendChild(node);
-            }
+            adoptTopLevelDomRoot(inst, node, container);
         }
         else {
             // Island leaf adopt: preserve Element identity (resume nodeIdentity).

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

@@ -97,10 +97,18 @@ export async function loadComponentEntries(distDir, opts = {}) {
 export async function importAndRegisterComponentEntries(distDir, entries, registerComponents, opts = {}) {
     const map = {};
     const loaded = opts.loaded ?? null;
+    const packNode = opts.unpacked ? null : readPackNodeManifest(distDir);
     for (const entry of entries) {
         if (loaded && loaded.has(entry.chunkId))
             continue;
-        const abs = path.join(distDir, entry.entry);
+        // 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. 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 !== '') {
             href = `${href}?t=${encodeURIComponent(String(opts.cacheBust))}`;
@@ -114,6 +122,44 @@ export async function importAndRegisterComponentEntries(distDir, entries, regist
         registerComponents(map);
     return map;
 }
+/** `vmz.pack.node-manifest.v0` 的唯一消费点：缺失即未打包（dev），调用方回退未打包模块。 */
+function readPackNodeManifest(distDir) {
+    const manifestPath = path.join(distDir, '_vmz', 'pack-node-manifest.json');
+    if (!fs.existsSync(manifestPath))
+        return null;
+    // Freshness gate: `vmz build` writes the deployment document first and packs
+    // the node graph strictly after; a dev soft rebuild rewrites the deployment
+    // document without re-packing. A deployment newer than the manifest means the
+    // unpacked tree moved on — packed bytes are stale and must not be served.
+    try {
+        const deploymentMtime = fs.statSync(path.join(distDir, 'vmz-deployment.json')).mtimeMs;
+        const manifestMtime = fs.statSync(manifestPath).mtimeMs;
+        if (deploymentMtime > manifestMtime)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        return Array.isArray(parsed.entryFiles) ? { entryFiles: parsed.entryFiles } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Packed node chunk for one component entry; missing logical/file is an explicit error, never a fallback. */
+function packNodeEntryAbs(distDir, entry, manifest) {
+    const hit = manifest.entryFiles.find((e) => e && e.logical === entry.chunkId);
+    if (!hit || typeof hit.file !== 'string' || !hit.file) {
+        throw new Error(`vmz: pack-node manifest has no entry file for "${entry.chunkId}" under ${distDir}`);
+    }
+    const abs = path.join(distDir, '_vmz', 'pack-node', ...hit.file.split('/'));
+    if (!fs.existsSync(abs)) {
+        throw new Error(`vmz: pack-node chunk missing on disk for "${entry.chunkId}": ${path.relative(distDir, abs)}`);
+    }
+    return abs;
+}
 export async function bootstrapComponentRegistry(distDir, registerComponents, opts = {}) {
     const preload = opts.preload ?? (opts.closureRoots?.length ? 'closure' : 'all');
     if (preload === 'none')

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;