@vmz/core 0.3.13 → 0.3.15

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

@@ -12,6 +12,7 @@ import { setRoutes } from '../../faces/vmz-runtime.js';
 import { LOCALE_LINK_PLAN_REL } from './constants.js';
 import { loadDeploymentStyle } from './locale-theme.js';
 import { bustUrl, isEventOnlyShell, isEventStrategy, listPageClientFiles, loadPageResumeEntries, pageNeedsReload } from './page-catalog.js';
+import { packIslandHrefs } from './pack-entry.js';
 import { serveState } from './state.js';
 export function installDevImportTokenHooks() {
     if (!serveState.isDev)
@@ -133,34 +134,52 @@ export async function* emitDevErrorHtml(err) {
 function escapeHtml(s) {
     return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
-function emitEntryClient(eager, lazy, token) {
-    const q = `?t=${token}`;
+/**
+ * 客户端入口模块由 pack 消费，必须保持内容稳定：每次重建都把 `?t=` 注入
+ * 动态 import 会让打包产物每轮都变，也会让浏览器拿到两个不同 URL 的同一模块。
+ * 缓存破坏由打包文件名（内容哈希）与 SSE 侧的 reload 负责。
+ */
+function emitEntryClient(eager, lazy) {
     const native = loadNativeAddon();
     if (typeof native.generateServeEntryClient !== 'function') {
         throw new Error('vmz native addon missing generateServeEntryClient — rebuild with `pnpm napi:build`');
     }
-    return native.generateServeEntryClient(eager, lazy, q);
+    return native.generateServeEntryClient(eager, lazy, '');
 }
-function emitEntryEvent(eager, lazy, token) {
-    const q = `?t=${token}`;
+function emitEntryEvent(eager, lazy) {
     const native = loadNativeAddon();
     if (typeof native.generateServeEntryEvent !== 'function') {
         throw new Error('vmz native addon missing generateServeEntryEvent — rebuild with `pnpm napi:build`');
     }
-    return native.generateServeEntryEvent(eager, lazy, q);
+    return native.generateServeEntryEvent(eager, lazy, '');
 }
-export async function softReload(opts = {}) {
+let pendingReload = null;
+let pendingRollback = null;
+/**
+ * 第一阶段：加载构建产物、写客户端入口模块，但**不**发布 SSE、不置 ready。
+ *
+ * dev 的浏览器交付必须经 `vmz-pack`，而 pack 由 CLI 侧执行（runtime 不反向
+ * 依赖 `@vmz/vmz`）。因此先把入口写到 outDir，让调用方 pack，再 `commitReload`。
+ */
+export async function prepareReload(opts = {}) {
     const prevToken = serveState.reloadToken;
     const prevCatalog = serveState.pageCatalog;
     const prevCtors = new Map(serveState.pageCtors);
     const nextToken = Date.now();
     serveState.reloadToken = nextToken;
+    pendingReload = null;
+    pendingRollback = () => {
+        serveState.reloadToken = prevToken;
+        serveState.pageCatalog = prevCatalog;
+        serveState.pageCtors.clear();
+        for (const [k, v] of prevCtors)
+            serveState.pageCtors.set(k, v);
+    };
     const affected = opts.payload?.affectedChunks ?? [];
     const seeds = opts.payload?.seedChunks ?? [];
     const full = opts.payload?.full;
     const islandHmr = Boolean(opts.payload?.islandHmr);
     const rerunLoaders = opts.payload?.rerunLoaders ?? [];
-    const skipEntryRewrite = Boolean(opts.payload?.skipEntryRewrite);
     const buildId = opts.payload?.buildId != null ? String(opts.payload.buildId) : null;
     const sourceRevision = opts.payload?.sourceRevision != null ? String(opts.payload.sourceRevision) : null;
     const bundleRevision = opts.payload?.bundleRevision != null ? String(opts.payload.bundleRevision) : null;
@@ -255,13 +274,28 @@ export async function softReload(opts = {}) {
             }
         }
         const layoutEntries = [...layoutNames].sort().map((id) => ({ name: id, entry: `${id}.client.js` }));
-        await writeFile(path.join(serveState.distDir, 'entry-client.js'), emitEntryClient([...eagerComponents, ...pageEntries, ...layoutEntries], lazyComponents, skipEntryRewrite ? serveState.reloadToken : nextToken), 'utf8');
+        await writeFile(path.join(serveState.distDir, 'entry-client.js'), emitEntryClient([...eagerComponents, ...pageEntries, ...layoutEntries], lazyComponents), 'utf8');
         const strategies = resumeEntries.map((e) => e.strategy);
         const eventOnlyShell = isEventOnlyShell(strategies);
-        await writeFile(path.join(serveState.distDir, 'entry-event.js'), emitEntryEvent([], lazyComponents, skipEntryRewrite ? serveState.reloadToken : nextToken), 'utf8');
-        serveState.lastDevError = null;
+        await writeFile(path.join(serveState.distDir, 'entry-event.js'), emitEntryEvent([], lazyComponents), 'utf8');
         const mode = islandHmr ? 'island' : eventOnlyShell ? 'event-shell' : 'full';
-        notifySse(JSON.stringify({
+        const info = {
+            affectedChunks: affected,
+            seedChunks: seeds,
+            full: Boolean(full),
+            islandHmr,
+            mode,
+            eventOnlyShell,
+            pageCount: serveState.pageCatalog.length,
+            reloadedPages: islandHmr ? 0 : nextCtors.size,
+            reloadAllPages,
+            buildId: buildId || serveState.lastDevBuildId,
+            sourceRevision,
+            bundleRevision,
+            serveRevision: String(serveState.reloadToken),
+            token: serveState.reloadToken,
+        };
+        const sse = {
             type: 'hmr',
             mode,
             affectedChunks: affected,
@@ -273,7 +307,8 @@ export async function softReload(opts = {}) {
             serveRevision: String(serveState.reloadToken),
             full: Boolean(full),
             eventOnlyShell,
-        }));
+        };
+        let logLine = null;
         if (!opts.quiet) {
             const aff = affected.length > 0 ? ` affected=[${affected.join(', ')}]` : full === false ? ' affected=[]' : '';
             const scope = islandHmr ? 'island' : reloadAllPages ? 'all-pages' : `pages=${nextCtors.size}`;
@@ -281,32 +316,58 @@ export async function softReload(opts = {}) {
             const rev = bid || sourceRevision || bundleRevision
                 ? ` buildId=${bid || '-'} source=${sourceRevision || '-'} bundle=${bundleRevision || '-'} serve=${serveState.reloadToken}`
                 : ` t=${serveState.reloadToken}`;
-            console.log(`vmz serve: soft reload ok (mode=${mode}; ${scope}; catalog=${serveState.pageCatalog.length};${rev}${aff})`);
+            logLine = `vmz serve: soft reload ok (mode=${mode}; ${scope}; catalog=${serveState.pageCatalog.length};${rev}${aff})`;
         }
-        return {
-            affectedChunks: affected,
-            seedChunks: seeds,
-            full: Boolean(full),
-            islandHmr,
-            mode,
-            eventOnlyShell,
-            pageCount: serveState.pageCatalog.length,
-            reloadedPages: islandHmr ? 0 : nextCtors.size,
-            reloadAllPages,
-            buildId: buildId || serveState.lastDevBuildId,
-            sourceRevision,
-            bundleRevision,
-            serveRevision: String(serveState.reloadToken),
-            token: serveState.reloadToken,
-        };
+        pendingReload = { info, sse, logLine };
+        return info;
     }
     catch (err) {
-        serveState.reloadToken = prevToken;
-        serveState.pageCatalog = prevCatalog;
-        serveState.pageCtors.clear();
-        for (const [k, v] of prevCtors)
-            serveState.pageCtors.set(k, v);
+        pendingRollback?.();
+        pendingRollback = null;
+        pendingReload = null;
         serveState.lastDevError = normalizeDevError(err);
         throw err;
     }
 }
+/**
+ * 第二阶段：发布 SSE 并置 ready。island 热更新的地址表从 pack manifest 精确
+ * 查得（逻辑 `chunkId` → chunk 文件、含 `dom.browser` 的共享 chunk），不做后缀
+ * 猜测；查不到即整页 reload。
+ */
+export function commitReload() {
+    const prepared = pendingReload;
+    if (!prepared)
+        throw new Error('commitReload: no prepared reload');
+    let island = null;
+    if (serveState.isDev) {
+        try {
+            island = packIslandHrefs(serveState.distDir);
+        }
+        catch (err) {
+            abortReload(err);
+            throw err;
+        }
+    }
+    pendingReload = null;
+    pendingRollback = null;
+    serveState.lastDevError = null;
+    serveState.ready = true;
+    notifySse(JSON.stringify({ ...prepared.sse, island }));
+    if (prepared.logLine)
+        console.log(prepared.logLine);
+    return { ...prepared.info, island };
+}
+/** pack 失败：回滚到上一轮已发布状态，并以 SSE error 显式告知浏览器。 */
+export function abortReload(err) {
+    pendingReload = null;
+    pendingRollback?.();
+    pendingRollback = null;
+    serveState.ready = false;
+    serveState.lastDevError = normalizeDevError(err);
+    notifySse(JSON.stringify({
+        type: 'error',
+        message: serveState.lastDevError.message,
+        stack: serveState.lastDevError.stack,
+        at: serveState.lastDevError.at,
+    }));
+}

package/dist/host/serve/http.js

@@ -1,7 +1,7 @@
 import http from 'node:http';
 import { handleNodeRequest } from '../../faces/vmz-runtime.js';
 import { SHUTDOWN_TIMEOUT_MS } from './constants.js';
-import { normalizeDevError, notifySse, softReload } from './hmr-dev.js';
+import { abortReload, commitReload, normalizeDevError, notifySse, prepareReload } from './hmr-dev.js';
 import { renderPage, renderPageStream } from './page-render.js';
 import { serveState } from './state.js';
 function readRequestBody(req) {
@@ -70,21 +70,38 @@ export function startServeHttp() {
         if (url.pathname === '/__vmz/reload' && req.method === 'POST') {
             readRequestBody(req)
                 .then((raw) => {
-                let payload = {};
+                let body = {};
                 try {
-                    payload = raw ? JSON.parse(String(raw)) : {};
+                    body = raw ? JSON.parse(String(raw)) : {};
                 }
                 catch {
-                    payload = {};
+                    body = {};
                 }
-                return softReload({ payload });
+                // dev 两阶段：prepare 写入口 → CLI 侧 `vmz-pack` → commit 发布。
+                // 未带 phase 的请求不属于 v0 合同，直接拒绝而不是猜测阶段。
+                const phase = body.phase;
+                if (phase === 'prepare') {
+                    return prepareReload({ payload: body.payload }).then((info) => ({
+                        phase,
+                        info,
+                    }));
+                }
+                if (phase === 'commit') {
+                    return { phase, info: commitReload() };
+                }
+                if (phase === 'abort') {
+                    const rawError = body.error;
+                    abortReload(new Error(rawError?.message || 'pack failed'));
+                    return { phase, info: { ok: true } };
+                }
+                throw Object.assign(new Error('reload: unknown phase'), { statusCode: 400 });
             })
-                .then((info) => {
+                .then(({ phase, info }) => {
                 res.writeHead(200, { 'content-type': 'application/json' });
-                res.end(JSON.stringify({ ok: true, token: serveState.reloadToken, ...info }));
+                res.end(JSON.stringify({ ok: true, phase, ...info }));
             })
                 .catch((err) => {
-                console.error('vmz serve: soft reload failed', err);
+                console.error('vmz serve: reload failed', err);
                 serveState.lastDevError = normalizeDevError(err);
                 notifySse(JSON.stringify({
                     type: 'error',

package/dist/host/serve/pack-entry.d.ts

@@ -8,3 +8,24 @@
  * `vmz-pack` rewrites.
  */
 export declare function packEntryHref(distDir: string, logical: string): string;
+/**
+ * 部署单元逻辑 `chunkId` → 浏览器 chunk URL。
+ *
+ * 只读 `unitChunks[]` 的精确 `logical` 匹配：逻辑 `chunkId` 与 pack chunk id
+ * 不保证相同，禁止前缀推导或后缀猜测。单元未进客户端图（`fileName: null`）
+ * 视为错误，消费方不得回退到未打包文件。
+ */
+export declare function packChunkHref(distDir: string, logical: string): string;
+/** 含指定产物模块的 chunk URL（精确路径匹配，如 `dom.browser.js`）。 */
+export declare function packModuleChunkHref(distDir: string, moduleRel: string): string;
+export interface PackIslandHrefs {
+    /** 含 `dom.browser` 的共享 chunk（`hydrate` 由该 chunk 导出）。 */
+    dom: string;
+    /** 部署单元逻辑 `chunkId` → 其客户端 chunk URL（未进图的不列出）。 */
+    pages: Record<string, string>;
+}
+/**
+ * island 热更新地址表：一次读 manifest，给出 runtime 共享 chunk 与各页面 chunk
+ * 的 URL。调用方只按 `data-vmz-page` 逻辑名查表，缺失即走整页 reload。
+ */
+export declare function packIslandHrefs(distDir: string): PackIslandHrefs;

package/dist/host/serve/pack-entry.js

@@ -3,6 +3,24 @@ import path from 'node:path';
 const PACK_MANIFEST_REL = ['_vmz', 'pack-manifest.json'];
 const PACK_OUTPUT_DIR_REL = ['_vmz', 'pack'];
 const DEFAULT_PUBLIC_BASE = '/';
+function readPackManifest(distDir, caller) {
+    const manifestPath = path.join(distDir, ...PACK_MANIFEST_REL);
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error(`${caller}: missing pack manifest at ${manifestPath} — run vmz build (pack) first`);
+    }
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+}
+function chunkHref(manifest, fileName) {
+    const base = String(manifest.publicBase || DEFAULT_PUBLIC_BASE).replace(/\/$/, '');
+    return `${base}/${PACK_OUTPUT_DIR_REL.join('/')}/${fileName}`;
+}
+/**
+ * 模块路径比较键：去掉 Windows verbatim 前缀（Rust `canonicalize` 给
+ * `//?/E:/…`，Node 给 `E:/…`）并统一分隔符，避免同一文件因前缀差异查不到。
+ */
+function moduleKey(filePath) {
+    return filePath.replace(/^(?:\\\\\?\\|\/\/\?\/)/, '').replace(/\\/g, '/');
+}
 /**
  * Resolve the browser URL of a packed bootstrap entry from
  * `_vmz/pack-manifest.json`.
@@ -13,15 +31,68 @@ const DEFAULT_PUBLIC_BASE = '/';
  * `vmz-pack` rewrites.
  */
 export function packEntryHref(distDir, logical) {
-    const manifestPath = path.join(distDir, ...PACK_MANIFEST_REL);
-    if (!fs.existsSync(manifestPath)) {
-        throw new Error(`packEntryHref: missing ${manifestPath} — run vmz build (pack) first`);
-    }
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const manifest = readPackManifest(distDir, 'packEntryHref');
     const hit = (manifest.entryFiles || []).find((entry) => entry && entry.logical === logical);
     if (!hit || typeof hit.file !== 'string' || !hit.file) {
         throw new Error(`packEntryHref: pack manifest has no entry file for "${logical}"`);
     }
-    const base = String(manifest.publicBase || DEFAULT_PUBLIC_BASE).replace(/\/$/, '');
-    return `${base}/${PACK_OUTPUT_DIR_REL.join('/')}/${hit.file}`;
+    return chunkHref(manifest, hit.file);
+}
+/**
+ * 部署单元逻辑 `chunkId` → 浏览器 chunk URL。
+ *
+ * 只读 `unitChunks[]` 的精确 `logical` 匹配：逻辑 `chunkId` 与 pack chunk id
+ * 不保证相同，禁止前缀推导或后缀猜测。单元未进客户端图（`fileName: null`）
+ * 视为错误，消费方不得回退到未打包文件。
+ */
+export function packChunkHref(distDir, logical) {
+    const manifest = readPackManifest(distDir, 'packChunkHref');
+    const hit = (manifest.unitChunks || []).find((entry) => entry && entry.logical === logical);
+    if (!hit) {
+        throw new Error(`packChunkHref: pack manifest has no unit chunk for "${logical}"`);
+    }
+    if (typeof hit.fileName !== 'string' || !hit.fileName) {
+        throw new Error(`packChunkHref: unit "${logical}" is not in the browser client graph`);
+    }
+    return chunkHref(manifest, hit.fileName);
+}
+/** 含指定产物模块的 chunk URL（精确路径匹配，如 `dom.browser.js`）。 */
+export function packModuleChunkHref(distDir, moduleRel) {
+    const manifest = readPackManifest(distDir, 'packModuleChunkHref');
+    const target = moduleKey(path.join(distDir, ...moduleRel.split('/')));
+    for (const chunk of manifest.chunks || []) {
+        if (typeof chunk.fileName !== 'string' || !chunk.fileName)
+            continue;
+        for (const module of chunk.modules || []) {
+            if (moduleKey(String(module)) === target)
+                return chunkHref(manifest, chunk.fileName);
+        }
+    }
+    throw new Error(`packModuleChunkHref: no chunk carries "${moduleRel}"`);
+}
+/**
+ * island 热更新地址表：一次读 manifest，给出 runtime 共享 chunk 与各页面 chunk
+ * 的 URL。调用方只按 `data-vmz-page` 逻辑名查表，缺失即走整页 reload。
+ */
+export function packIslandHrefs(distDir) {
+    const manifest = readPackManifest(distDir, 'packIslandHrefs');
+    const pages = {};
+    for (const unit of manifest.unitChunks || []) {
+        if (!unit || typeof unit.logical !== 'string' || !unit.logical)
+            continue;
+        if (typeof unit.fileName !== 'string' || !unit.fileName)
+            continue;
+        pages[unit.logical] = chunkHref(manifest, unit.fileName);
+    }
+    const target = moduleKey(path.join(distDir, 'dom.browser.js'));
+    for (const chunk of manifest.chunks || []) {
+        if (typeof chunk.fileName !== 'string' || !chunk.fileName)
+            continue;
+        for (const module of chunk.modules || []) {
+            if (moduleKey(String(module)) === target) {
+                return { dom: chunkHref(manifest, chunk.fileName), pages };
+            }
+        }
+    }
+    throw new Error('packIslandHrefs: no chunk carries "dom.browser.js"');
 }

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

@@ -291,11 +291,15 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
       hideOverlay();
       if (msg.mode === "island") {
         try {
-          const { hydrate } = await import("/dom.browser.js?t=" + msg.token);
+          // 地址表来自 pack manifest（逻辑名精确匹配），缺失即整页 reload：
+          // 不再单独加载裸 dom.browser.js，避免与 packed bootstrap 形成两份 runtime。
+          const island = msg.island || {};
           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);
+          const pageHref = pageChunk && island.pages ? island.pages[pageChunk] : null;
+          if (root && pageChunk && island.dom && pageHref) {
+            const { hydrate } = await import(island.dom);
+            const pageMod = await import(pageHref);
             let hmrProps = {};
             try {
               const raw = root.getAttribute("data-vmz-props");
@@ -394,12 +398,10 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
     if (typeof native.generatePageShell !== 'function') {
         throw new Error('vmz native addon missing generatePageShell — rebuild with `pnpm napi:build`');
     }
-    // 生产 serve 必须注入打包条目：原始 `entry-client.js` 及其拉取的客户端模块保留
-    // 裸包说明符，浏览器无法解析。dev 仍走带 token 的原始 bootstrap。
+    // 客户端入口一律经 pack manifest 解析：原始 `entry-client.js` 及其拉取的
+    // 客户端模块保留裸包说明符，浏览器无法解析。dev 与生产因此走同一张表。
     const entryLogical = eventOnlyShell ? 'entry-event.js' : 'entry-client.js';
-    const entrySrc = serveState.isDev
-        ? `/${entryLogical}?t=${serveState.reloadToken}`
-        : packEntryHref(serveState.distDir, entryLogical);
+    const entrySrc = packEntryHref(serveState.distDir, entryLogical);
     const cssHref = cssEntryWithBust(serveState.cssEntry);
     yield native.generatePageShell({
         bodyHtml,

package/dist/shared/dom-attr-normalize.d.ts

@@ -12,5 +12,11 @@
  */
 /** Normalize one or more class fragments into a deduped class string. */
 export declare function mergeClassParts(...parts: unknown[]): string;
+/**
+ * Split a style fragment on top-level `;`. Semicolons inside `url(...)` /
+ * nested parens and inside quotes (e.g. `content: 'a;b'`, data URIs with
+ * `;base64,`) do not split — a naive split would truncate those values.
+ */
+export declare function splitStyleDeclarations(text: string): string[];
 /** Merge static + dynamic style fragments; later parts override same keys. */
 export declare function mergeStyleParts(...parts: unknown[]): string;

package/dist/shared/dom-attr-normalize.js

@@ -129,7 +129,7 @@ function pushStyleValues(out, key, value) {
  * nested parens and inside quotes (e.g. `content: 'a;b'`, data URIs with
  * `;base64,`) do not split — a naive split would truncate those values.
  */
-function splitStyleDeclarations(text) {
+export function splitStyleDeclarations(text) {
     const chunks = [];
     let depth = 0;
     let quote = null;

package/dist/shared/host.types.d.ts

@@ -66,6 +66,13 @@ export type DedupeComponentEntriesOpts = {
 export type ImportComponentEntriesOpts = {
     cacheBust?: string | number;
     loaded?: Set<string>;
+    /**
+     * Import the unpacked client tree (`${chunkId}.client.js`) even when
+     * `_vmz/pack-node-manifest.json` exists. Client hosts (headless logic
+     * mounts) execute unpacked client bytes, so their registry must use the
+     * same tree. Node/SSR hosts keep the default packed-node lookup.
+     */
+    unpacked?: boolean;
 };
 export type BootstrapComponentRegistryOpts = LoadComponentEntriesOpts & ImportComponentEntriesOpts & {
     preload?: 'all' | 'closure' | 'none';
@@ -109,5 +116,7 @@ export type RenderHostOpts = {
     preload?: 'all' | 'closure' | 'none';
     cacheBust?: string | number;
     rootChunkIds?: string[] | null;
+    /** Client hosts import registry entries from the unpacked client tree. */
+    unpackedEntries?: boolean;
     [key: string]: unknown;
 };

package/dist/shared/html-digest.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Content identity for `v-html` payloads shared by SSR and resume.
+ *
+ * The browser serializer expands self-closing tags (`<path/>` becomes
+ * `<path></path>`), so comparing a generated markup string with the serialized
+ * SSR DOM always misses. SSR therefore records the digest of the exact string
+ * it wrote, and resume compares that marker with the digest of the string it
+ * would write. The digest is taken over the generated string only: no DOM
+ * serialization, no normalization.
+ *
+ * Two independent 32-bit FNV-1a lanes plus the code-unit length give 64 bits of
+ * identity without pulling a crypto dependency into the browser bundle.
+ */
+export declare const HTML_HASH_ATTR = "data-vmz-html-hash";
+export declare function htmlDigest(value: string): string;

package/dist/shared/html-digest.js

@@ -0,0 +1,25 @@
+/**
+ * Content identity for `v-html` payloads shared by SSR and resume.
+ *
+ * The browser serializer expands self-closing tags (`<path/>` becomes
+ * `<path></path>`), so comparing a generated markup string with the serialized
+ * SSR DOM always misses. SSR therefore records the digest of the exact string
+ * it wrote, and resume compares that marker with the digest of the string it
+ * would write. The digest is taken over the generated string only: no DOM
+ * serialization, no normalization.
+ *
+ * Two independent 32-bit FNV-1a lanes plus the code-unit length give 64 bits of
+ * identity without pulling a crypto dependency into the browser bundle.
+ */
+export const HTML_HASH_ATTR = 'data-vmz-html-hash';
+export function htmlDigest(value) {
+    const text = value == null ? '' : String(value);
+    let laneA = 0x811c9dc5;
+    let laneB = 0x9e3779b9;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        laneA = Math.imul(laneA ^ code, 0x01000193) >>> 0;
+        laneB = Math.imul(laneB ^ code, 0x85ebca77) >>> 0;
+    }
+    return `${text.length.toString(36)}-${laneA.toString(36)}-${laneB.toString(36)}`;
+}

package/dist/shared/row-key.d.ts

@@ -0,0 +1,13 @@
+/** SSR row identity for multi-root `<template v-for>` rows. */
+export declare const ROW_MARKER_PREFIX = "vmz-row:";
+export declare const ROW_END_MARKER_PREFIX = "vmz-row-end:";
+/**
+ * Comment-safe row key token.
+ *
+ * Row identity travels inside HTML comments, where `--` is illegal. Encode the
+ * key once (both SSR writer and resume reader use this same function) and strip
+ * the remaining hyphens so no key can ever close the comment early.
+ */
+export declare function rowKeyToken(key: unknown): string;
+export declare function rowMarker(key: unknown): string;
+export declare function rowEndMarker(key: unknown): string;

package/dist/shared/row-key.js

@@ -0,0 +1,19 @@
+/** SSR row identity for multi-root `<template v-for>` rows. */
+export const ROW_MARKER_PREFIX = 'vmz-row:';
+export const ROW_END_MARKER_PREFIX = 'vmz-row-end:';
+/**
+ * Comment-safe row key token.
+ *
+ * Row identity travels inside HTML comments, where `--` is illegal. Encode the
+ * key once (both SSR writer and resume reader use this same function) and strip
+ * the remaining hyphens so no key can ever close the comment early.
+ */
+export function rowKeyToken(key) {
+    return encodeURIComponent(String(key)).replace(/-/g, '%2D');
+}
+export function rowMarker(key) {
+    return `${ROW_MARKER_PREFIX}${rowKeyToken(key)}`;
+}
+export function rowEndMarker(key) {
+    return `${ROW_END_MARKER_PREFIX}${rowKeyToken(key)}`;
+}